diff --git a/skills/implement/SKILL.md b/skills/implement/SKILL.md new file mode 100644 index 0000000..161fb98 --- /dev/null +++ b/skills/implement/SKILL.md @@ -0,0 +1,197 @@ +--- +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. + +The pattern is `superpowers:subagent-driven-development` adapted to +the AILang agent toolchain. + +## When to Use / Skipping + +Triggers: +- A plan exists at `docs/plans/.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/.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 a fresh subagent (`general-purpose` or appropriate role) +with: +- the original task text from the plan +- the diff the implementer produced (`git diff ..HEAD`) +- prompt: "Does this diff implement the task as specified? List + missing requirements; list extras not requested." + +If issues found: implementer (same subagent role) fixes; re-dispatch +the spec reviewer; loop until ✅. + +#### 2.4 — Code quality review + +ONLY after spec compliance is ✅, dispatch a fresh code-quality +reviewer with: +- the diff +- prompt: "Strengths, issues by severity (Important / Minor / Nit), + recommendation." + +If issues found: implementer fixes; re-dispatch quality reviewer; +loop until ✅. + +#### 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 : `, +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 + +- **Upstream pattern:** `superpowers:subagent-driven-development` — + source of the per-task fresh-subagent + two-stage review pattern. + `superpowers:executing-plans` for the parallel-session variant + (rarely used in AILang). +- **Agents dispatched:** + - `skills/implement/agents/ailang-implementer.md` — task execution + - `skills/implement/agents/ailang-tester.md` — 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.