AILang/docs/plans/0029-orchestrator-refactor.md

# Orchestrator-Refactor — Implementation Plan

> **Parent spec:** `docs/specs/0008-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/<YYYY-MM-DD>-iter-<id>.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 <X>: read DESIGN.md, JOURNAL.md, the latest milestone
```

Replace with:

```markdown
For milestone <X>: 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 <X>.<n>: e2e for <feature>`).
```

Replace with:

```markdown
5. Commit per existing journal style (`iter <X>.<n>: e2e for <feature>`).
```

- [ ] **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: "<verbatim block>"`) to a file path
(`task_text_path: "/tmp/ail-iter/<iter_id>/task-<N>.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/<iter_id>/task-<N>.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/<iter_id>/task-<N>.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/<iter_id>`), 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-<short-symptom>"` (mini). Used for branch name, scratch dir, journal filename, stats filename, commit subjects |
| `plan_path` | (standard only) `docs/plans/<file>.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/<iter_id>`, 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/<iter_id>` already exists locally
   (Boss-side repair re-dispatch): `git switch iter/<iter_id>`.
   Otherwise: `git switch -c iter/<iter_id> origin/main`.
3. Record `pre_iter_sha = $(git rev-parse HEAD)` for the end-report.
4. Create scratch dir: `mkdir -p /tmp/ail-iter/<iter_id>`.

### 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/<iter_id>/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/<iter_id>/task-1.md` of the form:

  ```
  Make this RED test pass: <red_test_path>

  Cause (from debugger):
  <cause_summary>

  Constraint: <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/<iter_id>/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/<YYYY-MM-DD>-iter-<iter_id>.md` (date is today,
not the iter's plan date). Template:

```markdown
# iter <iter_id> — <one-line title>

**Date:** YYYY-MM-DD
**Branch:** iter/<iter_id>
**Status:** DONE | PARTIAL | BLOCKED
**Tasks completed:** <N> of <total>

## Summary

<1-paragraph summary; the Boss may rewrite this section during merge>

## Per-task subjects

- iter <iter_id>.1: <commit subject>
- iter <iter_id>.2: <commit subject>
- ...

## Concerns

<aggregated DONE_WITH_CONCERNS lines, one per task; empty list if none>

## Known debt

<one-liner each, with why-not-touched; empty list if none>

## Blocked detail

<only if BLOCKED / PARTIAL: task N, reason from the sub-status table,
worker's verbatim BLOCKED text, suggested next step>

## Commits

<pre_iter_sha>..<head_sha>

## Stats

bench/orchestrator-stats/<YYYY-MM-DD>-iter-<iter_id>.json
```

Commit on the branch:

```bash
git add docs/journals/<file>.md
git commit -m "iter <iter_id>: per-iter journal"
```

### Phase 5 — Write stats file

Write `bench/orchestrator-stats/<YYYY-MM-DD>-iter-<iter_id>.json`
with at least these fields:

```json
{
  "iter_id": "<iter_id>",
  "date": "YYYY-MM-DD",
  "mode": "standard|mini",
  "outcome": "DONE|PARTIAL|BLOCKED",
  "tasks_total": <int>,
  "tasks_completed": <int>,
  "reloops_per_task": { "1": 0, "2": 1, ... },
  "review_loops_spec": <int>,
  "review_loops_quality": <int>,
  "blocked_reason": "<one of: context-exhausted | review-loop-exhausted | worker-blocked | spec-ambiguous | infra | null>"
}
```

Commit on the branch:

```bash
git add bench/orchestrator-stats/<file>.json
git commit -m "iter <iter_id>: 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:             <iter_id>
Branch:           iter/<iter_id>
Tasks completed:  <N> of <total>
                  - <commit subject 1>
                  - <commit subject 2>
                  ...
Journal file:     docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md (on branch)
Stats:            bench/orchestrator-stats/<YYYY-MM-DD>-iter-<iter_id>.json (on branch)
Commits:          <pre_iter_sha>..<head_sha>
Tests:            <count> green, <count> red
E2E coverage:     <new fixture paths, or "none (mini mode)">
Blocked detail:   (only if BLOCKED or PARTIAL)
                  Task: <N>
                  Reason: context-exhausted | review-loop-exhausted | worker-blocked | spec-ambiguous | infra
                  Worker says: <verbatim reason from the worker's report>
                  Suggested next step: <one sentence>
```

## 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/<iter_id>`, 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/<iter_id>`.
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/<iteration>.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/<iter_id>`, 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: "<iter_id>",         // e.g. "ct.2.3", "or.1", "23.4"
  plan_path: "docs/plans/<file>.md",
  task_range: [3, 8]            // optional
})
```

For a debug-handoff (mini mode):

```
Agent("ailang-implement-orchestrator", {
  mode: "mini",
  iter_id: "bugfix-<short-symptom>",
  red_test_path: "<absolute 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/<iter_id>:docs/journals/<YYYY-MM-DD>-iter-<iter_id>.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_id>: <one-line title> → <YYYY-MM-DD>-iter-<iter_id>.md`
4. Rebase the iter branch onto main:
   `git rebase iter/<iter_id> onto main` (or fast-forward if linear).
5. Optionally delete the branch: `git branch -D iter/<iter_id>`.
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/<iter_id>`. 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/<iteration>.md` (+ optional `task_range`) |
| from `debug` | RED-test path + cause summary + minimal-fix constraint |

`implement` produces: a feature branch `iter/<iter_id>` carrying
per-task commits, a per-iter journal file (`docs/journals/<file>.md`),
and a stats file (`bench/orchestrator-stats/<file>.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 `<one-line title>` 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/<iter_id>` 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/<an existing tiny plan>" })`
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/<date>-iter-<id>.md` on the branch, stats file at
`bench/orchestrator-stats/<date>-iter-<id>.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.