diff --git a/docs/plans/2026-05-11-orchestrator-refactor.md b/docs/plans/2026-05-11-orchestrator-refactor.md new file mode 100644 index 0000000..46869fb --- /dev/null +++ b/docs/plans/2026-05-11-orchestrator-refactor.md @@ -0,0 +1,1589 @@ +# Orchestrator-Refactor — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-11-implement-orchestrator-agent.md` +> +> **For agentic workers:** REQUIRED SUB-SKILL: use `skills/implement` +> to run this plan. Steps use `- [ ]` checkboxes for tracking. +> +> **Bootstrap note:** this plan is executed with the *pre-refactor* +> `/implement` skill (Boss dispatches `ailang-implementer` directly). +> The `ailang-implement-orchestrator` agent introduced here goes +> live only on the *next* `/implement` run after this iteration +> lands. The Boss must NOT attempt to dispatch the new agent during +> this run. + +**Goal:** ship the three coupled changes from the parent spec — +Boss-context offload via a new `ailang-implement-orchestrator` agent, +per-iter branch isolation, and per-iter journal files replacing the +14k-line monolith — without altering any worker agent's role or any +language behaviour. + +**Architecture:** seven discrete tasks in dependency order. Filesystem +migration first (JOURNAL.md → journal-archive.md, new `docs/journals/` +subdir with INDEX.md). Then references are repointed in two waves +(top-level docs, then skill/agent files) so the `JOURNAL.md` path +disappears from active reading lists. Then the implementer and +spec-reviewer carriers are switched from `task_text` to +`task_text_path` so the new orchestrator can hand them a file. Then +the new orchestrator agent is created. Then `skills/implement/SKILL.md` +is rewritten to delegate both modes to the new agent. Finally the +one-line exception note in `skills/README.md`. The verification ladder +is a manual checklist at the end — no `cargo test` applies (skill/agent +files are not Rust code). + +**Tech Stack:** markdown files only; one `git mv`; no Rust or build +changes. + +--- + +**Files this plan creates or modifies:** + +- Rename: `docs/JOURNAL.md` → `docs/journal-archive.md` (Task 1) +- Create: `docs/journals/INDEX.md` (Task 1) +- Modify: `CLAUDE.md` (Task 2) — 4 sites under "Code layout" + "Roles" + + "Done-state notifications" +- Modify: `docs/DESIGN.md` (Task 2) — 1 site +- Modify: `docs/roadmap.md` (Task 2) — 1 site +- Modify: `skills/README.md` (Task 3 partial, Task 7 final) — 5 sites + total split between the two tasks +- Modify: `skills/audit/SKILL.md` (Task 3) — 9 sites (most are + conceptual "JOURNAL ratify entry"-phrasing, not path refs; path + refs only on lines 49) +- Modify: `skills/audit/agents/ailang-architect.md` (Task 3) — 8 sites +- Modify: `skills/audit/agents/ailang-bencher.md` (Task 3) — 4 sites +- Modify: `skills/audit/agents/ailang-docwriter.md` (Task 3) — 4 sites +- Modify: `skills/brainstorm/SKILL.md` (Task 3) — 1 path site + 2 + conceptual sites +- Modify: `skills/debug/agents/ailang-debugger.md` (Task 3) — 3 sites +- Modify: `skills/fieldtest/agents/ailang-fieldtester.md` (Task 3) — 7 + sites +- Modify: `skills/implement/agents/ailang-implementer.md` (Task 3 for + JOURNAL refs + Task 4 for carrier) — 3 JOURNAL sites + carrier + rewrite of Step 1 / Carrier-contract block +- Modify: `skills/implement/agents/ailang-spec-reviewer.md` (Task 4) — + carrier rewrite, `task_text` → `task_text_path` +- Modify: `skills/implement/agents/ailang-tester.md` (Task 3) — 2 sites +- Create: `skills/implement/agents/ailang-implement-orchestrator.md` + (Task 5) +- Rewrite: `skills/implement/SKILL.md` (Task 6) — from ~210 lines to + ~100 lines, structure per spec §"`skills/implement/SKILL.md` + (rewritten)" +- Modify: `skills/README.md` (Task 7) — exception sentence + agent + roster row + +Historical files in `docs/plans/` and `docs/specs/` and +`docs/WhatsNew.md` are **not** rewritten — they are dated artifacts +of past decisions and remain mutable only to the iteration that +produced them. + +--- + +## Task 1: Filesystem migration — JOURNAL.md archived, new docs/journals/ + +**Files:** +- Rename: `docs/JOURNAL.md` → `docs/journal-archive.md` +- Modify: `docs/journal-archive.md` (header note) +- Create: `docs/journals/INDEX.md` + +- [ ] **Step 1: Verify clean working tree before destructive move** + +Run: `git status --porcelain` +Expected: empty output (no staged or unstaged changes). + +If non-empty, STOP and surface to the Boss — the task assumes a clean +tree. + +- [ ] **Step 2: Rename JOURNAL.md to journal-archive.md** + +Run: `git mv docs/JOURNAL.md docs/journal-archive.md` +Expected: rename recorded in `git status`; file content identical +modulo path. + +- [ ] **Step 3: Prepend archived-status header to journal-archive.md** + +The first line of `docs/journal-archive.md` is currently +`# AILang JOURNAL`. Insert a blockquote note immediately after it, +followed by a blank line. + +Exact insertion (after the existing H1 title, before whatever blank +line or content follows): + +```markdown +# AILang JOURNAL + +> **Status:** archived 2026-05-11. New iter journals live under +> `docs/journals/`. See `docs/journals/INDEX.md` for the +> chronological pointer list. This file remains the historical +> record for entries prior to that date. + +``` + +If the existing line 1 is not `# AILang JOURNAL`, read the first 5 +lines first and adjust the insertion anchor accordingly without +removing existing content. + +- [ ] **Step 4: Create docs/journals/INDEX.md** + +Write the file with this exact content: + +```markdown +# Journal index + +> Chronological pointer list of per-iter journal files. Append-only. +> One line per iter, newest at the bottom. Filenames are relative to +> `docs/journals/`. + +- pre-2026-05-11 — see `../journal-archive.md` for all prior history +``` + +- [ ] **Step 5: Verify the migration** + +Run: `ls docs/journal-archive.md docs/journals/INDEX.md && head -10 docs/journal-archive.md` +Expected: both paths exist; the first ~5 visible lines of +journal-archive.md show the archived-status blockquote. + +- [ ] **Step 6: Commit** + +```bash +git add docs/journal-archive.md docs/journals/INDEX.md docs/JOURNAL.md +git commit -m "iter or.1.1: migrate JOURNAL.md to journal-archive.md + docs/journals/" +``` + +(`docs/JOURNAL.md` is included in `git add` to record the rename +deletion alongside the new path; `git mv` already staged it but a +re-add is a no-op safety.) + +--- + +## Task 2: Repoint references — top-level docs + +**Files:** +- Modify: `CLAUDE.md` (4 sites) +- Modify: `docs/DESIGN.md` (1 site) +- Modify: `docs/roadmap.md` (1 site) + +- [ ] **Step 1: Patch CLAUDE.md — Code layout table (line 40)** + +Replace the line: + +```markdown +| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` | +``` + +with: + +```markdown +| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/journals/` (per-iter journals + `INDEX.md`), `docs/journal-archive.md` (pre-2026-05-11 history), `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` | +``` + +- [ ] **Step 2: Patch CLAUDE.md — orchestrator role paragraph (line 66)** + +Find the line: + +```markdown + invariants, and the contents of `docs/JOURNAL.md` and +``` + +Replace with: + +```markdown + invariants, and the contents of `docs/journals/` and +``` + +- [ ] **Step 3: Patch CLAUDE.md — Done-state notifications paragraph (line 191)** + +Find the line: + +```markdown + append-only — same chronological convention as `JOURNAL.md`). +``` + +Replace with: + +```markdown + append-only — same chronological convention as the per-iter journals). +``` + +- [ ] **Step 4: Patch CLAUDE.md — "Roles of …" section header + body** + +Two related edits in the same region (currently lines 239–262 in the +pre-edit file). + +(a) Section header (currently line 239): + +```markdown +## Roles of `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/` +``` + +Replace with: + +```markdown +## Roles of `docs/DESIGN.md`, `docs/journals/`, `docs/journal-archive.md`, `docs/roadmap.md`, `docs/specs/`, `docs/plans/` +``` + +(b) The `**docs/JOURNAL.md**` bullet (currently line 249 and the +following paragraph that defines it). Replace the entire bullet +(from `- **\`docs/JOURNAL.md\`**` through the end of its paragraph) +with two new bullets: + +```markdown +- **`docs/journals/-iter-.md`** is the decisions + log, one file per iter. Each file records *why* the iter moved + the way it did — alternatives considered and rejected, lessons, + rationale that does not belong in `docs/DESIGN.md`. Append-only + per file; new files are appended via `docs/journals/INDEX.md`. + `docs/journals/INDEX.md` is the chronological pointer list, + Boss-maintained, one line per iter. + +- **`docs/journal-archive.md`** is the archived monolithic + decisions log for everything pre-2026-05-11. Content-frozen. + Read it only when chasing long-tail history; do not append. +``` + +- [ ] **Step 5: Patch docs/DESIGN.md (line 49)** + +Find: + +```markdown + `JOURNAL.md` (chronological decisions log), +``` + +Replace with: + +```markdown + `docs/journals/` (per-iter decisions log; see `INDEX.md`) plus the archived `docs/journal-archive.md` for pre-2026-05-11 history, +``` + +(One line; do not reflow paragraph breaks.) + +- [ ] **Step 6: Patch docs/roadmap.md (line 14)** + +Read the file at line 14 first to see the exact context. + +Find: + +```markdown + `docs/JOURNAL.md`). +``` + +Replace with: + +```markdown + `docs/journals/`). +``` + +- [ ] **Step 7: Verify no JOURNAL.md path remains in top-level docs** + +Run: `grep -n "JOURNAL.md" CLAUDE.md docs/DESIGN.md docs/roadmap.md` +Expected: empty output. + +- [ ] **Step 8: Commit** + +```bash +git add CLAUDE.md docs/DESIGN.md docs/roadmap.md +git commit -m "iter or.1.2: repoint top-level docs to docs/journals/ + journal-archive.md" +``` + +--- + +## Task 3: Repoint references — skill and agent files + +**Files (read all once, edit each, commit together):** +- Modify: `skills/audit/SKILL.md` +- Modify: `skills/audit/agents/ailang-architect.md` +- Modify: `skills/audit/agents/ailang-bencher.md` +- Modify: `skills/audit/agents/ailang-docwriter.md` +- Modify: `skills/brainstorm/SKILL.md` +- Modify: `skills/debug/agents/ailang-debugger.md` +- Modify: `skills/fieldtest/agents/ailang-fieldtester.md` +- Modify: `skills/implement/agents/ailang-implementer.md` (JOURNAL refs only; + carrier rewrite is Task 4) +- Modify: `skills/implement/agents/ailang-tester.md` +- Modify: `skills/README.md` (JOURNAL refs only; exception note is Task 7) + +**General replacement rule:** + +There are two kinds of `JOURNAL` reference in these files. Apply the +rule per kind, NOT a blind global replace: + +1. **Path references** (`docs/JOURNAL.md`, `` `JOURNAL.md` ``, "the + JOURNAL.md tail") — repoint to the new layout. The canonical + phrasing is: + + - Standing-reading-list entries: `docs/journals/INDEX.md` + the latest 1–3 referenced files + - Generic mentions of the log: `docs/journals/` + - "tail of JOURNAL" → "latest entries linked from `docs/journals/INDEX.md`" + +2. **Conceptual references** that name a JOURNAL *entry* as a process + artefact ("JOURNAL ratify entry", "JOURNAL the impasse", "no JOURNAL + ticket") — these are about the *act of journalling*, not the path. + Keep the word "JOURNAL" or "journal" as a process noun; do NOT add + a path. Example: `"JOURNAL ratify entry"` stays as-is (a journal + entry is now a per-iter file, but the concept "ratify entry" still + names the same artefact in the new layout). Optionally clarify on + first use per file with "(in the per-iter journal)" if the file + talks about journalling at length. + +The verification step at the bottom enumerates expected counts. + +- [ ] **Step 1: skills/audit/SKILL.md** + +Line 49 has the only path reference: + +```markdown +For milestone : read DESIGN.md, JOURNAL.md, the latest milestone +``` + +Replace with: + +```markdown +For milestone : read DESIGN.md, `docs/journals/INDEX.md` and the latest 1–3 referenced files, the latest milestone +``` + +All other `JOURNAL` mentions in this file (lines 3, 20, 38, 83, 92, +95, 118, 127, 130) are conceptual references to *the act of journalling* +and stay verbatim. + +- [ ] **Step 2: skills/audit/agents/ailang-architect.md** + +(a) Line 33 (standing reading list): + +```markdown +3. `docs/JOURNAL.md` — the full log, with focus on the milestone you're +``` + +Replace with: + +```markdown +3. `docs/journals/INDEX.md` + the per-iter files for the milestone you're +``` + +(b) Line 100 (Iron Law): + +```markdown +NO EDITS. NOT TO CODE, NOT TO DESIGN.MD, NOT TO JOURNAL.MD. +``` + +Replace with: + +```markdown +NO EDITS. NOT TO CODE, NOT TO DESIGN.MD, NOT TO ANY JOURNAL FILE. +``` + +(c) Line 109 (Process Step 1): + +```markdown +1. Read the standing list, in this order: CLAUDE.md → DESIGN.md → JOURNAL +``` + +Replace with: + +```markdown +1. Read the standing list, in this order: CLAUDE.md → DESIGN.md → `docs/journals/INDEX.md` + the per-iter files +``` + +(d) Lines 60, 70, 71, 77, 155 — conceptual references ("JOURNAL +ticket", "most recent JOURNAL entry", "JOURNAL citation", "JOURNAL +truthfulness", "JOURNAL says…"). Keep as-is. + +- [ ] **Step 3: skills/audit/agents/ailang-bencher.md** + +(a) Line 40 (standing reading list): + +```markdown +3. `docs/JOURNAL.md` — most recent entries are the current state of +``` + +Replace with: + +```markdown +3. `docs/journals/INDEX.md` + the latest 3 referenced files — current state of +``` + +(b) Line 43 ("any prior bench results recorded in JOURNAL"): + +```markdown +4. `bench/run.sh` and any prior bench results recorded in JOURNAL. +``` + +Replace with: + +```markdown +4. `bench/run.sh` and any prior bench results recorded in the per-iter journals. +``` + +(c) Line 53 (carrier-contract row "Pointer to existing JOURNAL bench entries"): + +```markdown +| `prior_data` | Pointer to existing JOURNAL bench entries that frame this question, or `none` | +``` + +Replace with: + +```markdown +| `prior_data` | Pointer to existing per-iter-journal bench entries that frame this question, or `none` | +``` + +(d) Line 148 ("DESIGN.md / JOURNAL.md edits"): + +```markdown +- DESIGN.md / JOURNAL.md edits. The orchestrator writes those based on +``` + +Replace with: + +```markdown +- DESIGN.md / journal edits. The orchestrator writes those based on +``` + +- [ ] **Step 4: skills/audit/agents/ailang-docwriter.md** + +(a) Line 35: + +```markdown +3. The most recent entries in `docs/JOURNAL.md` — to know which crates +``` + +Replace with: + +```markdown +3. The most recent entries linked from `docs/journals/INDEX.md` — to know which crates +``` + +(b) Line 80 ("DESIGN.md, JOURNAL.md, the `ail` CLI"): + +```markdown +- **Cross-repo references** (DESIGN.md, JOURNAL.md, the `ail` CLI +``` + +Replace with: + +```markdown +- **Cross-repo references** (DESIGN.md, journals, the `ail` CLI +``` + +(c) Line 90: + +```markdown +- No edits in `docs/`. The orchestrator owns DESIGN.md and JOURNAL.md. +``` + +Replace with: + +```markdown +- No edits in `docs/`. The orchestrator owns DESIGN.md and the journal files. +``` + +(d) Line 141: + +```markdown +- About to edit `docs/DESIGN.md` or `docs/JOURNAL.md` +``` + +Replace with: + +```markdown +- About to edit `docs/DESIGN.md` or any file under `docs/journals/` / `docs/journal-archive.md` +``` + +- [ ] **Step 5: skills/brainstorm/SKILL.md** + +(a) Line 59 (path reference in standing reading): + +```markdown +- Read the latest entries in `docs/JOURNAL.md` (most recent +``` + +Replace with: + +```markdown +- Read the latest entries linked from `docs/journals/INDEX.md` (most recent +``` + +(b) Lines 191, 194 — conceptual ("write a JOURNAL entry", "JOURNAL the +impasse"). Keep as-is; these now refer to writing a per-iter journal, +which is still called "a JOURNAL entry" in the discipline. + +- [ ] **Step 6: skills/debug/agents/ailang-debugger.md** + +(a) Line 27 (standing reading list): + +```markdown +3. `docs/JOURNAL.md` — most recent entries; the last iteration may have +``` + +Replace with: + +```markdown +3. `docs/journals/INDEX.md` + the latest referenced file — the last iteration may have +``` + +(b) Line 128 — conceptual ("JOURNAL entry didn't flag"). Keep as-is. + +(c) Line 155 ("DESIGN.md / JOURNAL.md edits"): + +```markdown +- DESIGN.md / JOURNAL.md edits. +``` + +Replace with: + +```markdown +- DESIGN.md / journal edits. +``` + +- [ ] **Step 7: skills/fieldtest/agents/ailang-fieldtester.md** + +(a) Line 44 (standing reading list): + +```markdown +3. `docs/JOURNAL.md` (most recent ~10 entries) — what shipped, what +``` + +Replace with: + +```markdown +3. `docs/journals/INDEX.md` and the latest ~5 referenced files — what shipped, what +``` + +(b) Line 62: + +```markdown +If `axis_hints` is empty, infer from JOURNAL tail and the milestone +``` + +Replace with: + +```markdown +If `axis_hints` is empty, infer from the latest per-iter journals and the milestone +``` + +(c) Line 95: + +```markdown + JOURNAL + spec + `axis_hints`. +``` + +Replace with: + +```markdown + latest per-iter journals + spec + `axis_hints`. +``` + +(d) Line 219 — conceptual ("separate JOURNAL entry's claim"). Replace +"JOURNAL entry" with "journal entry" (lowercase) for clarity, no path: + +```markdown + separate JOURNAL entry's claim is contradicted by what you saw, +``` + +Replace with: + +```markdown + separate per-iter journal entry's claim is contradicted by what you saw, +``` + +(e) Line 221: + +```markdown +- `NEEDS_CONTEXT` — `axis_hints` empty AND JOURNAL/spec do not +``` + +Replace with: + +```markdown +- `NEEDS_CONTEXT` — `axis_hints` empty AND per-iter journals/spec do not +``` + +(f) Line 223 — same paragraph, conceptual ("JOURNAL entry was thin"): + +```markdown + examples (rare; usually means the JOURNAL entry was thin). +``` + +Replace with: + +```markdown + examples (rare; usually means the per-iter journal entry was thin). +``` + +(g) Line 251: + +```markdown +- Edits to `docs/DESIGN.md` or `docs/JOURNAL.md`. Spec gaps are +``` + +Replace with: + +```markdown +- Edits to `docs/DESIGN.md` or any journal file. Spec gaps are +``` + +- [ ] **Step 8: skills/implement/agents/ailang-implementer.md (JOURNAL refs only)** + +(a) Line 32 (standing reading list): + +```markdown +3. `docs/JOURNAL.md` — the most recent milestone-relevant entries. The latest +``` + +Replace with: + +```markdown +3. `docs/journals/INDEX.md` + the latest 1–3 milestone-relevant per-iter files. The latest +``` + +(b) Line 89 — conceptual ("flagged in the JOURNAL"). Keep as-is. + +(c) Line 102 (Process Step 1): + +```markdown +1. Read the standing list (CLAUDE.md, DESIGN.md, JOURNAL.md tail). +``` + +Replace with: + +```markdown +1. Read the standing list (CLAUDE.md, DESIGN.md, latest per-iter journals). +``` + +Carrier-section edits (Step 1 of this agent's Process, plus the carrier +contract block) are NOT done here — they belong to Task 4. + +- [ ] **Step 9: skills/implement/agents/ailang-tester.md** + +(a) Line 27 (standing reading list): + +```markdown +2. `docs/JOURNAL.md` — most recent iteration entries; they tell you what +``` + +Replace with: + +```markdown +2. `docs/journals/INDEX.md` + the latest 1–3 referenced files — most recent iteration entries; they tell you what +``` + +(b) Line 78 ("Commit per existing JOURNAL style"): + +```markdown +5. Commit per existing JOURNAL style (`iter .: e2e for `). +``` + +Replace with: + +```markdown +5. Commit per existing journal style (`iter .: e2e for `). +``` + +- [ ] **Step 10: skills/README.md (JOURNAL refs only)** + +(a) Line 11: + +```markdown +`docs/JOURNAL.md` ("Skill system live") for the rationale. +``` + +Replace with: + +```markdown +`docs/journal-archive.md` ("Skill system live") for the rationale. +``` + +(b) Line 19 (table row, conceptual "JOURNAL entry"): + +```markdown +| [`implement`](implement/SKILL.md) | Plan exists | Code + tests + per-task commits + JOURNAL entry | Standard iteration path | +``` + +Replace with: + +```markdown +| [`implement`](implement/SKILL.md) | Plan exists | Code + tests + per-task commits + per-iter journal entry | Standard iteration path | +``` + +(c) Line 37 — conceptual ("ratify-> JOURNAL"). Keep "JOURNAL" as-is: +this is a process arrow naming the *act* of recording. + +(d) Line 81 (standing-reading-list paragraph in template description): + +```markdown + DESIGN.md, JOURNAL.md tail, plus role-specific anchors). +``` + +Replace with: + +```markdown + DESIGN.md, latest per-iter journals, plus role-specific anchors). +``` + +(e) Line 139: + +```markdown + the question in `docs/JOURNAL.md` before adding the agent. +``` + +Replace with: + +```markdown + the question via a per-iter journal entry before adding the agent. +``` + +(f) Line 145 (same paragraph as line 81 conceptually): + +```markdown + of the agent's standing reading list (CLAUDE.md, DESIGN.md, JOURNAL.md +``` + +Replace with: + +```markdown + of the agent's standing reading list (CLAUDE.md, DESIGN.md, latest per-iter journals +``` + +(g) Line 171: + +```markdown + raise the question in `docs/JOURNAL.md` first. +``` + +Replace with: + +```markdown + raise the question via a per-iter journal entry first. +``` + +- [ ] **Step 11: Verify** + +Run: `grep -rln "JOURNAL.md" CLAUDE.md docs/DESIGN.md docs/roadmap.md skills/` +Expected: empty output. Path `JOURNAL.md` no longer appears in any +active reading list. + +Run: `grep -rn "docs/JOURNAL" CLAUDE.md docs/DESIGN.md docs/roadmap.md skills/` +Expected: empty output. + +(Historical files in `docs/plans/`, `docs/specs/`, and +`docs/WhatsNew.md` are intentionally NOT scanned — they are dated +artifacts.) + +- [ ] **Step 12: Commit** + +```bash +git add skills/ CLAUDE.md docs/DESIGN.md docs/roadmap.md +git commit -m "iter or.1.3: repoint skill + agent reading lists to docs/journals/" +``` + +(CLAUDE.md, DESIGN.md, roadmap.md were already committed in or.1.2 — +`git add` will simply find nothing new there; this is safe.) + +--- + +## Task 4: Carrier change — task_text → task_text_path on implementer + spec-reviewer + +**Files:** +- Modify: `skills/implement/agents/ailang-implementer.md` (carrier + section + Process Step 1 mention) +- Modify: `skills/implement/agents/ailang-spec-reviewer.md` (carrier + section) + +The change: the carrier field for the task text moves from an inline +string (`task_text: ""`) to a file path +(`task_text_path: "/tmp/ail-iter//task-.md"`). The agent +reads the file as its first action. This eliminates per-task +duplication of the task text between the implementer and spec-reviewer +dispatches. + +- [ ] **Step 1: Read ailang-implementer.md carrier-contract block** + +The file currently has a Carrier-contract section (look for +`## Carrier contract` or `## Carrier` heading). Read it to locate the +`task_text` row. + +- [ ] **Step 2: Patch ailang-implementer.md — Carrier-contract block** + +Find the row that defines `task_text`: + +```markdown +| `task_text` | The verbatim text of the task block, copied from the plan | +``` + +(Exact phrasing may differ slightly — match by the cell containing +`task_text` and "verbatim"/"plan".) + +Replace with: + +```markdown +| `task_text_path` | Absolute path to a file (typically `/tmp/ail-iter//task-.md`) containing the verbatim task block extracted from the plan. Read this file as your first action. | +``` + +- [ ] **Step 3: Patch ailang-implementer.md — Process Step 1 (or wherever task_text is first read)** + +Find any mention in the Process section that the agent receives the +task as an inline string (typical phrasing: "Read the task text the +controller handed you" or "The task_text you received…"). Replace +with: "Read the file at `task_text_path` — that is your task block." + +If no such mention exists (the agent file relies entirely on the +carrier contract), the carrier change in Step 2 is sufficient; do not +invent text. + +- [ ] **Step 4: Patch ailang-spec-reviewer.md — Carrier-contract block** + +The spec-reviewer carrier contract typically has a `task_text` row +identical in spirit to the implementer's. Apply the same replacement: + +```markdown +| `task_text` | The verbatim text of the task block, identical to what the implementer received | +``` + +Replace with: + +```markdown +| `task_text_path` | Absolute path (typically `/tmp/ail-iter//task-.md`) — same file the implementer received. Read this file as your first action. | +``` + +- [ ] **Step 5: Patch ailang-spec-reviewer.md — first-action mention** + +Same as Task 4 Step 3 but for the spec-reviewer. Any phrasing like +"Compare the task_text against the diff" → "Read the file at +`task_text_path`; compare it against the diff." + +If no inline mention exists, the carrier change is sufficient. + +- [ ] **Step 6: Verify** + +Run: `grep -n "task_text\b" skills/implement/agents/ailang-implementer.md skills/implement/agents/ailang-spec-reviewer.md` +Expected: empty output. The literal `task_text` (without `_path` +suffix) no longer appears. + +Run: `grep -n "task_text_path" skills/implement/agents/ailang-implementer.md skills/implement/agents/ailang-spec-reviewer.md` +Expected: at least one match per file — typically two (carrier +contract row + first-action mention). + +- [ ] **Step 7: Commit** + +```bash +git add skills/implement/agents/ailang-implementer.md skills/implement/agents/ailang-spec-reviewer.md +git commit -m "iter or.1.4: carrier switch task_text -> task_text_path" +``` + +--- + +## Task 5: Create new agent — ailang-implement-orchestrator + +**Files:** +- Create: `skills/implement/agents/ailang-implement-orchestrator.md` + +The new agent follows the standard agent template documented in +`skills/README.md` ("Agent structure" section). The content below is +the verbatim file to write — no inventing structure, no skipping +sections, no abbreviating. + +- [ ] **Step 1: Write the agent file** + +Create `skills/implement/agents/ailang-implement-orchestrator.md` +with the following content: + +```markdown +--- +name: ailang-implement-orchestrator +description: Use to run one full /implement iteration in a dedicated subagent context. Carries the per-task loop end-to-end — implementer → spec-reviewer → quality-reviewer, with the canonical re-loop limits — on an isolated branch (`iter/`), writes a per-iter journal file, writes a stats file, returns a ≤500-token end-report. The named exception to "agents do not call other agents". +tools: Read, Edit, Write, Bash, Glob, Grep, Agent +--- + +# ailang-implement-orchestrator — per-iter loop in isolated context + +> **Violating the letter of these rules is violating the spirit.** + +## What this role is for + +The Boss-Orchestrator's context grew by ~100k tokens per `/implement` +run before this role existed — plan loaded once, task text duplicated +between implementer and spec-reviewer dispatches, review re-loops +amortised against the Boss's context budget. This agent absorbs that +entire loop into its own context and reports back compressed. + +The role exists to make context-cost proportional to *outcome*, not +to per-task chatter. Every decision-relevant signal the Boss needs +goes into the end-report; everything else stays inside this agent's +context and dies with it. + +## Standing reading list + +Read these before doing anything else, in this order: + +1. `CLAUDE.md` — orchestrator framing, in particular the + "Done-state notifications: WhatsNew.md" subsection (WhatsNew is + Boss-side, NOT this agent's job). +2. `docs/DESIGN.md` — invariants any iter must respect. +3. `docs/journals/INDEX.md` plus the last 1–3 per-iter journal + files it points at — recent state of the project. +4. `skills/implement/SKILL.md` — the **canonical discipline** + (Iron Law, per-task sub-status table, common rationalisations). + Re-read every dispatch; do not paraphrase from memory. + +Do NOT read `docs/journal-archive.md` by default; it is pre-2026-05-11 +history. + +## Carrier contract + +You receive from the Boss-Orchestrator: + +| Field | Content | +|-------|---------| +| `mode` | `"standard"` or `"mini"` | +| `iter_id` | e.g. `"ct.2.3"` (standard) or `"bugfix-"` (mini). Used for branch name, scratch dir, journal filename, stats filename, commit subjects | +| `plan_path` | (standard only) `docs/plans/.md` | +| `task_range` | (standard, optional) e.g. `[3, 8]` — run only Tasks 3..8 inclusive | +| `red_test_path` | (mini only) absolute path to the RED test from `debug` | +| `cause_summary` | (mini only) 1–2 sentences from the debugger agent | +| `constraint` | (mini only) `"minimal fix, no surrounding cleanup"` | + +You produce on return: the fixed-format end-report (see Output format). +You do NOT touch `docs/journals/INDEX.md` and you do NOT merge the +branch — both are Boss-side. + +## The Iron Law + +``` +ONE BRANCH PER ITER — `iter/`, created from origin/main. +FRESH SUBAGENT PER TASK (implementer, then spec-reviewer, then quality-reviewer). +TWO-STAGE REVIEW PER TASK: SPEC COMPLIANCE FIRST, CODE QUALITY SECOND. +NEVER START QUALITY REVIEW BEFORE SPEC COMPLIANCE IS GREEN. +NEVER PUSH PAST `BLOCKED` BY HAND — RETURN BLOCKED TO THE BOSS. +WRITE THE PER-ITER JOURNAL FILE BEFORE RETURNING — EVEN ON BLOCKED. +``` + +## The Process + +### Phase 0 — Branch setup (always first) + +1. `git fetch origin main` +2. If a branch named `iter/` already exists locally + (Boss-side repair re-dispatch): `git switch iter/`. + Otherwise: `git switch -c iter/ origin/main`. +3. Record `pre_iter_sha = $(git rev-parse HEAD)` for the end-report. +4. Create scratch dir: `mkdir -p /tmp/ail-iter/`. + +### Phase 1 — Load context (mode-dependent) + +**Standard mode:** + +- Read `plan_path` once. Extract every task with its verbatim block. +- For each task K in scope (full plan if no `task_range`, else + `task_range[0]..=task_range[1]`), write the verbatim block to + `/tmp/ail-iter//task-K.md`. +- Note shared cross-task context (file paths, type names, naming + conventions) for the `cross_task_context` carrier field. + +**Mini mode:** + +- Read the RED test at `red_test_path`. +- Compose a single one-task description into + `/tmp/ail-iter//task-1.md` of the form: + + ``` + Make this RED test pass: + + Cause (from debugger): + + + Constraint: + ``` + +- No multi-task expansion. + +### Phase 2 — Per-task loop + +For each task K in TodoWrite order (use TodoWrite to track tasks as +status changes — but TodoWrite items live in YOUR context, not the +Boss's): + +#### 2.1 — Dispatch implementer + +`Agent("ailang-implementer", { task_text_path: "/tmp/ail-iter//task-K.md", scene_set: ..., cross_task_context: ..., mode: ... })`. + +#### 2.2 — Handle implementer status + +Follow the per-task sub-status table in `skills/implement/SKILL.md` +verbatim. Re-loop limit: ≤ 2 retries with expanded context for +`NEEDS_CONTEXT`. 3rd → return `BLOCKED` to Boss (reason +`context-exhausted`). + +#### 2.3 — Spec-compliance review + +On implementer DONE / DONE_WITH_CONCERNS, dispatch +`ailang-spec-reviewer` with `task_text_path` (same file the +implementer read), `pre_task_sha`, `head_sha`, +`status_from_implementer`. + +`non_compliant`: re-dispatch the implementer with the reviewer's +report as repair brief. Re-loop limit: ≤ 2 retries. 3rd → return +`BLOCKED` (reason `review-loop-exhausted`). + +`unclear`: STOP. Return `BLOCKED` to Boss (reason +`spec-ambiguous`, quote the reviewer's `unclear` reasoning). + +#### 2.4 — Quality review + +Only after spec is `compliant`. Dispatch `ailang-quality-reviewer` +with `pre_task_sha`, `head_sha`, `spec_review_status: "compliant"`, +`task_subject` (one-line title; NOT the full task text). + +`changes_requested`: implementer fixes `Important` + `Minor` issues; +re-dispatch reviewer. Re-loop ≤ 2. 3rd → `BLOCKED` +(`review-loop-exhausted`). + +#### 2.5 — Task done + +TodoWrite update; proceed to next task. + +### Phase 3 — E2E coverage (standard mode, on full-iter completion) + +Dispatch `ailang-tester` with `iteration_scope`, `coverage_gap` (if +known), `mode: "e2e_after_iter"`. Tester writes E2E fixtures and +commits them on the branch. + +(Mini mode: skip Phase 3 — the RED test from `debug` IS the +coverage.) + +### Phase 4 — Write per-iter journal file + +Write `docs/journals/-iter-.md` (date is today, +not the iter's plan date). Template: + +```markdown +# iter — + +**Date:** YYYY-MM-DD +**Branch:** iter/ +**Status:** DONE | PARTIAL | BLOCKED +**Tasks completed:** of + +## Summary + +<1-paragraph summary; the Boss may rewrite this section during merge> + +## Per-task subjects + +- iter .1: +- iter .2: +- ... + +## Concerns + + + +## Known debt + + + +## Blocked detail + + + +## Commits + +.. + +## Stats + +bench/orchestrator-stats/-iter-.json +``` + +Commit on the branch: + +```bash +git add docs/journals/.md +git commit -m "iter : per-iter journal" +``` + +### Phase 5 — Write stats file + +Write `bench/orchestrator-stats/-iter-.json` +with at least these fields: + +```json +{ + "iter_id": "", + "date": "YYYY-MM-DD", + "mode": "standard|mini", + "outcome": "DONE|PARTIAL|BLOCKED", + "tasks_total": , + "tasks_completed": , + "reloops_per_task": { "1": 0, "2": 1, ... }, + "review_loops_spec": , + "review_loops_quality": , + "blocked_reason": "" +} +``` + +Commit on the branch: + +```bash +git add bench/orchestrator-stats/.json +git commit -m "iter : orchestrator stats" +``` + +### Phase 6 — Return end-report + +Compose the end-report per Output format below. Do NOT push the +branch — the Boss decides on integration. Do NOT touch +`docs/journals/INDEX.md` — Boss-only. + +## Status protocol + +The agent returns exactly one of: + +- `DONE` — full iter (or the requested task_range) completed; all + reviews green; journal + stats committed on branch. +- `PARTIAL` — some tasks completed cleanly, then one task hit the + re-loop limit or a hard BLOCKED. Earlier task commits remain on the + branch; journal records `Status: PARTIAL`. +- `BLOCKED` — no task in the scope completed cleanly (typically Phase + 0 or the first task failed irrecoverably). +- `NEEDS_CONTEXT` — the carrier from the Boss was missing required + fields (no `plan_path` in standard mode, no `red_test_path` in mini + mode, malformed `iter_id`). Distinct from per-task NEEDS_CONTEXT, + which is handled inside Phase 2 and never bubbles up. + +## Output format — end-report + +Plain-text, ≤ 500 tokens, fixed structure: + +``` +Status: DONE | PARTIAL | BLOCKED | NEEDS_CONTEXT +Iter: +Branch: iter/ +Tasks completed: of + - + - + ... +Journal file: docs/journals/-iter-.md (on branch) +Stats: bench/orchestrator-stats/-iter-.json (on branch) +Commits: .. +Tests: green, red +E2E coverage: +Blocked detail: (only if BLOCKED or PARTIAL) + Task: + Reason: context-exhausted | review-loop-exhausted | worker-blocked | spec-ambiguous | infra + Worker says: + Suggested next step: +``` + +## Common rationalisations + +| Excuse | Reality | +|--------|---------| +| "Plan said dispatch a single big task, I'll just inline it" | Then the plan is wrong, or you misread it. Tasks are the unit of dispatch; refuse to inline. | +| "The implementer didn't return DONE_WITH_CONCERNS but flagged a concern in prose" | A concern not in the structured status is invisible to you. Re-dispatch asking for the structured status; do not act on prose hints. | +| "I'll merge the branch myself, the Boss is busy" | Out of scope. Merge is Boss-only. Branch + journal + stats sit until the Boss reads the end-report. | +| "BLOCKED on task 3, I'll skip to task 4" | Skip is a Boss decision, not yours. Task dependencies are encoded in the plan and you do not know the graph. Return BLOCKED. | +| "Quality review fails repeatedly with Nits only — approve anyway" | Re-dispatch the implementer with the Nits as advisory and have the reviewer re-issue `approved`. Nits don't gate, but the reviewer's verdict does. | +| "I forgot to commit the journal file before returning" | Re-do Phase 4. Returning without the journal file committed is a bug, not a corner case. | +| "Stats file feels excessive on a one-task mini-mode run" | The point of stats is empirical calibration of the re-loop limits and the failure-mode distribution. One-task runs ARE the data. | + +## Red Flags — STOP + +- About to dispatch the implementer without reading + `skills/implement/SKILL.md` first this dispatch. +- About to edit `docs/journals/INDEX.md`. +- About to push the branch to remote (any `git push`). +- About to merge into main / rebase main / fast-forward main. +- About to skip Phase 4 (journal file) "because the run is BLOCKED". +- About to return more than 500 tokens of end-report. +- About to dispatch the quality-reviewer before spec is `compliant`. +- About to skip Phase 5 (stats file) "because mini mode". +``` + +- [ ] **Step 2: Verify the new file parses as agent frontmatter** + +Run: `head -5 skills/implement/agents/ailang-implement-orchestrator.md` +Expected: lines 1-4 form a valid YAML frontmatter block (`---`, three +`key: value` lines, `---`). + +- [ ] **Step 3: Commit** + +```bash +git add skills/implement/agents/ailang-implement-orchestrator.md +git commit -m "iter or.1.5: new agent ailang-implement-orchestrator" +``` + +--- + +## Task 6: Rewrite skills/implement/SKILL.md + +**Files:** +- Modify: `skills/implement/SKILL.md` (full rewrite, ~210 → ~100 lines) + +The rewrite delegates both Standard-Mode and Mini-Mode to the new +orchestrator-agent and documents the Boss-side merge step. The Iron +Law, per-task sub-status table, and Common Rationalisations remain — +they are the *canonical discipline source*, read by the orchestrator- +agent every dispatch. + +- [ ] **Step 1: Replace the file body** + +Overwrite `skills/implement/SKILL.md` with this exact content: + +```markdown +--- +name: implement +description: Use when an implementation plan exists in docs/plans/ and is ready to execute, OR when a debug RED-test is handed off for a bugfix. Dispatches the ailang-implement-orchestrator agent, which runs the entire per-task loop (implementer → spec-reviewer → quality-reviewer) on an isolated branch `iter/`, writes a per-iter journal + stats file, and returns a compressed end-report. The Boss reads the end-report, optionally rewrites the journal Summary section, appends one line to docs/journals/INDEX.md, and rebases onto main. +--- + +# implement — plan execution via a dedicated orchestrator-agent + +> **Violating the letter of these rules is violating the spirit.** + +## Overview + +Plan execution is fully delegated. The Boss-Orchestrator dispatches +ONE subagent (`ailang-implement-orchestrator`), which runs the entire +per-task loop in its own context: implementer → spec-reviewer → +quality-reviewer, per task, with the Iron Law and re-loop limits +below. All commits land on a dedicated branch `iter/`. +The Boss sees one ≤500-token end-report and a per-iter journal file +on the branch. + +This skill body is intentionally short. The procedural details of +the per-task loop live in +`skills/implement/agents/ailang-implement-orchestrator.md`. The +**canonical discipline** (Iron Law, sub-status table, common +rationalisations) lives in this file and is read by the +orchestrator-agent every dispatch. + +## When to Use / Skipping + +Triggers: +- A plan exists at `docs/plans/.md` (standard mode). +- A `debug` skill has produced a RED test + cause and is handing off + for the GREEN side (mini mode). + +**Never skipped** when there is code to ship. Trivial mechanical +edits (one-line typo fix, schema rename across N files) MAY be +handled inline by the Boss without dispatch, per CLAUDE.md "trivial +mechanical edits" carve-out — but no review-and-commit discipline +is shed. + +## The Iron Law + +``` +ONE BRANCH PER ITER — `iter/`, created from origin/main. +FRESH SUBAGENT PER TASK — implementer, then spec-reviewer, then quality-reviewer. +TWO-STAGE REVIEW: SPEC COMPLIANCE FIRST, CODE QUALITY SECOND. +NEVER START QUALITY REVIEW BEFORE SPEC COMPLIANCE IS GREEN. +NEVER PUSH PAST `BLOCKED` BY HAND. +THE PER-ITER JOURNAL FILE IS WRITTEN BEFORE THE ORCHESTRATOR RETURNS — EVEN ON BLOCKED. +``` + +## Per-task sub-status mechanics + +The orchestrator-agent reads and follows this table verbatim every +dispatch: + +| Sub-status | Orchestrator action | +|------------|---------------------| +| `DONE` | next task / next phase | +| `DONE_WITH_CONCERNS` | accumulate concern, next | +| `NEEDS_CONTEXT` (1st–2nd) | re-dispatch with expanded carrier | +| `NEEDS_CONTEXT` (3rd) | stop → `BLOCKED` to Boss, reason `context-exhausted` | +| `non_compliant` / `changes_requested` (1st–2nd) | implementer re-dispatch with the reviewer's report as repair brief | +| `non_compliant` / `changes_requested` (3rd) | stop → `BLOCKED` to Boss, reason `review-loop-exhausted` | +| `BLOCKED` (worker) | stop → `BLOCKED` to Boss, reason verbatim | +| `unclear` (spec-reviewer) | stop → `BLOCKED` to Boss, reason `spec-ambiguous` | +| Tool / infra error | stop → `BLOCKED` to Boss, reason `infra` + raw error | + +Re-loop limit: 2 retries per failure-mode per task. The 3rd is +`BLOCKED` to the Boss. `skip task K, continue` is intentionally NOT +a mode — tasks have implicit ordering dependencies and the +orchestrator does not know the dependency graph. + +## The Process — Boss side + +### Step 1 — Dispatch the orchestrator-agent + +For a standard iteration: + +``` +Agent("ailang-implement-orchestrator", { + mode: "standard", + iter_id: "", // e.g. "ct.2.3", "or.1", "23.4" + plan_path: "docs/plans/.md", + task_range: [3, 8] // optional +}) +``` + +For a debug-handoff (mini mode): + +``` +Agent("ailang-implement-orchestrator", { + mode: "mini", + iter_id: "bugfix-", + red_test_path: "", + cause_summary: "<1-2 sentences from debugger>", + constraint: "minimal fix, no surrounding cleanup" +}) +``` + +### Step 2 — Read the end-report + +The orchestrator returns a ≤500-token plain-text report (see the +agent's "Output format — end-report" section for the fixed +structure). Read it. The end-report is the only thing that costs the +Boss-context tokens; per-task chatter has stayed inside the +orchestrator-agent. + +### Step 3 — Boss merge step (on DONE / PARTIAL with partial DONE-tasks) + +1. Open the per-iter journal file on the branch: + `git show iter/:docs/journals/-iter-.md` + (or check out the branch if a closer look is needed). +2. Accept the agent's Summary section as-is, OR rewrite it with + Boss-level framing. The rest of the journal file is factual and + preserved verbatim. +3. Append one line to `docs/journals/INDEX.md`: + `- YYYY-MM-DD — iter : → -iter-.md` +4. Rebase the iter branch onto main: + `git rebase iter/ onto main` (or fast-forward if linear). +5. Optionally delete the branch: `git branch -D iter/`. +6. If trigger is done-state and the user is away, write a + `docs/WhatsNew.md` entry + `notify.sh` per CLAUDE.md's + "Done-state notifications" subsection. + +### Step 4 — Boss handling (on BLOCKED) + +1. Read the per-iter journal on the branch — `Blocked detail:` names + the failure mode. +2. Decide: + - **Repair:** adjust plan or extend context; re-dispatch the + orchestrator with the same `iter_id` and a `task_range` covering + the remaining tasks. The orchestrator picks up the existing + branch. + - **Discard:** `git branch -D iter/`. INDEX.md is NOT + touched (the orchestrator did not append). + - **Escalate:** ask the user via `notify.sh`. The branch sits + until the conversation resumes. + +## Handoff Contract + +`implement` consumes: + +| Source | Carrier | +|--------|---------| +| from `planner` | path to `docs/plans/.md` (+ optional `task_range`) | +| from `debug` | RED-test path + cause summary + minimal-fix constraint | + +`implement` produces: a feature branch `iter/` carrying +per-task commits, a per-iter journal file (`docs/journals/.md`), +and a stats file (`bench/orchestrator-stats/.json`). The Boss +merges and updates `docs/journals/INDEX.md`. No further hand-off — +`audit` runs independently at milestone close. + +## Common Rationalisations + +| Excuse | Reality | +|--------|---------| +| "Single task, dispatch overhead exceeds the work" | The orchestrator-agent IS the discipline. A single dispatch is cheap; the per-task review loop, the branch isolation, and the journal file are the value. | +| "I'll merge on main directly, no need for the iter branch" | The branch is what makes parallel `/implement` activity safe and makes "discard on BLOCKED" trivial. Skipping it puts you back in the pre-2026-05-11 coordination problems. | +| "BLOCKED end-report, let me dig into the branch and continue myself" | Read the `Blocked detail:` first. The orchestrator stopped at the re-loop limit for a reason. Continuing by hand undoes the discipline. | +| "End-report says PARTIAL with 4/5 DONE — close to enough" | The 5th task may carry an invariant the earlier 4 silently depend on. Either re-dispatch for the missing task or treat the iter as incomplete. | +| "Skip the INDEX line, the journal file is enough" | INDEX.md is the only thing that makes per-iter journals navigable. Without it, future agents have to ls the directory and parse filenames. | +| "I'll let the orchestrator-agent update INDEX.md" | No. INDEX.md is Boss-only. The orchestrator-agent does not know what `` the Boss will pick. | + +## Red Flags — STOP + +- Boss dispatching `ailang-implementer` directly (bypassing the + orchestrator-agent). +- Boss editing a per-iter journal file on `main` instead of on its + iter branch. +- Two `/implement` runs sharing one `iter_id`. +- INDEX.md modified by anything other than the Boss. +- Branch `iter/` pushed to remote before the merge step + decided what to do with it. +- End-report longer than ~500 tokens. + +## Cross-references + +- **Agent dispatched:** + `skills/implement/agents/ailang-implement-orchestrator.md` — + carries the per-task loop, including dispatch of: + - `skills/implement/agents/ailang-implementer.md` (Phase 2.1) + - `skills/implement/agents/ailang-spec-reviewer.md` (Phase 2.3) + - `skills/implement/agents/ailang-quality-reviewer.md` (Phase 2.4) + - `skills/implement/agents/ailang-tester.md` (Phase 3) +- **Input sources:** + - `skills/planner/SKILL.md` — produces the plan files this skill + consumes + - `skills/debug/SKILL.md` — produces the RED-test handoff for + mini-mode +- **Output target:** Boss reads the end-report and the per-iter + journal; `audit` runs at milestone close. +- **Documented exception:** in `skills/README.md`, this is the named + exception to "agents do not call other agents". +``` + +- [ ] **Step 2: Verify** + +Run: `wc -l skills/implement/SKILL.md` +Expected: between 110 and 160 lines (rough sanity; spec said ~100). + +Run: `grep -c "Iron Law" skills/implement/SKILL.md` +Expected: ≥ 1. (Discipline source preserved.) + +Run: `grep -c "Per-task sub-status" skills/implement/SKILL.md` +Expected: 1. (Sub-status table preserved.) + +- [ ] **Step 3: Commit** + +```bash +git add skills/implement/SKILL.md +git commit -m "iter or.1.6: rewrite skills/implement/SKILL.md to delegate to orchestrator-agent" +``` + +--- + +## Task 7: One-line exception note in skills/README.md + agent-roster row + +**Files:** +- Modify: `skills/README.md` + +- [ ] **Step 1: Patch the "Agents do not call other agents" line** + +Find this paragraph in the `## Conventions` section (currently near +the bottom of the file): + +```markdown +- **Agents do not call other agents.** The dirigierende skill + composes (e.g. `implement` dispatches implementer, then a separate + spec-compliance reviewer, then a code-quality reviewer). +``` + +Replace with: + +```markdown +- **Agents do not call other agents — one named exception.** The + dirigierende skill composes (e.g. `audit` dispatches architect, then + bencher, then docwriter). The single exception is + `ailang-implement-orchestrator`, which runs the per-task implementer + → spec-reviewer → quality-reviewer loop on its own; this exception + is documented in `skills/implement/SKILL.md` and exists to keep + per-iter chatter out of the Boss-context. No other agent gains the + `Agent` tool. +``` + +- [ ] **Step 2: Add the orchestrator-agent to the agent roster table** + +Find the agent roster table (starts with `| Agent | Path | +Dispatched by skill |`). Insert this row immediately above the +`ailang-implementer` row: + +```markdown +| `ailang-implement-orchestrator` | `implement/agents/` | `implement` (the only agent with the `Agent` tool; runs the per-task loop) | +``` + +- [ ] **Step 3: Verify** + +Run: `grep -n "ailang-implement-orchestrator" skills/README.md` +Expected: 1 match (the new roster row). + +Run: `grep -c "one named exception" skills/README.md` +Expected: 1. + +- [ ] **Step 4: Commit** + +```bash +git add skills/README.md +git commit -m "iter or.1.7: document ailang-implement-orchestrator as named exception" +``` + +--- + +## Verification ladder (post-implementation, manual) + +Run after all seven tasks have committed. The ladder is the 8-step +list from the parent spec §"Testing strategy". Steps 1–5 are sanity +checks the Boss can run inline; steps 6–7 require an intentionally +failing fixture and are deferred to the first real `/implement` run +that hits a re-loop; step 8 is performed live on the first successful +orchestrator-agent dispatch. + +- [ ] **Ladder 1: Agent file parses** + +`Agent("ailang-implement-orchestrator", { mode: "standard", iter_id: "smoke-test", plan_path: "docs/plans/" })` +on a one-task no-op plan resolves and returns either DONE or a +structured BLOCKED. (Defer to the first real iter — no synthetic +fixture is required for this ladder pass.) + +- [ ] **Ladder 2: Branch isolation** + +After Ladder 1's dispatch: `git branch | grep iter/smoke-test` +Expected: branch exists. `git diff main..iter/smoke-test` shows +commits. + +- [ ] **Ladder 3: Single-task standard-mode run** + +First real one-task `/implement` after the refactor lands. Expected: +green build, green tests on the branch, journal file at +`docs/journals/-iter-.md` on the branch, stats file at +`bench/orchestrator-stats/-iter-.json` on the branch, +end-report in the fixed format. + +- [ ] **Ladder 4: Multi-task standard-mode run** + +First real 3+-task `/implement` after the refactor lands. Same shape +as Ladder 3. + +- [ ] **Ladder 5: Mini-mode run** + +First real `debug` → `/implement` mini-mode handoff after the +refactor lands. Expected: end-report in same shape, branch named +`iter/bugfix-<>`, no Phase 3 (E2E coverage) — the RED test is the +coverage. + +- [ ] **Ladder 6: Re-loop run (deferred)** + +Marked complete once a real iter hits 2 review re-loops on the same +task and the orchestrator returns BLOCKED with reason +`review-loop-exhausted`. + +- [ ] **Ladder 7: BLOCKED run (deferred)** + +Marked complete once a real iter hits a worker BLOCKED and the +orchestrator returns BLOCKED with the worker's reason verbatim. + +- [ ] **Ladder 8: Boss-merge step** + +On Ladder 3 or 4's successful run: manually integrate — read journal, +write INDEX line, rebase, optionally delete branch. Verify linear +history with `git log --oneline main..HEAD` showing no merge commits +and INDEX.md gaining exactly one line. + +The ladder is not committed as code; it is a Boss checklist. +Ladders 1–5 should be runnable inside the same session that lands the +refactor. Ladders 6–8 are recorded as "passed on first encounter" in +the next per-iter journal that hits them. + +--- + +## Out of scope + +Per parent spec §"Out of scope": + +- Worker model downgrade — all roles stay at Opus 4.7. +- Stats aggregation tool — written once empirical data exists. +- Plan-drafter sub-agent for `/planner`. +- `/brainstorm` spec-drafter. +- `docs/DESIGN.md` semantic changes (only the JOURNAL.md → journals + reference is updated in Task 2). +- External-platform integration (Gitea PRs, GitHub mirror). + +--- + +## Acceptance + +This plan is accepted as complete when all seven tasks have green +commits, the post-implementation Verification Ladder steps 1–5 pass +inline, and Ladders 6–8 are tracked for "pass on first encounter" in +the next iter's journal that exercises them.