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"

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:

# 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

task-master parse-prd .taskmaster/docs/your-prd.md --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

task-master analyze-complexity --research

Review the complexity report to identify tasks that need expansion.

Step 4: Expand Tasks

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

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

task-master parse-prd --research

The --research flag leverages AI to enhance task generation with domain knowledge.

5. Validate Early

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.md
3. Co-create PRD: Work through each section with AI guidance
4. Save to docs: Place in .taskmaster/docs/your-project.md (use .md for better editor support)
5. Parse PRD: task-master parse-prd .taskmaster/docs/your-project.md --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
• Task Structure Documentation
• Microsoft Research RPG Paper (Original methodology)