AGENTS.md git:20260821.ab669deA

Immutable. This exact content is served forever at /api/v1/blob/7ba5690d62ca3627.

# AGENTS.md — `masterplan`

<!-- agentic-dispatch:central-pointer v2 -->
## Central agent policy

Cross-repo AskUserQuestion/ask_user_question (AUQ), Serena, Hindsight,
context-mode, and subagent/model-dispatch policy is centralized in the
agent-dispatch repo. Read it via `agent-dispatch where` (repo root) or
`agent-dispatch digest` (live routing policy). Do not duplicate or override
that policy here.

## What this repo is

`masterplan` is a Claude Code (and Codex) plugin providing the `/masterplan`
command — a resumable **brainstorm → plan → execute → finish** workflow on top
of [`obra/superpowers`](https://github.com/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`](./docs/internals.md); the public overview is
[`README.md`](./README.md).

## Where to read first

| If you need... | Read |
|---|---|
| The orchestrator prompt itself (L1 — the sequencer) | [`commands/masterplan.md`](./commands/masterplan.md) |
| Deterministic logic (the real "source code") | `lib/*.mjs` behind `bin/masterplan.mjs` |
| Layer-by-layer internals + failure modes | [`docs/internals.md`](./docs/internals.md) index → `docs/internals/{bundle-resume,wave-dispatch,plan-parser,task-verification,doctor}.md` |
| Public-facing overview + install + usage | [`README.md`](./README.md) · [`docs/install.md`](./docs/install.md) · [`docs/verbs.md`](./docs/verbs.md) |
| Release history + decision rationale per version | [`CHANGELOG.md`](./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`](./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:` via live-alias map `fable → litellm/fable-5`; managed colon leftovers removed; `--check` for drift). See [`docs/development.md`](./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`.

## Discipline & development

Generic agent policy — AUQ (structured questions, never a prose question),
verification-before-completion, durable handoff state, and dispatch class
selection — is **global / agent-dispatch policy and is not restated here**
(see the managed block below and `agent-dispatch digest`).

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`](./docs/conventions/cd-rules.md).
- **Build/test/lint + contributor discipline** — single-writer state (never
  hand-write `state.yml`/`events.jsonl`; mutate via `mp`), 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`](./docs/development.md).

<!-- agent-dispatch:begin routing hash=ab9bc373a67846a9f7ca9d9e4cff415f061bf461e385ef3020963d0799821040 -->
## §routing — managed by agent-dispatch (do not hand-edit)

Binding rules (enforced by PreToolUse guard):
- Some models are gated and require a live override grant; run `agent-dispatch digest` for current dispositions.
- model param MUST be explicit — missing model is denied, EXCEPT the built-in read-only types below (Explore/Plan), which inherit the session model.
- Route work to the roster role its class names (routing.yaml classes[].agent); the role pins the lane. Explore/Plan are exempt built-ins that BYPASS lane routing: dispatch them WITHOUT a model param (they inherit the session model; an explicit model outside the lineup is denied). Prefer the role.

For the full routing policy, fallback chains, and backend health:
  agent-dispatch digest          # live, from the canonical policy file
  agent-dispatch resolve <class> # deterministic tier for a task class

Source of truth: policy/dispatch-policy.jsonc in the agent-dispatch repo (run `agent-dispatch where` for its root).
<!-- agent-dispatch:end -->
## Knowledge

Structured project knowledge is cataloged in the `.okf/` directory.
See [`.okf/index.md`](.okf/index.md) for the repo's knowledge index.