roadmap

<context>
GitHub authentication: !`gh auth status >/dev/null 2>&1 && echo "✅ Authenticated" || echo "❌ Not authenticated"`

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 "{}"`
</context>

<architecture>
## Hybrid Pattern (v11.0)

**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
</architecture>

<objective>
Manage product roadmap via GitHub Issues with vision alignment validation.

**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
</objective>

<process>
1. **Verify GitHub authentication** from context:
   - If "❌ Not authenticated": Display authentication instructions and exit
   - If "✅ Authenticated": Proceed with action

2. **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
   ```

3. **Execute platform-specific script**:

   **Windows (PowerShell):**
   ```powershell
   . .\.spec-flow\scripts\powershell\github-roadmap-manager.ps1

   # Execute action-specific function
   # Examples:
   # - New-RoadmapIssue for "add"
   # - Search-Roadmap for "search"
   # - Move-IssueToSection for "move"
   # - Show-RoadmapSummary for "list"
   ```

   **macOS/Linux (Bash):**
   ```bash
   source .spec-flow/scripts/bash/github-roadmap-manager.sh

   # Execute action-specific function
   # Examples:
   # - create_roadmap_issue for "add"
   # - search_roadmap for "search"
   # - move_issue_to_section for "move"
   # - show_roadmap_summary for "list"
   ```

4. **For BRAINSTORM action — Spawn Research Agent (v11.0 Hybrid)**:

   **Step 4a: Gather context for agent:**
   ```javascript
   // Get existing roadmap items to avoid duplicates
   const existingFeatures = await exec(
     `gh issue list --label status:backlog,status:next --json number,title,labels --jq '.[] | {slug: .number, title: .title}'`
   )