# Roadmap > Strategic roadmap management for GitHub repositories. Syncs ROADMAP.md with GitHub Issues and labels, bootstraps roadmap files from scratch, runs brainstorming sessions with boundary checking, and provides quick status summaries. Use when managing project planning, syncing roadmap state, or exploring feature ideas. - Skill: `rshade/roadmap` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add rshade/roadmap` - Raw SKILL.md: https://api.skillmd.com/api/skills/rshade/roadmap/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Product & Planning - Author: rshade (https://skillmd.com/u/rshade) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/rshade/roadmap --- # Strategic Roadmap Management Manage project roadmaps through five modes: sync ROADMAP.md with GitHub reality, bootstrap planning files from scratch, brainstorm new features collaboratively, get a quick status summary, or show help. ## Prerequisite check ```bash gh --version 2>/dev/null && gh auth status 2>/dev/null ``` If `gh` is not installed, direct the user to . If not authenticated, direct them to run `gh auth login`. Do **not** proceed without a working, authenticated GitHub CLI. ## Constitutional principle **CONTEXT.md is the project constitution.** All modes must read and respect the boundaries defined in CONTEXT.md. If CONTEXT.md exists, read it first and constrain all analysis and recommendations. When any recommendation would violate CONTEXT.md boundaries: 1. Explicitly flag the violation 2. Explain which boundary would be crossed 3. Suggest an alternative that respects the boundaries ## Mode dispatch Determine the mode from the user's input. If no mode is specified, default to sync. | Argument | Mode | Purpose | | -------- | ---- | ------- | | *(none)* | sync | Sync ROADMAP.md with GitHub, recommend priorities | | `sync` | sync | Same as default | | `generate` | generate | Bootstrap CONTEXT.md + ROADMAP.md from scratch | | `brainstorm` | brainstorm | Creative ideation session (read-only) | | `status` | status | Quick read-only summary | | `help` | help | Show available modes | ## Mode: sync Synchronize ROADMAP.md with GitHub and provide prioritized recommendations. This is the primary mode. 1. Fetch open issues, recently closed issues, and milestones via `gh` CLI 2. Read ROADMAP.md and CONTEXT.md 3. Check for legacy section layout — if found, ask the user whether to migrate to canonical structure (Vision → Immediate Focus → Near-Term → Future → Completed → Boundaries) 4. Detect discrepancies between ROADMAP.md and GitHub (issues marked done but still open, open but closed, missing entirely) 5. Update ROADMAP.md — fix discrepancies, move closed issues to "Completed Milestones" under quarterly sub-headings 6. Estimate LOE for open issues without `effort/*` labels using the heuristics in `references/label-config.md` 7. Sync GitHub labels — create missing labels, add/remove `roadmap/*` labels to match ROADMAP.md sections 8. Append LOE indicators (`[S]`, `[M]`, `[L]`) to issue lines in ROADMAP.md 9. Generate 3-5 prioritized recommendations based on dependencies, impact vs effort, theme coherence, and LOE balance 10. Present summary of all changes and recommendations For detailed workflow steps, see `references/sync.md`. For label definitions and LOE heuristics, see `references/label-config.md`. ## Mode: generate Bootstrap CONTEXT.md and ROADMAP.md for a new or undocumented project. 1. If either file exists, ask the user: regenerate, merge, or abort 2. Investigate the codebase — structure, dependencies, entry points, capabilities 3. Infer project boundaries ("hard no's") — what the project does NOT do 4. Research externally for similar tools and industry context 5. Draft CONTEXT.md with: core identity, technical boundaries, data source of truth, interaction model, verification criteria 6. Fetch all GitHub issues and milestones 7. Categorize issues into Immediate Focus, Near-Term, Future, and Completed (grouped by quarter) 8. Estimate LOE per open issue and apply `effort/*` labels 9. Draft ROADMAP.md with canonical structure and LOE indicators 10. Write CONTEXT.md first, then ROADMAP.md. Run markdownlint on both. For detailed workflow steps and templates, see `references/generate.md`. For LOE heuristics, see `references/label-config.md`. ## Mode: brainstorm Explore new possibilities through collaborative ideation. This mode is **read-only by default** — do not create issues or modify ROADMAP.md until the user explicitly approves. 1. Read CONTEXT.md and ROADMAP.md for current state and boundaries 2. Investigate the codebase for extension points, underutilized capabilities, and seams for new features 3. Research externally for similar tools, user requests, and trends 4. Use ideation techniques with the user: "What if...", "Who else...", "Why not...", "What's missing...", "What annoys..." 5. Evaluate each idea: boundary check against CONTEXT.md, effort, impact, dependencies 6. Present ideas in structured format (description, rationale, boundary check, effort, impact, next step) 7. Ask the user which ideas to formalize — only then create issues or update ROADMAP.md For detailed workflow steps and idea template, see `references/brainstorm.md`. ## Mode: status Quick read-only summary of current roadmap state. No modifications. 1. Fetch issue counts and milestone progress via `gh` CLI 2. Read ROADMAP.md 3. Present summary tables: overall metrics, by category (enhancement/bug/docs), by LOE (small/medium/large) 4. Flag obvious discrepancies without deep analysis For detailed workflow steps and table templates, see `references/status.md`. ## Mode: help Display available modes and usage: ```text roadmap — Strategic Roadmap Management MODES: (default) Sync ROADMAP.md + labels with GitHub, recommend priorities sync Same as default generate Bootstrap CONTEXT.md + ROADMAP.md from scratch brainstorm Creative ideation session (collaborative, read-only) status Quick read-only summary of current state help Show this help message LABELS (synced automatically): roadmap/current → "Immediate Focus" section roadmap/next → "Near-Term Vision" section roadmap/future → "Future Vision" section effort/small → 1-2 hours effort/medium → half day to 1 day effort/large → multi-day KEY PRINCIPLES: CONTEXT.md is the project constitution (all modes respect it) Brainstorm mode is read-only until user approves ideas Generate mode asks before overwriting existing files Labels are synced to match ROADMAP.md sections LOE is auto-estimated for issues missing effort/* labels ``` ## Output guidelines - Use tables for structured comparisons - Use emoji sparingly and only for status indicators - Always include issue numbers when referencing GitHub issues - Run markdownlint after any file modifications