strategic-roadmap

Strategic Roadmap

Generate the work worth planning inside one repository. This is an audit-shaped senior judgment stage: mine repo docs, old plans, branches/bookmarks, and code shape; inspect across improvement categories; expand the user's seeds; generate non-obvious opportunities; reject low-value ideas; and sequence the best work.

Treat roadmap work as meta-work: prefer opportunities that improve future work loops, evaluation, verification, autonomy boundaries, standing policies, and plan quality over one-off task completion.

Use the ordinary roadmap skill for standard product/release roadmaps. Use this when the user wants repo-grounded opportunity discovery before investing in plan banks or feature planning artifacts. Do not reduce this to ranking a list the user already gave you. The planner is responsible for idea generation and judgment.

Source Frame

Before producing the roadmap, load the sources that match the scope:

• improve for read-only senior-advisor discovery, audit categories, evidence, vetting, leverage ranking, and “not worth doing” verdicts.
• The coding-standards skill as the canonical source for standards areas and review vocabulary. Load the matching reference files when a code-shaped opportunity needs that lens; do not restate the standards here.
• improve-codebase-architecture when architecture/deepening opportunities are in scope.
• Architecture vocabulary: module, interface, depth, seam, adapter, leverage, locality.
• Project docs: AGENTS.md, README.md, CONTEXT.md, architecture docs, ADRs, old plans, roadmap files, active branches/bookmarks, and relevant issue/ticket notes.

Workflow

1. Establish repo scope and goal

• Identify the single repository and existing artifacts to mine.
• Characterize what “better” means for this repo: user value, agent execution quality, architecture leverage, verification confidence, velocity, reliability, or other success criteria.
• Include the user's seed ideas, but treat them as inputs, not the full set.
• If the user names multiple repos, create one roadmap per repo or ask which repo to start with.
• If the repo goal or success criteria are unclear after reading context, ask a short interview question before ranking work.
• If the repo is too broad to inspect responsibly, ask one narrowing question or propose a bounded first pass.

1. Recon without implementation

• Read project context and existing plans before judging.
• Identify the project’s verification commands, missing verification baseline, active work state, and churn hotspots.
• Inspect current work state enough to avoid stale recommendations.
• Do not edit source code. Only write the roadmap artifact.
• If credentials or secrets appear, reference only the file path, line, and credential type; never copy secret values into the roadmap.

1. Audit for opportunities

• Audit like improve: correctness, security, performance, test coverage, tech debt and architecture, dependencies and migrations, DX and tooling, docs, and direction.
• Include repo-discovered ideas, architecture/deepening candidates, product/workflow ideas, plan salvage opportunities, obsolete work to retire, and system upgrades that improve future work.
• Look for decisions the user or agents keep re-litigating; propose standing policies, ADRs, evals, or plan templates when they would compound.
• For code-shaped opportunities, choose the Standards area from the coding-standards skill and load only the matching reference when the ranking or routing depends on it.
• For architecture candidates, use improve-codebase-architecture framing: current friction, files/modules, deepening direction, locality/leverage, testability, and recommendation strength.
• Use architecture audit probes: where understanding requires bouncing between modules, where the interface is nearly as complex as the implementation, where test-only extraction lost locality, where seams leak, and where the deletion test shows a module is shallow.
• Do not propose final interfaces at roadmap stage. Name the friction, direction, and next artifact instead.

1. Vet and sequence

• Verify every opportunity you rank by opening the cited code, plan, or artifact yourself; subagent output and old plans are leads, not evidence.
• Keep only ideas with evidence or a clear user-stated goal.
• Rank by leverage: impact divided by likely effort, discounted by confidence and fix risk; let verification-baseline and high-confidence security items float up when they unblock or de-risk later work.
• Separate problems worth fixing from direction options worth considering when they should not be ranked against bugs or verification gaps.
• Calibrate autonomy by risk: identify what routine executors can do later, what needs design review, and what needs human approval.
• Record rejected and not-now items so future runs do not rediscover the same low-value ideas.

1. Write `.agents/ROADMAP.md`

• Use the template in references/roadmap-template.md.
• Create .agents/ if it does not exist.
• Prefer Now / Next / Later over fake dates.
• Put provenance in top-level source material and item evidence, not required per-item source fields.
• State the coverage boundary: what was reviewed, lightly sampled, or not reviewed.
• Every item must name the next artifact: roadmap-to-improve-plans, feature-planning-artifacts, research/spike, user decision, defer, or drop.
• For architecture items, include recommendation strength: Strong, Worth exploring, or Speculative.

Output Rules

• Be evidence-backed. Cite file paths, artifact paths, branch/bookmark names, or user seed text.
• Say what was not reviewed; do not imply whole-repo coverage when the pass was bounded.
• Mark the audit category for each major opportunity unless it is purely user-seeded direction.
• Be willing to say “not worth doing.”
• Define what “better” means for the repo before ranking opportunities; if it is unclear, ask.
• Prefer durable system upgrades over one-off task suggestions when leverage is comparable.
• Do not produce implementation steps here; route selected items to roadmap-to-improve-plans or feature-planning-artifacts.
• Do not estimate effort unless the user explicitly asks. Prefer confidence, risk, dependency, autonomy boundary, and executor-readiness.
• Do not invent compatibility layers. If a shape should change, favor the clean end state unless real data/public contracts require migration planning.

Done Criteria

The roadmap is done when a future planner can choose the next artifact without redoing repo discovery: the best opportunities are ranked, rejected ideas are recorded, architecture candidates are framed with standards vocabulary, and the next planning stage is explicit for each item.