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)

TaskGraph automatically orders tasks based on this dependency chain. 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 TaskGraph

Step 1: Create PRD with RPG Template

Use a code-context-aware tool to fill out the template:

# In Claude Code
"Create a PRD using @.taskgraph/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)

Step 2: Parse PRD into Tasks

taskgraph parse-prd .taskgraph/docs/your-prd.md --research

TaskGraph will:

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

taskgraph analyze-complexity --research

Review the complexity report to identify tasks that need expansion.

Step 4: Expand Tasks

taskgraph 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. Don’t try to get everything perfect on the first pass:

Fill out high-level sections
Review and refine
Add detail where needed
Let taskgraph expand break down complex tasks further

4. Use Research Mode

taskgraph parse-prd --research

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

5. Validate Early

taskgraph 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

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 .taskgraph/docs/your-project.md (use .md for better editor support)
Parse PRD: taskgraph parse-prd .taskgraph/docs/your-project.md --research
Analyze: taskgraph analyze-complexity --research
Expand: taskgraph expand --all --research
Start work: taskgraph next

​Repository Planning Graph (RPG) Method

​When to Use RPG

​Core Principles

​1. Dual-Semantics

​2. Explicit Dependencies

​3. Topological Order

​4. Progressive Refinement

​Template Structure

​1. Overview

​2. Functional Decomposition (WHAT)

​3. Structural Decomposition (HOW)

​4. Dependency Graph (CRITICAL)

​5. Implementation Roadmap

​6. Test Strategy

​7. Architecture & Risks

​Using RPG with TaskGraph

​Step 1: Create PRD with RPG Template

​Step 2: Parse PRD into Tasks

​Step 3: Analyze Complexity

​Step 4: Expand Tasks

​RPG Benefits

​For Solo Developers

​For Teams

​For AI Agents

​RPG vs Standard Template

​Tips for Best Results

​1. Spend Time on Dependencies

​2. Keep Features Atomic

​3. Progressive Refinement

​4. Use Research Mode

​5. Validate Early

​Common Pitfalls

​❌ Mixing Functional and Structural

​❌ Vague Module Boundaries

​❌ Implicit Dependencies

​❌ Skipping Test Strategy

​Example Workflow

​Further Reading

Repository Planning Graph (RPG) Method

When to Use RPG

Core Principles

1. Dual-Semantics

2. Explicit Dependencies

3. Topological Order

4. Progressive Refinement

Template Structure

1. Overview

2. Functional Decomposition (WHAT)

3. Structural Decomposition (HOW)

4. Dependency Graph (CRITICAL)

5. Implementation Roadmap

6. Test Strategy

7. Architecture & Risks

Using RPG with TaskGraph

Step 1: Create PRD with RPG Template

Step 2: Parse PRD into Tasks

Step 3: Analyze Complexity

Step 4: Expand Tasks

RPG Benefits

For Solo Developers

For Teams

For AI Agents

RPG vs Standard Template

Tips for Best Results

1. Spend Time on Dependencies

2. Keep Features Atomic

3. Progressive Refinement

4. Use Research Mode

5. Validate Early

Common Pitfalls

❌ Mixing Functional and Structural

❌ Vague Module Boundaries

❌ Implicit Dependencies

❌ Skipping Test Strategy

Example Workflow

Further Reading