199 lines
9.0 KiB
Markdown
199 lines
9.0 KiB
Markdown
---
|
||
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 → 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.
|