cc-roadmap

An evidence-grounded roadmap from ground truth — for Claude Code.

/roadmap adversarially audits what a codebase has actually finished versus what only looks finished, hunts the blind spots a feature-by-feature audit structurally misses, and writes a prioritized, milestone-organized backlog to your repo's git-tracked docs/roadmap/ROADMAP.md.

The core insight: "Implemented" ≠ "reaches the user." A feature can be fully coded, tested, and committed — and still be dead: not wired to a surface, not scheduled, behind a mock, leaking demo data, or computed on an empty/stale table. Naive audits score code presence and declare victory. This skill finds the gap between exists in code and actually done.

What it does

Three layers, each adversarially verified:

1. Feature completeness audit — fans out one subagent per discovered capability area, each hunting the exists-vs-reaches-user gap with file:line evidence. A separate skeptic re-checks every finding (real gap? already done? overstated?) so plausible-but-wrong claims die before they reach the roadmap.
2. Blind-spot trace — three lanes for what a feature audit can't see by construction:
   • within-dimension depth — contradictions, half-wired flows, dead code (defined but never called).
   • cross-cutting seams — auth/session & the product's own security surface, multi-tenant isolation, deploy/CI, observability, performance, migrations, a11y/mobile — categories that fall between features and get owned by no one.
   • audit-premise verification — enumerate every route/endpoint and map it to a dimension (anything mapped to none is a blind spot); test data reality (empty/stale tables, leaked seed rows) and the real end-to-end path.
3. Synthesis — merges and dedups verified gaps into prioritized milestones (M1 blockers → M3 polish), with manual status labels and automatic milestone % (done/total — no invented numbers), plus an honest "the audit caught ~N% of real gaps" verdict.

Output: docs/roadmap/ROADMAP.md, git-tracked so it travels across machines and teammates.

Why

Roadmaps drift optimistic. Backends look ~85% done while the surfaces, automation, and cross-cutting seams that actually make a product usable sit at ~40%. The most dangerous bugs (a session-cookie name mismatch that 401-locks the whole app the moment auth turns on; demo seed rows lighting up "live" panels; a "weekly" email that nothing schedules) live precisely in the seams a feature checklist never inspects. cc-roadmap makes the model prove completeness with evidence instead of asserting it.

Install

/plugin marketplace add givepro91/cc-roadmap
/plugin install roadmap@cc-roadmap

Or point at a local clone:

/plugin marketplace add /path/to/cc-roadmap

Use

/roadmap            # audit + adversarial verify + blind-spot trace → docs/roadmap/ROADMAP.md
/roadmap quick      # single-pass triage (no verify lane, no trace) — fast & cheap
/roadmap deep       # larger finder pool + multi-vote verify + completeness critic
/roadmap deep ./packages/api   # scope to a subtree

It is explicitly invoked only (no auto-trigger) — it fans out many subagents, so you decide when to spend that. The skill states its plan and rough subagent count before a large run.

Principles

• Honesty over flattery — no guessing; every gap carries file:line or a command fact; unverified is labeled unverified.
• Adversarial verification — first-pass findings are claims, re-checked by a skeptic before they count.
• Evidence over assumptions — run the grep / enumerate the routes / count the rows.
• Code-agnostic — dimensions are discovered per repo; the cross-cutting and premise lanes are universal.
• Data lives in git — the roadmap is a committed artifact, not session-local state.

License

MIT © Jay (Spacewalk)