roadmap-integration

<objective>
Manage product roadmap via GitHub Issues with vision alignment validation and creation-order prioritization, ensuring features align with project goals before implementation.
</objective>

<quick_start>
<roadmap_workflow>
**Vision-aligned feature management:**

1. **Initialize**: Verify GitHub authentication (gh CLI or GITHUB_TOKEN)
2. **Load vision**: Read docs/project/overview.md for alignment validation
3. **Parse intent**: Identify action (add, brainstorm, move, delete, search, ship)
4. **Validate vision**: Check against out-of-scope exclusions and project vision
5. **Create issue**: Generate GitHub Issue with metadata (area, role, slug)
6. **Show summary**: Display roadmap state and suggest next action

**Quick actions:**
```bash
/roadmap add "student progress widget"
/roadmap brainstorm "CFI productivity tools"
/roadmap move auth-refactor Next
/roadmap search export
```

**Example workflow:**
```
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📋 VISION ALIGNMENT CHECK
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Project Vision:
AKTR helps flight instructors track student progress against ACS standards.

Proposed Feature:
  Add student progress widget showing mastery percentage by ACS area

✅ Feature aligns with project vision

Target User Check:
Does this feature serve: CFIs, Flight students, School admins
Confirm primary user (or 'skip'): Flight students

✅ Vision alignment complete

✅ Created issue #123: student-progress-widget in Backlog
   Area: app | Role: student

📊 Roadmap Summary:
   Backlog: 12 | Next: 3 | In Progress: 2 | Shipped: 45

Top 3 in Backlog (oldest/highest priority):
1. #98 cfi-batch-export (Created: 2025-11-01)
2. #87 study-plan-generator (Created: 2025-11-05)
3. #123 student-progress-widget (Created: 2025-11-13)

💡 Next: /feature cfi-batch-export
```
</roadmap_workflow>

<trigger_conditions>
**Auto-invoke when:**
- `/roadmap` command executed
- User mentions "roadmap", "add feature", "brainstorm ideas", "prioritize features"
- Starting feature planning workflow

**Prerequisites:**
- GitHub authentication (gh CLI or GITHUB_TOKEN)
- Git repository with GitHub remote
- Optional: docs/project/overview.md for vision validation
</trigger_conditions>
</quick_start>

<workflow>
<step number="1" name="initialize_github_context">
**1. Initialize GitHub Context**

Verify GitHub authentication and repository access.

**Actions:**
- Check GitHub CLI authentication (gh auth status)
- Fallback to GITHUB_TOKEN environment variable
- Verify git repository has GitHub remote
- Source roadmap manager scripts

**Script location:** See [references/github-setup.md](references/github-setup.md) for platform-specific bash/powershell scripts

**Validation:**
```bash
AUTH_METHOD=$(check_github_auth)  # Returns: gh-cli, token, or none
REPO=$(get_repo_info)             # Returns: owner/repo-name

if [ "$AUTH_METHOD" = "none" ]; then
  echo "❌ GitHub authentication required"
  echo "Options: gh auth login OR export GITHUB_TOKEN=ghp_..."
  exit 1
fi
```

**Output:**
```
✅ GitHub authenticated (gh-cli)
✅ Repository: owner/repo-name
```
</step>

<step number="2" name="load_project_docs">
**2. Load Project Documentation Context**

Load project vision, scope boundaries, and target users from overview.md.

**When to execute:**
- Always before ADD/BRAINSTORM actions
- Skip for MOVE/DELETE/SEARCH operations

**Actions:**
```bash
PROJECT_OVERVIEW="docs/project/overview.md"
HAS_PROJECT_DOCS=false

if [ -f "$PROJECT_OVERVIEW" ]; then
  HAS_PROJECT_DOCS=true
  # Extract: Vision, Out-of-Scope, Target Users
  # (see detailed extraction logic in references)
else
  echo "ℹ️  No project documentation found"
  echo "   Run /init-project to create (optional)"
fi
```

**Extracted context:**
- **Vision**: 1 paragraph describing project purpose
- **Out-of-Scope**: Bullet list of explicit exclusions
- **Target Users**: Bullet list of intended users

**See:** [references/vision-validation.md](references/vision-validation.md) for extraction logic and validation rules

**Token budget:** ~5-8K tokens (overview.md typically 2-3 pages)
</step>

<step number="3" name="parse_user_intent">
**3. Parse User Intent**

Identify action type and extract parameters.

**Action types:**
- `add` - Add new feature (vision-validated, prioritized by creation order)
- `brainstorm` - Generate feature ideas via web research
- `move` - Change feature status (Backlog → Next → In Progress)
- `delete` - Remove feature from roadmap
- `search` - Find features by keyword/area/role/sprint
- `ship` - Mark feature as shipped

**Parse logic:**
| User Input | Action | Parameters |
|------------|--------|------------|
| "Add student progress widget" | add | title: "student progress widget" |
| "Brainstorm ideas for CFI tools" | brainstorm | topic: "CFI tools" |
| "Move auth-refactor to Next" | move | slug: "auth-refactor", target: "Next" |
| "Delete deprecated-feature" | delete | slug: "deprecated-feature" |
| "Search for export features" | search | keywords: "export" |
</step>

<step number="4" name="vision_alignment_validation">
**4. Vision Alignment Validation**

Validate feature against project vision before creating GitHub Issue.

**Executes for:** ADD and BRAINSTORM actions only

**Validation checks:**
1. **Out-of-scope check**: Feature not in explicit exclusion list
2. **Vision alignment**: Feature supports project vision (semantic analysis)
3. **Target user check**: Feature serves documented target users

**Decision tree:**
```
Feature proposed
    ↓
overview.md present? → No → Skip validation, proceed to creation
    ↓ Yes
Extract: Vision, Out-of-Scope, Target Users
    ↓
Out-of-scope check → Match → Prompt: Skip/Update/Override
    ↓ No match
Vision alignment → Misaligned → Prompt: Add anyway/Revise/Skip
    ↓ Aligned
Target user check → Select primary user → Add role label
    ↓
✅ Validation passed → Proceed to GitHub Issue creation
```

**Blocking gates:**
- Out-of-scope feature detected → User must skip, update overview.md, or pro