2 added, 1 removed. Audit A to A.
---
name: roadmap
description: Ongoing entry point for a project's ROADMAP.jsonl. Pick the next task to work on (ranks candidates deterministically by dependencies and file-touch collisions, shows why each is where it is, then crafts a self-contained handoff prompt), add a new task, correct a stale one, review roadmap status, or check the roadmap's structural health.
when_to_use: Trigger when the user asks what to work on next, wants to add something to the roadmap, wants to fix or reword an entry that already exists, wants to see roadmap status, thinks the roadmap file itself is broken, says "what's next", "pick a task", "add to the roadmap", "that task's description is wrong", "roadmap status", "my roadmap is broken", or invokes /foreman:roadmap.
argument-hint: "<optional — a task description to add, or a hint about what to pick next>"
allowed-tools: AskUserQuestion, Read, Write, Bash, PowerShell, TaskCreate, TaskUpdate, Agent, SendMessage
---
# foreman:roadmap — pick, add to, correct, review, or check the project roadmap
All reads/writes to `ROADMAP.jsonl` at the project root go through
`${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js` — never `Read`/`Edit` the file
directly, the script enforces id computation and parse-before/after-write
- mechanically. Skim `${CLAUDE_PLUGIN_ROOT}/roadmap-schema.md` if you need
+ mechanically — run it with `--help` for the command shapes. Read the
+ **Fields** section of `${CLAUDE_PLUGIN_ROOT}/roadmap-schema.md` if you need
field semantics beyond what's obvious from the names.
**Pre-check**: if `ROADMAP.jsonl` doesn't exist at the project root, tell
the user to run `/foreman:init` first and stop here.
---
## Call 1 — menu
**Q1** — "What do you need?"
Options:
- `Pick the next task` — read the roadmap, reason about what to work on
next, craft a handoff prompt for it.
- `Add a task` — append a new entry to the roadmap.
- `Correct a task` — fix a stale title, why, what, kind, or planned files
on an entry that already exists.
- `Review status` — read-only summary of where every task stands.
- `Check the roadmap` — run the structural doctor and name a repair for
each finding.
If args were provided and read like a task description rather than a
question, treat it as a seed for "Add a task" and skip this call. If they
read like a pick request or a hint about what to pick ("what's next on
auth", "something quick I can finish today"), go straight to "Pick the
next task" with the hint in hand — that branch says what to do with it.
If they name an entry that already exists and say what's wrong with it
("003's what is out of date", "retarget 007 at the proxy"), that's
"Correct a task". If they say the roadmap itself looks broken ("my
roadmap is broken", "is the roadmap file healthy"), go straight to
"Check the roadmap".
If they ask to clear out or archive finished work ("archive the finished
tasks", "get the done ones out of the way"), skip the menu: run `list
--status done,dropped,rejected --summary`, show those ids, and ask **one**
`AskUserQuestion` (`Archive them` / `Leave them`). On yes, `echo
'{"ids":["001","002"]}' | node ${CLAUDE_PLUGIN_ROOT}/scripts/roadmap.js
archive` — one call, all the ids, nothing else moves. `restore` with the
same shape is the way back if one has to change again.
---
## Branch: Pick the next task
Read `${CLAUDE_PLUGIN_ROOT}/skills/roadmap/pick.md` and follow it.
---
## Branch: Add a task
Read `${CLAUDE_PLUGIN_ROOT}/skills/roadmap/add.md` and follow it.
---
## Branch: Correct a task
Read `${CLAUDE_PLUGIN_ROOT}/skills/roadmap/correct.md` and follow it.
---
## Branch: Review status
Read `${CLAUDE_PLUGIN_ROOT}/skills/roadmap/status.md` and follow it.
---
## Branch: Check the roadmap
Read `${CLAUDE_PLUGIN_ROOT}/skills/roadmap/doctor.md` and follow it.