masterplan

masterplan

A Claude Code & Codex CLI plugin for durable multi-hour engineering work — brainstorm → plan → execute → finish on top of obra/superpowers skills.

Current release: v9.1.1 · License: MIT · Works with: Claude Code, Codex CLI · See CHANGELOG.md

---

What is masterplan

masterplan provides the /masterplan slash command. It orchestrates a brainstorm → plan → execute → finish development lifecycle on top of the obra/superpowers skills suite.

The core design principle: state lives on disk, not in the chat session. A run bundle at docs/masterplan/<slug>/ is the single source of truth. The orchestrator sequences decisions; all real work is delegated to short-lived subagents that return digests, never raw logs. If the session crashes, compacts, or is cleared, /masterplan re-reads the bundle and picks up exactly where it left off.

---

The Four-Phase Lifecycle

brainstorm  →  plan  →  execute  →  finish

Phase	What happens
brainstorm	Codebase discovery; spec.md authored and reviewed
plan	spec.md → task decomposition → plan.index.json + plan.md
execute	Wave-by-wave task dispatch; each wave is one workflow launch
finish	Verification → retro.md → branch-finish gate → archive

The state.yml phase field holds the enum brainstorm|plan|execute. finish is a terminal finalization flow that fires automatically when the last execute wave completes — it is not a phase value.

---

Architecture

masterplan v8 is a five-layer system. Each layer delegates downward and never writes state on behalf of the layer above it.

┌─────────────────────────────────────────────────────────────┐
│  L0 — Run bundle (disk)                                      │
│  docs/masterplan/<slug>/state.yml  spec.md  plan.md          │
│  plan.index.json  events.jsonl  retro.md  handoff.md         │
└───────────────────────┬─────────────────────────────────────┘
                        │ read / atomic write (CD-7)
┌───────────────────────▼─────────────────────────────────────┐
│  L1 — Thin shell                                             │
│  commands/masterplan.md  (~800-line verb sequencer)          │
│  bin/masterplan.mjs  (mp — filesystem-only subcommands)      │
│  lib/resume.mjs  (pure decideNextAction)                     │
│  ← SOLE durable state writer; git commit/checkout live here  │
└───────────────────────┬─────────────────────────────────────┘
                        │ launch + receive digests
┌───────────────────────▼─────────────────────────────────────┐
│  L2 — Workflow engine                                        │
│  workflows/execute.workflow.js  (one wave per launch)        │
│  workflows/plan.workflow.js     (subsystem fan-out)          │
│  lib/plan-merge.mjs  lib/dispatch/  lib/wave.mjs             │
│  ← returns digests/fragments only; never writes disk/git     │
└───────────────────────┬─────────────────────────────────────┘
                        │ bounded briefs / structured digests
┌───────────────────────▼─────────────────────────────────────┐
│  L3 — Agents                                                 │
│  agents/mp-explorer.md        agents/mp-implementer.md       │
│  agents/mp-planner.md         agents/mp-codex-reviewer.md    │
│  agents/mp-plan-reviewer.md   agents/mp-subsystem-planner.md │
│  agents/mp-spec-decomposer.md                                │
│  ← no session history; return structured output only         │
└───────────────────────┬─────────────────────────────────────┘
                        │ node bin/doctor.mjs
┌───────────────────────▼─────────────────────────────────────┐
│  L4 — Doctor                                                 │
│  bin/doctor.mjs  dispatcher                                  │
│  lib/doctor/*.mjs  (14 check modules, auto-discovered)       │
│  ← Finding {id, severity, summary, fix}; non-zero on ERROR   │
└─────────────────────────────────────────────────────────────┘

Key invariants:

• L1 (commands/masterplan.md + mp) is the only durable state writer (CD-7). All state mutations go through mp subcommands; L2 and below never commit to git or write state.yml.
• bin/masterplan.mjs is filesystem-only — git (commit, checkout, clean) is the shell's job.
• L2 workflows communicate via args on launch and return digests in the completion notification.

---

Installation

Claude Code

Run inside the Claude Code CLI:

/plugin marketplace add rasatpetabit/masterplan
/plugin install masterplan@rasatpetabit-masterplan
/reload-plugins

The marketplace commands register the catalog and install the masterplan-detect skill. The upstream superpowers core plugin is declared as a dependency and will be automatically resolved. See docs/install.md for offline, desktop-app, or manual installation paths.

Codex CLI