Roadmap Skill

Plan project execution by creating milestones and organizing PRDs into an executable queue.

Workspace Mode Note

When running in workspace mode, all paths are relative to .aha-loop/ directory:

• Vision analysis: .aha-loop/project.vision-analysis.md
• Architecture: .aha-loop/project.architecture.md
• Roadmap: .aha-loop/project.roadmap.json
• PRD files: .aha-loop/tasks/

The orchestrator will provide the actual paths in the prompt context.

The Job

1. Read project.vision-analysis.md and project.architecture.md
2. Decompose project into milestones
3. Break each milestone into PRDs
4. Order PRDs by dependencies
5. Output project.roadmap.json
6. Generate initial PRD files in tasks/

Milestone Strategy

Standard Milestone Structure

Milestone Sizing

Each milestone should:

• Be completable in a reasonable timeframe
• Have 3-7 PRDs (avoid too many or too few)
• Deliver tangible, testable value
• Build on previous milestones

PRD Decomposition

From Features to PRDs

For each milestone, break down features into PRDs:

Milestone: M1 - MVP
├── PRD-001: Project Scaffolding
├── PRD-002: Database Schema
├── PRD-003: Core Data Models
├── PRD-004: Basic API Endpoints
└── PRD-005: Minimal UI

PRD Sizing

Each PRD should:

• Take 1-5 Aha Loop iterations (5-25 stories)
• Focus on one coherent feature area
• Be independently testable
• Not depend on unfinished PRDs

PRD Ordering

Order PRDs by dependencies:

1. Infrastructure first - Project setup, database, auth
2. Backend before frontend - APIs before UI that uses them
3. Core before optional - Must-have before nice-to-have
4. Data before presentation - Models before views

Roadmap JSON Structure

{
  "version": 1,
  "projectName": "[From vision]",
  "status": "in_progress",
  "currentMilestone": "M1",
  "currentPRD": "PRD-002",
  "createdAt": "[timestamp]",
  "updatedAt": "[timestamp]",
  "milestones": [
    {
      "id": "M0",
      "title": "Foundation",
      "description": "Project setup and development environment",
      "status": "completed",
      "completedAt": "[timestamp]",
      "prds": [
        {
          "id": "PRD-001",
          "title": "Project Scaffolding",
          "description": "Initialize project structure, dependencies, and tooling",
          "status": "completed",
          "prdFile": "tasks/prd-scaffolding.md",
          "stories": 5,
          "completedAt": "[timestamp]"
        }
      ]
    },
    {
      "id": "M1",
      "title": "MVP",
      "description": "Minimum viable product with core functionality",
      "status": "in_progress",
      "prds": [
        {
          "id": "PRD-002",
          "title": "Database Schema",
          "description": "Design and implement database schema",
          "status": "in_progress",
          "prdFile": "tasks/prd-database.md",
          "stories": 8,
          "dependsOn": ["PRD-001"]
        },
        {
          "id": "PRD-003",
          "title": "Core API",
          "description": "Implement core API endpoints",
          "status": "pending",
          "prdFile": "tasks/prd-core-api.md",
          "stories": 12,
          "dependsOn": ["PRD-002"]
        }
      ]
    },
    {
      "id": "M2",
      "title": "Essential Features",
      "description": "Complete essential features for basic use",
      "status": "pending",
      "prds": []
    }
  ],
  "changelog": [
    {
      "timestamp": "[timestamp]",
      "action": "created",
      "description": "Initial roadmap created from vision and architecture"
    }
  ]
}

Roadmap Creation Process

Step 1: Analyze Requirements

From vision analysis, categorize features:

## Feature Categories

### M1: MVP (Must ship)
- [Feature 1]
- [Feature 2]

### M2: Essential (Should ship)
- [Feature 3]
- [Feature 4]

### M3: Enhanced (Nice to ship)
- [Feature 5]

Step 2: Create M0 Foundation

Every project starts with M0:

## M0: Foundation PRDs

### PRD-001: Project Scaffolding
- Initialize project with chosen tech stack
- Set up directory structure
- Configure linting and formatting
- Set up basic CI (if applicable)
- Create initial README

### PRD-002: Development Environment
- Database setup (if applicable)
- Environment configuration
- Development scripts
- Basic testing infrastructure

Step 3: Decompose Milestones into PRDs

For each milestone after M0:

1. List all features for this milestone
2. Group related features
3. Order by dependencies
4. Create PRD for each group
5. Estimate stories per PRD

Step 4: Generate PRD Files

For each PRD, create a stub file in tasks/:

# PRD: [Title]

**ID:** PRD-XXX
**Milestone:** M[N]
**Status:** Pending

## Overview

[Brief description from roadmap]

## Context

[How this relates to previous PRDs and the overall project]

## Goals

- [Goal 1]
- [Goal 2]

## User Stories

