slice-roadmap

Roadmap: scope, manage, and orchestrate Claude Code sessions in any repo

roadmap is a CLI and a Claude Code plugin. It turns one YAML file into your repo's plan of record (a hierarchical, dependency-aware graph), then fans that plan out into parallel Claude Code sessions, each scoped to a single unit of work in its own git worktree.

• One source of truth. docs/roadmap/roadmap.yaml holds the PIs, sprints, deps, file-ownership, session estimates, gates, and kickoff briefs.
• Generated view. docs/SLICES.md is rendered from the YAML; never hand-edit it.
• Derived, never stored. Per-PI exec-plan lines ((S0 ∥ S1)→S2→S3), the cross-PI "ready now" wave map, and "sessions remaining" rollups are all computed from deps + touches + status.
• Deterministic fanout. A scheduler decides which slices can run concurrently under a cap (which it recommends from a CPU/RAM and review eval), then launches each in its own worktree and Claude Code session.
• 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.
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.

Roadmap = the whole plan. Slice = one launchable piece of it. You edit the roadmap (the YAML); you launch slices (by invoke key). SLICES.md is the human-readable render of the roadmap, generated and never hand-edited.

---

Quickstart

# 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 render     # regenerate docs/SLICES.md
roadmap validate   # structural + cycle checks
roadmap fan -w 1   # spin up wave 1 (lead + slice sessions); add -d to preview first

That's the whole loop: cd into a repo, type roadmap ..., it finds the roadmap and fires.

---

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.