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 phase → spec-compliance check → quality check, as sequential role-switches in its own context) directly in the working tree without creating commits, writes a per-iter journal + stats file (also uncommitted), and returns a compressed end-report. The Boss reads the end-report, inspects the working tree, decides commit shape, and performs all commits.

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 work lives in the working tree: code edits, the per-iter journal file, and the stats file. The orchestrator does NOT commit. The Boss sees one ≤500-token end-report and an unstaged working tree, then decides commit shape.

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

THE IMPLEMENTER NEVER COMMITS. CODE EDITS, THE PER-ITER JOURNAL, AND THE STATS FILE ALL LIVE IN THE WORKING TREE AS UNSTAGED CHANGES UNTIL THE BOSS COMMITS THEM.
MAIN HEAD IS SACROSANCT — NO RESET, NO REVERT, BY ANY ACTOR. MAIN MOVES FORWARD ONLY VIA BOSS COMMITS.
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"
})

Before dispatch: ensure the working tree is clean (git status --porcelain empty). The orchestrator's Phase 0 will refuse to start on a dirty tree.

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 inspect + commit step (on DONE or PARTIAL)

The orchestrator returns with code edits, the per-iter journal file, and the stats file all sitting in the working tree as unstaged changes. Nothing is committed yet.

1. Inspect: git status and git diff — confirm the changes match what the end-report claims. Read the per-iter journal file at docs/journals/<YYYY-MM-DD>-iter-<iter_id>.md directly from the working tree.
2. Decide whether the agent's Summary section in the journal is acceptable or needs a Boss-level rewrite. Edit it in place if needed.
3. Decide commit shape — by default one cohesive commit for the whole iter; split into a few logical commits only if the diff genuinely covers multiple unrelated changes. Per-task commit splitting is NOT a goal; the iter is the unit of consistency the Boss is committing to.
4. Stage + commit the code edits, the journal, and the stats file.
5. Append one line to docs/journals/INDEX.md and include it in the same commit (or a follow-up commit): - YYYY-MM-DD — iter <iter_id>: <one-line title> → <YYYY-MM-DD>-iter-<iter_id>.md
6. If trigger is done-state and the user is away, write a docs/WhatsNew.md entry + run notify.sh per skills/boss/SKILL.md "Done-state notifications: WhatsNew.md" subsection.

Step 4 — Boss handling (on BLOCKED)

The orchestrator returns with whatever work-in-progress it managed plus the per-iter journal recording Status: BLOCKED. Nothing is committed. The Boss decides what to do with the dirty working tree:

1. Read the per-iter journal at the working-tree path — Blocked detail: names the failure mode. Read git diff to see what was attempted.
2. Decide:
   • Repair: keep the working-tree changes in place (or stash them with git stash if a clarifying read of clean main is needed first). Adjust plan or extend context; re-dispatch the orchestrator with the same iter_id and a task_range covering the remaining tasks. Phase 0's clean-tree check will refuse if the tree is dirty — Boss either stashes or commits a known-good subset before re-dispatch.
   • Discard: git checkout -- . to drop unstaged file changes; git clean -fd for any new files (with care). INDEX.md is not touched (no commit happened). main HEAD does NOT move.
   • Escalate: ask the user via notify.sh. Working tree sits until the conversation resumes.

Under no circumstance does the Boss git reset or git revert on main: there is nothing on main to undo (the orchestrator did not commit), and the policy forbids history rewinding on main even if there were.

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: an unstaged working tree containing the code edits, the per-iter journal file (docs/journals/<file>.md), and the stats file (bench/orchestrator-stats/<file>.json). The Boss inspects, commits, 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 working-tree isolation, and the journal file are the value.
"Let me have the orchestrator commit the per-task work, it's cleaner"	The orchestrator never commits. Boss-only commit is a project-wide rule (see CLAUDE.md): only the Boss decides when a state is consistent enough to enter main history.
"Per-task commits would help bisection later"	The orchestrator's per-task phases are review gates, not bisection points. Iter-level commits are the bisection unit — and they only exist if the whole iter passes the Boss's review.
"BLOCKED end-report, let me dig into the journal 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 tasks DONE — close enough, commit them"	The 5th task may carry an invariant the earlier 4 silently depend on. Either re-dispatch for the missing task or git checkout -- . and re-plan.
"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 have the orchestrator-agent update INDEX.md to save a Boss step"	No. INDEX.md is Boss-only. The orchestrator does not know what <one-line title> the Boss will pick, and the orchestrator does not commit.
"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.
"BLOCKED iter with a bad commit on main — let me git revert it"	There is no bad commit on main: the orchestrator did not commit. Bad work stays in the working tree where it is still discardable. main HEAD is sacrosanct.

Red Flags — STOP

• Boss dispatching ailang-implementer directly (bypassing the orchestrator-agent).
• Boss running git reset or git revert on main.
• Orchestrator-agent running git commit (anywhere, ever).
• Two /implement runs overlapping on the same working tree.
• INDEX.md modified by anything other than the Boss.
• 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, inspects the working tree, and commits; audit runs at milestone close.