| name | roadmap-create |
| description | Create a structured execution-plan roadmap in wiki/work/roadmaps/ via short Socratic Q&A — captures goal, phases, and the initial hybrid (task-link OR inline) checklist |
| category | planning |
| model | claude-sonnet-4-6 |
| argument-hint | <initiative/goal description> |
| disable-model-invocation | false |
| user-invocable | true |
Always obey .docs/guides/mcp-tools.md. Read it now if not already in context.
Read wiki/work/roadmaps/README.md first — it is authoritative for the roadmap template, file template, status lifecycle, item format rules, index format, and anti-patterns this skill must enforce.
Run /primer first if you have not already this session.
Run /research <topic> on the roadmap topic BEFORE any Q&A or file creation. Do not skip this step.
Create Roadmap
Create a new Roadmap — a structured, phased execution checklist that sits orthogonal to the PRD → ADR → Task pipeline. A roadmap answers exactly one question: in what sequence will we execute the work?
The hard boundary:
A roadmap shows order. A task contains implementation steps. Never smuggle step-level detail into a roadmap item.
If a checkbox starts growing sub-bullets like "run pnpm install" or "edit src/foo.ts", that content belongs in a real task file — created via /task-add (or /task-add --roadmap ROADMAP-NNN to auto-link). Redirect the user when this happens.
This skill drives a short Socratic Q&A session via AskUserQuestion. Roadmap creation is execution planning, not product strategy — keep questions focused and tight. Aim for one or two batched AskUserQuestion rounds plus per-phase follow-ups, not a full PRD-style interrogation.
Topic: $ARGUMENTS
When to write a Roadmap
See wiki/work/roadmaps/README.md for the canonical "When to Write" / "When NOT to Write" tables. In short: write a roadmap when work spans multiple discrete units, ordering matters, and you want at-a-glance visibility of what's next.
If the topic is a single task with several steps, stop and tell the user — the task file's own ## Steps checklist already serves that purpose. Suggest /task-add instead.
Instructions
Step 1: Parse the topic and recall project context
- Extract the core initiative from
$ARGUMENTS. If it is too vague (e.g. "auth", "cleanup", "the next thing"), use AskUserQuestion to narrow it before any other work.
- Invoke
/research <topic> — run the research skill on the roadmap topic now. Do not proceed to Step 2 until this completes. Use its findings to inform phase ordering, known constraints, and item content throughout the Q&A.
- Recall Serena memories that may inform the execution order:
mcp__serena__list_memoriesmcp__serena__read_memory for any topic-relevant memory (sequencing constraints, prior roadmaps, known dependency rules)
- Read project context:
CLAUDE.md (project conventions)wiki/work/roadmaps/README.md (template, lifecycle, anti-patterns — authoritative)- A sample of recent roadmaps in
wiki/work/roadmaps/ to learn local conventions
- The Tasks table in
wiki/work/tasks/README.md so you know what task files already exist and can be linked
Step 2: Locate the roadmap directory and assign a number
Roadmaps live at wiki/work/roadmaps/NNN-slug.md. Numbers are 3-digit zero-padded.
- Use
mcp__serena__list_dir on wiki/work/roadmaps/ to scan existing files. Collect every NNN- prefix.
- Use
mcp__serena__search_for_pattern against wiki/work/roadmaps/README.md for ROADMAP-\d{3} entries in the Index — these may reserve numbers not yet on disk.
- Take
max + 1, zero-pad to 3 digits. The first roadmap is 001.
- Derive the file slug — names the initiative. Lowercase, dash-separated, ≤ 60 chars:
- "Ship the billing portal" →
001-ship-billing-portal.md
- "Migrate to Postgres 17" →
004-migrate-postgres-17.md
Confirm the chosen number and slug with the user via AskUserQuestion only if either is non-obvious.
Step 3: Socratic Q&A via AskUserQuestion (short — this is the heart of this skill)
Walk through the elicitations below. Batch related questions into a single AskUserQuestion round (max 4 questions per call) to minimize round-trips. For each elicitation, the table names the quality bar the answer must clear. If the user's answer fails the bar, ask a follow-up — do not silently accept a weak answer or invent better content yourself.
| # | Elicitation | Quality bar | Anti-pattern to reject (re-ask) |
|---|
| 1 | Goal | 1-2 sentences describing the destination — what state will the system be in when every box is checked? | "Make X better"; vague aspiration with no observable end state |
| 2 | Phases (2-5) | Each phase is a short name capturing an execution stage. Order matters | One mega-phase ("Build it"); >5 phases (suggests over-planning) |
| 3 | Owner | One named person or role accountable for execution | "The team", "everyone", missing owner |
| 4 | Linked PRD / ADRs (may be empty) | Existing PRD-NNN or DEC-NNNN#DM references, or — if standalone | Inventing references that don't exist |
Suggested first batch (one AskUserQuestion call covering all four):
| Batch | Questions covered |
|---|
| 1 | Goal, Phases, Owner, Linked PRD/ADRs |
Then per-phase, in a single follow-up AskUserQuestion round (one question per phase, up to 4 — split into multiple rounds only if there are 5 phases):
| # | Elicitation | Quality bar |
|---|
| 5 | Phase N items | For each phase, the user names (a) any existing tasks (TASK-NNN or slug fragments) that belong in this phase, and (b) any inline placeholder items. Items may be empty if the user wants to fill in later via /roadmap-add — but at least one phase must contain at least one item (a roadmap with zero items is not a roadmap) |
When the user supplies a task reference:
- Look it up in
wiki/work/tasks/ via mcp__serena__find_file to confirm it exists. The link must read [[TASK-NNN: <task title>]].
- If the user supplies a task reference that does not exist, treat it as an inline placeholder (do not fabricate a link). Note in the per-phase clarification that a task file must be created before this item can be worked on — it will be created automatically when
/roadmap-next is run.
Inline placeholders: items without a corresponding task file are written as - [ ] <description>. They are valid at creation time because tasks may not exist yet. However, inline items cannot be worked on — /roadmap-next will automatically invoke /task-add to create a task file for each inline item before surfacing it. The roadmap item is then upgraded to a task-link in place.
Redirection rule: if the user starts spelling out implementation detail under an item (file paths, function names, sub-steps), respond:
That sounds like task content, not a roadmap item. Roadmaps show ordering. The how belongs in a task file — file one with /task-add --roadmap ROADMAP-NNN <description> and the roadmap will auto-link to it.
Then re-ask for a single checkbox-sized item.
Step 4: Present the plan and confirm before writing
Before writing the file, present a tabular preview of the roadmap:
| Section | Preview format |
|---|
| Header | Title, Status (active), Owner, Linked PRD, Linked ADRs, Tags |
| Goal | Full text |
| Phases | Table of Phase N → Name → # items (task-link + inline counts) |
| Per-phase items | One sub-list per phase showing each item's rendered form ([[TASK-NNN: title]] or inline text) |
The user confirms via AskUserQuestion with options like Approve and write, Edit specific phase, Cancel. Do not write the file until the user explicitly approves.
If the user requests edits, loop back to the relevant Step 3 elicitation, re-ask, and re-present.
Step 5: Re-verify the next available number — IMMEDIATELY before writing
The number determined in Step 2 may now be stale (other roadmaps created mid-session, the README Index may list reservations not yet on disk). Do a fresh scan now:
mcp__serena__list_dir on wiki/work/roadmaps/mcp__serena__search_for_pattern against wiki/work/roadmaps/README.md for ROADMAP-\d{3} entries- Collect every
NNN- prefix, take max + 1, zero-pad to 3 digits
- If the number you planned to use in Step 4 has been taken, silently bump to the new next-available number and use it. Do not re-prompt the user.
- Never call
Write before completing this re-scan.
Step 6: Write the roadmap file
Use Write to create wiki/work/roadmaps/NNN-slug.md following the template in wiki/work/roadmaps/README.md exactly.
| Field | Value at creation time |
|---|
Status | active |
Created | Today's date (derive at runtime — use the conversation environment's currentDate, otherwise date +%Y-%m-%d) |
Last updated | Same as Created |
Owner | From Step 3 #3 |
Linked PRD | From Step 3 #4, or — |
Linked ADRs | From Step 3 #4, or — |
Tags | 1-3 short area tags inferred from the topic (e.g. auth, billing, infra). If the user did not name any, propose tags during Step 4's confirmation rather than inventing them silently |
## Goal | From Step 3 #1 |
## Phase N: <name> | One block per phase from Step 3 #2, each containing the items from Step 3 #5. At least one phase must contain at least one item. |
## Notes | Empty placeholder line (the section header is retained for future use) |
Item rendering rules:
- Task-link item:
- [ ] [[TASK-NNN: <task title>]]
- Inline item:
- [ ] <free-form description>
Refuse to write if:
- The Goal is missing or vague
- The Owner is missing or "the team"/"everyone"
- Every phase is empty (zero items total)
Loop back to Step 3 instead — do not silently invent content.
Step 7: Update the roadmap index
Edit wiki/work/roadmaps/README.md to add a new row in the ## Index table.
-
Read the README to locate the Index table.
-
If the placeholder row _No roadmaps yet — use /roadmap-create to draft the first one._ exists, replace it with the new row. Otherwise append the new row in numerical order.
-
Use the column format from wiki/work/roadmaps/README.md:
| Column | Format |
|---|
File | [ROADMAP-NNN](NNN-slug.md) |
Title | The roadmap's H1 sub-title (without the Roadmap NNN: prefix) |
Status | active |
Progress | 0/<total> where <total> is the count of - [ ] checkboxes you just wrote across all phases |
Owner | One name or role |
Linked PRD | PRD-NNN or — |
Use Edit (not sed, awk, echo >>, or any shell redirection). See .docs/guides/mcp-tools.md.
Step 8: Report completion
Print a tabular summary:
| Field | Value |
|---|
| File path | wiki/work/roadmaps/NNN-slug.md |
| Status | active |
| Phases | N |
| Total items | M (task-link: X, inline: Y) |
| Owner | |
| Linked PRD | PRD-NNN or — |
| Linked ADRs | list or — |
| Index updated | yes (1 row added) |
| Suggested next steps | /roadmap-next wiki/work/roadmaps/NNN-slug.md — surfaces the first item and creates task files for any inline placeholders • /task-add --roadmap ROADMAP-NNN <description> — file a new task auto-linked to this roadmap |
If any phase was left empty by design (user plans to fill via /roadmap-add), note it in a separate Gaps section so the user can address it before execution begins.
If the roadmap contains any inline placeholder items (items without a task-link), include a Placeholders section listing them:
Placeholders (task file pending): These items will have task files created for them automatically when /roadmap-next runs. They cannot be tackled until a task file exists.
This is informational only — no action required now.
Output Formatting Rules (mandatory — these override any default style)
- Tables, not bullets, for every preview and summary in the conversation. The roadmap file itself uses checklists (that's its format), but every Q&A preview and Step 8 report uses tables.
- Phase names are short and execution-flavored. "Foundation", "API", "Tests", "Release" — not "Phase where we figure out the database stuff".
- Items are single checkbox-sized. No sub-bullets, no indented steps, no embedded code blocks. If an item needs detail, it's a task — file one. Items without a task file are written as inline placeholders (
- [ ] <description>) and are valid at creation time, but will be converted to task-links automatically by /roadmap-next before they can be worked on.
- Task-link items must use
[[TASK-NNN: <title>]] format. The TASK-NNN: prefix is required so the auto-checkoff machinery can detect references. Path-based markdown links break when files move to archive/; wiki-style ID links never do.
- At least one phase must contain at least one item. An empty roadmap is a hard fail — loop back to Step 3 #5.
- Never invent task references. If the user says "TASK-42" and no
042-*.md file exists, render it as an inline placeholder, not a [[TASK-NNN: ...]] wiki link.
CRITICAL Rules
- Refuse to write the file if any required field is empty or fails its quality bar (Goal, Owner, ≥1 phase with ≥1 item). Loop back to Step 3 — do not silently fill gaps with invented content.
- Never invent task links. Every
[[TASK-NNN: ...]] wiki link must correspond to a real file under wiki/work/tasks/. Verify with mcp__serena__find_file before rendering.
- Never use
sed, awk, echo >>, or shell redirection to edit markdown. Always Read then Edit. See .docs/guides/mcp-tools.md.
- Never auto-create downstream artifacts. This skill creates exactly one roadmap file (plus the index row edit). Do not create tasks, PRDs, or ADRs as a side effect — the user can file tasks afterward via
/task-add --roadmap ROADMAP-NNN.
- Redirect step-level detail to task territory — if the user starts specifying how under an item, restate the question as "what's the single checkable unit?" and re-elicit.
- Status starts as
active and stays there. This skill never writes done. The flip from active → done is a manual decision the human makes when every box is [x]. After flipping, the file may be moved to wiki/work/roadmaps/archive/ — /roadmap-next will suggest this step.
