phased

phased

Break a big feature into phase documents, then let Claude implement them in order, automatically. Each phase runs in its own fresh subagent (so phase 1's forty file-reads never bloat phase 2's context), and no phase counts as done until your build + tests actually pass. Start it, walk away, come back to green.

Install

You need Claude Code ≥ 2.1 and jq (brew install jq / apt install jq).

Option A — try it for one session (nothing installed):

git clone https://github.com/RaynLight/phased.git
claude --plugin-dir /path/to/phased

Option B — install it properly (persists across sessions; this repo doubles as its own marketplace):

claude plugin marketplace add RaynLight/phased    # or a local path
claude plugin install phased@phased

Then restart your session so the hooks register. Update later with claude plugin update phased.

Verify it's wired up:

1. /phased:status answers (with "no phased run here" in a fresh project).
2. /hooks lists the phased SubagentStart / SubagentStop / Stop entries.
3. Optional but recommended: enable the status bar (see Watching progress) for live workers and per-phase cost.

Quick start

1. In your project, run /phased:init my-feature — creates phases/phase-01.md from the template below.
2. Write one markdown file per phase — phase-01.md, phase-02.md, … (zero-padded so they sort). Phases run strictly in file order and later phases can build on earlier ones, so each needs a clear Definition of Done. Mark batch-shaped phases with an optional Mode: workflow line.
3. Not a Go project? Set your gate first — e.g. export PHASED_GATE="npm run build && npm test" (see Configuring the gate).
4. /phased:run — then walk away. Each phase runs in its own fresh agent, the gate blocks anything that doesn't build and pass tests, and the board shows live progress, workers, and cost.
5. Come back to a ✓-per-phase summary. Interrupted or failed? /phased:run again — it resumes where it stopped and retries failed phases.

How it works

The lead session loops over your phase docs in order. Each phase is handed to a fresh phase-orchestrator subagent, and every time that subagent tries to finish, a SubagentStop hook runs your build + test gate — blocking the return until the gate is green. Progress lives in .phased/state.json, written by the hook script, never by the model's self-assessment. Interrupted? /phased:run resumes where it left off.

Inside a phase, the orchestrator can deploy its own subagent workers when the work splits into independent pieces. For batch-shaped phases, add a Mode: workflow line to the phase doc: the lead then runs a true dynamic Workflow over the pieces (the Workflow tool only exists at the lead level — subagents can't host it) and hands the results to the orchestrator, which verifies, integrates, and faces the gate as usual. Either way, SubagentStart/SubagentStop hooks track the workers in state.json, so the status line shows what a phase is working on right now, and the list collapses automatically at each phase boundary.

Who does what:

• Lead (the director) — sequences phases, maintains the on-screen board, and carries short cross-phase summaries forward. It never reads your source and never implements — it stays cheap.
• phase-orchestrator (one per phase, fresh context) — a full Claude Code agent (inherits your session's model, effort, and entire toolset) that reads its phase doc, implements it, fans out workers when the work splits, and cannot return until the gate is green.
• Workers — disposable subagents or workflow agents, one independent piece each.
• gate.sh (not an agent) — deterministic shell run by hooks, and the only writer of phase verdicts. It cannot be talked out of a red build.

Everything on disk lives in .phased/: state.json (progress — the source of truth), cost.json (per-phase $, recorded by the statusline), gate.log (latest gate output), and active (run-in-progress sentinel). Delete the directory for a clean slate.