AILang/skills/implement/SKILL.md

name, description

name

description

implement

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 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 → 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 or PARTIAL)

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. Fast-forward main to the iter branch: git switch main && git merge --ff-only iter/<iter_id>. Since the iter branch was created from origin/main (Phase 0 of the orchestrator-agent) and no commits have landed on main since, the fast-forward is always 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. ailang-implement-orchestrator is the named exception to "agents do not call other agents". See its file frontmatter and Iron Law for the precise scope.