AILang/skills/implement/SKILL.md

---
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 phase → spec-compliance check → quality check, as sequential role-switches in its own context) 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 fast-forwards main to the iter branch.
---

# 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 phase → spec-compliance
check → quality check, per task, as sequential role-switches inside
the orchestrator-agent itself (Claude Code does not permit nested
subagent dispatch — see Cross-references). 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 local main.
PER-TASK PHASES RUN SEQUENTIALLY IN THE ORCHESTRATOR-AGENT'S OWN CONTEXT — implementer phase, then spec-compliance check, then quality check. Each phase is a deliberate role-switch, NOT a fresh subagent (nested-subagent dispatch is forbidden by Claude Code).
TWO-STAGE CHECK PER TASK: SPEC COMPLIANCE FIRST, CODE QUALITY SECOND.
NEVER START THE QUALITY CHECK BEFORE THE SPEC-COMPLIANCE CHECK 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 values are *internal* to the orchestrator-agent
— they describe the state of an inline role-phase, not the status
of a separate subagent. The vocabulary is preserved because it maps
1:1 to the phase reference files
(`ailang-implementer.md` / `ailang-spec-reviewer.md` /
`ailang-quality-reviewer.md`) the orchestrator-agent consults at
each role-switch.

| Sub-status | Orchestrator action |
|------------|---------------------|
| `DONE` | next phase / next task |
| `DONE_WITH_CONCERNS` | accumulate concern, next phase |
| `NEEDS_CONTEXT` (1st–2nd) | re-attempt the phase with expanded context |
| `NEEDS_CONTEXT` (3rd) | stop → `BLOCKED` to Boss, reason `context-exhausted` |
| `non_compliant` / `changes_requested` (1st–2nd) | switch back to implementer mindset, repair with the check's report as repair brief, then re-run the check phase |
| `non_compliant` / `changes_requested` (3rd) | stop → `BLOCKED` to Boss, reason `review-loop-exhausted` |
| `BLOCKED` (implementer phase) | stop → `BLOCKED` to Boss, reason verbatim |
| `unclear` (spec-compliance phase) | 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 or PARTIAL)

> **Switch to main FIRST.** The orchestrator-agent ends its run with
> the worktree on `iter/<iter_id>` (Phase 0 created the branch and
> all per-task commits land on it). Any Boss commit issued before
> `git switch main` lands on the iter branch by mistake — including
> the INDEX-append below. This is a recurring papercut. Do the
> switch before any Boss-side edit.

1. Open the per-iter journal file on the branch (read-only, branch-
   independent): `git show iter/<iter_id>:docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md`.
2. Decide whether the agent's Summary section is acceptable or needs
   a Boss-level rewrite. The rest of the journal file is factual and
   preserved verbatim. Defer the actual edit to step 5 — it lands on
   main, not on the iter branch.
3. Fast-forward main to the iter branch:
   `git switch main && git merge --ff-only iter/<iter_id>`. Since the
   iter branch was created from local `main` (Phase 0 of the
   orchestrator-agent) and no commits have landed on main since, the
   fast-forward is always linear.
4. Append one line to `docs/journals/INDEX.md` and commit:
   `- YYYY-MM-DD — iter <iter_id>: <one-line title> → <YYYY-MM-DD>-iter-<iter_id>.md`
5. If the Summary needed rewriting (step 2), edit the journal file
   on main now and commit.
6. Optionally delete the branch: `git branch -D iter/<iter_id>`.
7. 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 phase 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. |
| "The per-task phases run inline anyway, just have the Boss dispatch the reviewer-agents instead and skip the orchestrator-agent" | That gives back fresh-per-phase context but loses the Boss-context offload — the per-task chatter goes back through the Boss. The orchestrator-agent exists precisely for the offload. If you want fresh-per-phase context AND offload, you want a capability Claude Code does not provide. |

## 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 inline; each phase is a role-switch in
  the orchestrator-agent's own context. The role-files below are
  *phase references* (the orchestrator-agent reads them at each
  role-switch to inhale the discipline) — they are NOT separately
  dispatched subagents:
  - `skills/implement/agents/ailang-implementer.md` — Phase 2.1
    reference (implementer mindset, TDD discipline)
  - `skills/implement/agents/ailang-spec-reviewer.md` — Phase 2.2
    reference (spec-compliance mindset)
  - `skills/implement/agents/ailang-quality-reviewer.md` — Phase
    2.3 reference (quality-review mindset)
  - `skills/implement/agents/ailang-tester.md` — Phase 3 reference
    (E2E coverage mindset)
- **Why inline phases, not nested subagents.** Claude Code does not
  permit a subagent to spawn other subagents. The orchestrator-agent
  cannot dispatch the role-agents above; it adopts each role as a
  sequential phase in its own context. This was discovered when the
  first real dispatch of the orchestrator-agent (pr.1, 2026-05-11)
  reported that the `Agent` tool was absent from its tool set even
  though frontmatter declared it. The architecture has been revised
  accordingly (see `docs/journals/2026-05-11-iter-or.2.md`).
- **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.