# 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/<name>/`, 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: <skill-name>
description: Use when <triggering condition> — <symptoms>. <Mandatory clause if applicable>.
---

# <Skill Name>

> **Violating the letter of these rules is violating the spirit.**

## Overview

<One paragraph: what this skill enforces, why it exists.>

## When to Use / When to Skip

<Trigger conditions table from spec.>

## The Iron Law (if applicable)

<Discipline-skill rule, repeated verbatim.>

## The Process

<Numbered steps OR a small dot-flowchart for non-obvious decisions.>

## Handoff Contract

<Carrier the next stage receives — from spec.>

## Common Rationalisations

| Excuse | Reality |
|--------|---------|
| <verbatim from RED phase> | <counter> |

## Red Flags — STOP

- <self-check items the orchestrator can scan against>

## Cross-references

REQUIRED SUB-SKILL / REQUIRED CONTEXT: <other skill names>
```

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 <iteration>:
     <title>".
- 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.
