---
name: implement
description: Use when an implementation plan exists in docs/plans/ and is ready to execute. Dispatches one fresh subagent per task with two-stage review (spec compliance, then code quality). Continuous execution; stops only on BLOCKED status or completion. Also runs in mini-mode for bug fixes handed off by debug.
---

# implement — plan execution with two-stage review

> **Violating the letter of these rules is violating the spirit.**

## Overview

Plan execution is delegated work. The orchestrator (me) reads the
plan once, dispatches a fresh subagent per task, and reviews each
task's output through two independent checks (spec compliance, then
code quality) before moving on. Subagents have isolated context; the
orchestrator only sees their reports. This is what gives AILang's
development cycle its context budget back.

## When to Use / Skipping

Triggers:
- A plan exists at `docs/plans/<iteration>.md` and is ready to run.
- A `debug` skill has produced a RED test + cause and is handing off
  for the GREEN side (mini-mode, no plan file).

**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 orchestrator without dispatching subagents,
per CLAUDE.md "trivial mechanical edits" carve-out — but the
review-and-commit discipline still applies.

## The Iron Law

```
FRESH SUBAGENT PER TASK
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 Process — standard mode (plan-driven)

### Step 1 — Load plan once, extract everything

Read `docs/plans/<iteration>.md` ONCE. Extract every task with full
text. Create TodoWrite entries for each task. Note any cross-task
context (shared types, file structure decisions).

The plan is NOT re-read by subagents. The orchestrator hands each
subagent the full task text plus surrounding scene-set context.

### Step 2 — Per-task loop

For each task in TodoWrite order:

#### 2.1 — Dispatch implementer

Dispatch `ailang-implementer` with:
- the full task text from the plan
- scene-set: parent milestone, where this task fits, dependencies
  on earlier tasks
- output expectations: build green, tests green, structured report

#### 2.2 — Handle implementer status

The implementer reports one of:

| Status | Action |
|--------|--------|
| `DONE` | Proceed to spec compliance review (Step 2.3). |
| `DONE_WITH_CONCERNS` | Read concerns first. If correctness/scope, address before review. If observation, note + proceed. |
| `NEEDS_CONTEXT` | Provide missing context, redispatch. Max 2 retries with the same model before escalating. |
| `BLOCKED` | Diagnose: context problem? → more context. Reasoning? → stronger model. Task too large? → split + re-plan. Plan wrong? → escalate to user. **Never** push past BLOCKED by hand. |

#### 2.3 — Spec compliance review

Dispatch `ailang-spec-reviewer` with:
- `task_text`: the verbatim text from the plan (same text the
  implementer received)
- `diff`: the implementer's diff (or `pre_task_sha` + `head_sha`)
- `status_from_implementer`: `DONE` or `DONE_WITH_CONCERNS` (with
  the concerns quoted)

The reviewer reports `compliant` / `non_compliant` / `unclear` /
`infra_blocked`.

If `non_compliant`: implementer (same subagent role) fixes the missing
requirements / removes the unrequested extras; re-dispatch the spec
reviewer; loop until `compliant`.

If `unclear`: the task text is ambiguous. Resolve at the orchestrator
level — either by re-stating the task to the implementer with the
ambiguity removed, or by bouncing back to `plan` if the spec itself
is the source of the ambiguity.

#### 2.4 — Code quality review

ONLY after spec compliance is `compliant`, dispatch
`ailang-quality-reviewer` with:
- `diff` (or SHAs)
- `spec_review_status`: must be `compliant` (otherwise quality review
  refuses to run)
- `task_subject`: short title for context (NOT the full task text —
  quality review doesn't care about spec compliance)

The reviewer reports `approved` / `changes_requested` / `infra_blocked`.

If `changes_requested`: implementer fixes the `Important` and `Minor`
issues; `Nit` items are advisory. Re-dispatch the quality reviewer;
loop until `approved`.

#### 2.5 — Mark task complete

TodoWrite update. Move to next task.

### Step 3 — E2E coverage

After all tasks: dispatch `ailang-tester` to add or extend E2E tests
that protect the milestone's invariants. The tester reads the spec
and the recent commits to identify what to cover.

### Step 4 — JOURNAL entry

Append the iteration entry: `## YYYY-MM-DD — Iteration <X>: <title>`,
including:
- one-paragraph summary
- per-task subjects (mirrors commit messages)
- known debt (anything deliberately not touched)

