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.md) 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.md 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"
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)
- 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)
4. Progressive Refinement
Start broad, refine iteratively:
- High-level capabilities → Main tasks
- Features per capability → Subtasks
- 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:
# In Claude Code, Cursor, or similar
"Create a PRD using @.taskmaster/templates/example_prd_rpg.txt for [your project]"
- 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
task-master parse-prd .taskmaster/docs/your-prd.md --research
- Extract capabilities → Main tasks
- Extract features → Subtasks
- Parse dependencies → Task dependencies
- Order by phases → Task priorities
Result: A dependency-aware task graph ready for topological execution.
Step 3: Analyze Complexity
task-master analyze-complexity --research
Step 4: Expand Tasks
task-master expand --all --research
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:
- Fill out high-level sections
- Review and refine
- Add detail where needed
- Let
task-master expand break down complex tasks further
4. Use Research Mode
task-master parse-prd --research
--research flag leverages AI to enhance task generation with domain knowledge.
5. Validate Early
task-master validate-dependencies
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
- Discuss idea with AI: Explain your project concept
- Reference RPG template: Show AI the
example_prd_rpg.md
- Co-create PRD: Work through each section with AI guidance
- Save to docs: Place in
.taskmaster/docs/your-project.md (use .md for better editor support)
- Parse PRD:
task-master parse-prd .taskmaster/docs/your-project.md --research
- Analyze:
task-master analyze-complexity --research
- Expand:
task-master expand --all --research
- Start work:
task-master next
Further Reading
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.
