AILang/skills/implement/SKILL.md

name, description

name	description
implement	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 planner 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 planner	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/planner/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.