orchestrator.mdc
sha256:700fafdd1afa490919f9515d660ca6e75456bcd5bb67513abcd8757a634c01f6
docs: record AIP-b SD-21 land (KN #308)
Human
9 days ago
| 1 | --- |
| 2 | description: RULE #8 — Orchestrator via Overseer Kit (roadmap + handover day-to-day) |
| 3 | alwaysApply: true |
| 4 | --- |
| 5 | |
| 6 | # RULE #8 — Orchestrator (Overseer Kit) |
| 7 | |
| 8 | **Source of truth:** [🆗 Overseer Kit](https://github.com/aaronrene/overseer-kit). |
| 9 | When this repo has `.overseer/config.yaml`, run phased work **through the kit** — do not invent a |
| 10 | parallel hand-rolled ROADMAP / HANDOVER protocol. |
| 11 | |
| 12 | ## Install and refresh |
| 13 | |
| 14 | | Situation | Command | |
| 15 | | --- | --- | |
| 16 | | Greenfield (no kit yet) | `ok init --regime <git-only\|muse+git-mirror\|muse-only>` (or `init --migrate` if living docs already exist) | |
| 17 | | Pull kit updates | `ok sync` | |
| 18 | | Health / drift | `ok status` (use `--exit-code` when gates matter) | |
| 19 | | Docs vs VCS hygiene | `ok governance-sync --dry-run` then apply when correct | |
| 20 | | Freeze gate | `ok review --freeze <artifact>` | |
| 21 | | Ad-hoc honesty | `ok check-ok` / `/check-ok` | |
| 22 | |
| 23 | Resolve the `ok` shim from the kit checkout (`./cli/ok` or a path to it). Prefer `ok` over the |
| 24 | deprecated `overseer` compat shim. |
| 25 | |
| 26 | **Doc paths are config-driven** — read `docs.roadmap` / `docs.handover` from `.overseer/config.yaml` |
| 27 | (here: `{{docs.roadmap_path}}`, `{{docs.handover_path}}`). Do not assume root `ROADMAP.md` / |
| 28 | `OVERSEER_HANDOVER.md` unless config says so. |
| 29 | |
| 30 | ## Two durable docs (always together) |
| 31 | |
| 32 | | Doc | Role | |
| 33 | | --- | --- | |
| 34 | | `{{docs.roadmap_path}}` | Phase control: Phase Model Key, build queue (phase → **Model** → Status → deliverable), Definition of Done | |
| 35 | | `{{docs.handover_path}}` | Session relay: **NEXT SESSION**, paste-ready prompt, verified snapshot, VCS table, change log (KH1 shape) | |
| 36 | |
| 37 | Trust the handover **verified snapshot** over chat history. Update both docs in the same closing |
| 38 | commit (SD-17). `/governance-sync` automates the hygiene check — it does not invent policy. |
| 39 | |
| 40 | ## Model labels (`policy/model-labels.yaml`) |
| 41 | |
| 42 | Every roadmap row and handover NEXT / paste block **must** include **`Model:`** with exactly one of: |
| 43 | |
| 44 | | Label | Meaning | |
| 45 | | --- | --- | |
| 46 | | **Thinking** | Design + freeze spec (interfaces, fail-closed rules, test matrix) — no mechanical build | |
| 47 | | **Auto** | Build exactly against a frozen spec — no redesign | |
| 48 | | **Thinking → Auto** | Split into `{step}a` (Thinking) then `{step}b` (Auto) — never one combined prompt | |
| 49 | | **Operator + Auto** | Human for Tier-3 live/merge gates; Auto for implementation + doc sync | |
| 50 | |
| 51 | Never Outline/Plan on **Auto**. Never start **Auto** until the consumed freeze has review verdict |
| 52 | **`pass`**. Never mark **DONE** on green tests alone. |
| 53 | |
| 54 | ## Starting a phase |
| 55 | |
| 56 | 1. Fresh chat with the **Model** tier named in the handover |
| 57 | 2. Read `{{docs.roadmap_path}}` (target phase) and `{{docs.handover_path}}` (NEXT + verified snapshot) |
| 58 | 3. Paste the **Paste-ready prompt** fence (self-contained; no prior chat required) |
| 59 | 4. **Thinking:** freeze WHAT/HOW in a `frozen: true` artifact; run `/freeze-review-loop` → `pass` |
| 60 | 5. **Auto:** implement mechanically; run seven-tier tests (`policy/test-tiers.yaml`); run |
| 61 | `/build-verification-review` → `pass` before ROADMAP → **DONE** |
| 62 | 6. Close: update roadmap status + regenerate handover NEXT together; feature-branch commit; PR per |
| 63 | `{{vcs.regime}}` — **no** merge to `{{vcs.git.main_branch}}` without Tier 3 |
| 64 | |
| 65 | ## Definition of Done (every phase) |
| 66 | |
| 67 | - Deliverables match the frozen spec |
| 68 | - Freeze review **`pass`** before Auto that consumes the freeze |
| 69 | - Required seven-tier tests green locally |
| 70 | - Build verification **`pass`** after Auto before status → **DONE** |
| 71 | - No secrets committed |
| 72 | - Both governance docs updated together |
| 73 | - Feature-branch hygiene complete; merge remains Tier 3 |
| 74 | |
| 75 | ## Agent behavior |
| 76 | |
| 77 | - Prefer kit rules/skills (`.cursor/rules/*`, `.cursor/skills/*`, `.claude/skills/*`) over folklore |
| 78 | - One **THE ONE NEXT STEP** at a time in the handover |
| 79 | - Dirty tree at session end is a failure — commit on the feature branch (Tier 1) |
| 80 | - Hard stops: secrets, live posture flips, real money, merge to `{{vcs.git.main_branch}}` without operator authorization |
File History
1 commit
sha256:700fafdd1afa490919f9515d660ca6e75456bcd5bb67513abcd8757a634c01f6
docs: record AIP-b SD-21 land (KN #308)
Human
9 days ago