智能工作流

Required successors

An intent_rejected:<class> archive writes required_successor {slug, reason} (slug from the mandatory --successor flag; a rejection without it is refused before any event is written). mp runs list and mp status print the open obligation with the exact seed command (mp seed --predecessor=<slug>); for class intent, the stored correction text opens the successor's interview as quoted context. The required-successor doctor check verifies the obligation resolves to a seeded bundle.

Installation

Usage / Quick Start

Start a new run end-to-end:

/masterplan full <topic>

Start step-by-step:

/masterplan brainstorm <topic>   # discovery + spec
/masterplan plan                 # decompose spec into tasks
/masterplan execute              # wave-by-wave execution

Resume after a crash or clear:

/masterplan                      # bare — re-reads bundle, continues

Check run health:

/masterplan status               # active bundle summary
/masterplan doctor               # structural lint (24 check modules)

---

Configuration

Configuration resolves through a four-layer hierarchy — CLI > repo > user > default (lib/config.mjs, resolveRunConfig):

1. CLI — mp seed / mp continue flags win over everything.
2. Repo — .masterplan.yaml at the repository root.
3. User — ~/.masterplan.yaml in the home directory.
4. Default — the schema default when no layer sets the value.

Each recognized key is validated against the schema enum and its source layer is reported (config show prints the resolved values and *_source for every key). done and context_watch support whole-object replacement with partial context_watch defaults; auto_compact is a deprecated alias for context_watch (both present → refused). Unsupported keys are warned and ignored; a malformed file or an invalid enum value is a hard error — a value never silently falls through to a lower layer.

Recognized config keys (schema CONFIG_SCHEMA):

Seed-time flags (mp seed, persisted into state.yml at run creation): --complexity, --autonomy, --planning-mode, --adversary-review=on|off (alias --codex-review), --render-images=on|off, --fabric=on, --overlap-review=<json> (required — see Overlap below), --predecessor=<slug>. mp continue accepts --planning-mode on the command line and resolves it through the same chain.

Definition of done (done) — deploy groups run in a fixed order across release → install → user_only → live_check (DEPLOY_GROUP_ORDER in lib/finish.mjs): every release step runs first, then every install step, then user_only, then the live_check run. Group order is normative; within a group, steps run in their list order. A done: none definition deploys nothing. version_from points at a version-bearing file (e.g. .claude-plugin/plugin.json) and ${version} is substituted into release commands. Deploy steps are recorded via mp finish-step --deploy-step-done=<group>[<index>] --exit=<code>; a failing step opens a hard gate.

Review config (mp set-review-config, a CD-7 write on an existing bundle — not a seed flag; alias: mp set-codex-config): --review=true|false arms/disarms state.review.adversary; --routing=auto|on|off is the legacy per-task dispatch default.

Environment

Every readEnv-backed control — set these in the environment, not in config files (the seam is readEnv/readEnvAll in bin/masterplan.mjs; env.X property reads in bin/ + lib/ go through the same seam):

mp context-status reports the measured context window (tokens_at_last_request, appended_est, window) and one of current / post-compaction / malformed / not-found / unsupported (lib/context-status.mjs; not-found when no transcript resolves, unsupported when there is no session id). When no measurement is available (not-found / malformed / unsupported) the reported window is null and used_pct is null — there is no unknown state. MP_CONTEXT_WINDOW overrides the window (or --window=<n> explicitly). mp resume-brief --repo-root=<path> resolves zero, one, or several active bundles and renders a carry-forward brief — wired as a SessionStart hook on hosts that register hooks.