[To be generated when this PRD becomes active]

## Dependencies

- PRD-XXX: [What it depends on]

## Acceptance Criteria

- [ ] [High-level criterion]
- [ ] [Another criterion]

---

*This PRD will be fully expanded when it becomes the active PRD.*

Dynamic Roadmap Updates

When to Update Roadmap

The roadmap should be updated when:

1. PRD Completed - Mark as complete, update timestamps
2. New Requirement Discovered - Add new PRD
3. Scope Change - Modify or remove PRDs
4. Better Approach Found - Restructure PRDs
5. Milestone Complete - Update status, move to next

Update Process

{
  "changelog": [
    {
      "timestamp": "2026-01-29T12:00:00Z",
      "action": "prd_completed",
      "prdId": "PRD-002",
      "description": "Database schema implemented"
    },
    {
      "timestamp": "2026-01-29T14:00:00Z",
      "action": "prd_added",
      "prdId": "PRD-007",
      "description": "Added caching layer PRD based on performance research"
    }
  ]
}

Automatic Triggers

The orchestrator should trigger roadmap review:

• After each PRD completion
• After each milestone completion
• When significant learnings are recorded
• When errors repeatedly occur

Integration with Orchestrator

Orchestrator Reads

# Get current PRD
jq '.currentPRD' project.roadmap.json

# Get PRD file path
jq -r '.milestones[].prds[] | select(.id == "PRD-002") | .prdFile' project.roadmap.json

Orchestrator Updates

After PRD completion:

# Update PRD status
jq '.milestones[].prds[] |= if .id == "PRD-002" then .status = "completed" else . end' project.roadmap.json

PRD Queue Management

Getting Next PRD

# Pseudocode for finding next PRD
def get_next_prd(roadmap):
    for milestone in roadmap.milestones:
        if milestone.status == "completed":
            continue
        for prd in milestone.prds:
            if prd.status == "pending":
                if all_dependencies_complete(prd):
                    return prd
    return None  # All complete or blocked

Handling Blocked PRDs

If a PRD's dependencies aren't met:

1. Skip to next available PRD
2. If no PRDs available, report blocking issue
3. Consider if dependencies need reprioritization

Example Roadmap

Project: Personal Finance Tracker (from vision example)

{
  "version": 1,
  "projectName": "Finance Tracker",
  "status": "in_progress",
  "currentMilestone": "M0",
  "currentPRD": "PRD-001",
  "milestones": [
    {
      "id": "M0",
      "title": "Foundation",
      "status": "in_progress",
      "prds": [
        {
          "id": "PRD-001",
          "title": "SvelteKit Project Setup",
          "description": "Initialize SvelteKit project with TypeScript, Tailwind, PWA support",
          "status": "in_progress",
          "prdFile": "tasks/prd-project-setup.md",
          "stories": 6
        }
      ]
    },
    {
      "id": "M1",
      "title": "MVP - Core Expense Tracking",
      "status": "pending",
      "prds": [
        {
          "id": "PRD-002",
          "title": "Data Layer",
          "description": "Implement IndexedDB with Dexie for expense storage",
          "status": "pending",
          "prdFile": "tasks/prd-data-layer.md",
          "stories": 8,
          "dependsOn": ["PRD-001"]
        },
        {
          "id": "PRD-003",
          "title": "Quick Expense Entry",
          "description": "Fast expense input form (< 5 seconds goal)",
          "status": "pending",
          "prdFile": "tasks/prd-expense-entry.md",
          "stories": 10,
          "dependsOn": ["PRD-002"]
        },
        {
          "id": "PRD-004",
          "title": "Expense List View",
          "description": "View and manage recorded expenses",
          "status": "pending",
          "prdFile": "tasks/prd-expense-list.md",
          "stories": 8,
          "dependsOn": ["PRD-002"]
        }
      ]
    },
    {
      "id": "M2",
      "title": "Reports & PWA",
      "status": "pending",
      "prds": [
        {
          "id": "PRD-005",
          "title": "Monthly Reports",
          "description": "Auto-generated monthly expense reports",
          "status": "pending",
          "prdFile": "tasks/prd-reports.md",
          "stories": 10,
          "dependsOn": ["PRD-003", "PRD-004"]
        },
        {
          "id": "PRD-006",
          "title": "PWA Offline Support",
          "description": "Full offline capability with service worker",
          "status": "pending",
          "prdFile": "tasks/prd-pwa.md",
          "stories": 8,
          "dependsOn": ["PRD-002"]
        }
      ]
    }
  ]
}

Checklist

Before completing roadmap:

• All milestones defined with clear goals
• PRDs created for at least M0 and M1
• Dependencies between PRDs mapped
• PRD stub files created in tasks/
• Roadmap JSON validates
• Current milestone and PRD set correctly
• Changelog initialized
• Saved to project.roadmap.json