// 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.
Use when creating or updating AGENTS.md files, .github/copilot-instructions.md, or other AI agent rule files, onboarding AI agents to a project, standardizing agent documentation, or when anyone mentions AGENTS.md, agent rules, project onboarding, or codebase documentation for AI agents.
Prepares Go applications to work effectively with AI coding agents. Use when setting up a new Go project or retrofitting an existing one to ensure: structured JSON logging (slog/Zap/ZeroLog/Logrus), machine-readable command output, thorough golangci-lint configuration, non-interactive CLI design with --yes flags, structured error handling with meaningful exit codes, proper context.Context propagation, graceful shutdown, health check endpoints, and a standardized Makefile. Triggers when a user asks to make their Go app "agent-ready," "AI-friendly," wants to improve agent tooling/observability in a Go project, or needs to audit an existing Go project against agent-readiness best practices.
Validate commit messages against the Conventional Commits specification. Auto-detects and installs commitlint CLI if missing. Checks project config or falls back to sensible defaults. Use when validating commit messages, preparing PRs, or enforcing commit conventions.
Audit Go nolint directives for staleness and lazy justifications. Mechanically verifies each suppression with golangci-lint, then runs adversarial Red/Blue/White debates on the top candidates for removal. Use when inheriting a Go codebase, during periodic cleanup, or when nolint count is growing unchecked.
Validate markdown files against formatting standards. Auto-detects and installs markdownlint-cli if missing. Checks project config or falls back to sensible defaults. Supports auto-fix mode. Use when creating or modifying markdown files, validating documentation, or enforcing markdown conventions.
Generate a PR_MESSAGE.md file from session context using GitHub CLI. Detects related issues via branch-keyword search, writes a structured PR description with commit subject, summary, test plan, and changelog. Validates with commitlint and markdownlint. Use when preparing a pull request on GitHub.
| name | roadmap |
| description | 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. |
| compatibility | Requires GitHub CLI (gh) authenticated. Works with any GitHub repository that uses Issues and milestones for project planning. |
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.
gh --version 2>/dev/null && gh auth status 2>/dev/null
If gh is not installed, direct the user to
https://cli.github.com. If not authenticated, direct them to run
gh auth login. Do not proceed without a working, authenticated
GitHub CLI.
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:
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 |
Synchronize ROADMAP.md with GitHub and provide prioritized recommendations. This is the primary mode.
gh CLIeffort/* labels using the
heuristics in references/label-config.mdroadmap/* labels to match ROADMAP.md sections[S], [M], [L]) to issue lines in
ROADMAP.mdFor detailed workflow steps, see references/sync.md. For label
definitions and LOE heuristics, see references/label-config.md.
Bootstrap CONTEXT.md and ROADMAP.md for a new or undocumented project.
effort/* labelsFor detailed workflow steps and templates, see
references/generate.md. For LOE heuristics, see
references/label-config.md.
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.
For detailed workflow steps and idea template, see
references/brainstorm.md.
Quick read-only summary of current roadmap state. No modifications.
gh CLIFor detailed workflow steps and table templates, see
references/status.md.
Display available modes and usage:
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