Roadmap Integration

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:

/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

Prerequisites:

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

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 for platform-specific bash/powershell scripts

Validation:

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

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:

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 for extraction logic and validation rules

Token budget: ~5-8K tokens (overview.md typically 2-3 pages)

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:

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 provide justification
• Vision misalignment → User must revise, skip, or override with note

Overrides:

• Add ALIGNMENT_NOTE to issue body when user overrides validation
• Document justification for future reference

See: references/vision-validation.md for complete validation logic, prompts, and output examples

Create GitHub Issue with metadata after vision validation passes.

Actions:

1. Generate URL-friendly slug from title (max 30 chars)
2. Check for duplicate slugs
3. Extract area (backend, frontend, api, infra, design)
4. Extract role (all, free, student, cfi, school)
5. Create issue with YAML frontmatter metadata
6. Auto-apply labels (area, role, type:feature, status:backlog)

Issue structure:

---
metadata:
  area: app
  role: student
  slug: student-progress-widget
---

## Problem
[User pain point or need]

## Proposed Solution
[High-level approach]

## Requirements
- [ ] Requirement 1
- [ ] Requirement 2

---

⚠️  **Alignment Note**: Validated against project vision (overview.md)

Prioritization:

• Features prioritized by creation order (oldest issue = highest priority)
• No ICE scoring required (creation timestamp determines priority)
• Top of Backlog = oldest unworked issue

Labels auto-applied:

• area:$AREA - System area (backend, frontend, api, etc.)
• role:$ROLE - Target user role
• type:feature - Issue type
• status:backlog - Initial status

See: references/issue-creation.md for bash/powershell scripts and examples

Display current roadmap state and suggest next action.

Actions:

1. Fetch all issues from GitHub via gh CLI
2. Count features by status (Backlog, Next, In Progress, Shipped)
3. Show top 3 features in Backlog (oldest first = highest priority)
4. Suggest next action (/feature [oldest-slug])

Summary format:

✅ 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

Priority guidance:

• Work on oldest Backlog item first (creation-order prioritization)
• Move items to "Next" when ready to plan (3-5 item queue)
• Move to "In Progress" when actively implementing
• Close with "Shipped" label when deployed

• ✓ GitHub authenticated (gh CLI or GITHUB_TOKEN verified)
• ✓ Project documentation loaded (if docs/project/overview.md exists)
• ✓ Vision alignment validated (out-of-scope check, vision match, target user)
• ✓ Metadata extracted (area, role, slug from feature description)
• ✓ GitHub Issue created with YAML frontmatter metadata
• ✓ Labels auto-applied (area:, role:, type:feature, status:backlog)
• ✓ Roadmap summary displayed (counts by status, top 3 by creation order)
• ✓ Next action suggested (/feature [oldest-slug])

Quality gates passed:

• Out-of-scope gate: Feature not in explicit exclusion list (or override justified)
• Vision alignment gate: Feature supports project vision (or override justified)
• Duplicate check: Slug is unique across all issues
• Metadata completeness: Area, role, slug present in YAML frontmatter

Integration working:

• /roadmap feeds into /feature command (issue → spec)
• /feature updates issue labels (backlog → in-progress)
• /ship-prod marks issue as shipped (in-progress → closed with shipped label)

• references/github-setup.md - Platform-specific authentication and initialization scripts (bash/powershell)
• references/vision-validation.md - Complete validation logic, decision tree, prompts, and output examples
• references/issue-creation.md - GitHub Issue creation scripts, metadata structure, label application
• references/project-integration.md - How roadmap integrates with /init-project, /feature, /ship workflows

Scripts:

• .spec-flow/scripts/bash/github-roadmap-manager.sh
• .spec-flow/scripts/powershell/github-roadmap-manager.ps1

Command: .claude/commands/project/roadmap.md

Execution time:

• ADD with vision check: 30-60 seconds
• MOVE/DELETE/SEARCH: <10 seconds
• BRAINSTORM quick: 30-60 seconds
• BRAINSTORM deep: 2-5 minutes

Converted and distributed by TomeVault — claim your Tome and manage your conversions.