---
description: Create a plan doc and roadmap doc for implementing updates
---

# Roadmap Command

Create a plan doc and concise roadmap doc to implement the requested updates. Save them under `ai/roadmaps/`, and prefix the file names with the date (e.g., `01.16.feature-name-plan.md` and `01.16.feature-name-roadmap.md`).

## Phase 1: Planning

1. **Understand the request** - Clarify requirements with the user if needed
2. **Research the codebase** - Explore relevant files to understand current state and patterns
3. **Create the plan doc** - Document the approach, rationale, and design decisions
4. **Create the roadmap doc** - List specific implementation tasks with checkboxes

Both documents must:
- Reference each other
- Include this note at the top: *"Clean Code Project: Avoid cruft, over-engineering, and backward-compatibility features or comments."*

## Phase 2: Expert Review

After creating the plan and roadmap, launch a **review sub-agent** to validate the approach before implementation begins.

### Review Sub-Agent Instructions

Launch a sub-agent with the Task tool using this prompt structure:

You are a senior engineer reviewing a proposed implementation plan. Your job is to catch issues BEFORE implementation begins.

## Context
- Plan document: [path to plan]
- Roadmap document: [path to roadmap]
- This is a clean-code project with no backward compatibility requirements

## Your Review Tasks

1. **Read the plan and roadmap thoroughly**

2. **Examine the codebase for alignment:**
   - Read files that will be modified (listed in the roadmap)
   - Check adjacent/related files that might be affected
   - Look for existing patterns the plan should follow
   - Find similar implementations that could be reused

3. **Check for these specific issues:**

   **Alignment Issues** - Does the plan match reality?
   - Files referenced actually exist?
   - Current code state matches assumptions?
   - Dependencies/imports are accurate?

   **Missing Considerations**
   - Edge cases not accounted for?
   - Error handling gaps?
   - Test coverage plans adequate?
   - Documentation updates needed?

   **Over-Engineering Concerns**
   - Features beyond what was requested?
   - Unnecessary abstractions?
   - Premature optimization?
   - Configurable when it should be simple?

   **Cruft/Compatibility Risks**
   - Backward compatibility code that isn't needed?
   - Legacy patterns being preserved unnecessarily?
   - Dead code being left in place?
   - Comments explaining removed code?

   **Missed Opportunities**
   - Existing utilities that should be reused?
   - Patterns elsewhere in codebase that should be followed?
   - Simpler approaches available?

4. **Produce a structured review**

### Processing the Review

After the sub-agent returns its review:

**Auto-fix (do without asking):**
- Factual errors (wrong file paths, incorrect assumptions about current state)
- Missing files from scope that are clearly needed
- Adding obviously missing error handling or edge cases
- Removing cruft/compatibility code the reviewer identified
- HIGH confidence issues with clear fixes

**Ask user (use AskUserQuestion):**
- Design approach changes
- Adding or removing scope items
- Architectural disagreements
- MEDIUM/LOW confidence suggestions where tradeoffs exist
- Anything under "Questions for User"

**Apply fixes:**
1. Update the plan and/or roadmap documents with corrections
2. Note what was changed and why (brief comment at bottom of doc)
3. If significant changes were made, consider a quick re-review

### Completion

Once the review is processed and any fixes applied:
1. Inform the user the plan and roadmap are ready
2. Summarize any changes made based on the review
3. List any open questions that need user input
4. Provide the paths to both documents
                                

---
description: Implement a roadmap using sub-agents with progress tracking, PR review, fix cycles, and completion archival
---

# Implement Roadmap Command

You are the **orchestrating agent** responsible for implementing a roadmap document. You coordinate sub-agents to do the implementation work, track progress, and ensure quality.

## Phase 1: Preparation

1. **Read the roadmap** specified by the user (or ask which roadmap to implement)
2. **Read the related plan document** if one exists (roadmaps usually reference their plan for context)
3. **Check dependencies** - if the roadmap depends on another roadmap, verify that dependency is complete first (check that its items are marked `[x]`)
4. **Read `CLAUDE.md`** and relevant project docs to understand conventions
5. **Create a mental model** of the work: identify independent vs dependent tasks, estimate parallelization opportunities

## Phase 2: Implementation with Sub-Agents

Use the Task tool to delegate implementation work. You are the orchestrator - sub-agents do the coding.

### Delegation Strategy

1. **Group related tasks** from the roadmap into logical work packages
2. **Launch sub-agents in parallel** for independent work packages
3. **Run sequentially** when tasks depend on outputs from previous work
4. **Batch appropriately** - not too granular (overhead) or too broad (loses parallelism)

### Sub-Agent Instructions

When launching a sub-agent, provide:
- The specific roadmap tasks to implement (copy the relevant section)
- Context from the plan document explaining the *why* behind decisions
- Clear boundaries: what files to create/modify, what NOT to touch
- Instruction to report back: what was done, any deviations, any blockers

