feat: skill implement — plan execution with two-stage review
This commit is contained in:
@@ -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/<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 a fresh subagent (`general-purpose` or appropriate role)
|
||||
with:
|
||||
- the original task text from the plan
|
||||
- the diff the implementer produced (`git diff <pre-task>..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 <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 `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.
|
||||
Reference in New Issue
Block a user