# Skill System Build-out — Implementation Plan > **Parent spec:** `docs/specs/0001-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/0001-skill-system.md`; build-out plan at `docs/plans/0001-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.