roadmap

Repository: !gh repo view --json nameWithOwner -q .nameWithOwner 2>/dev/null || echo "Not a GitHub repo"

Project docs exist: !test -f docs/project/overview.md && echo "✅ Found" || echo "❌ Missing"

Roadmap issue count: !gh issue list --label status:backlog,status:next,status:in-progress --json number --jq 'length' 2>/dev/null || echo "0"

Open issues by status: !gh issue list --json labels --jq '[.[] | .labels[] | select(.name | startswith("status:")) | .name] | group_by(.) | map({(.[0]): length}) | add' 2>/dev/null || echo "{}"

For brainstorm action (heavy web research):

User: /roadmap brainstorm "user onboarding"
         │
         ▼
┌──────────────────────────────────────────────────────┐
│ MAIN CONTEXT (context gathering - lightweight)       │
│                                                      │
│ 1. Verify GitHub authentication                      │
│ 2. Load project vision from overview.md              │
│ 3. Get existing roadmap items (avoid duplicates)     │
│ 4. Save context to temp config                       │
│    → .spec-flow/temp/brainstorm-context.yaml         │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────┐
│ Task(roadmap-brainstorm-agent) ← ISOLATED            │
│                                                      │
│ 1. Read context from temp config                     │
│ 2. Web search for similar products                   │
│ 3. Research best practices                           │
│ 4. Generate feature ideas (up to 15)                 │
│ 5. Validate against project vision                   │
│ 6. Deduplicate against existing features             │
│ 7. Return ranked list of ideas                       │
│ 8. EXIT                                              │
└──────────────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────────────────────────────────────┐
│ MAIN CONTEXT (user selection - interactive)          │
│                                                      │
│ 1. Display generated ideas with alignment status     │
│ 2. AskUserQuestion: which ideas to add to roadmap?   │
│ 3. Create GitHub Issues for selected ideas           │
│ 4. Display roadmap summary                           │
└──────────────────────────────────────────────────────┘

For lightweight actions (add, move, delete, list, etc.):

• Run directly in main context (no Task spawning needed)
• These are simple GitHub CLI operations

Actions supported:

• add — Add new feature with vision validation
• brainstorm — Generate feature ideas via web research
• from-ultrathink — Materialize features from ultrathink session (v2.0)
• move — Change feature status (Backlog → Next → In Progress → Shipped)
• delete — Remove feature from roadmap
• search — Find features by keyword/area/role
• list — Show roadmap summary
• milestone — Manage milestones (list, create, plan)
• epic — Manage epic labels (list, create)

Workflow integration:

/init-project → /roadmap add|brainstorm → /feature or /epic

Dependencies:

• GitHub authentication (gh CLI or GITHUB_TOKEN)
• Git repository with remote
• Optional: docs/project/overview.md for vision validation

1. Parse user intent from $ARGUMENTS and route to action:

   Action routing:

   If $ARGUMENTS starts with "add "            → ADD action (remaining = feature description)
   If $ARGUMENTS starts with "brainstorm "     → BRAINSTORM action (remaining = topic)
   If $ARGUMENTS starts with "from-ultrathink" → FROM-ULTRATHINK action (remaining = path or --list)
   If $ARGUMENTS starts with "move "           → MOVE action (parse: slug, target status)
   If $ARGUMENTS starts with "delete "         → DELETE action (remaining = slug)
   If $ARGUMENTS starts with "search "         → SEARCH action (remaining = query)
   If $ARGUMENTS equals "list"                 → LIST action (no params)
   If $ARGUMENTS starts with "milestone "      → MILESTONE sub-actions:
      - "milestone list"                       → list all milestones
      - "milestone create <name> [date]"       → create milestone
      - "milestone plan <name>"                → interactive assignment
   If $ARGUMENTS starts with "epic "           → EPIC sub-actions:
      - "epic list"                            → list all epic labels
      - "epic create <name> [description]"     → create epic label