**Important:** Sub-agents implement and report back. They do NOT update the roadmap checkboxes.

### Progress Tracking (Your Responsibility)

As the orchestrator, YOU manage the roadmap document:
- When a sub-agent reports successful completion, **you check off the items** (`- [ ]` to `- [x]`)
- If a task cannot be completed as specified, **you add a note** in the roadmap explaining the deviation
- This prevents race conditions and ensures accurate tracking

### Handling Deviations

Reality doesn't always match the plan. When sub-agents encounter issues:
- **Minor adjustments** (implementation details) - proceed and document
- **Significant deviations** (different approach, missing prerequisite) - pause, assess, document in roadmap
- **Blockers** (can't proceed) - stop that work stream, note in roadmap, continue other tasks

The goal is **faithful implementation with pragmatic flexibility**. Document deviations, don't hide them.

## Phase 2.5: Targeted Verification (High-Risk Work)

For high-risk implementations, launch a **verification sub-agent** after the implementation sub-agent completes. This catches issues early before they compound.

### When to Verify

Launch a verification sub-agent for:
- **Security-sensitive code** (authentication, authorization, crypto, input validation)
- **Complex business logic** or algorithms
- **External API integrations** (hallucinated APIs are common)
- **Database migrations** or schema changes
- **Core infrastructure changes** that many other components depend on

Skip verification for:
- Simple/mechanical changes (renaming, moving files)
- Test file additions (tests themselves are verification)
- Documentation updates
- Configuration changes

### Verification Sub-Agent Instructions

Provide explicit error-seeking criteria:

Verify the implementation of [task description]. Check for:
- Hallucinated API calls or non-existent methods
- Missing error handling and edge cases
- Security vulnerabilities (injection, XSS, auth bypass)
- Logic that doesn't match the stated requirements
- Missing or inadequate tests for the new code

Report: what looks correct, what issues you found, severity of each issue.

**Important:** Do NOT tell the verifier to "be skeptical because this was AI-generated" - research shows this doesn't improve review quality. Instead, give specific criteria to check.

### Handling Verification Results

- **No issues found**: Proceed, check off roadmap items
- **Minor issues found**: Launch fix sub-agent, then proceed
- **Significant issues found**: Re-implement with clearer instructions, then re-verify

## Phase 3: Verification

After all implementation is complete:

1. **Run the build**: `npm run build`
2. **Run all tests**: `npm test`
3. **Fix any failures** before proceeding to review
4. **Verify all roadmap items** are checked off or have documented exceptions

## Phase 4: PR Review and Remediation

Once implementation is complete and tests pass, **do a thorough PR review of everything that was implemented to make sure we got it right**.

### Review Focus

- Does the implementation match what the roadmap specified?
- Are there bugs, missing edge cases, or logic errors?
- Is the code quality acceptable (no cruft, no over-engineering)?
- Are tests adequate for the new functionality?

### Fix vs Escalate

**Fix directly** (minor issues):
- Typos, formatting, lint issues
- Missing error handling for obvious edge cases
- Small bugs with clear fixes
- Missing or incomplete tests

**Escalate to user** (drift from plan):
- Changes that would alter the design or approach
- New risks or security concerns
- Ambiguous requirements
- Issues suggesting the original plan was flawed

### Remediation Process

**Maximum 3 iterations** to prevent infinite loops.

1. Fix minor issues yourself or via sub-agents
2. Ask user about escalated issues
3. Re-verify after fixes (build + test must pass)
4. Repeat or conclude

## Phase 5: Completion (Archive and Changelog)

When all roadmap items are checked off and review is clean:

### Final Verification
1. Confirm all items complete
2. Build and tests pass
3. No outstanding review issues

### Archive Roadmap Files
1. Move the roadmap file to `ai/roadmaps/complete/`
2. Move the associated plan file to `ai/roadmaps/complete/`

### Update Changelog
Add entry to `ai/CHANGELOG.md`:

## YYYY-MM-DD: [Brief Title]
[1-3 sentence summary]
**Details:** See `ai/roadmaps/complete/[roadmap-filename].md`

### Commit Changes
Stage moved files + changelog, commit with message:
`feat: [brief description of what was implemented]`

### Notify User
"Implementation complete. Files moved to ai/roadmaps/complete/, changelog updated, changes committed."

## Important Principles

1. **Never skip Phase 5** - archival and changelog are REQUIRED
2. **You orchestrate, sub-agents implement** - clear separation
3. **You own the roadmap updates** - single source of truth
4. **Document everything** - deviations, decisions, blockers
5. **Pragmatic flexibility** - follow the plan, deviate when reality demands it
6. **Verify high-risk work early** - catch issues before they compound
7. **Fix minor issues, escalate drift** - handle small fixes, ask about plan changes
8. **Iterate with limits** - max 3 fix cycles, then escalate