An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.
JavaScript aicursorcursor-aicursorailovablelovable-devroocodetask-managertaskstasks-listwindsurfwindsurf-ai
feat: add rpg method prd example template (#1285)
Ralph Khreish2a910a40bac3
diff --git a/.changeset/nice-ways-hope.md b/.changeset/nice-ways-hope.mdnew file mode 100644index 00000000..f8581bfd--- /dev/null+++ b/.changeset/nice-ways-hope.md@@ -0,0 +1,17 @@+---+"task-master-ai": minor+---++Add RPG (Repository Planning Graph) method template for structured PRD creation. The new `example_prd_rpg.txt` template teaches AI agents and developers the RPG methodology through embedded instructions, inline good/bad examples, and XML-style tags for structure. This template enables creation of dependency-aware PRDs that automatically generate topologically-ordered task graphs when parsed with Task Master.++Key features:+- Method-as-template: teaches RPG principles (dual-semantics, explicit dependencies, topological order) while being used+- Inline instructions at decision points guide AI through each section+- Good/bad examples for immediate pattern matching+- Flexible plain-text format with XML-style tags for parseability+- Critical dependency-graph section ensures correct task ordering+- Automatic inclusion during `task-master init`+- Comprehensive documentation at [docs.task-master.dev/capabilities/rpg-method](https://docs.task-master.dev/capabilities/rpg-method)+- Tool recommendations for code-context-aware PRD creation (Claude Code, Cursor, Gemini CLI, Codex/Grok)++The RPG template complements the existing `example_prd.txt` and provides a more structured approach for complex projects requiring clear module boundaries and dependency chains.\ No newline at end of filediff --git a/.taskmaster/templates/example_prd_rpg.txt b/.taskmaster/templates/example_prd_rpg.txtnew file mode 100644index 00000000..5ad908fd--- /dev/null+++ b/.taskmaster/templates/example_prd_rpg.txt@@ -0,0 +1,511 @@+<rpg-method>+# Repository Planning Graph (RPG) Method - PRD Template++This template teaches you (AI or human) how to create structured, dependency-aware PRDs using the RPG methodology from Microsoft Research. The key insight: separate WHAT (functional) from HOW (structural), then connect them with explicit dependencies.++## Core Principles++1. **Dual-Semantics**: Think functional (capabilities) AND structural (code organization) separately, then map them+2. **Explicit Dependencies**: Never assume - always state what depends on what+3. **Topological Order**: Build foundation first, then layers on top+4. **Progressive Refinement**: Start broad, refine iteratively++## How to Use This Template++- Follow the instructions in each `<instruction>` block+- Look at `<example>` blocks to see good vs bad patterns+- Fill in the content sections with your project details+- The AI reading this will learn the RPG method by following along+- Task Master will parse the resulting PRD into dependency-aware tasks++## Recommended Tools for Creating PRDs++When using this template to **create** a PRD (not parse it), use **code-context-aware AI assistants** for best results:++**Why?** The AI needs to understand your existing codebase to make good architectural decisions about modules, dependencies, and integration points.++**Recommended tools:**+- **Claude Code** (claude-code CLI) - Best for structured reasoning and large contexts+- **Cursor/Windsurf** - IDE integration with full codebase context+- **Gemini CLI** (gemini-cli) - Massive context window for large codebases+- **Codex/Grok CLI** - Strong code generation with context awareness++**Note:** Once your PRD is created, `task-master parse-prd` works with any configured AI model - it just needs to read the PRD text itself, not your codebase.+</rpg-method>++---++<overview>+<instruction>+Start with the problem, not the solution. Be specific about:+- What pain point exists?+- Who experiences it?+- Why existing solutions don't work?+- What success looks like (measurable outcomes)?++Keep this section focused - don't jump into implementation details yet.+</instruction>++## Problem Statement+[Describe the core problem. Be concrete about user pain points.]++## Target Users+[Define personas, their workflows, and what they're trying to achieve.]++## Success Metrics+[Quantifiable outcomes. Examples: "80% task completion via autopilot", "< 5% manual intervention rate"]++</overview>++---++<functional-decomposition>+<instruction>+Now think about CAPABILITIES (what the system DOES), not code structure yet.++Step 1: Identify high-level capability domains+- Think: "What major things does this system do?"+- Examples: Data Management, Core Processing, Presentation Layer++Step 2: For each capability, enumerate specific features+- Use explore-exploit strategy:+ * Exploit: What features are REQUIRED for core value?+ * Explore: What features make this domain COMPLETE?++Step 3: For each feature, define:+- Description: What it does in one sentence+- Inputs: What data/context it needs+- Outputs: What it produces/returns+- Behavior: Key logic or transformations++<example type="good">+Capability: Data Validation+ Feature: Schema validation+ - Description: Validate JSON payloads against defined schemas+ - Inputs: JSON object, schema definition+ - Outputs: Validation result (pass/fail) + error details+ - Behavior: Iterate fields, check types, enforce constraints++ Feature: Business rule validation+ - Description: Apply domain-specific validation rules+ - Inputs: Validated data object, rule set+ - Outputs: Boolean + list of violated rules+ - Behavior: Execute rules sequentially, short-circuit on failure+</example>++<example type="bad">+Capability: validation.js+ (Problem: This is a FILE, not a CAPABILITY. Mixing structure into functional thinking.)++Capability: Validation+ Feature: Make sure data is good+ (Problem: Too vague. No inputs/outputs. Not actionable.)+</example>+</instruction>++## Capability Tree++### Capability: [Name]+[Brief description of what this capability domain covers]++#### Feature: [Name]+- **Description**: [One sentence]+- **Inputs**: [What it needs]+- **Outputs**: [What it produces]+- **Behavior**: [Key logic]++#### Feature: [Name]+- **Description**:+- **Inputs**:+- **Outputs**:+- **Behavior**:++### Capability: [Name]+...++</functional-decomposition>++---++<structural-decomposition>+<instruction>+NOW think about code organization. Map capabilities to actual file/folder structure.++Rules:+1. Each capability maps to a module (folder or file)+2. Features within a capability map to functions/classes+3. Use clear module boundaries - each module has ONE responsibility+4. Define what each module exports (public interface)++The goal: Create a clear mapping between "what it does" (functional) and "where it lives" (structural).++<example type="good">+Capability: Data Validation+ → Maps to: src/validation/+ ├── schema-validator.js (Schema validation feature)+ ├── rule-validator.js (Business rule validation feature)+ └── index.js (Public exports)++Exports:+ - validateSchema(data, schema)+ - validateRules(data, rules)+</example>++<example type="bad">+Capability: Data Validation+ → Maps to: src/utils.js+ (Problem: "utils" is not a clear module boundary. Where do I find validation logic?)++Capability: Data Validation+ → Maps to: src/validation/everything.js+ (Problem: One giant file. Features should map to separate files for maintainability.)+</example>+</instruction>++## Repository Structure++```+project-root/+├── src/+│ ├── [module-name]/ # Maps to: [Capability Name]+│ │ ├── [file].js # Maps to: [Feature Name]+│ │ └── index.js # Public exports+│ └── [module-name]/+├── tests/+└── docs/+```++## Module Definitions++### Module: [Name]+- **Maps to capability**: [Capability from functional decomposition]+- **Responsibility**: [Single clear purpose]+- **File structure**:+ ```+ module-name/+ ├── feature1.js+ ├── feature2.js+ └── index.js+ ```+- **Exports**:+ - `functionName()` - [what it does]+ - `ClassName` - [what it does]++</structural-decomposition>++---++<dependency-graph>+<instruction>+This is THE CRITICAL SECTION for Task Master parsing.++Define explicit dependencies between modules. This creates the topological order for task execution.++Rules:+1. List modules in dependency order (foundation first)+2. For each module, state what it depends on+3. Foundation modules should have NO dependencies+4. Every non-foundation module should depend on at least one other module+5. Think: "What must EXIST before I can build this module?"++<example type="good">+Foundation Layer (no dependencies):+ - error-handling: No dependencies+ - config-manager: No dependencies+ - base-types: No dependencies++Data Layer:+ - schema-validator: Depends on [base-types, error-handling]+ - data-ingestion: Depends on [schema-validator, config-manager]++Core Layer:+ - algorithm-engine: Depends on [base-types, error-handling]+ - pipeline-orchestrator: Depends on [algorithm-engine, data-ingestion]+</example>++<example type="bad">+- validation: Depends on API+- API: Depends on validation+(Problem: Circular dependency. This will cause build/runtime issues.)++- user-auth: Depends on everything+(Problem: Too many dependencies. Should be more focused.)+</example>+</instruction>++## Dependency Chain++### Foundation Layer (Phase 0)+No dependencies - these are built first.++- **[Module Name]**: [What it provides]+- **[Module Name]**: [What it provides]++### [Layer Name] (Phase 1)+- **[Module Name]**: Depends on [[module-from-phase-0], [module-from-phase-0]]+- **[Module Name]**: Depends on [[module-from-phase-0]]++### [Layer Name] (Phase 2)+- **[Module Name]**: Depends on [[module-from-phase-1], [module-from-foundation]]++[Continue building up layers...]++</dependency-graph>++---++<implementation-roadmap>+<instruction>+Turn the dependency graph into concrete development phases.++Each phase should:+1. Have clear entry criteria (what must exist before starting)+2. Contain tasks that can be parallelized (no inter-dependencies within phase)+3. Have clear exit criteria (how do we know phase is complete?)+4. Build toward something USABLE (not just infrastructure)++Phase ordering follows topological sort of dependency graph.++<example type="good">+Phase 0: Foundation+ Entry: Clean repository+ Tasks:+ - Implement error handling utilities+ - Create base type definitions+ - Setup configuration system+ Exit: Other modules can import foundation without errors++Phase 1: Data Layer+ Entry: Phase 0 complete+ Tasks:+ - Implement schema validator (uses: base types, error handling)+ - Build data ingestion pipeline (uses: validator, config)+ Exit: End-to-end data flow from input to validated output+</example>++<example type="bad">+Phase 1: Build Everything+ Tasks:+ - API+ - Database+ - UI+ - Tests+ (Problem: No clear focus. Too broad. Dependencies not considered.)+</example>+</instruction>++## Development Phases++### Phase 0: [Foundation Name]+**Goal**: [What foundational capability this establishes]++**Entry Criteria**: [What must be true before starting]++**Tasks**:+- [ ] [Task name] (depends on: [none or list])+ - Acceptance criteria: [How we know it's done]+ - Test strategy: [What tests prove it works]++- [ ] [Task name] (depends on: [none or list])++**Exit Criteria**: [Observable outcome that proves phase complete]++**Delivers**: [What can users/developers do after this phase?]++---++### Phase 1: [Layer Name]+**Goal**:++**Entry Criteria**: Phase 0 complete++**Tasks**:+- [ ] [Task name] (depends on: [[tasks-from-phase-0]])+- [ ] [Task name] (depends on: [[tasks-from-phase-0]])++**Exit Criteria**:++**Delivers**:++---++[Continue with more phases...]++</implementation-roadmap>++---++<test-strategy>+<instruction>+Define how testing will be integrated throughout development (TDD approach).++Specify:+1. Test pyramid ratios (unit vs integration vs e2e)+2. Coverage requirements+3. Critical test scenarios+4. Test generation guidelines for Surgical Test Generator++This section guides the AI when generating tests during the RED phase of TDD.++<example type="good">+Critical Test Scenarios for Data Validation module:+ - Happy path: Valid data passes all checks+ - Edge cases: Empty strings, null values, boundary numbers+ - Error cases: Invalid types, missing required fields+ - Integration: Validator works with ingestion pipeline+</example>+</instruction>++## Test Pyramid++```+ /\+ /E2E\ ← [X]% (End-to-end, slow, comprehensive)+ /------\+ /Integration\ ← [Y]% (Module interactions)+ /------------\+ / Unit Tests \ ← [Z]% (Fast, isolated, deterministic)+ /----------------\+```++## Coverage Requirements+- Line coverage: [X]% minimum+- Branch coverage: [X]% minimum+- Function coverage: [X]% minimum+- Statement coverage: [X]% minimum++## Critical Test Scenarios++### [Module/Feature Name]+**Happy path**:+- [Scenario description]+- Expected: [What should happen]++**Edge cases**:+- [Scenario description]+- Expected: [What should happen]++**Error cases**:+- [Scenario description]+- Expected: [How system handles failure]++**Integration points**:+- [What interactions to test]+- Expected: [End-to-end behavior]++## Test Generation Guidelines+[Specific instructions for Surgical Test Generator about what to focus on, what patterns to follow, project-specific test conventions]++</test-strategy>++---++<architecture>+<instruction>+Describe technical architecture, data models, and key design decisions.++Keep this section AFTER functional/structural decomposition - implementation details come after understanding structure.+</instruction>++## System Components+[Major architectural pieces and their responsibilities]++## Data Models+[Core data structures, schemas, database design]++## Technology Stack+[Languages, frameworks, key libraries]++**Decision: [Technology/Pattern]**+- **Rationale**: [Why chosen]+- **Trade-offs**: [What we're giving up]+- **Alternatives considered**: [What else we looked at]++</architecture>++---++<risks>+<instruction>+Identify risks that could derail development and how to mitigate them.++Categories:+- Technical risks (complexity, unknowns)+- Dependency risks (blocking issues)+- Scope risks (creep, underestimation)+</instruction>++## Technical Risks+**Risk**: [Description]+- **Impact**: [High/Medium/Low - effect on project]+- **Likelihood**: [High/Medium/Low]+- **Mitigation**: [How to address]+- **Fallback**: [Plan B if mitigation fails]++## Dependency Risks+[External dependencies, blocking issues]++## Scope Risks+[Scope creep, underestimation, unclear requirements]++</risks>++---++<appendix>+## References+[Papers, documentation, similar systems]++## Glossary+[Domain-specific terms]++## Open Questions+[Things to resolve during development]+</appendix>++---++<task-master-integration>+# How Task Master Uses This PRD++When you run `task-master parse-prd <file>.txt`, the parser:++1. **Extracts capabilities** → Main tasks+ - Each `### Capability:` becomes a top-level task++2. **Extracts features** → Subtasks+ - Each `#### Feature:` becomes a subtask under its capability++3. **Parses dependencies** → Task dependencies+ - `Depends on: [X, Y]` sets task.dependencies = ["X", "Y"]++4. **Orders by phases** → Task priorities+ - Phase 0 tasks = highest priority+ - Phase N tasks = lower priority, properly sequenced++5. **Uses test strategy** → Test generation context+ - Feeds test scenarios to Surgical Test Generator during implementation++**Result**: A dependency-aware task graph that can be executed in topological order.++## Why RPG Structure Matters++Traditional flat PRDs lead to:+- ❌ Unclear task dependencies+- ❌ Arbitrary task ordering+- ❌ Circular dependencies discovered late+- ❌ Poorly scoped tasks++RPG-structured PRDs provide:+- ✅ Explicit dependency chains+- ✅ Topological execution order+- ✅ Clear module boundaries+- ✅ Validated task graph before implementation++## Tips for Best Results++1. **Spend time on dependency graph** - This is the most valuable section for Task Master+2. **Keep features atomic** - Each feature should be independently testable+3. **Progressive refinement** - Start broad, use `task-master expand` to break down complex tasks+4. **Use research mode** - `task-master parse-prd --research` leverages AI for better task generation+</task-master-integration>diff --git a/apps/docs/capabilities/rpg-method.mdx b/apps/docs/capabilities/rpg-method.mdxnew file mode 100644index 00000000..360c5745--- /dev/null+++ b/apps/docs/capabilities/rpg-method.mdx@@ -0,0 +1,326 @@+---+title: RPG Method for PRD Creation+sidebarTitle: "RPG Method"+---++# Repository Planning Graph (RPG) Method++The RPG (Repository Planning Graph) method is an advanced approach to creating Product Requirements Documents that generate highly-structured, dependency-aware task graphs. It's based on Microsoft Research's methodology for scalable codebase generation.++## When to Use RPG++Use the RPG template (`example_prd_rpg.txt`) for:++- **Complex multi-module systems** with intricate dependencies+- **Large-scale codebases** being built from scratch+- **Projects requiring explicit architecture** and clear module boundaries+- **Teams needing dependency visibility** for parallel development++For simpler features or smaller projects, the standard `example_prd.txt` template may be more appropriate.++---++## Core Principles++### 1. Dual-Semantics++Separate **functional** thinking (WHAT) from **structural** thinking (HOW):++```+Functional: "Data Validation capability with schema checking and rule enforcement"+ ↓+Structural: "src/validation/ with schema-validator.js and rule-validator.js"+```++This separation prevents mixing concerns and creates clearer module boundaries.++### 2. Explicit Dependencies++Never assume dependencies - always state them explicitly:++```+Good:+ Module: data-ingestion+ Depends on: [schema-validator, config-manager]++Bad:+ Module: data-ingestion+ (Assumes schema-validator exists somewhere)+```++Explicit dependencies enable:+- Topological ordering of implementation+- Parallel development of independent modules+- Clear build/test order+- Early detection of circular dependencies++### 3. Topological Order++Build foundation layers before higher layers:++```+Phase 0 (Foundation): error-handling, base-types, config+ ↓+Phase 1 (Data): validation, ingestion (depend on Phase 0)+ ↓+Phase 2 (Core): algorithms, pipelines (depend on Phase 1)+ ↓+Phase 3 (API): routes, handlers (depend on Phase 2)+```++Task Master automatically orders tasks based on this dependency chain.++### 4. Progressive Refinement++Start broad, refine iteratively:++1. High-level capabilities → Main tasks+2. Features per capability → Subtasks+3. Implementation details → Expanded subtasks++---++## Template Structure++The RPG template guides you through 7 key sections:++### 1. Overview+- Problem statement+- Target users+- Success metrics++### 2. Functional Decomposition (WHAT)+- High-level capability domains+- Features per capability+- Inputs/outputs/behavior for each feature++**Example:**+```+Capability: Data Management+ Feature: Schema validation+ Description: Validate JSON against defined schemas+ Inputs: JSON object, schema definition+ Outputs: Validation result + error details+ Behavior: Iterate fields, check types, enforce constraints+```++### 3. Structural Decomposition (HOW)+- Repository folder structure+- Module-to-capability mapping+- File organization+- Public interfaces/exports++**Example:**+```+Capability: Data Management+ → Maps to: src/data/+ ├── schema-validator.js (Schema validation feature)+ ├── rule-validator.js (Rule validation feature)+ └── index.js (Exports)+```++### 4. Dependency Graph (CRITICAL)+- Foundation layer (no dependencies)+- Each subsequent layer's dependencies+- Explicit "depends on" declarations++**Example:**+```+Foundation Layer (Phase 0):+ - error-handling: No dependencies+ - base-types: No dependencies++Data Layer (Phase 1):+ - schema-validator: Depends on [base-types, error-handling]+ - data-ingestion: Depends on [schema-validator]+```++### 5. Implementation Roadmap+- Phases with entry/exit criteria+- Tasks grouped by phase+- Clear deliverables per phase++### 6. Test Strategy+- Test pyramid ratios+- Coverage requirements+- Critical test scenarios per module+- Guidelines for test generation++### 7. Architecture & Risks+- Technical architecture+- Data models+- Technology decisions+- Risk mitigation strategies++---++## Using RPG with Task Master++### Step 1: Create PRD with RPG Template++Use a code-context-aware tool to fill out the template:++```bash+# In Claude Code, Cursor, or similar+"Create a PRD using @.taskmaster/templates/example_prd_rpg.txt for [your project]"+```++**Why code context matters:** The AI needs to understand your existing codebase to make informed decisions about:+- Module boundaries+- Dependency relationships+- Integration points+- Naming conventions++**Recommended tools:**+- Claude Code (claude-code CLI)+- Cursor/Windsurf+- Gemini CLI (large contexts)+- Codex/Grok CLI++### Step 2: Parse PRD into Tasks++```bash+task-master parse-prd .taskmaster/docs/your-prd.txt --research+```++Task Master will:+1. Extract capabilities → Main tasks+2. Extract features → Subtasks+3. Parse dependencies → Task dependencies+4. Order by phases → Task priorities++**Result:** A dependency-aware task graph ready for topological execution.++### Step 3: Analyze Complexity++```bash+task-master analyze-complexity --research+```++Review the complexity report to identify tasks that need expansion.++### Step 4: Expand Tasks++```bash+task-master expand --all --research+```++Break down complex tasks into manageable subtasks while preserving dependency chains.++---++## RPG Benefits++### For Solo Developers+- Clear roadmap for implementing complex features+- Prevents architectural mistakes early+- Explicit dependency tracking avoids integration issues+- Enables resuming work after interruptions++### For Teams+- Parallel development of independent modules+- Clear contracts between modules (explicit dependencies)+- Reduced merge conflicts (proper module boundaries)+- Onboarding aid (architectural overview in PRD)++### For AI Agents+- Structured context for code generation+- Clear scope boundaries per task+- Dependency awareness prevents incomplete implementations+- Test strategy guidance for TDD workflows++---++## RPG vs Standard Template++| Aspect | Standard Template | RPG Template |+|--------|------------------|--------------|+| **Best for** | Simple features | Complex systems |+| **Dependency handling** | Implicit | Explicit graph |+| **Structure guidance** | Minimal | Step-by-step |+| **Examples** | Few | Inline good/bad examples |+| **Module boundaries** | Vague | Precise mapping |+| **Task ordering** | Manual | Automatic (topological) |+| **Learning curve** | Low | Medium |+| **Resulting task quality** | Good | Excellent |++---++## Tips for Best Results++### 1. Spend Time on Dependencies+The dependency graph section is the most valuable. List all dependencies explicitly, even if they seem obvious.++### 2. Keep Features Atomic+Each feature should be independently testable. If a feature description is vague ("handle data"), break it into specific features.++### 3. Progressive Refinement+Don't try to get everything perfect on the first pass:+1. Fill out high-level sections+2. Review and refine+3. Add detail where needed+4. Let `task-master expand` break down complex tasks further++### 4. Use Research Mode+```bash+task-master parse-prd --research+```+The `--research` flag leverages AI to enhance task generation with domain knowledge.++### 5. Validate Early+```bash+task-master validate-dependencies+```+Check for circular dependencies or orphaned modules before starting implementation.++---++## Common Pitfalls++### ❌ Mixing Functional and Structural+```+Bad: "Capability: validation.js"+Good: "Capability: Data Validation" → maps to "src/validation/"+```++### ❌ Vague Module Boundaries+```+Bad: "Module: utils"+Good: "Module: string-utilities" with clear exports+```++### ❌ Implicit Dependencies+```+Bad: "Module: API handlers (needs validation)"+Good: "Module: API handlers, Depends on: [validation, error-handling]"+```++### ❌ Skipping Test Strategy+Without test strategy, the AI won't know what to test during implementation.++---++## Example Workflow++1. **Discuss idea with AI**: Explain your project concept+2. **Reference RPG template**: Show AI the `example_prd_rpg.txt`+3. **Co-create PRD**: Work through each section with AI guidance+4. **Save to docs**: Place in `.taskmaster/docs/your-project.txt`+5. **Parse PRD**: `task-master parse-prd .taskmaster/docs/your-project.txt --research`+6. **Analyze**: `task-master analyze-complexity --research`+7. **Expand**: `task-master expand --all --research`+8. **Start work**: `task-master next`++---++## Further Reading++- [PRD Creation and Parsing Guide](/getting-started/quick-start/prd-quick)+- [Task Structure Documentation](/capabilities/task-structure)+- [Microsoft Research RPG Paper](https://arxiv.org/abs/2410.21376) (Original methodology)++---++<Tip>+The RPG template includes inline `<instruction>` and `<example>` blocks that teach the method as you use it. Read these sections carefully - they provide valuable guidance at each decision point.+</Tip>diff --git a/apps/docs/getting-started/quick-start/prd-quick.mdx b/apps/docs/getting-started/quick-start/prd-quick.mdxindex 5ffc202d..6b38aef3 100644--- a/apps/docs/getting-started/quick-start/prd-quick.mdx+++ b/apps/docs/getting-started/quick-start/prd-quick.mdx@@ -32,7 +32,11 @@ The more context you give the model, the better the breakdown and results.## Writing a PRD for Task Master-<Note>An example PRD can be found in .taskmaster/templates/example_prd.txt</Note>+<Note>+Two example PRD templates are available in `.taskmaster/templates/`:+- `example_prd.txt` - Simple template for straightforward projects+- `example_prd_rpg.txt` - Advanced RPG (Repository Planning Graph) template for complex projects with dependencies+</Note>You can co-write your PRD with an LLM model using the following workflow:@@ -43,6 +47,29 @@ You can co-write your PRD with an LLM model using the following workflow:This approach works great in Cursor, or anywhere you use a chat-based LLM.+### Choosing Between Templates++**Use `example_prd.txt` when:**+- Building straightforward features+- Working on smaller projects+- Dependencies are simple and obvious++**Use `example_prd_rpg.txt` when:**+- Building complex systems with multiple modules+- Need explicit dependency management+- Want structured guidance on architecture decisions+- Planning a large codebase from scratch++The RPG template teaches you to think about:+1. **Functional decomposition** (WHAT the system does)+2. **Structural decomposition** (HOW it's organized in code)+3. **Explicit dependencies** (WHAT depends on WHAT)+4. **Topological ordering** (build foundation first, then layers)++<Tip>+For complex projects, using the RPG template with a code-context-aware ai agent produces the best results because the AI can understand your existing codebase structure. [Learn more about the RPG method →](/capabilities/rpg-method)+</Tip>+---## Where to Save Your PRDdiff --git a/assets/example_prd_rpg.txt b/assets/example_prd_rpg.txtnew file mode 100644index 00000000..5ad908fd--- /dev/null+++ b/assets/example_prd_rpg.txt@@ -0,0 +1,511 @@+<rpg-method>+# Repository Planning Graph (RPG) Method - PRD Template++This template teaches you (AI or human) how to create structured, dependency-aware PRDs using the RPG methodology from Microsoft Research. The key insight: separate WHAT (functional) from HOW (structural), then connect them with explicit dependencies.++## Core Principles++1. **Dual-Semantics**: Think functional (capabilities) AND structural (code organization) separately, then map them+2. **Explicit Dependencies**: Never assume - always state what depends on what+3. **Topological Order**: Build foundation first, then layers on top+4. **Progressive Refinement**: Start broad, refine iteratively++## How to Use This Template++- Follow the instructions in each `<instruction>` block+- Look at `<example>` blocks to see good vs bad patterns+- Fill in the content sections with your project details+- The AI reading this will learn the RPG method by following along+- Task Master will parse the resulting PRD into dependency-aware tasks++## Recommended Tools for Creating PRDs++When using this template to **create** a PRD (not parse it), use **code-context-aware AI assistants** for best results:++**Why?** The AI needs to understand your existing codebase to make good architectural decisions about modules, dependencies, and integration points.++**Recommended tools:**+- **Claude Code** (claude-code CLI) - Best for structured reasoning and large contexts+- **Cursor/Windsurf** - IDE integration with full codebase context+- **Gemini CLI** (gemini-cli) - Massive context window for large codebases+- **Codex/Grok CLI** - Strong code generation with context awareness++**Note:** Once your PRD is created, `task-master parse-prd` works with any configured AI model - it just needs to read the PRD text itself, not your codebase.+</rpg-method>++---++<overview>+<instruction>+Start with the problem, not the solution. Be specific about:+- What pain point exists?+- Who experiences it?+- Why existing solutions don't work?+- What success looks like (measurable outcomes)?++Keep this section focused - don't jump into implementation details yet.+</instruction>++## Problem Statement+[Describe the core problem. Be concrete about user pain points.]++## Target Users+[Define personas, their workflows, and what they're trying to achieve.]++## Success Metrics+[Quantifiable outcomes. Examples: "80% task completion via autopilot", "< 5% manual intervention rate"]++</overview>++---++<functional-decomposition>+<instruction>+Now think about CAPABILITIES (what the system DOES), not code structure yet.++Step 1: Identify high-level capability domains+- Think: "What major things does this system do?"+- Examples: Data Management, Core Processing, Presentation Layer++Step 2: For each capability, enumerate specific features+- Use explore-exploit strategy:+ * Exploit: What features are REQUIRED for core value?+ * Explore: What features make this domain COMPLETE?++Step 3: For each feature, define:+- Description: What it does in one sentence+- Inputs: What data/context it needs+- Outputs: What it produces/returns+- Behavior: Key logic or transformations++<example type="good">+Capability: Data Validation+ Feature: Schema validation+ - Description: Validate JSON payloads against defined schemas+ - Inputs: JSON object, schema definition+ - Outputs: Validation result (pass/fail) + error details+ - Behavior: Iterate fields, check types, enforce constraints++ Feature: Business rule validation+ - Description: Apply domain-specific validation rules+ - Inputs: Validated data object, rule set+ - Outputs: Boolean + list of violated rules+ - Behavior: Execute rules sequentially, short-circuit on failure+</example>++<example type="bad">+Capability: validation.js+ (Problem: This is a FILE, not a CAPABILITY. Mixing structure into functional thinking.)++Capability: Validation+ Feature: Make sure data is good+ (Problem: Too vague. No inputs/outputs. Not actionable.)+</example>+</instruction>++## Capability Tree++### Capability: [Name]+[Brief description of what this capability domain covers]++#### Feature: [Name]+- **Description**: [One sentence]+- **Inputs**: [What it needs]+- **Outputs**: [What it produces]+- **Behavior**: [Key logic]++#### Feature: [Name]+- **Description**:+- **Inputs**:+- **Outputs**:+- **Behavior**:++### Capability: [Name]+...++</functional-decomposition>++---++<structural-decomposition>+<instruction>+NOW think about code organization. Map capabilities to actual file/folder structure.++Rules:+1. Each capability maps to a module (folder or file)+2. Features within a capability map to functions/classes+3. Use clear module boundaries - each module has ONE responsibility+4. Define what each module exports (public interface)++The goal: Create a clear mapping between "what it does" (functional) and "where it lives" (structural).++<example type="good">+Capability: Data Validation+ → Maps to: src/validation/+ ├── schema-validator.js (Schema validation feature)+ ├── rule-validator.js (Business rule validation feature)+ └── index.js (Public exports)++Exports:+ - validateSchema(data, schema)+ - validateRules(data, rules)+</example>++<example type="bad">+Capability: Data Validation+ → Maps to: src/utils.js+ (Problem: "utils" is not a clear module boundary. Where do I find validation logic?)++Capability: Data Validation+ → Maps to: src/validation/everything.js+ (Problem: One giant file. Features should map to separate files for maintainability.)+</example>+</instruction>++## Repository Structure++```+project-root/+├── src/+│ ├── [module-name]/ # Maps to: [Capability Name]+│ │ ├── [file].js # Maps to: [Feature Name]+│ │ └── index.js # Public exports+│ └── [module-name]/+├── tests/+└── docs/+```++## Module Definitions++### Module: [Name]+- **Maps to capability**: [Capability from functional decomposition]+- **Responsibility**: [Single clear purpose]+- **File structure**:+ ```+ module-name/+ ├── feature1.js+ ├── feature2.js+ └── index.js+ ```+- **Exports**:+ - `functionName()` - [what it does]+ - `ClassName` - [what it does]++</structural-decomposition>++---++<dependency-graph>+<instruction>+This is THE CRITICAL SECTION for Task Master parsing.++Define explicit dependencies between modules. This creates the topological order for task execution.++Rules:+1. List modules in dependency order (foundation first)+2. For each module, state what it depends on+3. Foundation modules should have NO dependencies+4. Every non-foundation module should depend on at least one other module+5. Think: "What must EXIST before I can build this module?"++<example type="good">+Foundation Layer (no dependencies):+ - error-handling: No dependencies+ - config-manager: No dependencies+ - base-types: No dependencies++Data Layer:+ - schema-validator: Depends on [base-types, error-handling]+ - data-ingestion: Depends on [schema-validator, config-manager]++Core Layer:+ - algorithm-engine: Depends on [base-types, error-handling]+ - pipeline-orchestrator: Depends on [algorithm-engine, data-ingestion]+</example>++<example type="bad">+- validation: Depends on API+- API: Depends on validation+(Problem: Circular dependency. This will cause build/runtime issues.)++- user-auth: Depends on everything+(Problem: Too many dependencies. Should be more focused.)+</example>+</instruction>++## Dependency Chain++### Foundation Layer (Phase 0)+No dependencies - these are built first.++- **[Module Name]**: [What it provides]+- **[Module Name]**: [What it provides]++### [Layer Name] (Phase 1)+- **[Module Name]**: Depends on [[module-from-phase-0], [module-from-phase-0]]+- **[Module Name]**: Depends on [[module-from-phase-0]]++### [Layer Name] (Phase 2)+- **[Module Name]**: Depends on [[module-from-phase-1], [module-from-foundation]]++[Continue building up layers...]++</dependency-graph>++---++<implementation-roadmap>+<instruction>+Turn the dependency graph into concrete development phases.++Each phase should:+1. Have clear entry criteria (what must exist before starting)+2. Contain tasks that can be parallelized (no inter-dependencies within phase)+3. Have clear exit criteria (how do we know phase is complete?)+4. Build toward something USABLE (not just infrastructure)++Phase ordering follows topological sort of dependency graph.++<example type="good">+Phase 0: Foundation+ Entry: Clean repository+ Tasks:+ - Implement error handling utilities+ - Create base type definitions+ - Setup configuration system+ Exit: Other modules can import foundation without errors++Phase 1: Data Layer+ Entry: Phase 0 complete+ Tasks:+ - Implement schema validator (uses: base types, error handling)+ - Build data ingestion pipeline (uses: validator, config)+ Exit: End-to-end data flow from input to validated output+</example>++<example type="bad">+Phase 1: Build Everything+ Tasks:+ - API+ - Database+ - UI+ - Tests+ (Problem: No clear focus. Too broad. Dependencies not considered.)+</example>+</instruction>++## Development Phases++### Phase 0: [Foundation Name]+**Goal**: [What foundational capability this establishes]++**Entry Criteria**: [What must be true before starting]++**Tasks**:+- [ ] [Task name] (depends on: [none or list])+ - Acceptance criteria: [How we know it's done]+ - Test strategy: [What tests prove it works]++- [ ] [Task name] (depends on: [none or list])++**Exit Criteria**: [Observable outcome that proves phase complete]++**Delivers**: [What can users/developers do after this phase?]++---++### Phase 1: [Layer Name]+**Goal**:++**Entry Criteria**: Phase 0 complete++**Tasks**:+- [ ] [Task name] (depends on: [[tasks-from-phase-0]])+- [ ] [Task name] (depends on: [[tasks-from-phase-0]])++**Exit Criteria**:++**Delivers**:++---++[Continue with more phases...]++</implementation-roadmap>++---++<test-strategy>+<instruction>+Define how testing will be integrated throughout development (TDD approach).++Specify:+1. Test pyramid ratios (unit vs integration vs e2e)+2. Coverage requirements+3. Critical test scenarios+4. Test generation guidelines for Surgical Test Generator++This section guides the AI when generating tests during the RED phase of TDD.++<example type="good">+Critical Test Scenarios for Data Validation module:+ - Happy path: Valid data passes all checks+ - Edge cases: Empty strings, null values, boundary numbers+ - Error cases: Invalid types, missing required fields+ - Integration: Validator works with ingestion pipeline+</example>+</instruction>++## Test Pyramid++```+ /\+ /E2E\ ← [X]% (End-to-end, slow, comprehensive)+ /------\+ /Integration\ ← [Y]% (Module interactions)+ /------------\+ / Unit Tests \ ← [Z]% (Fast, isolated, deterministic)+ /----------------\+```++## Coverage Requirements+- Line coverage: [X]% minimum+- Branch coverage: [X]% minimum+- Function coverage: [X]% minimum+- Statement coverage: [X]% minimum++## Critical Test Scenarios++### [Module/Feature Name]+**Happy path**:+- [Scenario description]+- Expected: [What should happen]++**Edge cases**:+- [Scenario description]+- Expected: [What should happen]++**Error cases**:+- [Scenario description]+- Expected: [How system handles failure]++**Integration points**:+- [What interactions to test]+- Expected: [End-to-end behavior]++## Test Generation Guidelines+[Specific instructions for Surgical Test Generator about what to focus on, what patterns to follow, project-specific test conventions]++</test-strategy>++---++<architecture>+<instruction>+Describe technical architecture, data models, and key design decisions.++Keep this section AFTER functional/structural decomposition - implementation details come after understanding structure.+</instruction>++## System Components+[Major architectural pieces and their responsibilities]++## Data Models+[Core data structures, schemas, database design]++## Technology Stack+[Languages, frameworks, key libraries]++**Decision: [Technology/Pattern]**+- **Rationale**: [Why chosen]+- **Trade-offs**: [What we're giving up]+- **Alternatives considered**: [What else we looked at]++</architecture>++---++<risks>+<instruction>+Identify risks that could derail development and how to mitigate them.++Categories:+- Technical risks (complexity, unknowns)+- Dependency risks (blocking issues)+- Scope risks (creep, underestimation)+</instruction>++## Technical Risks+**Risk**: [Description]+- **Impact**: [High/Medium/Low - effect on project]+- **Likelihood**: [High/Medium/Low]+- **Mitigation**: [How to address]+- **Fallback**: [Plan B if mitigation fails]++## Dependency Risks+[External dependencies, blocking issues]++## Scope Risks+[Scope creep, underestimation, unclear requirements]++</risks>++---++<appendix>+## References+[Papers, documentation, similar systems]++## Glossary+[Domain-specific terms]++## Open Questions+[Things to resolve during development]+</appendix>++---++<task-master-integration>+# How Task Master Uses This PRD++When you run `task-master parse-prd <file>.txt`, the parser:++1. **Extracts capabilities** → Main tasks+ - Each `### Capability:` becomes a top-level task++2. **Extracts features** → Subtasks+ - Each `#### Feature:` becomes a subtask under its capability++3. **Parses dependencies** → Task dependencies+ - `Depends on: [X, Y]` sets task.dependencies = ["X", "Y"]++4. **Orders by phases** → Task priorities+ - Phase 0 tasks = highest priority+ - Phase N tasks = lower priority, properly sequenced++5. **Uses test strategy** → Test generation context+ - Feeds test scenarios to Surgical Test Generator during implementation++**Result**: A dependency-aware task graph that can be executed in topological order.++## Why RPG Structure Matters++Traditional flat PRDs lead to:+- ❌ Unclear task dependencies+- ❌ Arbitrary task ordering+- ❌ Circular dependencies discovered late+- ❌ Poorly scoped tasks++RPG-structured PRDs provide:+- ✅ Explicit dependency chains+- ✅ Topological execution order+- ✅ Clear module boundaries+- ✅ Validated task graph before implementation++## Tips for Best Results++1. **Spend time on dependency graph** - This is the most valuable section for Task Master+2. **Keep features atomic** - Each feature should be independently testable+3. **Progressive refinement** - Start broad, use `task-master expand` to break down complex tasks+4. **Use research mode** - `task-master parse-prd --research` leverages AI for better task generation+</task-master-integration>diff --git a/scripts/init.js b/scripts/init.jsindex 79d2ecfe..1d048221 100755--- a/scripts/init.js+++ b/scripts/init.js@@ -628,6 +628,12 @@ function createProjectStructure(// Copy example_prd.txt to NEW locationcopyTemplateFile('example_prd.txt', path.join(targetDir, EXAMPLE_PRD_FILE));+ // Copy example_prd_rpg.txt to templates directory+ copyTemplateFile(+ 'example_prd_rpg.txt',+ path.join(targetDir, TASKMASTER_TEMPLATES_DIR, 'example_prd_rpg.txt')+ );+// Initialize git repository if git is availabletry {if (initGit === false) {@@ -856,10 +862,10 @@ function createProjectStructure()}\n${chalk.white(' ├─ ')}${chalk.dim('Models: Use `task-master models` commands')}\n${chalk.white(' └─ ')}${chalk.dim('Keys: Add provider API keys to .env (or inside the MCP config file i.e. .cursor/mcp.json)')}\n${chalk.white('2. ')}${chalk.yellow(- 'Discuss your idea with AI and ask for a PRD using example_prd.txt, and save it to scripts/PRD.txt'- )}\n${chalk.white('3. ')}${chalk.yellow(+ 'Discuss your idea with AI and ask for a PRD, and save it to .taskmaster/docs/prd.txt'+ )}\n${chalk.white(' ├─ ')}${chalk.dim('Simple projects: Use ')}${chalk.cyan('example_prd.txt')}${chalk.dim(' template')}\n${chalk.white(' └─ ')}${chalk.dim('Complex systems: Use ')}${chalk.cyan('example_prd_rpg.txt')}${chalk.dim(' template (for dependency-aware task graphs)')}\n${chalk.white('3. ')}${chalk.yellow('Ask Cursor Agent (or run CLI) to parse your PRD and generate initial tasks:'- )}\n${chalk.white(' └─ ')}${chalk.dim('MCP Tool: ')}${chalk.cyan('parse_prd')}${chalk.dim(' | CLI: ')}${chalk.cyan('task-master parse-prd scripts/prd.txt')}\n${chalk.white('4. ')}${chalk.yellow(+ )}\n${chalk.white(' └─ ')}${chalk.dim('MCP Tool: ')}${chalk.cyan('parse_prd')}${chalk.dim(' | CLI: ')}${chalk.cyan('task-master parse-prd .taskmaster/docs/prd.txt')}\n${chalk.white('4. ')}${chalk.yellow('Ask Cursor to analyze the complexity of the tasks in your PRD using research')}\n${chalk.white(' └─ ')}${chalk.dim('MCP Tool: ')}${chalk.cyan('analyze_project_complexity')}${chalk.dim(' | CLI: ')}${chalk.cyan('task-master analyze-complexity')}\n${chalk.white('5. ')}${chalk.yellow('Ask Cursor to expand all of your tasks using the complexity analysis'