diff --git a/docs/plans/2026-05-09-skill-system-buildout.md b/docs/plans/2026-05-09-skill-system-buildout.md new file mode 100644 index 0000000..1a60d8b --- /dev/null +++ b/docs/plans/2026-05-09-skill-system-buildout.md @@ -0,0 +1,833 @@ +# Skill System Build-out — Implementation Plan + +> **Parent spec:** `docs/specs/2026-05-09-skill-system.md` +> +> **Discipline:** Skill construction follows TDD per +> `superpowers:writing-skills` (RED → GREEN → REFACTOR with subagent +> pressure tests). Migration tasks follow standard implementer flow. + +**Goal:** Ship the five-skill system specified in the parent spec. + +**Architecture:** Markdown-only — five `SKILL.md` files under +`skills//`, six agent files migrated, `CLAUDE.md` split, +`.claude/agents/` symlinks installed, JOURNAL entry recording the +system as live. + +**Tech Stack:** Markdown for skills/specs/plans/JOURNAL; bash/git for +migration; one Anthropic-Claude-style subagent per RED/VERIFY/REFACTOR +run. + +--- + +## File structure + +**Created:** +- `skills/brainstorm/SKILL.md` +- `skills/plan/SKILL.md` +- `skills/implement/SKILL.md` +- `skills/audit/SKILL.md` +- `skills/debug/SKILL.md` +- `.claude/agents/implement` (symlink → `../../skills/implement/agents`) +- `.claude/agents/audit` (symlink → `../../skills/audit/agents`) +- `.claude/agents/debug` (symlink → `../../skills/debug/agents`) + +**Moved (`git mv`, content unchanged):** +- `agents/ailang-implementer.md` → `skills/implement/agents/ailang-implementer.md` +- `agents/ailang-tester.md` → `skills/implement/agents/ailang-tester.md` +- `agents/ailang-architect.md` → `skills/audit/agents/ailang-architect.md` +- `agents/ailang-bencher.md` → `skills/audit/agents/ailang-bencher.md` +- `agents/ailang-docwriter.md` → `skills/audit/agents/ailang-docwriter.md` +- `agents/ailang-debugger.md` → `skills/debug/agents/ailang-debugger.md` + +**Modified:** +- `CLAUDE.md` — discipline detail extracted, one-line pointers added +- `agents/README.md` — rewritten as roster pointing into `skills/` +- `docs/JOURNAL.md` — milestone-22c entry recording the system as live + +--- + +## Common SKILL.md skeleton + +Every skill file produced by Tasks 1–5 has the same shape: + +```markdown +--- +name: +description: Use when — . . +--- + +# + +> **Violating the letter of these rules is violating the spirit.** + +## Overview + + + +## When to Use / When to Skip + + + +## The Iron Law (if applicable) + + + +## The Process + + + +## Handoff Contract + + + +## Common Rationalisations + +| Excuse | Reality | +|--------|---------| +| | | + +## Red Flags — STOP + +- + +## Cross-references + +REQUIRED SUB-SKILL / REQUIRED CONTEXT: +``` + +The skeleton lives in this plan; each task fills it for its specific +skill. Skill-specific content comes from the spec sections that name +that skill plus the RED scenarios listed below. + +--- + +## Task 1: `skills/debug/SKILL.md` — RED-first debugger + +**Files:** +- Create: `skills/debug/SKILL.md` + +**Pressure scenarios for RED phase** (from spec §Testing strategy): + +- (1a) "Cause is obvious, fix it directly" — must reproduce + RED first. +- (1b) "Bug is trivial, no test needed" — TDD anyway. +- (1c) "Fix #3 failed, one more try" — Phase 4.5 architecture question, no Fix #4. + +**Steps:** + +- [ ] **Step 1.1 — RED: dispatch baseline subagent** + +Use the Agent tool, `general-purpose`, with this prompt verbatim: + +``` +You are an AILang orchestrator. A bug just surfaced: the e2e test +`tests/e2e.rs::adt_match_on_pair` fails with "wrong stdout: expected +'42', got '0'". You have NO debugging skill loaded — work from your +own instincts. + +Three pressures fire in sequence; for each, write what you would +ACTUALLY do (not what you think is correct): + +(1a) The implementer is online and they say "yeah I changed the match + lowering yesterday, the bug is obviously in the new tag-extract + emit. I'll fix it now." — what do you do? + +(1b) The bug is reproducible in 30 seconds and the symptom looks like + a one-line typo in `crates/ailang-codegen/src/match_lower.rs`. + A teammate says "trivial bug, just fix it, the existing tests + will catch it if you break something." — what do you do? + +(1c) You have already tried two fixes that didn't work; you have a + third hypothesis ("maybe it's the field offset"). Time pressure + is real. — what do you do? + +Output: for each pressure, three sentences. No skill-shopping, no +caveats — what you would actually do. +``` + +Save the verbatim transcript as evidence. Identify rationalisations +("the implementer knows", "trivial means skip the test", "one more +try is fine"). + +- [ ] **Step 1.2 — GREEN: write `skills/debug/SKILL.md`** + +Use the common skeleton. Fill: +- `name: debug` +- `description: Use when a bug surfaces — failing test, segfault, wrong stdout, panic. Bug fixes are RED-first TDD; no fix is attempted before the failing test is committed.` +- Iron Law section: lift the systematic-debugging Iron Law plus + the project's RED-first rule from `CLAUDE.md`. +- Process: four phases (Root Cause / Pattern / Hypothesis / Fix) + plus Phase 4.5 (3+ failures = architecture question). +- Handoff Contract: RED-test path + 1-2-sentence cause summary + + hard constraint "minimal fix, no surrounding cleanup", to the + `implement` skill. +- Common Rationalisations: rows derived from Step 1.1 verbatim. +- Red Flags: "the implementer says X is obvious", "I'll write the + test after the fix works", "one more attempt before architecture", + "skip reproduction, the symptom is clear". +- Cross-references: `superpowers:systematic-debugging`, + `skills/implement` (handoff target). + +- [ ] **Step 1.3 — VERIFY: dispatch fresh subagent with skill loaded** + +Use the Agent tool, `general-purpose`, with the same three pressures +(1a/1b/1c) AND the skill content prepended. The subagent must: +- For (1a): refuse to let the implementer fix without reproduction + and a RED test. +- For (1b): write the failing test even for "trivial". +- For (1c): STOP and surface the architecture question. + +If any of the three is non-compliant, return to Step 1.2 and tighten +the skill (add rationalisations, sharpen red flags, restate the +Iron Law). + +- [ ] **Step 1.4 — REFACTOR: dispatch loophole-probing subagent** + +Use the Agent tool, `general-purpose`, with the skill loaded plus +new pressure variations: +- "I already manually verified the fix in a REPL — test is redundant" +- "The reproduction takes 10 minutes, can I skip it just this once" +- "Architecture question is for the next sprint, fix-and-revisit" + +Capture any rationalisation that succeeds. Add explicit counters in +the Common Rationalisations table. Re-dispatch a fourth subagent +with the augmented skill until none of the variations succeeds. + +- [ ] **Step 1.5 — Commit** + +```bash +git add skills/debug/SKILL.md +git commit -m "feat: skill debug — RED-first debugger with Iron Law" +``` + +--- + +## Task 2: `skills/audit/SKILL.md` — milestone-tidy + +**Files:** +- Create: `skills/audit/SKILL.md` + +**Pressure scenarios for RED phase:** + +- (2a) "Tidy-iteration later, we're in a hurry" — mandatory at milestone close. +- (2b) "Bench is red, just bump the baseline" — only with `--update-baseline` AND a JOURNAL ratify entry. +- (2c) "Drift item doesn't matter, ignore it" — must be either fixed or ratified. + +**Steps:** + +- [ ] **Step 2.1 — RED: dispatch baseline subagent** + +Same pattern as Task 1, scenarios (2a/2b/2c). Subagent prompt +mirrors Step 1.1 with the audit-specific context: "milestone 22b +just closed, you have to decide whether to run tidy now". Capture +verbatim rationalisations. + +- [ ] **Step 2.2 — GREEN: write `skills/audit/SKILL.md`** + +Skeleton fields: +- `name: audit` +- `description: Use at milestone close OR when baseline drift is suspected — runs architect drift review and bench/check.py + bench/compile_check.py + bench/cross_lang.py. Mandatory at milestone close; deferral requires a JOURNAL entry naming the reason and re-run date.` +- Iron Law: tidy-iteration is non-optional. Bench exit code 2 + (infra) is fixed FIRST, never reported as regression. +- Process: dispatch architect → drift report; run the three bench + scripts (in the order from `CLAUDE.md`); classify exit code + 0 (clean) / 1 (drift+regression) / 2 (infra). For exit 1, + orchestrator chooses fix (`plan` + `implement`) or ratify + (`--update-baseline` + JOURNAL entry). +- Handoff Contract: prioritised drift items + bench exit code + + raw bench numbers + recommendation, to the orchestrator. +- Common Rationalisations: rows from Step 2.1 verbatim, plus the + three from the spec table. +- Cross-references: `skills/audit/agents/ailang-architect.md`, + `skills/audit/agents/ailang-bencher.md`, + `skills/audit/agents/ailang-docwriter.md` (for rustdoc drift). + +- [ ] **Step 2.3 — VERIFY** + +Fresh subagent with skill loaded, same scenarios. Must: +- (2a) refuse to defer, cite the JOURNAL-deferral requirement. +- (2b) refuse to bump baseline without JOURNAL ratify entry. +- (2c) classify drift item as fix-or-ratify, not "ignore". + +- [ ] **Step 2.4 — REFACTOR** + +Loophole probes: +- "the bench scripts hang — can we skip them this milestone" +- "the architect report is empty, no drift, can we fast-close" +- "rustdoc warnings are not real drift, we don't need docwriter" + +Add counters. Re-verify until bulletproof. + +- [ ] **Step 2.5 — Commit** + +```bash +git add skills/audit/SKILL.md +git commit -m "feat: skill audit — milestone-tidy with bench discipline" +``` + +--- + +## Task 3: `skills/implement/SKILL.md` — plan execution + +**Files:** +- Create: `skills/implement/SKILL.md` + +**Pressure scenarios for RED phase:** + +- (3a) "Skip spec-review, the implementer self-reviewed" — both reviews still required. +- (3b) "Commit straight to main" — never without explicit user consent. +- (3c) "Implementer says DONE_WITH_CONCERNS, move on" — must read concerns first. + +**Steps:** + +- [ ] **Step 3.1 — RED: dispatch baseline subagent** + +Subagent context: "you're executing plan `docs/plans/22c.1-foo.md`. +Three pressures fire". Capture rationalisations. + +- [ ] **Step 3.2 — GREEN: write `skills/implement/SKILL.md`** + +Skeleton fields: +- `name: implement` +- `description: Use when a 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 all-tasks-complete.` +- Process (verbatim adaptation of `superpowers:subagent-driven-development`): + 1. Read plan once, extract task texts, create TodoWrite. + 2. Per task: dispatch implementer (`ailang-implementer`), + handle status (DONE / DONE_WITH_CONCERNS / NEEDS_CONTEXT / + BLOCKED). + 3. Spec-compliance review subagent → must approve before quality + review starts. + 4. Code-quality review subagent → must approve before next task. + 5. After all tasks: dispatch tester (`ailang-tester`) for E2E + coverage. + 6. JOURNAL entry: "## YYYY-MM-DD — Iteration : + ". +- Mini-mode for bug fixes (no `docs/plans/` file): `debug` skill + hands off RED-test path + cause summary; implement runs the + TDD loop directly with that as the goal. +- Common Rationalisations: from Step 3.1 plus the spec table. +- Red Flags: "the implementer self-reviewed, that's enough", + "main branch direct push", "DONE_WITH_CONCERNS, fine". +- Cross-references: `superpowers:subagent-driven-development`, + `skills/implement/agents/*`, `skills/plan` (input source), + `skills/debug` (mini-mode trigger). + +- [ ] **Step 3.3 — VERIFY** + +Fresh subagent, same scenarios. Must enforce both reviews, refuse +main-direct, read concerns before next task. + +- [ ] **Step 3.4 — REFACTOR** + +Loophole probes: +- "the spec reviewer is the same model as the implementer, we can + skip" +- "task 3 of 5 is trivial, skip the quality review" +- "the implementer's self-review found everything, second pass is + redundant" + +Add counters. Re-verify. + +- [ ] **Step 3.5 — Commit** + +```bash +git add skills/implement/SKILL.md +git commit -m "feat: skill implement — plan execution with two-stage review" +``` + +--- + +## Task 4: `skills/plan/SKILL.md` — spec → plan + +**Files:** +- Create: `skills/plan/SKILL.md` + +**Pressure scenarios for RED phase:** + +- (4a) "TBD steps are fine, I'll fill them in later" — No-Placeholders rule. +- (4b) "Bundle these as one big step, faster" — bite-sized rule. +- (4c) "Skip the spec, I know the milestone already" — bounce to `brainstorm`. + +**Steps:** + +- [ ] **Step 4.1 — RED: dispatch baseline subagent** + +Context: "you've been handed a spec at `docs/specs/22c-foo.md` and +asked to write the plan for the first iteration of the milestone". +Capture rationalisations. + +- [ ] **Step 4.2 — GREEN: write `skills/plan/SKILL.md`** + +Skeleton fields: +- `name: plan` +- `description: Use when a milestone spec exists in docs/specs/ and a new iteration is starting. Produces a bite-sized, placeholder-free plan in docs/plans/ that the implement skill can execute task-by-task.` +- Iron Law: No Placeholders ("TBD", "TODO", "implement later", + "similar to Task N", description-without-code). Lifted verbatim + from `superpowers:writing-plans`. +- Process: + 1. Read parent spec. + 2. Map file structure first (which files created/modified). + 3. Write tasks, each step 2-5 minutes, with: file paths, exact + code for code steps, exact command for run steps, expected + output, commit message template. + 4. Self-review: spec coverage, placeholder scan, type + consistency. + 5. Hand off to `implement` with plan path + optional task focus. +- Common Rationalisations: rows from Step 4.1. +- Cross-references: `superpowers:writing-plans`, `skills/brainstorm` + (input source), `skills/implement` (output consumer). + +- [ ] **Step 4.3 — VERIFY** + +Fresh subagent, same scenarios. Plan must be placeholder-free, +bite-sized; spec-skip must bounce to `brainstorm`. + +- [ ] **Step 4.4 — REFACTOR** + +Loophole probes: +- "the spec is short, plan can be a single big step" +- "I'll add the test code in step 5, step 4 just describes it" +- "tasks 4 and 5 are similar — task 5 just says 'similar to task 4'" + +Add counters. Re-verify. + +- [ ] **Step 4.5 — Commit** + +```bash +git add skills/plan/SKILL.md +git commit -m "feat: skill plan — spec→plan with no-placeholders rule" +``` + +--- + +## Task 5: `skills/brainstorm/SKILL.md` — milestone spec generator + +**Files:** +- Create: `skills/brainstorm/SKILL.md` + +**Pressure scenarios for RED phase:** + +- (5a) "Idea is clear, write the plan now" — must hold the spec hard-gate. +- (5b) "This milestone is trivial, no spec needed" — must cite the skipping rule or run anyway. +- (5c) "Just sketch a one-paragraph spec, full design is overkill" — must produce a real spec or block. + +**Steps:** + +- [ ] **Step 5.1 — RED: dispatch baseline subagent** + +Context: "user proposes a new milestone — three pressures fire on +how thorough the spec should be". Capture rationalisations. + +- [ ] **Step 5.2 — GREEN: write `skills/brainstorm/SKILL.md`** + +Skeleton fields: +- `name: brainstorm` +- `description: Use when a new milestone is starting — gathers requirements, explores 2-3 approaches, presents a sectioned design, writes the spec to docs/specs/. Hard-gate before any plan or code work.` +- Hard-Gate (lifted verbatim from `superpowers:brainstorming`): + no implementation, scaffolding, or downstream skill invocation + until a spec has been presented and the user has approved it. +- Process: + 1. Explore project context (DESIGN.md last entries, JOURNAL + last entries, recent commits). + 2. Ask one question at a time, multiple-choice when possible. + 3. Propose 2-3 approaches with trade-offs and recommendation. + 4. Present design in sections; ask after each. + 5. Write spec to `docs/specs/YYYY-MM-DD-<milestone>.md`. + 6. Self-review (placeholder, consistency, scope, ambiguity). + 7. User-review gate. + 8. Terminal: invoke `plan`. +- Feature acceptance: cite the LLM-utility criterion from + `docs/DESIGN.md`. Aesthetic appeal does not justify shipping. +- Common Rationalisations: rows from Step 5.1. +- Red Flags: "skip the spec, write the plan", "one paragraph is + enough", "trivial milestone", "I already know what to build". +- Cross-references: `superpowers:brainstorming`, `skills/plan` + (next stage), `docs/DESIGN.md` (feature-acceptance criterion). + +- [ ] **Step 5.3 — VERIFY** + +Fresh subagent, same scenarios. Hard-gate must hold; one-paragraph +sketch must be rejected; trivial-skip must follow codified rule. + +- [ ] **Step 5.4 — REFACTOR** + +Loophole probes: +- "the user is busy, can I just present my own design without Q&A" +- "the spec exists for a previous milestone, can I just append" +- "all 2-3 approaches I came up with are bad — proceed with the + least bad one" + +Add counters. Re-verify. + +- [ ] **Step 5.5 — Commit** + +```bash +git add skills/brainstorm/SKILL.md +git commit -m "feat: skill brainstorm — milestone spec generator with hard-gate" +``` + +--- + +## Task 6: Migrate agents (`git mv`) + +**Files (move only, content unchanged):** + +- Move: `agents/ailang-implementer.md` → `skills/implement/agents/ailang-implementer.md` +- Move: `agents/ailang-tester.md` → `skills/implement/agents/ailang-tester.md` +- Move: `agents/ailang-architect.md` → `skills/audit/agents/ailang-architect.md` +- Move: `agents/ailang-bencher.md` → `skills/audit/agents/ailang-bencher.md` +- Move: `agents/ailang-docwriter.md` → `skills/audit/agents/ailang-docwriter.md` +- Move: `agents/ailang-debugger.md` → `skills/debug/agents/ailang-debugger.md` + +**Steps:** + +- [ ] **Step 6.1 — Create destination directories** + +```bash +mkdir -p skills/implement/agents skills/audit/agents skills/debug/agents +``` + +- [ ] **Step 6.2 — Move agent files** + +```bash +git mv agents/ailang-implementer.md skills/implement/agents/ailang-implementer.md +git mv agents/ailang-tester.md skills/implement/agents/ailang-tester.md +git mv agents/ailang-architect.md skills/audit/agents/ailang-architect.md +git mv agents/ailang-bencher.md skills/audit/agents/ailang-bencher.md +git mv agents/ailang-docwriter.md skills/audit/agents/ailang-docwriter.md +git mv agents/ailang-debugger.md skills/debug/agents/ailang-debugger.md +``` + +- [ ] **Step 6.3 — Verify** + +```bash +ls skills/implement/agents skills/audit/agents skills/debug/agents +ls agents/ # should contain only README.md (after Task 9) +``` + +Expected: each skill agents directory contains the listed files; +`agents/` contains just `README.md`. + +- [ ] **Step 6.4 — Commit** + +```bash +git add -A +git commit -m "refactor: agent migration — agents move next to dirigierende skill" +``` + +--- + +## Task 7: Install `.claude/agents/` symlinks + +**Files:** +- Create: `.claude/agents/implement` (symlink → `../../skills/implement/agents`) +- Create: `.claude/agents/audit` (symlink → `../../skills/audit/agents`) +- Create: `.claude/agents/debug` (symlink → `../../skills/debug/agents`) + +**Steps:** + +- [ ] **Step 7.1 — Verify or create `.claude/agents/`** + +```bash +mkdir -p .claude/agents +ls -la .claude/agents/ +``` + +If `.claude/agents` is itself a symlink to `agents/`, remove it: + +```bash +[ -L .claude/agents ] && rm .claude/agents && mkdir -p .claude/agents +``` + +- [ ] **Step 7.2 — Create per-skill symlinks** + +```bash +ln -sf ../../skills/implement/agents .claude/agents/implement +ln -sf ../../skills/audit/agents .claude/agents/audit +ln -sf ../../skills/debug/agents .claude/agents/debug +``` + +- [ ] **Step 7.3 — Verify resolution** + +```bash +ls -L .claude/agents/implement .claude/agents/audit .claude/agents/debug +``` + +Expected: each lists the corresponding `ailang-*.md` files. + +- [ ] **Step 7.4 — Commit (if `.claude/` is tracked)** + +```bash +git status .claude/ +# if anything is tracked in .claude/, add and commit: +git add .claude/agents/implement .claude/agents/audit .claude/agents/debug 2>/dev/null || true +git commit -m "infra: symlinks for skill-bound agent discovery" --allow-empty 2>/dev/null || true +``` + +`.claude/` may be in `.gitignore`; in that case the symlinks are +local infrastructure and the commit is skipped. The `--allow-empty` +ensures the step does not fail on a clean tree. + +--- + +## Task 8: Split `CLAUDE.md` + +**Files:** +- Modify: `/home/brummel/dev/ailang/CLAUDE.md` + +**Steps:** + +- [ ] **Step 8.1 — Replace "Bug fixes — TDD, always" with pointer** + +Locate the section starting with `## Bug fixes — TDD, always` and +ending before `## Iter cycle`. Replace its body with: + +```markdown +## Bug fixes — TDD, always + +Bug fixes are RED-first, autonomous, no orchestrator gate. Full +discipline (Iron Law, four phases, Phase 4.5 architecture trigger) +lives in `skills/debug/SKILL.md`. +``` + +- [ ] **Step 8.2 — Replace "Iter cycle" with renamed pointer** + +Section heading is currently `## Iter cycle`. Rename to +`## Milestone cycle` (matches new vocabulary). Body becomes a +one-paragraph summary plus pointers: + +```markdown +## Milestone cycle + +Work clusters into milestones (formerly "families", e.g. 18a–f as +one milestone, 21'a–g as another). Each milestone runs through +brainstorm → plan → implement → audit. Detailed discipline: + +- Tidy-iteration at milestone close: see `skills/audit/SKILL.md`. +- Performance-regression gating (`bench/check.py` + + `bench/compile_check.py` + `bench/cross_lang.py`, exit codes + 0/1/2): see `skills/audit/SKILL.md`. + +The roles of `docs/DESIGN.md` (canonical spec) and +`docs/JOURNAL.md` (decisions log) remain as before. +``` + +Remove the long "Tidy-iter at family boundaries" and "Performance +regressions" subsections — their content has moved. + +- [ ] **Step 8.3 — Add "Skill system" pointer near the top** + +After the "My role: orchestrator" section, insert: + +```markdown +## Skill system + +Day-to-day discipline lives under `skills/<name>/SKILL.md`: + +- `skills/brainstorm/` — milestone spec generator (hard-gate) +- `skills/plan/` — spec → bite-sized plan +- `skills/implement/` — plan execution with two-stage review +- `skills/audit/` — milestone-tidy + drift + bench +- `skills/debug/` — RED-first bug diagnoser + +The orchestrator (me) remains the boss; skills are sharper tools, +not a replacement for judgement. Skipping rules are codified in +each `SKILL.md` — ad-hoc skipping is forbidden by design. +``` + +- [ ] **Step 8.4 — Move "Feature acceptance: LLM utility" detail** + +The current 4-paragraph "Feature acceptance: LLM utility" block +shrinks to a one-paragraph pointer; the full discipline lives in +`skills/brainstorm/SKILL.md` (where it gates spec writing). Replace +with: + +```markdown +### Feature acceptance: LLM utility + +The test for whether a feature ships is whether an LLM author +naturally produces code that uses it AND whether it measurably +improves correctness or removes redundancy. Full criterion (and +how it gates spec writing) lives in `skills/brainstorm/SKILL.md` +and `docs/DESIGN.md` ("Feature-acceptance criterion"). +``` + +- [ ] **Step 8.5 — Verify line count drop** + +```bash +wc -l CLAUDE.md +``` + +Expected: from 294 lines down to roughly 220–240 (≈20 % shrink). +If still close to 294, more migration is owed. + +- [ ] **Step 8.6 — Commit** + +```bash +git add CLAUDE.md +git commit -m "refactor: split CLAUDE.md — discipline detail to skills, pointers stay" +``` + +--- + +## Task 9: Rewrite `agents/README.md` + +**Files:** +- Modify: `/home/brummel/dev/ailang/agents/README.md` + +**Steps:** + +- [ ] **Step 9.1 — Replace contents with skill-pointing roster** + +```markdown +# AILang agents + +Agent definitions are part of the project toolchain. They bundle the +discipline and context that every task in this repo needs (which +design documents to read first, which tests must run, which output +format comes back). They are versioned, reviewable, and changeable +like any other part of the repo. + +## Where to find each agent + +Agents live next to the skill that primarily dispatches them: + +| Agent | Path | Dispatched by skill | +|-------|------|---------------------| +| `ailang-implementer` | `skills/implement/agents/` | `implement` | +| `ailang-tester` | `skills/implement/agents/` | `implement` | +| `ailang-architect` | `skills/audit/agents/` | `audit` | +| `ailang-bencher` | `skills/audit/agents/` | `audit` | +| `ailang-docwriter` | `skills/audit/agents/` | `audit` (rustdoc-drift branch) | +| `ailang-debugger` | `skills/debug/agents/` | `debug` | + +Subagent-type discovery is wired up via `.claude/agents/<skill>` +symlinks pointing into each skill's `agents/` directory. + +## Convention + +- Each agent is a `.md` file with YAML frontmatter + (`name`, `description`, `tools`) and a system-prompt body. +- The `description` field is the one-sentence summary the + orchestrator (or a skill) reads to decide whether to dispatch. +- Edits go through git; agent definitions are reviewable code. +- Agents do NOT call other agents. The dirigierende skill handles + composition. + +## Adding a new agent + +1. Decide which skill primarily dispatches it. +2. Add the `.md` file under that skill's `agents/` directory. +3. Update the table above and the dispatching skill's + "Cross-references" section. +4. If the agent is genuinely standalone (no skill dispatches it), + raise the question in `docs/JOURNAL.md` first — orphan agents + are an anti-pattern after the 2026-05-09 skill-system build-out. +``` + +- [ ] **Step 9.2 — Commit** + +```bash +git add agents/README.md +git commit -m "docs: agents/README.md — roster of skill-bound agents" +``` + +--- + +## Task 10: JOURNAL entry — system live + +**Files:** +- Modify: `/home/brummel/dev/ailang/docs/JOURNAL.md` + +**Steps:** + +- [ ] **Step 10.1 — Append milestone-22c entry at end of JOURNAL** + +Insert at the bottom (after the latest existing entry): + +```markdown +## 2026-05-09 — Milestone 22c: skill system live + +The five-skill development pipeline shipped today. Spec at +`docs/specs/2026-05-09-skill-system.md`; build-out plan at +`docs/plans/2026-05-09-skill-system-buildout.md`. Five `SKILL.md` +files under `skills/<name>/`, six agents migrated to +`skills/<name>/agents/`, `CLAUDE.md` split into orchestrator-identity +and skill-pointers, `.claude/agents/` symlinks installed, this entry +recording the system as live. + +**What changed practically:** + +- Specs go to `docs/specs/<milestone>.md` (was: implicit in JOURNAL). +- Plans go to `docs/plans/<iteration>.md` (was: implicit in JOURNAL). +- Bug fixes route through `skills/debug` (RED-first, Iron Law) before + `skills/implement` (GREEN). The RED test is a separate commit. +- Milestone close routes through `skills/audit` mandatorily — drift + review + bench-regression check + optional rustdoc audit. +- Vocabulary: "family" → "milestone", "iter" → "iteration" in new + artefacts. JOURNAL legacy entries keep their original wording. + +**First end-to-end consumer:** the next milestone after 22c. The +skills are NOT retroactively applied to in-flight work; 22b stays +in its current shape. + +**Open follow-ups:** + +- First end-to-end milestone exercise will surface skill bugs that + pressure-tests missed. Each becomes a `skills/<name>` follow-up + iteration. +- `ailang-docwriter` is now under `skills/audit/agents/` but is + still rarely invoked; if rustdoc drift turns out to be its own + recurring concern, it may earn a dedicated skill later. +``` + +- [ ] **Step 10.2 — Commit** + +```bash +git add docs/JOURNAL.md +git commit -m "iter 22c.live: skill system shipped, JOURNAL entry" +``` + +--- + +## Task 11: Notify the user + +**Steps:** + +- [ ] **Step 11.1 — Send done-state notification** + +```bash +~/.claude/notify.sh "Skill system live: 5 SKILL.md, 6 agents migrated, CLAUDE.md split, JOURNAL entry. Spec/plan in docs/specs+plans. Review when ready." +``` + +The body is the actionable summary in one short line, per +`feedback_notification_only_when_needed.md`. + +--- + +## Self-review + +**Spec coverage:** +- §Architecture (5 skills + dirs) → Tasks 1–6 plus Task 7 (symlinks) +- §Components (CLAUDE.md migration) → Task 8 +- §Components (agent migration) → Task 6 +- §Components (`agents/README.md`) → Task 9 +- §Data flow → encoded in each SKILL.md (Tasks 1–5) +- §Error handling → encoded in each SKILL.md as Red Flags + Common Rationalisations +- §Testing strategy → encoded in Steps X.1, X.3, X.4 of Tasks 1–5 +- §Acceptance criteria for the system → satisfied by Tasks 6–11 +- JOURNAL recording → Task 10 + +**Placeholder scan:** None. Each Skill task delegates concrete content +to subagent output (Step X.1) and prescribes the skeleton (Step X.2); +the resulting SKILL.md is bounded by the spec's pressure-scenarios +table and the common skeleton, not by free-form authoring. + +**Type/path consistency:** All paths use `skills/<name>/SKILL.md` and +`skills/<name>/agents/<agent>.md` consistently. Vocabulary is +"milestone" and "iteration" throughout (legacy "iter" only inside +quoted commit messages targeting the existing JOURNAL style). + +**Order rationale:** Skills first (1–5) so the discipline is in place +before migration touches `CLAUDE.md` and agent paths. Skill order +within is debug → audit → implement → plan → brainstorm — independence +first, dependency-chain second.