tegwick
a762be9e17
docs/construction-plan-format.md: one file per plan (plans/<id>.md), frontmatter status tracker (draft -> reviewed -> approved -> built -> catalogued, the phase-4 hard gate), six body sections threading all four phases through one document. Proven against real demand: plans/rein-openweights-openrouter-approle.md, phases 1-2 filled in. Found and reasoned through a real existing-structure question along the way -- the openrouter-llm-connect catalog lane could technically be reused, but its auth_method is interactive-caller-shaped and its policy is shared/high-risk; recommends a dedicated, narrowly scoped AppRole instead, same reasoning agent-harness-binky-mail used for its own dedicated lane. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
97 lines
4 KiB
Markdown
97 lines
4 KiB
Markdown
# Construction plan format
|
|
|
|
The artifact phase 1 (`INTENT.md`) produces. One markdown file per plan,
|
|
stored at `plans/<plan-id>.md` in this repo — plain, versioned, reviewable
|
|
in a diff, not a database. `<plan-id>` 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.
|