Cross-repo AskUserQuestion/ask_user_question (AUQ), Serena, Hindsight,
context-mode, and subagent/model-dispatch policy is centralized in the
fleet policy. Routing resolves from the repo-local policy/workflow-map.json
(a checked-in copy of the fleet workflow routing map) and the fleet dispatch
policy at /srv/workflows/policy/dispatch.md. Do not duplicate or override
that policy here.
masterplan is a Claude Code (and Codex) plugin providing the /masterplan
command — a resumable brainstorm → plan → execute → finish workflow on top
of obra/superpowers skills. As of
v8 it is a real Node codebase, not a markdown monolith: deterministic
decisions live in lib/*.mjs behind bin/masterplan.mjs (mp,
unit-tested), the markdown prompt is a thin sequencer that only orders mp
calls / agent dispatches / gates, and durable state lives in
docs/masterplan/<slug>/state.yml. It is built in five thin layers (L0 run
bundle → L4 doctor).
This file is a thin index. The full five-layer architecture and failure
modes are in docs/internals.md; the public overview is
README.md.
| If you need... | Read |
|---|---|
| The orchestrator prompt itself (L1 — the sequencer) | commands/masterplan.md |
| Deterministic logic (the real "source code") | lib/*.mjs behind bin/masterplan.mjs |
| Layer-by-layer internals + failure modes | docs/internals.md index → docs/internals/{bundle-resume,wave-dispatch,plan-parser,task-verification,doctor}.md |
| Public-facing overview + install + usage | README.md · docs/install.md · docs/verbs.md |
| Release history + decision rationale per version | CHANGELOG.md |
| Cross-cutting rules (CD-1…CD-10) + plan-field contract | docs/conventions/cd-rules.md · docs/conventions/plan-annotations.md |
| Build/test/lint + contributor discipline | docs/development.md |
| Agent registration (CC + pi) | CC: agents/ → masterplan:mp-* (plugin loader). pi: bin/register-pi-agents.mjs writes ~/.pi/agent/agents/ — bare mp-*.md only (model: is a routing-policy lane name, e.g. frontier, resolved to its lane model ref from policy/workflow-map.json; managed colon leftovers removed; --check for drift). See docs/development.md §"Never silently inline a delegated role" |
| Active plans (current work) | docs/masterplan/*/state.yml (source of truth per CD-7) |
Canonical reading order for a new session: this file →
commands/masterplan.md (the sequencer) → the relevant lib/*.mjs for the
decision you're touching → docs/internals.md for design context → any active
run state in docs/masterplan/*/state.yml.
Generic agent policy — AUQ (structured questions, never a prose question),
verification-before-completion, durable handoff state, and dispatch class
selection — is global fleet policy (/srv/workflows/policy/) and is not
restated here (see the §routing section below).
What is masterplan-specific lives in two docs:
- Cross-cutting CD-rule bodies (CD-1…CD-11) — code references the IDs:
docs/conventions/cd-rules.md. - Build/test/lint + contributor discipline — single-writer state (never
hand-write
state.yml/events.jsonl; mutate viamp), dispatch-don't-work- in-shell-context, keeping verb/doctor surfaces in sync, fresh-eyes / cross-vendor review of large edits, and finish-flow durability:docs/development.md.
Model/lane routing resolves from policy/workflow-map.json (the repo-local
copy of the fleet workflow routing map: lanes sweep/bulk/code/agentic/reason/longform/frontier/broad/mid/local with litellm/* refs, and classes such as bounded-edit/agentic-loop/planned-execution/adversary/critic/deep-investigation). Waves launch as native spawn plans executed by the harness's parallel subagent API; adversarial review is harness-native (adversary class: breaker role, frontier lane; adversarial panel for cross-vendor coverage), with records supplied via mp record-result --reviews-file. Agent frontmatter model: fields are routing-policy lane names.
Refresh the repo copy with node /srv/workflows/config/generate.mjs on a fleet host. Fleet dispatch policy lives at /srv/workflows/policy/dispatch.md.
Structured project knowledge is cataloged in the .okf/ directory.
See .okf/index.md for the repo's knowledge index.