- Initialize: Verify GitHub authentication (gh CLI or GITHUB_TOKEN)
- Load vision: Read docs/project/overview.md for alignment validation
- Parse intent: Identify action (add, brainstorm, move, delete, search, ship)
- Validate vision: Check against out-of-scope exclusions and project vision
- Create issue: Generate GitHub Issue with metadata (area, role, slug)
- 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 researchmove - Change feature status (Backlog → Next → In Progress)delete - Remove feature from roadmapsearch - Find features by keyword/area/role/sprintship - 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" |
|
|
|
Validate feature against project vision before creating GitHub Issue.
Executes for: ADD and BRAINSTORM actions only
Validation checks:
- Out-of-scope check: Feature not in explicit exclusion list
- Vision alignment: Feature supports project vision (semantic analysis)
- 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:
- Generate URL-friendly slug from title (max 30 chars)
- Check for duplicate slugs
- Extract area (backend, frontend, api, infra, design)
- Extract role (all, free, student, cfi, school)
- Create issue with YAML frontmatter metadata
- 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 roletype:feature - Issue typestatus:backlog - Initial status
See: references/issue-creation.md for bash/powershell scripts and examples
Display current roadmap state and suggest next action.
Actions:
- Fetch all issues from GitHub via gh CLI
- Count features by status (Backlog, Next, In Progress, Shipped)
- Show top 3 features in Backlog (oldest first = highest priority)
- 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
1---2name: roadmap-integration3description: Manages product roadmap via GitHub Issues (brainstorm, prioritize, track). Auto-validates features against project vision (from overview.md) before adding to roadmap. Use when running /roadmap command or mentions 'roadmap', 'add feature', 'brainstorm ideas', or 'prioritize features'.4---5
6<objective>
7Manage product roadmap via GitHub Issues with vision alignment validation and creation-order prioritization, ensuring features align with project goals before implementation.
8</objective>
9
10<quick_start>
11<roadmap_workflow>
12**Vision-aligned feature management:**
13
141. **Initialize**: Verify GitHub authentication (gh CLI or GITHUB_TOKEN)
152. **Load vision**: Read docs/project/overview.md for alignment validation
163. **Parse intent**: Identify action (add, brainstorm, move, delete, search, ship)
174. **Validate vision**: Check against out-of-scope exclusions and project vision
185. **Create issue**: Generate GitHub Issue with metadata (area, role, slug)
196. **Show summary**: Display roadmap state and suggest next action
20
21**Quick actions:**
22```bash
23/roadmap add "student progress widget"
24/roadmap brainstorm "CFI productivity tools"
25/roadmap move auth-refactor Next
26/roadmap search export
27```
28
29**Example workflow:**
30```
31━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
32📋 VISION ALIGNMENT CHECK
33━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
34
35Project Vision:
36AKTR helps flight instructors track student progress against ACS standards.
37
38Proposed Feature:
39 Add student progress widget showing mastery percentage by ACS area
40
41✅ Feature aligns with project vision
42
43Target User Check:
44Does this feature serve: CFIs, Flight students, School admins
45Confirm primary user (or 'skip'): Flight students
46
47✅ Vision alignment complete
48
49✅ Created issue #123: student-progress-widget in Backlog
50 Area: app | Role: student
51
52📊 Roadmap Summary:
53 Backlog: 12 | Next: 3 | In Progress: 2 | Shipped: 45
54
55Top 3 in Backlog (oldest/highest priority):
561. #98 cfi-batch-export (Created: 2025-11-01)
572. #87 study-plan-generator (Created: 2025-11-05)
583. #123 student-progress-widget (Created: 2025-11-13)
59
60💡 Next: /feature cfi-batch-export
61```
62</roadmap_workflow>
63
64<trigger_conditions>
65**Auto-invoke when:**
66- `/roadmap` command executed
67- User mentions "roadmap", "add feature", "brainstorm ideas", "prioritize features"
68- Starting feature planning workflow
69
70**Prerequisites:**
71- GitHub authentication (gh CLI or GITHUB_TOKEN)
72- Git repository with GitHub remote
73- Optional: docs/project/overview.md for vision validation
74</trigger_conditions>
75</quick_start>
76
77<workflow>
78<step number="1" name="initialize_github_context">
79**1. Initialize GitHub Context**
80
81Verify GitHub authentication and repository access.
82
83**Actions:**
84- Check GitHub CLI authentication (gh auth status)
85- Fallback to GITHUB_TOKEN environment variable
86- Verify git repository has GitHub remote
87- Source roadmap manager scripts
88
89**Script location:** See [references/github-setup.md](references/github-setup.md) for platform-specific bash/powershell scripts
90
91**Validation:**
92```bash
93AUTH_METHOD=$(check_github_auth) # Returns: gh-cli, token, or none
94REPO=$(get_repo_info) # Returns: owner/repo-name
95
96if [ "$AUTH_METHOD" = "none" ]; then
97 echo "❌ GitHub authentication required"
98 echo "Options: gh auth login OR export GITHUB_TOKEN=ghp_..."
99 exit 1
100fi
101```
102
103**Output:**
104```
105✅ GitHub authenticated (gh-cli)
106✅ Repository: owner/repo-name
107```
108</step>
109
110<step number="2" name="load_project_docs">
111**2. Load Project Documentation Context**
112
113Load project vision, scope boundaries, and target users from overview.md.
114
115**When to execute:**
116- Always before ADD/BRAINSTORM actions
117- Skip for MOVE/DELETE/SEARCH operations
118
119**Actions:**
120```bash
121PROJECT_OVERVIEW="docs/project/overview.md"
122HAS_PROJECT_DOCS=false
123
124if [ -f "$PROJECT_OVERVIEW" ]; then
125 HAS_PROJECT_DOCS=true
126 # Extract: Vision, Out-of-Scope, Target Users
127 # (see detailed extraction logic in references)
128else
129 echo "ℹ️ No project documentation found"
130 echo " Run /init-project to create (optional)"
131fi
132```
133
134**Extracted context:**
135- **Vision**: 1 paragraph describing project purpose
136- **Out-of-Scope**: Bullet list of explicit exclusions
137- **Target Users**: Bullet list of intended users
138
139**See:** [references/vision-validation.md](references/vision-validation.md) for extraction logic and validation rules
140
141**Token budget:** ~5-8K tokens (overview.md typically 2-3 pages)
142</step>
143
144<step number="3" name="parse_user_intent">
145**3. Parse User Intent**
146
147Identify action type and extract parameters.
148
149**Action types:**
150- `add` - Add new feature (vision-validated, prioritized by creation order)
151- `brainstorm` - Generate feature ideas via web research
152- `move` - Change feature status (Backlog → Next → In Progress)
153- `delete` - Remove feature from roadmap
154- `search` - Find features by keyword/area/role/sprint
155- `ship` - Mark feature as shipped
156
157**Parse logic:**
158| User Input | Action | Parameters |
159|------------|--------|------------|
160| "Add student progress widget" | add | title: "student progress widget" |
161| "Brainstorm ideas for CFI tools" | brainstorm | topic: "CFI tools" |
162| "Move auth-refactor to Next" | move | slug: "auth-refactor", target: "Next" |
163| "Delete deprecated-feature" | delete | slug: "deprecated-feature" |
164| "Search for export features" | search | keywords: "export" |
165</step>
166
167<step number="4" name="vision_alignment_validation">
168**4. Vision Alignment Validation**
169
170Validate feature against project vision before creating GitHub Issue.
171
172**Executes for:** ADD and BRAINSTORM actions only
173
174**Validation checks:**
1751. **Out-of-scope check**: Feature not in explicit exclusion list
1762. **Vision alignment**: Feature supports project vision (semantic analysis)
1773. **Target user check**: Feature serves documented target users
178
179**Decision tree:**
180```
181Feature proposed
182 ↓
183overview.md present? → No → Skip validation, proceed to creation
184 ↓ Yes
185Extract: Vision, Out-of-Scope, Target Users
186 ↓
187Out-of-scope check → Match → Prompt: Skip/Update/Override
188 ↓ No match
189Vision alignment → Misaligned → Prompt: Add anyway/Revise/Skip
190 ↓ Aligned
191Target user check → Select primary user → Add role label
192 ↓
193✅ Validation passed → Proceed to GitHub Issue creation
194```
195
196**Blocking gates:**
197- Out-of-scope feature detected → User must skip, update overview.md, or provide justification
198- Vision misalignment → User must revise, skip, or override with note
199
200**Overrides:**
201- Add ALIGNMENT_NOTE to issue body when user overrides validation
202- Document justification for future reference
203
204**See:** [references/vision-validation.md](references/vision-validation.md) for complete validation logic, prompts, and output examples
205</step>
206
207<step number="5" name="github_issue_creation">
208**5. GitHub Issue Creation**
209
210Create GitHub Issue with metadata after vision validation passes.
211
212**Actions:**
2131. Generate URL-friendly slug from title (max 30 chars)
2142. Check for duplicate slugs
2153. Extract area (backend, frontend, api, infra, design)
2164. Extract role (all, free, student, cfi, school)
2175. Create issue with YAML frontmatter metadata
2186. Auto-apply labels (area, role, type:feature, status:backlog)
219
220**Issue structure:**
221```yaml
222---
223metadata:
224 area: app
225 role: student
226 slug: student-progress-widget
227---
228
229## Problem
230[User pain point or need]
231
232## Proposed Solution
233[High-level approach]
234
235## Requirements
236- [ ] Requirement 1
237- [ ] Requirement 2
238
239---
240
241⚠️ **Alignment Note**: Validated against project vision (overview.md)
242```
243
244**Prioritization:**
245- Features prioritized by **creation order** (oldest issue = highest priority)
246- No ICE scoring required (creation timestamp determines priority)
247- Top of Backlog = oldest unworked issue
248
249**Labels auto-applied:**
250- `area:$AREA` - System area (backend, frontend, api, etc.)
251- `role:$ROLE` - Target user role
252- `type:feature` - Issue type
253- `status:backlog` - Initial status
254
255**See:** [references/issue-creation.md](references/issue-creation.md) for bash/powershell scripts and examples
256</step>
257
258<step number="6" name="return_roadmap_summary">
259**6. Return Roadmap Summary**
260
261Display current roadmap state and suggest next action.
262
263**Actions:**
2641. Fetch all issues from GitHub via gh CLI
2652. Count features by status (Backlog, Next, In Progress, Shipped)
2663. Show top 3 features in Backlog (oldest first = highest priority)
2674. Suggest next action (/feature [oldest-slug])
268
269**Summary format:**
270```
271✅ Created issue #123: student-progress-widget in Backlog
272 Area: app | Role: student
273
274📊 Roadmap Summary:
275 Backlog: 12 | Next: 3 | In Progress: 2 | Shipped: 45
276
277Top 3 in Backlog (oldest/highest priority):
2781. #98 cfi-batch-export (Created: 2025-11-01)
2792. #87 study-plan-generator (Created: 2025-11-05)
2803. #123 student-progress-widget (Created: 2025-11-13)
281
282💡 Next: /feature cfi-batch-export
283```
284
285**Priority guidance:**
286- Work on oldest Backlog item first (creation-order prioritization)
287- Move items to "Next" when ready to plan (3-5 item queue)
288- Move to "In Progress" when actively implementing
289- Close with "Shipped" label when deployed
290</step>
291</workflow>
292
293<anti_patterns>
294**Avoid these roadmap management mistakes:**
295
296<pitfall name="skip_vision_alignment">
297**❌ Adding features without vision validation**
298```bash
299# BAD: Skip vision check, add any feature
300HAS_PROJECT_DOCS=false # Force skip even if docs exist
301/roadmap add "social media integration"
302```
303**✅ Always run vision validation when overview.md exists**
304```bash
305# GOOD: Load project docs, validate alignment
306if [ -f "docs/project/overview.md" ]; then
307 HAS_PROJECT_DOCS=true
308 # Extract vision context, run validation
309fi
310```
311**Impact:** Roadmap fills with out-of-scope features, dilutes project focus
312**Prevention:** Never set `HAS_PROJECT_DOCS=false` if docs exist
313</pitfall>
314
315<pitfall name="override_out_of_scope_without_justification">
316**❌ Overriding out-of-scope exclusions without updating docs**
317```bash
318# BAD: Add out-of-scope feature, provide vague justification
319Feature: "flight scheduling"
320Matches exclusion: "Flight scheduling or aircraft management"
321Justification: "it would be nice to have"
322```
323**✅ Update overview.md if scope legitimately changed**
324```bash
325# GOOD: Update source docs first
326# Edit docs/project/overview.md:
327# - Remove "Flight scheduling" from Out-of-Scope section
328# - Document scope expansion in Vision section
329# Then add feature normally
330```
331**Impact:** Overview.md becomes outdated, vision validation unreliable
332**Prevention:** Treat overview.md as source of truth, update before overriding
333</pitfall>
334
335<pitfall name="missing_metadata">
336**❌ Manually creating GitHub Issues without metadata**
337```bash
338# BAD: Create issue via gh CLI directly
339gh issue create --title "new feature" --body "description"
340# Missing: area, role, slug, YAML frontmatter
341```
342**✅ Always use create_roadmap_issue() function**
343```bash
344# GOOD: Use roadmap manager function
345create_roadmap_issue \
346 "$TITLE" \
347 "$BODY" \
348 "$AREA" \
349 "$ROLE" \
350 "$SLUG" \
351 "type:feature,status:backlog"
352# Auto-adds metadata, labels, frontmatter
353```
354**Impact:** Cannot filter/search issues, roadmap state tracking breaks
355**Prevention:** Never create roadmap issues manually, always use manager functions
356</pitfall>
357
358<pitfall name="duplicate_slugs">
359**❌ Creating features with duplicate slugs**
360```bash
361# BAD: Don't check for existing slug
362SLUG="user-auth"
363create_roadmap_issue ... # Issue #50 already has slug "user-auth"
364```
365**✅ Check for duplicates before creation**
366```bash
367# GOOD: Validate slug uniqueness
368EXISTING_ISSUE=$(get_issue_by_slug "$SLUG")
369if [ -n "$EXISTING_ISSUE" ]; then
370 echo "⚠️ Slug '$SLUG' already exists (Issue #$EXISTING_ISSUE)"
371 SLUG="${SLUG}-v2" # Append version suffix
372fi
373```
374**Impact:** Multiple issues with same slug, /feature command ambiguous
375**Prevention:** Always call get_issue_by_slug() before creation
376</pitfall>
377
378<pitfall name="unclear_feature_descriptions">
379**❌ Vague feature descriptions that fail vision check**
380```bash
381# BAD: Ambiguous description
382FEATURE="Make it better for users"
383# Vision validator cannot assess alignment
384```
385**✅ Use Problem + Solution + Requirements format**
386```bash
387# GOOD: Structured description
388PROBLEM="Students struggle to track mastery across ACS areas"
389SOLUTION="Add progress widget showing mastery percentage by area"
390REQUIREMENTS="
391- [ ] Display mastery % per ACS area
392- [ ] Color-code by proficiency level
393- [ ] Export progress report"
394```
395**Impact:** Vision alignment validation fails, feature rejected
396**Prevention:** Prompt user for Problem/Solution/Requirements if description unclear
397</pitfall>
398
399<pitfall name="roadmap_state_sync_issues">
400**❌ Not updating issue labels when feature progresses**
401```bash
402# BAD: Create spec but don't update GitHub Issue
403/feature user-auth # Creates spec
404# Issue #50 still has status:backlog (should be status:in-progress)
405```
406**✅ Update labels when feature state changes**
407```bash
408# GOOD: Mark in progress when spec created
409mark_issue_in_progress "user-auth" # Updates to status:in-progress
410# Later: mark_issue_shipped when deployed
411```
412**Impact:** Roadmap summary shows stale counts, misleading prioritization
413**Prevention:** Hook /feature, /ship commands to update issue labels
414</pitfall>
415</anti_patterns>
416
417<success_criteria>
418**Roadmap management successful when:**
419
420- ✓ GitHub authenticated (gh CLI or GITHUB_TOKEN verified)
421- ✓ Project documentation loaded (if docs/project/overview.md exists)
422- ✓ Vision alignment validated (out-of-scope check, vision match, target user)
423- ✓ Metadata extracted (area, role, slug from feature description)
424- ✓ GitHub Issue created with YAML frontmatter metadata
425- ✓ Labels auto-applied (area:*, role:*, type:feature, status:backlog)
426- ✓ Roadmap summary displayed (counts by status, top 3 by creation order)
427- ✓ Next action suggested (/feature [oldest-slug])
428
429**Quality gates passed:**
430- Out-of-scope gate: Feature not in explicit exclusion list (or override justified)
431- Vision alignment gate: Feature supports project vision (or override justified)
432- Duplicate check: Slug is unique across all issues
433- Metadata completeness: Area, role, slug present in YAML frontmatter
434
435**Integration working:**
436- /roadmap feeds into /feature command (issue → spec)
437- /feature updates issue labels (backlog → in-progress)
438- /ship-prod marks issue as shipped (in-progress → closed with shipped label)
439</success_criteria>
440
441<reference_guides>
442For detailed scripts, validation logic, and integration patterns:
443
444- **[references/github-setup.md](references/github-setup.md)** - Platform-specific authentication and initialization scripts (bash/powershell)
445- **[references/vision-validation.md](references/vision-validation.md)** - Complete validation logic, decision tree, prompts, and output examples
446- **[references/issue-creation.md](references/issue-creation.md)** - GitHub Issue creation scripts, metadata structure, label application
447- **[references/project-integration.md](references/project-integration.md)** - How roadmap integrates with /init-project, /feature, /ship workflows
448
449**Scripts:**
450- `.spec-flow/scripts/bash/github-roadmap-manager.sh`
451- `.spec-flow/scripts/powershell/github-roadmap-manager.ps1`
452
453**Command:** `.claude/commands/project/roadmap.md`
454</reference_guides>
455
456<performance>
457**Token budget per action:**
458- ADD (with vision validation): ~8-12K tokens
459 - overview.md read: ~5-8K
460 - Vision alignment analysis: ~2-3K
461 - GitHub Issue creation: ~1K
462- ADD (without docs): ~2-3K tokens
463- BRAINSTORM (quick): ~15-20K tokens
464- BRAINSTORM (deep): ~40-60K tokens
465- MOVE/DELETE/SEARCH: ~1-2K tokens
466
467**Execution time:**
468- ADD with vision check: 30-60 seconds
469- MOVE/DELETE/SEARCH: <10 seconds
470- BRAINSTORM quick: 30-60 seconds
471- BRAINSTORM deep: 2-5 minutes
472</performance>
majiayu000