AGENTS.md git:20260929.460e1b5A

Immutable. This exact content never changes and is served at /api/v1/blob/1676f6abe97d961c.

# AGENTS.md — `masterplan`

## Development host — 2026-09-21

Use `ras@ai` (`192.168.100.200`) for all AI work, source/documentation edits,
build development, and working-copy synchronization. The canonical checkout
keeps this repository's `/srv/dev/...` path on `ai`; GitHub remains the
source-control remote where configured. Do not replicate code or docs to
`epyc1` or `epyc2`; they are VM servers. Older host references in evidence and
runtime runbooks do not authorize development there. Verify a service's actual
guest/endpoint before operating it; this policy does not prove runtime,
credential, timer, or private-data migration.

<!-- 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
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.

## 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

<!-- intent:consultation-rule v1 -->
**Intent.** `INTENT.md` at the repo root states why this repo exists, what must never
happen, what it is not, and where it is going. Before a substantive change, read it and
state in one line which of `serves` / `neutral` / `fights` / `unavailable` the change is,
judged against its checked sections:
Purpose / Top invariant / Non-goals / Direction / Posture.
`fights` or unsure stops and puts it to the owner before code is written. Its decisions
are the owner's — amend it through the owner, never to fit the change.
<!-- /intent:consultation-rule -->

| 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` |
| The design-intent integration (interview host contract, schema capture + skill identity, §5.3 convergence, format pin, reconciliation, promotion, checkpoints, knob-contract verification) | [`docs/internals/design-intent-integration.md`](./docs/internals/design-intent-integration.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:` in the source is a routing-policy lane name, e.g. `frontier`; registration validates it against `policy/workflow-map.json` and then **removes** the line, because pi refuses a frontmatter hint outside the preset's class chain and the preset's class policy routes the child; 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 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`](./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).

## §routing — resolved from the checked-in policy

Model/lane routing resolves from the `MP_ROUTING_POLICY` path when set, then the delivered `~/.pi/workflows/workflow-map.json` when present, otherwise from `policy/workflow-map.json` (the repo-local fallback copy of the fleet workflow routing map, with `litellm/*` refs and governed work classes). Waves launch as native spawn plans executed by the harness's parallel subagent API; adversarial review is harness-native (adversary class: breaker role, governed 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.

The authoritative producer is `/srv/inference/config/src/*.hcl`, rendered by inference reconfigure to the delivered map. After delivery and a public-secret exposure review against the existing copy, refresh **only this fallback** with `cp ~/.pi/workflows/workflow-map.json policy/workflow-map.json` and verify byte equality with `cmp policy/workflow-map.json ~/.pi/workflows/workflow-map.json`. Do not reconfigure to refresh this repo copy. Fleet dispatch policy lives at `/srv/workflows/policy/dispatch.md`.

## Knowledge

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