# Construction plan format The artifact phase 1 (`INTENT.md`) produces. One markdown file per plan, stored at `plans/.md` in this repo — plain, versioned, reviewable in a diff, not a database. `` is kebab-case and traceable to the demand that triggered it (usually a workplan task id from the requesting repo, e.g. `rein-openweights-openrouter-approle` for `glas-harness/GLAS-WP-0002-T02`). A plan file is the single source of truth across all four phases: phase 1 writes it, phase 2 edits it in place (self-review, not a separate document), phase 3's executive summary is generated *from* it (not a parallel artifact that can drift), and phase 4 reads the same file to execute and appends a result section when done. ## Frontmatter ```yaml --- id: rein-openweights-openrouter-approle demand_source: glas-harness/workplans/GLAS-WP-0002-T02 consumer_repo: rein-openweights credential_type: openbao-approle-kv status: draft # draft -> reviewed -> approved -> built -> catalogued approved_by: null # founder identity string, set only at phase 3 -> 4 approved_at: null # ISO date, set alongside approved_by created: "2026-07-27" updated: "2026-07-27" --- ``` `status` is the phase tracker for the plan itself, distinct from any State Hub task status — it's what the build executor (`MASON-WP-0001-T04`) checks before doing anything: **refuses to execute unless `status: approved` and both `approved_by`/`approved_at` are set.** No other field or file can substitute for this — that's the one hard gate. ## Body sections ### 1. Demand Plain description: who needs what, why, and what they need it *for* (one paragraph — this feeds the executive summary's plain-language framing directly, so write it for the founder, not for `bao`). ### 2. Existing-structure survey What already exists that might cover this, checked *before* proposing anything new: - Relevant `bao policy list` / `bao auth list` / `bao secrets list` entries (paste the actual output, not a paraphrase) - Relevant `ops-warden/registry/routing/catalog.yaml` entries (grep by `owner_repo`/`subsystem`/`need_keywords`) - Explicit answer: **does an existing lane already satisfy this demand?** If yes, the plan's proposed changes should be "bind to existing policy X" or "reuse existing path Y," not "create new." (See `binky-control/integrations/executor-worker-secrets.md`'s own Lane 1 — reused the existing `llm-connect-provider-secrets` secret instead of minting a new one, because the scoping already covered the new consumer.) ### 3. Proposed changes A list, each item tagged `create` / `modify` / `tear-down`, each with a one-line reuse-vs-new rationale referencing section 2. Every item names exactly what OpenBao object it touches (policy name, AppRole name, KV path) — no vague "provision access" line items. ### 4. Review notes (phase 2) Filled in during the self-review pass, before a human ever sees the plan: naming/TTL/scoping convention check against existing lanes (e.g. the `agent-harness-binky-mail` shape — `token_ttl=15m`, `token_max_ttl=30m`, bounded `token_num_uses`), redundancy check, and any compaction opportunity spotted along the way. If this section is empty, the plan is not ready for phase 3. ### 5. Executive summary (phase 3, generated from sections 1-4) See `docs/executive-summary-format.md` (`MASON-WP-0001-T03`) for the exact rendering. Lives in the same plan file so there is one document to read, not two to cross-reference. ### 6. Build result (phase 4, appended after execution) What was actually created/modified/torn down (object names, not values), the ops-warden catalog entry proposed (id + PR/commit reference once filed), and the exact `paste_once_provision` step the founder still needs to run (path, field) if the plan involved a new secret value. This section does not exist until phase 4 has run. ## Worked example (also the input to `MASON-WP-0001-T05`) See `plans/rein-openweights-openrouter-approle.md` once T01 is implemented against this format — the first real plan, not a synthetic one, per `MASON-WP-0001`'s own scoping.