roadmap

# Roadmap: scope, manage, and orchestrate AI coding sessions in any repo `roadmap` is a CLI, MCP server, and Claude Code plugin. It turns two YAML files into your repo's plan of record — a **hierarchical, dependency-aware roadmap graph** plus a **prioritized backlog** for the work that surfaces erratically — then **fans that plan out into parallel coding sessions**, each scoped to a single unit of work in its own git worktree. In a Codex environment, the primary surfaces are the CLI, the MCP server, and the repo-level [`AGENTS.md`](AGENTS.md). The Claude plugin assets are included for teams using them. - **One source of truth (each).** `docs/roadmap/roadmap.yaml` holds the PIs, sprints, deps, priorities, file-ownership, session estimates, gates, prompts, and kickoff briefs. `docs/roadmap/backlog.yaml` holds the erratic work: follow-ups, bugs, chores, urgent items. - **Generated views.** `docs/SLICES.md` and `docs/BACKLOG.md` are *rendered* from the YAML; never hand-edit them. - **Derived, never stored.** Per-PI exec-plan lines (`(S0 ∥ S1)→S2→S3`), the cross-PI "ready now" wave map, "sessions remaining" rollups, and priority ordering are all computed from `deps` + `touches` + `status` + `priority`. - **Deterministic fanout with feasibility pre-checks.** A scheduler decides which slices can run concurrently under a cap it *recommends* from five real ceilings — CPU, RAM, independent work, human review, and **free disk for the worktrees** — then launches each in its own worktree and Claude Code session. When even one worktree won't fit on disk, launch is refused before anything is created. - **Zero-prompt pickup.** Stash the pickup instructions on the slice itself (`prompt:`); `/slice <key>` or `roadmap grab <id>` is then all a session needs. - **Repo-agnostic.** The resource classifier reads the build/test runner command in each sprint's gate (not its language) to size the session. It recognizes the common runners across JS/TS, Python, Java/Kotlin, C/C++, Go, Rust, and Ruby, and `meta.weight_patterns` teaches it anything bespoke. Nothing is hardcoded to one stack. --- ## Concepts `roadmap` has a small, deliberate vocabulary: | Term | What it is | |---|---| | **Roadmap** | The whole graph: every PI and sprint in `roadmap.yaml`. The map of *all* the work. | | **PI** *(Program Increment)* | A top-level initiative or epic. Groups related sprints; carries a status, dependencies, and exit criteria. | | **Sprint** | A unit of work inside a PI (`s1`, `s2`, ...). Carries its deps, the files it `touches`, a session estimate, a verification `gate`, and a kickoff brief. | | **Slice** | A sprint *as the thing you act on*, addressed by its stable `invoke` key (e.g. `auth-sessions`): "show me a slice", "fan out this slice." The slice is the atomic, **launchable** unit. | | **Wave** | The set of slices that can run **concurrently right now**: mutually dependency-free, sharing no files, under the cap. Within a wave, declared `priority` decides who gets a scarce cap slot. | | **Fanout** | Launching a wave. One git worktree plus Claude Code session per slice, plus an optional **lead** session that reviews and merges the resulting PRs. | | **Backlog** | The tracker beside the roadmap for **erratic work** — follow-ups, bugs, chores, urgent items that surface outside the plan. Items are directly launchable (`roadmap grab <id>`) or promotable into roadmap sprints (`roadmap promote <id> --pi <pi>`), cross-linked both ways. | | **Priority** | `{ tier: P0–P3, weight: 0–100, reason }` on any sprint or backlog item. Sort order is derived (tier, then weight), never stored — resorting is just editing the fields. | > **Roadmap = the planned feature/value work. Backlog = the erratic work. Slice = one launchable piece of either.** > You edit the **YAML**; you launch **slices** (by `invoke` key) and **backlog items** (by id). `SLICES.md` / `BACKLOG.md` are the human-readable renders, generated and never hand-edited. --- ## Quickstart ```bash # 1) one-time: install deps + put the `roadmap` CLI on your PATH git clone https://github.com/ConnorBritain/roadmap.git cd roadmap && npm install && npm link # 2) in any repo, author docs/roadmap/roadmap.yaml (see "The roadmap.yaml model") # 3) from ANYWHERE inside that repo (root or a subdir; the roadmap is auto-discovered): roadmap # interactive console: pick terminal / wave / cap, then launch roadmap plan # the text plan: recommended cap + what's runnable (no prompts) roadmap next # the single highest-priority ready thing across roadmap + backlog roadmap render # regenerate docs/SLICES.md (+ docs/BACKLOG.md when a backlog exists) roadmap validate # structural + cycle checks roadmap fan -w 1 # spin up wave 1 (lead + slice sessions); add -d to preview first # and the erratic-work loop: roadmap backlog add "wt adapter mangles quotes" -k bug --tier P0 --why "breaks every fanout" roadmap grab b1 # launch that one item in its own worktree + session roadmap promote b2 --pi auth # or fold a bigger one into the roadmap as a sprint ``` That's the whole loop: `cd` into a repo, type `roadmap ...`, it finds the roadmap and fires. ### Using it in Codex - Codex reads [`AGENTS.md`](AGENTS.md) from this repo automatically, so repo conventions live there now. - You can drive everything from the shared terminal with `npm run plan`, `npm run validate`, `npm run render`, or `node scripts/cli.mjs ...`. - `npm run mcp` starts the same MCP server the Claude plugin uses. - The fanout launcher still opens `claude` worker sessions today; the rest of the repo is usable from Codex directly. --- ## The three surfaces The same engine (`roadmap.yaml` plus the graph brain) driven three ways. ### 1 · The `roadmap` CLI (from your shell) Run from anywhere inside a repo. `docs/roadmap/roadmap.yaml` is found by walking up from your cwd, and every subcommand runs with cwd set to that repo root. Two ways to drive it: - **Interactive console.** Bare `roadmap` in a terminal opens a guided picker: terminal, then max concurrency, then wave, then lead?, then launch / preview / save. Walk the prompts with the arrow keys and hit Enter. Best when you want to *see* what's runnable and choose. (Piped or non-interactive, bare `roadmap` prints the text plan instead, so scripts and CI are unaffected; `roadmap go` forces the console.) - **Flag-fed.** Every choice as a flag: `roadmap fan -w 1 -c 2 -t wt`. No prompts, same outcome, for muscle memory, aliases, and scripts. | Command | What it does | |---|---| | `roadmap` / `roadmap go` | The **interactive console** (above). Hot-loads this repo's roadmap and walks you through the launch. Worker permission mode isn't asked here; it comes from `meta.worker_mode`. | | `roadmap plan [-c N] [--review-ceiling N] [--use-free-ram] [-j]` | **Recommended cap** (and what constrains it — CPU / RAM / work / review / disk), the execution **waves** (priority-ordered), and per-node launch commands. Spawns nothing. `-j/--json` emits the plan for tooling. | | `roadmap next` | The **single highest-priority ready thing** across the roadmap AND the backlog, with its pickup brief. Roadmap wins ties. Read-only. | | `roadmap show <name>` | One slice's detail: what / priority / stashed prompt / read-order / next / gate / branch. | | `roadmap set <name> f=v [...]` | Edit a slice's fields from the shell: YAML-scalar values (`priority='{tier: P1, weight: 60}'`), `f=@file` for multiline (prompts/briefs), `f=null` deletes. Same allow-list + pre-write gate as the MCP tools. | | `roadmap render [-c N] [-s]` | Regenerate `docs/SLICES.md` (+ `docs/BACKLOG.md` when a backlog exists) from the YAML (`-s/--stdout` prints SLICES instead of writing). | | `roadmap validate` | Structural, dependency, and cycle checks. Non-zero exit on error. | | `roadmap backlog [list\|add\|set]` | The erratic-work tracker: `add "title" [-k kind] [--tier PN] [--weight N] [--why reason] [--slice invoke]` (first add creates `backlog.yaml`), `set <id> f=v ...`, bare = priority-sorted open items. | | `roadmap grab <id> [-t term] [--dry]` | Launch **one backlog item** in its own worktree (`<root>/backlog-<id>`, branch `backlog/<id>`) with a synthesized kickoff brief (the item's `prompt` embedded). Marks it `in_progress`. | | `roadmap promote <id> --pi <pi> [--id sN]` | Promote a backlog item into a roadmap **sprint** (item id becomes the invoke key; title/est/gate/touches/prompt/priority carry; `promoted_to` back-links). Both YAMLs validated before either is written. | | `roadmap linear status\|auth\|setup\|provision\|sync\|post-update` | Optional **Linear** integration (see [Linear](#linear-optional--project-manage-from-linear-while-agents-execute)): `status [--probe]` state check, `auth` env-var instructions, `setup --team KEY` guided config, `provision` (labels + views + guidance texts), `sync [--dry] [--push-only] [--pull-only]`, `post-update --pi <id> --body <text>` (digest → project update). | | `roadmap review [--since <rev\|date>] [-j]` | The **date-anchored review digest**: shipped vs captured vs aging vs new PIs vs sprawl since `meta.last_review` (git-snapshot diff). The `/debrief` and `/retro` engine; works with zero Linear. | | `roadmap dispatch <key> [--to claude]` | Send one slice/backlog item to a **cloud agent** via its Linear issue (v0.5 seam, pending live verification). `roadmap fan --cloud` does the whole wave — no worktrees, no disk ceiling. | | `roadmap fan [-t wt\|warp\|tmux\|print\|background] [-c N] [-w N] [--track A] [--lead-claude] [-d] [-o file] [--worker-mode <m>] [--autonomous --yes-spawn-autonomous]` | Launch a wave: a lead pane/tab plus one per slice, each in its own worktree with a synthesized kickoff brief. **Launches by default**; `-d/--dry` or `-o/--out` to preview. `--track <lane>` fans out only the slices in that lane. Worker **and** lead sessions take `--permission-mode` from `meta.worker_mode` (falls back to `plan`); `--worker-mode` overrides per run. Terminal defaults per platform (win32 to `wt`, else `tmux`). | | `roadmap cleanup [-r] [-f]` | Prune fanout worktrees merged into the base branch and clean. **Dry by default**; `-r/--remove` acts; `-f/--force` includes unmerged/dirty. Only touches worktrees under the worktree root. | | `roadmap mcp` | Run the MCP server (stdio JSON-RPC) directly, for debugging or non-plugin registration. The plugin starts it for you. | | `roadmap watch` | Watch this roadmap's fanout PRs and print a line as each becomes ready / conflicts / merges. The plugin runs it as a monitor; this is the manual pane version. | | `roadmap sync` / `roadmap init` | Reserved on the CLI. Reconcile and bootstrap live as the `/sync` and `/init` **plugin skills** (surface 2). | Short flags (`-w -c -t -d -o -j -r -f -lc -wm`) expand to their long forms; positional slice keys pass through untouched. ```bash # See the plan + why the cap is what it is (the binding constraint is reported): roadmap plan # Concurrency cap: 5 (recommended) # bound by: review (PR review/merge bottleneck, soft ceiling) # machine: 24 cores, 59.6GB total / 20.6GB free # ceilings: 12 [CPU] · 13 [RAM] · 23 [work] · 5 [review] · 41 [disk] # Wave 1, 5 concurrent: [P0] auth-sessions, billing-invoices, search-index, ... roadmap fan -w 1 # launch: lead + one watched session per slice (default) roadmap fan -w 1 -d # preview the launch script, spawn nothing roadmap fan -w 1 -o wave1.sh # write the script to a file to inspect/run yourself roadmap fan -c 3 # override the recommended cap roadmap fan --autonomous --yes-spawn-autonomous # headless workers that commit/push/PR (double-acked) ``` **Safety.** `fan` launches by default, but an interactive launch just opens watchable panes (you're at the keyboard). Preview without spawning via `-d` or `-o`. The only unattended mode, `--autonomous` (headless `claude -p` that commits/pushes/PRs), additionally requires `--yes-spawn-autonomous`. **No launched session ever merges:** each opens a PR and stops; the lead (or you) merges. If `tmux` isn't on PATH (e.g. you're in PowerShell), `fan` prints the script and how to run it in WSL instead of failing. ### 2 · The Claude Code plugin (inside a session) Install it as a plugin (see [Install](#install)) and the roadmap becomes an *in-session* surface: slash-command **skills**, **agents**, and a startup **hook**. - **Skills** (`skills/*/SKILL.md`) - `/slice <key>`: orient on one slice (read-only) — what, priority, the stashed `prompt` (relayed verbatim), read-order, next action, gate, branch. With a prompt stashed, this is the whole pickup: slash command + slice name, nothing else. - `/sync`: reconcile statuses against merged PRs and the tracker, harvest PR-body "Leftovers" into proposed backlog captures, then re-render `SLICES.md`. - `/init`: a PM-style interview that bootstraps a `roadmap.yaml` (warm-start from existing docs, or cold). - `/fanout`: compute the waves and launch (wraps the same scheduler and adapters as the CLI). - `/backlog`: capture + triage erratic work — normalizes your dump into prioritized items, then offers `grab` or `promote` per item. - `/imagine`: divergent strategy interview on a live roadmap — vision drift, bets, risks/cuts — whose every conclusion lands **in the graph** (north-star pointer, new PIs, thin scheduled slices). `/init` bootstraps; `/imagine` re-plans. - `/prioritize`: convergent tier-by-tier triage of ready slices + open backlog with a forced reason per placement ("these two can't both be P1 — which ships first and why?"); source-aware (an item from a public Linear intake team is weighted knowingly); writes in one atomic `bulk_set`. - `/debrief`: the atomic lookback — date-anchored digest under hard high-signal rules, captain's-log entry in `docs/roadmap/REVIEWS.md`, anchor update. No graph mutations. - `/retro`: the full review-and-redirect ritual — debrief's lookback + per-bet double-down/kill/defer decisions applied to the graph + optional `/imagine` handoff. - **Hook** (`hooks/hooks.json`): a `SessionStart` hook injects the at-a-glance plus the current ready-wave and the backlog open-count, so a fresh session immediately knows what's runnable (and, on first run, installs the `yaml` dep). - **Agents** (`agents/*.md`): four specialized subagents Claude invokes across the roadmap, fanout, and review lifecycle. | Agent | Role | Read/write | Suggested model | |---|---|---|---| | **roadmap-bootstrapper** | Cold/warm-start: reads the repo's existing roadmap docs, tracker, sprint dirs, and `git log`, and **drafts a `roadmap.yaml`**. Used by `/init` to pre-fill before the interactive confirmation. | reads repo, proposes YAML | sonnet | | **slice-scoper** | Takes a thin `scheduled` slice and **fills it in**: infers `touches`/`owns` by grepping the code, drafts `read_order`, `est_sessions`, and the `gate`, and writes the sprint spec, turning it into a `next`-ready slice. | reads code, proposes slice fields | sonnet/opus | | **roadmap-auditor** | Read-only **drift and gap finder**: audits `roadmap.yaml` against reality (merged PRs, strategy docs, sprint dirs) and reports stale statuses and un-surfaced work. | read-only report | sonnet | | **wave-shepherd** | The **lead-pane brain**: after a fanout wave produces PRs, reviews each against its slice's gate and scope and recommends a safe **merge order** (respecting deps, flagging conflicts). Reviews; never merges. | read-only review | opus | The CLI and the plugin share the same scripts: the CLI is your *shell* entry, the plugin is the *in-session* entry. The interactive PM interview stays a **skill** (not an agent), because a forked subagent can't hold a back-and-forth with you. ### 3 · MCP (agent-callable) The plugin ships its own MCP server — named **`graph`** in `.mcp.json`, auto-started on install (plugin tool ids read `mcp__plugin_roadmap_graph__*`) — so an agent drives the roadmap with typed tools instead of shelling out and parsing text: - **Read:** `plan`, `ready_wave`, `show`, `validate`, `backlog_list` return structured JSON. - **Mutate (roadmap):** `add_pi`, `add_sprint`, `set_status`, `set_fields`, `bulk_set` (atomic multi-slice edit: one validate, one write, one render — all-or-nothing), `prune` edit `roadmap.yaml` through the YAML Document API (comments preserved), refuse any edit that would corrupt the graph (duplicate invoke key, unresolved dependency, cycle, bad priority/execution block), and re-render `SLICES.md` in the same step. - **Mutate (backlog):** `backlog_add` (creates `backlog.yaml` on first capture), `backlog_set`, and `backlog_promote` (spans both files: both validated before either is written). - **Linear:** `linear_status` (zero-network state check) and `linear_sync { dry, push, pull }` — always registered, politely erroring with setup guidance when `meta.linear` is absent. - **Cloud dispatch:** `dispatch { key }` fires one cloud session; `fan_cloud { wave, cap, confirm }` conducts a whole wave — **previews by default, fires only on `confirm: true`**, returning the session URLs. This is the conductor pattern: a local session plans the wave, fires cloud workers on its own plan (no worktree/disk), and reconciles their PRs via `/sync`. Launched worker sessions are told to file leftovers before opening their PR — `backlog_add` if the MCP is available, `roadmap backlog add` if the CLI is linked, else a **Leftovers** section in the PR body that `/sync` harvests. Mutators are natural `ask`-list entries in a consuming repo's `.claude/settings.json` (reads can be `allow`-listed). Separately, launched fanout sessions inherit whatever other MCP servers your repo already has wired, so a worker can drive your issue tracker or database while it works its slice. --- ## The roadmap.yaml model ```yaml meta: schema_version: 1 program: Q3-PLATFORM default_gate: | # inherited by sprints whose gate is 'default'/{{default}} npm test base_branch: main # worktree base + PR base (default main) remote: origin # git remote (default origin) terminal: tmux # default fanout adapter: tmux|warp|wt|background|print worker_mode: plan # launched sessions' --permission-mode: plan|auto|acceptEdits|bypassPermissions agent_cmd: "claude --permission-mode {mode} {prompt}" # optional: launch a different agent default_concurrency: 3 # Optional: teach the resource classifier a bespoke runner / override per-class cost weight_patterns: { heavy: ["my-e2e-suite"], medium: ["my-bundler"] } weight_cost: { heavy: { ram: 5, cores: 3 } } # Optional: the renderer cross-links these in SLICES.md (omit any you don't have) links: { narrative: ROADMAP.md, status: ../STATUS.md, tracker: roadmap/TRACKER.md } pis: - id: auth # stable; == branch slug title: Authentication status: active # active|next|scheduled|complete|blocked|paused|gated|optionality initiative: Launch readiness # optional; groups this PI's Linear project under a named Initiative priority: { tier: P1 } # optional; STRATEGIC → Linear project priority (not slice-derived) target_date: 2026-09-01 # optional; YYYY-MM-DD → Linear project target date sprints: - id: s1 title: Login flow status: complete invoke: auth-login # the slice key, stable, unique across the file prs: ["#42"] - id: s2 title: Session tokens status: active invoke: auth-sessions deps: [s1] # sibling sprint id | pi-id/sprint-id | a whole PI id est_sessions: 3 # focused sessions remaining (drives rollups + scheduling) touches: [src/session.ts] # files written; used for two-wave contention detection gate: | {{default}} PLUS the session integration tests read_order: ["docs/auth.md (the design)"] resume_action: Wire JWT issuance + refresh; thread through middleware. priority: # optional; sort is derived (tier asc, weight desc), never stored tier: P1 weight: 60 reason: launch blocker for the pilot prompt: | # optional author-stashed pickup instructions — embedded VERBATIM Start from the failing e2e test in tests/session.e2e.ts. # in the kickoff brief; shown Do not touch the middleware pipeline. # by /slice and roadmap show track: A # optional lane label (forward-compat with the three-track partition) execution: # optional per-slice staffing-strategy hint (see below) mode: agent-team concurrency: 5 min_concurrency: 4 team: - role: verifier - role: implementer count: 3 - role: reviewer rationale: "16 disjoint fault-class files; verifier-first; one reviewer reconciles." ``` - **`invoke`** is the slice key you launch with. Stable and unique across the file, so renaming a title never breaks a reference. - **`deps`** are the DAG edges; the exec-plan line and wave map are *derived* from them. - **`touches`/`owns`** mechanize the two-wave pattern: two ready slices that write the same file never share a wave; a convergence sprint just `deps`-on the divergent ones. - **`gated_on: <name>`** marks a human-gated slice. It never auto-schedules; it surfaces under "held on a human." - **`worker_mode`** sets the `--permission-mode` launched sessions start in; **`weight`** (`heavy|medium|light`) optionally overrides a sprint's inferred resource class. - **`agent_cmd`** templates every INTERACTIVE worker/lead launch (`{mode}` + `{prompt}` tokens) so fanout can spawn codex or any other CLI agent; the default reproduces today's claude command byte-for-byte. Autonomous headless launches stay claude. - **`priority`** (`{ tier: P0–P3, weight: 0–100, reason }`, all optional) decides who gets a scarce cap slot within a wave, badges the renders (`[P0]`), and drives `roadmap next`. Two unprioritized slices order exactly as before — an existing roadmap schedules and renders identically. - **`prompt`** is the stashed init prompt: `/slice <key>` relays it, the synthesized kickoff brief embeds it verbatim (`## 0.5 Author instructions`), and it's updatable as new info comes in via `roadmap set <key> prompt=@notes.md` or the `set_fields`/`bulk_set` tools. - **`execution`** declares HOW to staff the slice (see [Execution strategy hints](#execution-strategy-hints)); **`track`** tags the slice's lane for `--track`. ### Execution strategy hints Agents chronically **under-parallelize** — a lone subagent where a team fits, 2–3 workers where 5+ are fruitful, rarely reaching for Agent Teams. The optional per-slice `execution:` block lets the author *declare* the staffing so the launched session works at the intended topology instead of choosing by gut. **Every field is optional and backward-compatible: a slice that omits the block behaves exactly as before, and an existing `roadmap.yaml` validates and renders unchanged.** ```yaml execution: mode: agent-team # solo | subagents | dynamic-workflow | agent-team concurrency: 5 # suggested LIVE worker count min_concurrency: 4 # floor — /sync warns if a run used fewer on disjoint files team: # composition (omit for solo); roles: verifier|implementer|reviewer|researcher|integrator - role: verifier - role: implementer count: 3 - role: reviewer rationale: "16 disjoint fault-class files; verifier-first; one reviewer reconciles." ``` **Modes** (the topology rubric): | `mode` | When | What the directive tells the session | |---|---|---| | `solo` | Atomic, exploratory, or branching-sequential work. | Single agent, no fan-out. | | `subagents` | A scoped sprint: lead-merges + disjoint-file workers (the current default). | Spawn N background subagents per CLAUDE.md § Subagent Hand-off. | | `dynamic-workflow` | An in-slice pipeline whose steps depend on each other. | Run a step-gated pipeline; don't collapse it to one pass. | | `agent-team` | Many genuinely-independent file-clusters needing peer coordination. | Invoke Agent Teams now (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`) with the named count + composition. | The block renders as an **imperative directive** at the top of the slice's read-out — in `SLICES.md`, in `roadmap show` / `/slice`, and verbatim in each launched session's kickoff brief: ``` ▶ EXECUTION: agent-team — 5 workers (1 verifier · 3 implementers · 1 reviewer). The touched files are disjoint. DO NOT run solo or fewer than 4. Invoke Agent Teams now (set CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Rationale: 16 disjoint fault-class files; verifier-first; one reviewer reconciles. ``` **Validation** (`roadmap validate`) checks the enums (`mode`, `role`), the integer bounds (`concurrency`/`min_concurrency`/`count` ≥ 1), `min_concurrency ≤ concurrency`, and that a declared `team` head-count agrees with `concurrency` when both are present. When `execution` is absent or `concurrency` is unset, a *suggested* floor is computed from the slice's `touches` (the count of distinct disjoint top-level dir clusters, capped at 6) and surfaced as a hint — never a hard default. After a wave, `/sync` flags any slice that declared a `min_concurrency` floor, touches disjoint dirs, yet ran with fewer live workers (*"slice X ran 2 workers; min_concurrency 4 — under-parallelized"*). **`--track`** lets one person fan out only their lane: `roadmap fan --wave 1 --track A` keeps just the wave's slices tagged `track: A` (forward-compat with the three-track partition). --- ## The backlog (backlog.yaml) Roadmap work is planned, feature-driven, value-driven. But there's a second kind of work — follow-ups, necessary chores, trivial fixes, urgent/critical items — that **surfaces erratically** and needs a tracker, not a plan. That's `docs/roadmap/backlog.yaml`, rendered to `docs/BACKLOG.md` (priority-tier sections, untriaged last, in-progress / promoted / recently-closed tables). `SLICES.md` carries a one-line pointer with the open count. ```yaml meta: schema_version: 1 items: - id: fix-wt-quoting # stable slug; auto b1..bN when omitted at add title: wt adapter mangles prompts containing quotes kind: bug # bug | chore | followup | urgent | idea status: open # open | in_progress | promoted | done | dropped priority: { tier: P1, weight: 70, reason: breaks every Windows fanout } source: { slice: fanout-adapters, date: 2026-07-06 } # where it surfaced refs: [fanout-adapters] # related roadmap slices touches: [scripts/fanout.mjs] est_sessions: 0.5 gate: default # inherits the roadmap's meta.default_gate prompt: | # embedded verbatim in the grab kickoff brief Repro: roadmap fan -t wt with a prompt containing '"'. Fix the wtSafe escaping; add a run.mjs case. ``` **Capture** anywhere work surfaces: `/backlog` (in-session dump → normalized items), `roadmap backlog add` (shell), `backlog_add` (agents), or automatically at the end of a slice — every kickoff brief tells the worker to file leftovers before opening its PR, and `/sync` harvests any that landed as a PR-body "Leftovers" section instead. **Consume** by size: - **Small / self-contained** → `roadmap grab <id>`: its own worktree (`<root>/backlog-<id>`, branch `backlog/<id>`) and session, kickoff brief synthesized from the item (prompt embedded), item marked `in_progress`. - **Bigger / belongs in the plan** → `roadmap promote <id> --pi <pi>`: becomes a `scheduled` sprint (the item id becomes the invoke key; title/est/gate/touches/prompt/priority carry over) with a `promoted_to` back-link on the item. Both YAMLs are validated before either is written. - **Not sure what's next?** → `roadmap next` picks the single highest-priority ready thing across both trackers (roadmap wins ties) and prints its pickup brief. --- ## Linear (optional) — project-manage from Linear while agents execute Add `meta.linear` and the roadmap projects itself into Linear: **the YAML stays canonical; Linear is a projection plus a proposal inbox.** Humans see and steer the plan on a board; agents keep executing from the graph; nothing is written twice. ```yaml meta: linear: team: ENG # push target (team key). Auth = LINEAR_API_KEY env var, never a file. granularity: slices # pis (Projects only) | slices | slices+backlog — what leaks to Linear horizon: all # all | near — near keeps scheduled/optionality slices off the board until promoted verbosity: brief # title | brief | full — issue-description detail cycles: off # off | on — on mirrors the team's active cycle from slice status (active+next = this week's batch) history: off # off | window | full — whether DONE slices project as completed issues (progress % becomes real) stale_days: 3 # optional — flag committed work (active/next) with no journal note in N days ('stale' label + view) pull: propose # off | propose (walk the inbox in /sync) | auto status_map: { blocked: "Blocked" } # optional exact-name overrides; defaults map by state TYPE watch: # inbound sources — e.g. a public "Submit an issue" team - { team: PUB, project: "Submit an issue", kind: bug, priority: { tier: P3 } } ``` **Mapping.** PI ↔ Linear **Project** (grouped under an **Initiative** when `pi.initiative` is set) · slice / backlog item ↔ **Issue** · `priority.tier` P0–P3 ↔ Urgent/High/Medium/Low · `status` ↔ workflow state by TYPE (`active`→In Progress; `next`/held→Todo; `scheduled`/`optionality`→Backlog; `complete`→Done; `status_map` overrides by name) · `est_sessions` → the issue's native **estimate** (rounded to an integer, clamped to `estimate_max`) — a sortable board column, not prose. Issue ids are written back into the YAML (`linear: ABC-123`) — the mapping's source of truth survives any machine. **Project enrichment.** A PI's project carries a rich `content` body (the full theme + exit criteria + deps — the uncapped project doc, so nothing truncates) and a concise `description` subtitle (the exit's first sentence). Optional `pi.priority` (a **strategic** tier, *not* derived from slice heat — an urgent slice shouldn't hijack a PI's ranking) → the project's Linear priority; optional `pi.target_date` (`YYYY-MM-DD`) → its target date. Every project also gets a **color + icon by initiative** (same initiative → same hue + glyph), so the board reads as grouped lanes instead of Linear's random per-project assignment. Declare meaningful styling in `meta.initiatives` (`{ <name>: { icon, color } }`, e.g. `Lumen: { icon: WritingAI }`, `Trust surface: { icon: Shield }`) so grouping is *signal* rather than a coincidence of first-seen order — a declared initiative also gets its **header** styled to match. Undeclared initiatives keep Linear's default header, and their projects use the deterministic fallback palette. Icon names are a fixed Linear set pushed best-effort — an unrecognized name degrades to "no icon" (color still groups) rather than failing the sync. `validate` warns when a `meta.initiatives` entry names an initiative no PI references (a typo, or a half-applied rename). **Estimates & the split-don't-extend rule.** `est_sessions` rides the issue's native estimate field, so session cost sorts and rolls up on the board. Set your Linear team to the **Linear scale** (`1..5`) for a direct 1-point = 1-session read (Fibonacci/T-shirt would distort it), and leave `meta.linear.estimate_max` at its default `5`. `validate` warns when a slice's estimate exceeds the max — the deliberate signal to **split** an oversize slice, not extend the scale: a slice bigger than one agent session isn't a slice. (Raise `estimate_max` to `7` only if you genuinely extend the team's scale.) **Milestones — stages within a project.** A slice can carry `milestone: "<stage>"` (e.g. `harness` / `hardening` / `ship`); the sync creates the distinct milestones on the PI's Linear project and attaches each issue, turning a project's flat issue list into legible stages on the roadmap/timeline view. Milestones are **project-scoped** (the same name under two PIs is two milestones) and entirely opt-in — no `milestone` fields anywhere → the milestone sync is a no-op. Idempotent (skips existing milestones by name, re-attaches an issue only when its stage drifts) and best-effort (a `projectMilestone` API rejection is a skip, not a failure). **The plate — Linear's "My Issues" as your active-work hopper.** Assigning *everything* to yourself is no signal; instead `meta.plate` is a curated list of slice/backlog keys the sync assigns to **you** (Linear's built-in My Issues tab = `assignee: you`). So initiatives/projects/views answer "how's the whole effort" at their tiers, and My Issues answers "what's on my desk right now." The live plate is `meta.plate` **∪ whatever you're actively working** (active slices, `in_progress` items) — so starting work always surfaces it. Curate it with `roadmap plate add|rm|set|clear` (or a planning skill), and completed slices **auto-drain** on the next sync (blocked ones stay as a reminder). Each assigned issue carries a `plate` label, so a hand-assignment you make directly in Linear is never disturbed. `meta.linear.plate_max` (default 7) keeps the explicit list signal-rich; the feature is entirely off until `meta.plate` exists. **The journal — a progress trail on each issue, so in-flight work survives a dead session.** The plate makes work *visible* on My Issues; the journal makes it *resumable*. As an agent works a slice it posts notes to the mapped issue's comment stream — `roadmap linear note <key> "…" [--kind progress|blocker|done]` (or the `issue_note` MCP tool) — at checkpoints (a gate cleared, a blocker hit, session end). On pickup, an agent reads the stream first (`roadmap linear notes <key>` / `issue_notes`), so a session that died mid-flight is picked up from where it left off, not from zero — the kickoff brief and dispatch guidance both instruct this loop. A **session-end `Stop` hook** also auto-posts a **git-derived snapshot** (branch · recent commits · uncommitted paths) whenever the current branch maps cleanly to a mapped slice with real work — best-effort and heavily guarded (not a roadmap repo / no key / not a slice branch / nothing to report → silent no-op), so it never blocks or slows a session. PI-level rollups go to the project update (`roadmap linear post-update` / `project_update`). All of it is written tracker-neutral, so a future `jira.mjs` mirrors it. **Push** (`roadmap linear sync`, or automatically inside `/sync` when authed): diff-based and idempotent — an unchanged roadmap sends zero ops. Descriptions follow the `verbosity` lever, never copy read-order/prompt, and always end with a machine footer (`roadmap: slice=<invoke> · pick up: /slice <invoke>` + a SLICES.md link) — so an agent dispatched *from Linear* (via Linear's own agent delegation or hosted MCP) self-orients in one command. Set `branch_convention: "{pi}/{linear}-{sprint}"` and Linear auto-links every fanout PR to its issue. **Pull.** New issues in `watch` sources become **proposed backlog items** carrying `source.linear: {team, project, issue}` — so `/prioritize` can weight work by where it came from (a public intake team ≠ a maintainer capture), with the watch's default `priority` as the implicit weighting. Edits to mapped issues (state/priority changes made in Linear) become proposed deltas. With `pull: propose` (recommended), `/sync` walks the inbox with you — keep / edit / skip per item; nothing enters the graph unconfirmed. The sync cursor is per-machine (`.roadmap-linear-state.json`, git-ignored) and only advances once the inbox is handled, so unhandled proposals reappear rather than vanish. **Detection is graceful.** No `meta.linear` → every Linear behavior is off and the tool is byte-identical to before. Configured but no `LINEAR_API_KEY` → one advisory line, everything else works. The session-start hook reports state with zero network; `roadmap linear status --probe` is the only networked check. Bootstrap: `roadmap linear auth` (key instructions) → `roadmap linear setup --team <KEY>` → `roadmap linear sync --dry`. **Per-PI override.** A PI can set its own `linear.granularity` (e.g. keep an internal PI's slices off a shared board) or `linear.verbosity` (quiet a noisy PI's issue descriptions to `title`, or richen an active one to `full`). Creating one that conflicts with the global requires an explicit `yes_linear_override: true` ack — otherwise the mutation is rejected with instructions and nothing is written; `roadmap validate` warns on stored mismatches. ### Topology: Linear as the board The recommended workspace shape at agent scale: **one team per actively-managed repo** (dispatch routing is deterministic, workflow states and `status_map` compose 1:1, and the issue identifier tells you the repo), **PIs = Projects, slices/items = Issues, native priority = tier**, plus **one shared intake team** (a public "Submit an issue" board) wired as a `watch` source. Repos not under agent management get no team. `roadmap linear provision` shapes the workspace idempotently: creates the labels the graph knows (`roadmap` marker on every synced issue, `kind:*` for backlog items, `track:*` for the lanes present, `status:*` for held work), the standard views (**Ready wave · In flight · Held on human · Backlog triage · Recently shipped** plus a **Track X** view per lane; view API rejection degrades to a manual checklist), and prints two guidance texts — the workspace agent guidance and the **repo dispatch contract** for `CLAUDE.md`/`AGENTS.md`. Projects carry PI theme + exit criteria as descriptions. **A clean board, not a wall.** The projection is honest and navigable, not a 1:1 dump: - **Empty projects are skipped.** A PI whose slices are all shipped doesn't create a bare 0-issue project (already-mapped projects stay in sync). - **Project names are the PI headline.** A title authored `Headline — subhead` projects as just **Headline**; the subhead moves into the description. No context lost, no tacky names. - **Only `active` shows In Progress.** Held work (`blocked`/`paused`/`gated`) maps to Todo with a `status:<held>` label, so the board's In-Progress count means real live work and the "Held on human" view filters the rest. (The pull inbox also suppresses the round-trip echo, so held slices don't generate false status proposals every sync.) - **Initiatives group the projects.** A PI declares `initiative: <name>` and sync creates the Linear Initiative (the tier above projects) and attaches the PI's project — turning a flat wall of projects into a handful of strategic groups you can steer. *(The initiative API is behind graceful degradation, pending live verification.)* ### Cloud dispatch `roadmap dispatch <key>` sends one slice/backlog item to a **Claude Code cloud session** — the default `claude-cloud` transport fires the Routines API directly (**no Linear plan required, no worktrees, no disk ceiling**; bounded only by the firing account's Claude plan). Multi-account workstations hot-swap automatically: routine credentials live in `~/.claude-routines.json` keyed by account email, and dispatch fires as **whoever is currently `claude /login`'d** (see [DEPLOYMENT.md § Cloud dispatch](docs/DEPLOYMENT.md)). When the slice is also Linear-mapped, the session URL is commented onto the issue — the board links to the live session. ⚠ Routines fire is a beta API. `roadmap fan --cloud` does it for a whole wave; the cap defaults to the review ceiling (machine ceilings vanish, but a human still merges). The alternative `--to claude|codex|oz` transport posts an @-mention capsule comment on the Linear issue instead — useful when the workspace has that agent's integration installed (Linear's native coding sessions are paid-plan-gated). --- ## Estimation & timeline (optional) — pairs with [agent-time](https://github.com/ConnorBritain/agent-time) `target_date` is the one roadmap date that's usually a guess. [**agent-time**](https://github.com/ConnorBritain/agent-time) — a local-first estimation skill — prices a task in calibrated *agent-rounds → wall-clock minutes* (never human hours) and self-corrects from logged outcomes. Wire it in and the roadmap turns those durations into a **projected timeline**: - **`roadmap estimate <slice|--all>`** tags each classified slice (`shape` + optional `risks`) with a cached `estimate` (low/expected/high minutes + confidence). Idempotent; `--force` refreshes. An unclassified slice is skipped, not guessed. - **`roadmap estimate timeline`** rolls those durations up along the **same wave / dependency / concurrency schedule the fanout actually runs** — a wave counts as its slowest slice, waves accumulate — into a `projected_target_date` per PI. That fills Linear's `targetDate` wherever you haven't set an explicit commitment (**an explicit `target_date` always wins**). Honesty is enforced at the date, not just the report: an **unpriced** slice *suppresses* its PI's date (a PI is dated only when every remaining slice is estimated), and **blocked/gated** slices are excluded as a labelled optimistic frontier — both are surfaced, never folded into the number as a silent zero. - **`roadmap estimate log <slice> --status pass|fail|partial|abandoned`** closes the **calibration loop** — it records the slice's outcome to agent-time so the next estimate self-corrects. Idempotent per estimate (safe to re-run). The journal Stop-hook fires it automatically when a mapped slice finishes. Actual rounds/minutes auto-fill **only if agent-time's round-counter (`PostToolUse`) hook ran in that session** — otherwise pass `--actual-rounds N` (agent-time rejects an outcome with no actuals). Enable that hook per-repo from agent-time's `hooks/README.md` to make auto-calibration real. - `estimate`, `timeline`, and `estimate_log` are also **MCP tools**, so a session picking up or finishing a slice can drive them in-band. Config lives in `meta.estimation` (`engine` path, `hours_per_day` throughput, `expected|high` point). **agent-time itself is untouched** — the roadmap is just another caller of its `estimate --json` CLI. Install the [`agent-time-estimator`](https://github.com/ConnorBritain/agent-time) skill (or set `meta.estimation.engine`) and the default resolution finds it. The two are built to work hand-in-hand: the same calibrated numbers that size one task plan the whole program. --- ## Riding the wave: discipline + the review ritual Two second-order effects of agent-scale work, both encoded: **Sprawl curbing (advisory, never blocking).** Helpful agents love filing follow-up scope; unchecked, every sprint spawns two backlog items and a sibling sprint. The kickoff brief now hard-forbids worker sessions from adding sprints/PIs (leftovers go to the **backlog only**; "YAGNI applies to captures too"), the `add_sprint`/`add_pi` tool descriptions carry the same scope-discipline nudge, and `/sync` + the review digest surface **sprawl warnings**: a capture ratio ((captured items + added sprints) per completed slice, threshold `meta.discipline.capture_ratio`, default 2) plus an unconditional flag on any PI that appeared since the last review. **Coherence wave packing.** Under a cap, the scheduler now prefers **finishing started PIs over opening fresh ones** (then closest-to-done first) — strictly *below* declared priority, so a P0 in a fresh PI still wins. Same-PI siblings fill the cap contiguously, `roadmap plan` prints `(closes auth)` on waves that finish a PI, and the digest reports **PIs in flight** (the fragmentation count). Opt out with `meta.discipline.coherence: false`. **The review ritual — three modalities.** This is how the human stays in control of the deluge: - **`/debrief`** — atomic lookback, **no graph mutations**: `roadmap review` diffs the graph against the date-anchored snapshot (`meta.last_review.commit`, via `git show`) and the skill presents it under hard style rules (≤15 lines; recommendations in "X instead of Y" form, tied to the north star; agent-originated scope named; no cheerleading), then logs a ≤10-line hand-authored entry to `docs/roadmap/REVIEWS.md` and re-anchors. - **`/imagine` + `/prioritize`** — the forward atomics (strategy interview; tier triage with forced reasons). - **`/retro`** — the composition: the debrief lookback, then per-bet **double-down / kill / defer** (every kill names what the freed sessions buy; every sprawl-flagged sidequest gets an explicit keep-or-drop), decisions applied through the mutation tools, optional `/imagine` handoff, and the close covers the decisions. When Linear is wired, the digest posts as project updates (`roadmap linear post-update`). `roadmap review [--since <rev|date>] [--json]` is the engine: shipped vs captured vs aging vs new PIs vs sprawl, computed from git history — works with zero Linear. --- ## Feasibility pre-checks (the disk ceiling) Fanning out N worktrees costs real disk. `roadmap plan` / `fan` / `grab` estimate the per-worktree cost (the tracked tree's size × 1.3, or `meta.worktree_gb` when your gates install `node_modules`/build artifacts per worktree — that's the calibration knob) and compare it against free space on the volume holding `meta.worktree_root`. Disk joins CPU / RAM / work / review as a **fifth ceiling**: the recommended cap auto-dials down and the plan reports `bound by: disk (need ~X GB/worktree, Y GB free)`. When even **one** worktree won't fit, `fan` and `grab` refuse to launch before creating anything. If the environment can't be probed (no git HEAD, unsupported statfs), the ceiling silently drops out — never blocking a plan on a failed probe. --- ## Install > **Full deployment guide** — every surface (CLI, Claude Code plugin, standalone MCP, Claude Desktop, Codex, CI), exactly where config vs. secrets live, Linear setup per environment, and the planned Jira shape: **[docs/DEPLOYMENT.md](docs/DEPLOYMENT.md)**. The short versions follow. ### The `roadmap` CLI ```bash git clone https://github.com/ConnorBritain/roadmap.git cd roadmap && npm install && npm link ``` `npm link` puts `roadmap` on your PATH in every shell. On Windows it writes `roadmap.cmd`/`roadmap.ps1` shims (PowerShell and cmd) plus a unix bin (WSL/bash; run `npm link` once in each Node environment you use). `npm unlink -g roadmap` removes it. ### In Codex No plugin install is required. Open the repo in Codex, use the commands above, and rely on [`AGENTS.md`](AGENTS.md) for repo-local guidance. For MCP usage in agent environments, run: ```bash npm run mcp ``` The checked-in [`.mcp.json`](.mcp.json) remains the Claude-plugin entrypoint (server name `graph`). **Alias fallback (no npm):** drop a shim in your shell profile instead. ```powershell # PowerShell, $PROFILE function roadmap { node "$HOME\Code\roadmap\scripts\cli.mjs" @args } ``` ```bash # bash/zsh, ~/.bashrc / ~/.zshrc roadmap() { node "$HOME/Code/roadmap/scripts/cli.mjs" "$@"; } ``` ### As a Claude plugin The repo is its own marketplace (`.claude-plugin/marketplace.json`). Add it, then install: ```bash # from a GitHub clone: claude plugin marketplace add ConnorBritain/roadmap # or from a local checkout: claude plugin marketplace add /path/to/roadmap claude plugin install roadmap@roadmap # user scope; --scope project to pin per-repo ``` That wires the skills, agents, the SessionStart hook, the PR-watch monitor, and the MCP server in one step (new sessions pick them up; `/mcp` reconnects the current one). The plugin bundles its MCP via `.mcp.json` as `graph`, so don't also `claude mcp add` a second copy of the server. ### Upgrading from `slice-roadmap` (≤ 0.1.x) The plugin, marketplace entry, and npm package were renamed **`slice-roadmap` → `roadmap`** (and the bundled MCP server `roadmap` → `graph`) in 0.2.0. Old installs won't auto-update — migrate once: - **npm:** `npm unlink -g slice-roadmap`, then `npm link` again from the repo (per Node environment). The `roadmap` bin name itself is unchanged. - **Plugin:** `claude plugin uninstall slice-roadmap`, re-add the marketplace, `claude plugin install roadmap@roadmap`. - **⚠ Permission allow-lists:** any `settings.json` entries naming `mcp__plugin_slice-roadmap_roadmap__*` tools **silently stop matching** — rewrite them as `mcp__plugin_roadmap_graph__*`. - **Skills:** `/slice` is unchanged; `/slice-sync` → `/sync`, `/slice-init` → `/init`, `/slice-fanout` → `/fanout` (plus new `/backlog`). - **Env:** the api-lane variable is now `ROADMAP_API_KEY` (was `SLICE_ROADMAP_API_KEY`). - **Generated files:** the first `roadmap render` after upgrading rewrites SLICES.md boilerplate with the new skill names — a one-time diff. ### Recommending it in a consuming repo Don't commit a device-specific alias into a repo. Point contributors at this tool from your onboarding docs (e.g. a CONTRIBUTING note): *"Drive the roadmap from your shell. Clone `roadmap`, `npm install && npm link`, then run `roadmap` from anywhere in this repo."* A consuming repo only ever carries its own `docs/roadmap/roadmap.yaml` and `backlog.yaml` (plus the generated `SLICES.md` / `BACKLOG.md`). --- ## What's built - **Graph brain** (`graph.mjs`): dependency resolution (sibling / fully-qualified / whole-PI deps), cycle detection, wave scheduling with two-wave file-contention + priority-first cap packing, sessions-remaining and exec-plan derivation. - **Priority** (`lib/priority.mjs`): the shared tier/weight/reason model — validation, the derived comparator, tier badges. - **Backlog** (`lib/backlog-core.mjs` + `backlog.mjs`, `grab.mjs`, `promote.mjs`, `next.mjs`): the erratic-work tracker — capture/triage/launch/promote, `BACKLOG.md` rendering, the item→node adapter that reuses the fanout brief machinery, and cross-tracker pick-next. - **Renderer** (`render.mjs`): hierarchical `SLICES.md` (per-PI sections, nested sprint tables, priority badges, derived exec-plan lines, cross-PI wave map, held-on-human, backlog pointer) + `BACKLOG.md`. - **Scheduler** (`scheduler.mjs`): recommended-cap eval (CPU / RAM / independent-work / review / **disk** ceilings, reporting which binds) plus the waves. - **Fanout** (`fanout.mjs`): `tmux`, `wt`, `warp`, `print`, `background` adapters; per-slice worktree plus synthesized kickoff brief (stashed `prompt` embedded, leftover-capture instruction); disk hard-block; the interactive console (`wizard.mjs`); guarded launch (`--dry`/`--out` preview, autonomous double-ack); `cleanup.mjs` worktree pruning. - **Shared mutation store** (`lib/store.mjs`): the one read → mutate → validate → write → re-render path under every mutating surface (MCP, `set`, `backlog`, `promote`), including the validate-both-before-writing-either two-file promote. - **Plugin surface**: five skills (`slice`, `sync`, `init`, `fanout`, `backlog`), four agents, and a `SessionStart` hook (ready wave + reconcile nudge + backlog count). - **MCP server** (`mcp.mjs`, server `graph`): a bundled, hand-rolled JSON-RPC stdio server with read tools (plan / ready_wave / show / validate / backlog_list) and comment-preserving, schema-validated mutate tools (add_pi / add_sprint / set_status / set_fields / bulk_set / prune / backlog_add / backlog_set / backlog_promote) that re-render the generated views on every edit. - **PR-watch monitor** (`watch-prs.mjs` + `lib/pr-watch-core.mjs` + `monitors/monitors.json`): polls `gh` for the fanout branches and notifies the lead on each PR phase transition. - **Tests**: `npm test` runs the zero-dependency suite over the pure brain (graph, recommender + disk ceiling, priority, backlog, brief, plan, render, validate, CLI core, wizard core, MCP core, PR-watch core). The resource classifier matches build/test runner commands, not languages. It ships patterns for the common runners (`npm`/`yarn`/`pnpm`, `jest`, `vitest`, `tsc`, `pytest`, `tox`, Maven, Gradle, `make`, CMake/CTest, `go`, `cargo`, and more), ordered by how common they are, and `meta.weight_patterns` teaches it any bespoke runner. ## Requirements & license Node 18.15+ (for `fs.statfsSync`, the disk pre-check) and a one-time `npm install` (for the `yaml` parser). MIT licensed.