Roadmap Management

roadmap-manager

When to use

Use this skill when:

• Creating a new roadmap (/roadmap:create command)
• Executing a roadmap (/roadmap:process-step|phase|full commands)
• Checking roadmap progress
• Updating roadmap status after completing work

Do NOT use when:

• Small tasks that don't span multiple steps
• One-off questions or fixes

⚠ Dashboard sync — non-negotiable

agents/roadmaps-progress.md is auto-generated and must reflect the live state in real time. After any checkbox edit ([x], [~], [-], [ ]) or phase add/rename/remove in a roadmap file, regenerate the dashboard in the same response.

Completion = archival. If an edit takes a roadmap to count_open == 0 (pure [x], or [x] + [~]/[-]), git mv it into agents/roadmaps/archive/ before regenerating — see the auto-archive decision table under "Check completion status" below. A 100%-complete roadmap left in agents/roadmaps/ makes the next reader think work is still open.

This is enforced by the roadmap-progress-sync rule. Batching multiple edits in one response is fine — one final regeneration before replying is enough. But the response must not end without it.

Archival — preferred sweep, untracked-safe manual fallback

The robust path is the archive_completed_roadmaps --all sweep: it detects a completed roadmap (count_open == 0, count_deferred == 0), moves it to agents/roadmaps/archive/ — git mv in a tracked repo, a plain mv in a pre-first-commit / untracked one — rewrites inbound refs, and regenerates the dashboard. It is PR-independent: it does not need /create-pr to have run.

Manual fallback — script-less consumer (the sweep is not vendored). Do it by hand, in the same response, and never leave a 100 %-complete roadmap in the active tree because git mv failed:

1. mkdir -p agents/roadmaps/archive.
2. Move the file — git mv agents/roadmaps/<x>.md agents/roadmaps/archive/<x>.md in a tracked repo; a plain mv if the file is untracked or the repo has no commits (git mv errors there).
3. Rewrite inbound full-path references agents/roadmaps/<x>.md → agents/roadmaps/archive/<x>.md across the tree — on the working tree, not just the git index, when untracked.
4. Regenerate agents/roadmaps-progress.md.

Procedure: Manage a roadmap

1. Identify need — Is this a multi-step change that spans sessions or agents?
2. Create or locate — Create new roadmap in agents/roadmaps/ or find existing one.
3. Update progress — Mark completed steps with [x], add notes for blockers, then regenerate the dashboard in the same response (enforced by roadmap-progress-sync).
4. Verify — Confirm all steps reflect current state, no stale information.

A roadmap is a structured .md file in agents/roadmaps/ that describes a multi-step change (refactoring, feature, migration). It ensures work can be picked up across sessions and by different agents.

Roadmap locations

Module path resolution. {module_root} and {agent_folder} come from modules.root_paths and modules.agent_folder in .agent-project-settings.yml — see layered-settings. Common shapes:

• Laravel — app/Modules/{Module}/agents/roadmaps/
• Symfony bundles — src/Bundle/{Bundle}/agents/roadmaps/
• Node / Python / Go monorepo packages — packages/{Pkg}/agents/roadmaps/

Use scripts/_lib/agent_settings.ts::enumerate_modules() to discover the actual paths in the current project; never assume app/Modules/.

The file .augment/templates/roadmaps.md defines the canonical structure. Always read it first before creating or modifying roadmaps.

Modes

This skill is a router head. The dashboard-sync obligation above, the procedure skeleton, and the location table are true in every mode and stay here. The per-mode procedure bodies live in references/; load the one the task calls for, not the set.

Archival is the mode with the sharpest failure: an archive that buries deferred work or open blockers is the thing the sweep refuses to do, so load references/archival.md before archiving anything rather than working from memory of it.

Rubric pass (optional, surfacing-only)

After producing a roadmap, run judge-artifact-completeness with rubric roadmap-score to surface missing dimensions (risk, tests per step, migration, maintainability). The score is a recommendation; it never blocks the roadmap from shipping. Invoke only when the user wants a completeness check — not on every roadmap creation by default.

Output format

1. Roadmap file in agents/roadmaps/ with ordered phases and tasks
2. Progress tracking with checkbox status
3. agents/roadmaps-progress.md regenerated on every change

Auto-trigger keywords

• roadmap
• roadmap creation
• phase tracking
• step completion

Gotcha

• Roadmap files go in agents/roadmaps/ — don't create them in other directories.
• Don't mark phases complete without running verification (tests, quality checks) — the verify-before-complete rule applies.
• The model tends to skip phases it deems "simple" — every phase must be explicitly completed.
• Auto-archive is allowed when count_open == 0 AND count_deferred == 0. [-] cancelled items archive silently (explicit drops). [~] deferred items block silent archive — they trigger the Iron Law 3 flow (see step 4b).
• archive/ and skipped/ are distinct — archive/ = work happened, skipped/ = no meaningful work, not pursuing. Create either directory if it doesn't exist.
• Use git mv (not mv) so history follows the file.

Do NOT

• Do NOT skip quality gates between steps.
• Do NOT mark steps as done without actually completing them.
• Do NOT modify completed steps (only add notes if needed).
• Do NOT create roadmaps for trivial changes (single-file fixes don't need a roadmap).
• Do NOT commit or push — only local changes.
• Do NOT archive roadmaps with open [ ] items without asking the user.
• Do NOT delete roadmaps — always move to archive/ or skipped/.
• Do NOT use skipped/ as a dumping ground for partially-finished work — that is what archive/ with deferred items is for.
• Do NOT assign version numbers, git tags, deprecation dates, or release identifiers to phases. Roadmaps plan work; releases and tags are decided by the user separately. Hard rule — see scope-control.
• Do NOT propose a branch switch while executing a roadmap. The branch question is settled at creation time; if the user already declined (or you never asked because it wasn't sensible), stay silent. See scope-control.