Commit pattern matches existing JOURNAL style:
`iter <X>.<n>: <subject>` for task commits.

## The Process — mini-mode (debug handoff)

When invoked from `skills/debug` with a RED-test path + cause
summary:

1. Skip plan loading (no plan file).
2. Dispatch `ailang-implementer` with:
   - "make this RED test pass: `<path>`"
   - cause summary from `debug`
   - hard constraint: *minimal fix, no surrounding cleanup*
3. Spec compliance review: "does this fix the RED test without
   touching anything outside the bug's scope?"
4. Code quality review: standard.
5. Commit pattern: `fix: <symptom>` (single commit, GREEN side).
6. JOURNAL entry: `## YYYY-MM-DD — Bug fix: <symptom>`.

## Handoff Contract

`implement` consumes:

| Source | Carrier |
|--------|---------|
| from `plan` | path to `docs/plans/<iteration>.md` + optional task focus |
| from `debug` | RED-test path + cause summary + minimal-fix constraint |

`implement` produces: per-task commits + JOURNAL entry. No further
hand-off — `audit` runs independently at milestone close.

## Model Selection

Use the cheapest model that handles each role.

| Task complexity | Model |
|-----------------|-------|
| 1-2 files, complete spec, mechanical | cheap/fast |
| Multi-file integration, judgement | standard |
| Architecture, design, review | most capable |

Reviewer subagents typically need at least the standard model.

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| "Implementer self-reviewed, skip spec compliance" | Self-review is intent, not outcome. Past iters showed self-review misses spec drift and quality issues that compound. |
| "Task is trivial, skip quality review" | The marginal cost of one subagent dispatch is trivial vs. catching a quality issue three iters later. |
| "Working on `main` directly is fine for this iter" | Branch first, reset main to pre-iter, cherry-pick onto feature branch. Defeats rollback discipline if not. |
| "DONE_WITH_CONCERNS, move on" | Read the concerns first. If correctness/scope, address before review. If observation, note in JOURNAL and proceed. |
| "Reviewer is the same model as implementer, dispatching twice is redundant" | Fresh context per dispatch is the point, not the model identity. The reviewer doesn't see the implementer's reasoning, only its diff. |
| "BLOCKED with 'task too large' — let me push through" | Split + re-plan. Pushing through wastes context and produces low-quality output. |

## Red Flags — STOP

- Quality review running before spec compliance is ✅
- Two reviewers dispatched in parallel (must be sequential)
- Subagent re-reading the plan file (controller curates context)
- Direct edit to `main` without feature branch
- Skipping JOURNAL entry "because the commits are self-explanatory"
- "I'll do the E2E coverage in the next iter"

## Cross-references

- **Agents dispatched:**
  - `skills/implement/agents/ailang-implementer.md` — task execution
    (carries TDD discipline as an independent layer; falls back to
    RED-first even when the plan template forgot)
  - `skills/implement/agents/ailang-spec-reviewer.md` — Step 2.3, did
    the diff match the task text?
  - `skills/implement/agents/ailang-quality-reviewer.md` — Step 2.4,
    is the diff well-built?
  - `skills/implement/agents/ailang-tester.md` — Step 3, E2E coverage
- **Input sources:**
  - `skills/plan/SKILL.md` — produces the plan files this skill
    consumes
  - `skills/debug/SKILL.md` — produces the RED-test handoff for
    mini-mode
- **Output target:** orchestrator (me) reads JOURNAL entry and
  commits; `audit` runs at milestone close.