| name | workflow:roadmap |
| description | Chart or resequence a multi-unit work horizon — destination, thin claimable streams, order, and NEXT — user-approved map for continue to consume |
| argument-hint | [optional: initiative/goal text, 'update', 'resequence', or path to existing roadmap] |
| user-invocable | true |
Horizon Roadmap (/workflow:roadmap)
Chart a multi-unit body of work: name the destination, list claimable streams (or order
existing units), set dependencies/parallelization, and leave a consumable NEXT pointer for
/workflow:continue.
Plan, don't do. This skill produces a map and order — not ACs, tasks, or code.
Shared invariant: no durable stream list or committed NEXT without an explicit user
approval turn. Draft; user approves before write.
User Input
$ARGUMENTS
| Input | Meaning |
|---|
| Empty / goal text | Chart a new map or open an existing one for update |
update / resequence | Load existing map; revise order/streams with approval |
| Path to roadmap / workstream dir | Target that artifact |
When to use
- Multiple independently claimable units; order or decomposition is unclear.
- Cold-start / path-not-established from
/workflow:continue.
- Resequence after reality changed.
Not this skill
- Single fuzzy concept →
/workflow:brainstorm
- Exact requirements for one unit →
/workflow:refine
- Task breakdown →
/workflow:plan
- Driving the loop →
/workflow:continue
Bail if single unit
If charting shows one claimable unit and no multi-stream structure, stop without writing a
map. Offer /workflow:brainstorm or /workflow:refine instead.
A claimable unit is something continue can pick: a stable slug/name, a planning/<item>/ path
(optional at claim time), a PM issue id, or an explicit stub the user accepts as next work —
not a phase of one story and not an AC list. Missing planning dir does not make a named
stream unclaimable — continue claims it and enters refine/plan, which create the shell.
Modes
Pick early (state it to the user):
| Mode | When | Focus |
|---|
| Decompose | Few/no claimable units yet | Destination + thin streams that will become units |
| Sequence | Units already exist (PM, planned session-states, workstreams) | Order only (→ / ∥); do not invent a new destination if SoT already has one |
Dialects (layout)
Default (no conventions): planning/roadmap.md (sequence-overlay / single-file map).
Honor existing: if planning/initiatives/ + planning/workstreams/ already exist, update
those instead of inventing a second SoT. Do not create hybrid sprawl for new projects unless the
user asks.
planning/conventions.md may name the dialect; absent → default file.
Protocol
- Destination. One or two lines: what "this horizon is done" looks like. (Decompose always;
Sequence only if missing.)
- Breadth-first frontier. List streams or existing units — don't deep-dive one thread.
Don't invent fake streams you can't claim later.
- Order & deps. Use the formal notation below. Note blockers and collision watches.
- Out of scope for this horizon.
- NEXT. One resolvable unit, an explicit wave package (
{A ∥ B}), or map-only /
sequencing-choice prose. Named NEXT without a planning shell is still consumable. Continue
auto-handoffs to swarm only for explicit ∥ / {wave} groups at the active head —
never invents a wave from ungrouped peers.
- Present draft → user approves → then write. Never write durable map before approval.
- Stop. Do not refine or implement.
HITL checklist (confirm before write)
Default artifact (planning/roadmap.md)
# Roadmap: [horizon title]
Status: Active
Updated: [date]
## Destination
[One or two lines — what done looks like]
## Streams / order
Notation: `→` sequential · `∥` (or `||`) parallelizable · `{A ∥ B}` wave · `⚠ A ∥ B` collision watch
1. [claimable unit or stream name] — [one-line purpose]
2. …
Example order line: `Wave 0 → Wave 1 → (Wave 2 ∥ Wave 3) → Wave 4`
## NEXT
[resolvable unit | `{A ∥ B}` wave package | `map-only` | user sequencing choice — list options]
## Out of scope
- [ruled out for this horizon]
## Notes
[optional: depends-on, ⚠ collision watches, links to initiatives/workstreams]
Notation (formal — continue consumes this)
| Token | Meaning | Continue behavior |
|---|
→ | Hard sequential dependency | Right side not claimable until left done |
∥ or ` | | ` |
{A ∥ B} | Named wave package | Preferred form for a swarm goal list |
⚠ A ∥ B | Soft collision (same layer / watch) | Not auto-launch; prefer sequential or caution |
map-only / sequencing choice | No single resolvable NEXT | hard-stop / surface choice — do not invent |
ASCII || is an accepted fallback for ∥ (U+2225). Informal // in chat means the same as ∥
but maps should use ∥ or ||.
Thin only: no acceptance criteria, no task lists, no status SoT (PM/session-state own status).
Titles are mnemonics when PM owns the issue.
Initiative + workstream dialect (when already in use)
planning/initiatives/<name>.md — objective, priority order, guardrailsplanning/workstreams/<slug>.md — purpose, success, depends-on, link to item dir when started- Keep streams thin; point continue at handoff
NEXT or first incomplete workstream's unit
Relationship to continue
- Continue is the principal session entry; it consumes NEXT / order notation; it does
not author this map.
- Portfolio mode (see
@workflow:continue): explicit target → active swarm resume →
explicit ∥ / {wave} auto-handoff → in_progress → single NEXT → planned queue →
hard-stop.
- On slice complete, continue may advance a pointer; it must not rewrite stream structure.
What this skill does not do
- Does not invent ACs or implementation plans.
- Does not auto-run from continue (continue only offers this command).
- Does not create PM issues unless the user explicitly asks as a separate step.
- Does not replace refine/plan for a single unit.
Key principles
- Destination first — scope every stream against it.
- Claimable units — if continue can't pick it by name/id, it isn't a stream yet (shell optional).
- Index, not store — detail lives in unit planning/PM, not the map.
- Approve before write — durable path decisions are user-gated.
- Signal, not ceremony — bail when one unit is enough.
