diff --git a/docs/specs/2026-05-09-skill-system.md b/docs/specs/2026-05-09-skill-system.md index afc0a32..cfa4820 100644 --- a/docs/specs/2026-05-09-skill-system.md +++ b/docs/specs/2026-05-09-skill-system.md @@ -12,16 +12,21 @@ spread across `CLAUDE.md` and the orchestrator's habits, and they emit durable artefacts (specs, plans) that future iterations can reference. The orchestrator (the user) remains the boss: skills are sharper tools, not -a replacement for judgement. Where the existing per-iter workflow already -works (small focused commits, JOURNAL discipline, agent delegation), it is -preserved verbatim. The new layer formalises the *pre-iter design step* -(spec) and the *iter handoff contract* (plan), and turns implicit -discipline (tidy-iter at family close, RED-first for bugs) into explicit -skill invocations. +a replacement for judgement. Where the existing per-iteration workflow +already works (small focused commits, JOURNAL discipline, agent +delegation), it is preserved verbatim. The new layer formalises the +*pre-iteration design step* (spec) and the *iteration handoff contract* +(plan), and turns implicit discipline (tidy-iteration at milestone close, +RED-first for bugs) into explicit skill invocations. + +A second goal is **context relief**. Skills delegate to subagents that +work in isolated context windows; the orchestrator only sees the +subagent's report, not its raw transcript. Long-running design cycles no +longer have to fit in one main-context window. This is the bootstrap spec. It defines the system that future specs will -go through. Once the system is in place, every new family starts with a -spec under `docs/specs/`, and every iter starts with a plan under +go through. Once the system is in place, every new milestone starts with +a spec under `docs/specs/`, and every iteration starts with a plan under `docs/plans/`. ## Architecture @@ -29,15 +34,16 @@ spec under `docs/specs/`, and every iter starts with a plan under ### Five skills All five skills are project-local under `skills/`. Names are imperative -verbs without iter-/family- scope prefixes — the trigger condition is -encoded in each skill's `description` frontmatter, not in its name. +verbs without milestone-/iteration- scope prefixes — the trigger +condition is encoded in each skill's `description` frontmatter, not in +its name. | Skill | Trigger | Output | Verbindlichkeit | |-------|---------|--------|-----------------| -| `brainstorm` | New family starting | `docs/specs/.md` | Hard-gate before plan | -| `plan` | New iter within an open family | `docs/plans/.md` | Hard-gate before implement | -| `implement` | Plan exists | Code + tests + per-task commits + JOURNAL entry | Standard iter path | -| `audit` | Family closing OR baseline drift suspected | Drift report + bench-regression report | **Mandatory** at family close | +| `brainstorm` | New milestone starting | `docs/specs/.md` | Hard-gate before plan | +| `plan` | New iteration within an open milestone | `docs/plans/.md` | Hard-gate before implement | +| `implement` | Plan exists | Code + tests + per-task commits + JOURNAL entry | Standard iteration path | +| `audit` | Milestone closing OR baseline drift suspected | Drift report + bench-regression report + rustdoc audit | **Mandatory** at milestone close | | `debug` | Bug encountered (red test, segfault, wrong stdout) | RED-test commit + cause analysis | **Mandatory RED-first** for any bug | ### Directory layout @@ -58,13 +64,13 @@ skills/ agents/ ailang-architect.md ailang-bencher.md + ailang-docwriter.md debug/ SKILL.md agents/ ailang-debugger.md agents/ - ailang-docwriter.md # orphan — invoked directly by orchestrator - README.md # roster: pointers to skills/ + orphans + README.md # roster: pointers into skills//agents/ docs/ specs/ # NEW — emitted by brainstorm plans/ # NEW — emitted by plan @@ -78,33 +84,121 @@ between orchestrator and user, producing the artefact directly. `implement`, `audit`, and `debug` each own the agents they dispatch. An agent definition lives next to the skill that primarily uses it. -`ailang-docwriter` stays in `agents/` as an orphan tool. It is rarely -invoked, exclusively for rustdoc drift, and does not slot into any of the -five skill pipelines. +`ailang-docwriter` lives under `audit` because rustdoc drift is a form +of drift covered by the milestone-close audit pass — even though +docwriter writes (rather than only diagnoses) it is a low-frequency, +read-mostly tool that fits the audit cycle. ### `.claude/agents/` discovery Subagent-type discovery requires the agent definitions to be reachable -from `.claude/agents/`. Pragmatic resolution: one symlink per skill, -created at install time: +from `.claude/agents/`. Pragmatic resolution: one symlink per agent +directory, created at install time: ``` .claude/agents/implement -> ../../skills/implement/agents .claude/agents/audit -> ../../skills/audit/agents .claude/agents/debug -> ../../skills/debug/agents -.claude/agents/orphan -> ../../agents ``` This keeps the agent files visible in the project tree (per the existing convention in `agents/README.md`) while still letting the Claude harness find them. +## Core rules adopted from Superpowers + +The five skills inherit non-trivial discipline from the Anthropic +`superpowers` skill set. These are the rules adopted verbatim or with +minimal adaptation. They live at the top of each relevant SKILL.md so +future readers do not have to recover them from the upstream source. + +### From `superpowers:brainstorming` → adopted by `brainstorm` + +- **HARD-GATE:** No implementation, scaffolding, or downstream skill + invocation until a spec has been presented and the user has approved + it. Applies to every milestone regardless of perceived simplicity. +- **One question at a time.** Multi-question messages overwhelm and + collapse signal. +- **Propose 2-3 approaches** with trade-offs and a recommendation + before settling on a design. Lead with the recommended option. +- **Design in sections** scaled to complexity; ask after each section + whether it looks right. +- **Spec self-review** after writing: placeholder scan, internal + consistency, scope check, ambiguity check. Fix issues inline. +- **User review gate** after the spec is committed: ask the user to + review the file before proceeding to plan. +- **Terminal state = invoke `plan`.** No other skill is invoked from + `brainstorm`. + +### From `superpowers:writing-plans` → adopted by `plan` + +- **Bite-sized tasks** (one action per step, 2-5 minutes each). +- **No Placeholders rule:** the plan MUST NOT contain "TBD", "TODO", + "implement later", "add appropriate error handling", "similar to + Task N", or steps that describe what to do without showing the code. +- **File structure first:** before defining tasks, map which files + are created or modified and what each one is responsible for. +- **Plan header** with required sub-skill reference, goal, architecture + summary, tech stack. +- **Self-review** after writing: spec coverage, placeholder scan, type + consistency across tasks. + +### From `superpowers:executing-plans` and `superpowers:subagent-driven-development` → adopted by `implement` + +- **Fresh subagent per task.** Subagents do not inherit orchestrator + context; the orchestrator constructs exactly the context the subagent + needs. +- **Two-stage review per task:** spec compliance first, code quality + second. Code-quality review never starts before spec compliance is + green. +- **Continuous execution.** No "should I continue?" between tasks. + Stop only on `BLOCKED` status or unresolvable ambiguity. +- **Status handling:** `DONE` → spec review; `DONE_WITH_CONCERNS` → + read concerns first; `NEEDS_CONTEXT` → provide context, redispatch; + `BLOCKED` → escalate (context, model, split, or user). +- **Model selection** scales with task complexity: cheap model for + isolated mechanical tasks, standard for multi-file integration, top + model for design judgement and review. +- **Controller curates context.** The orchestrator hands the subagent + full task text and surrounding scene-set; the subagent does not + re-read the plan file. + +### From `superpowers:systematic-debugging` → adopted by `debug` + +- **Iron Law:** *NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.* + Symptom fixes are failure. +- **Four phases:** Root Cause → Pattern Analysis → Hypothesis → Fix. + Each phase must complete before the next. +- **Phase 4.5:** if 3+ fixes have failed, the architecture is wrong, + not the latest hypothesis. STOP, surface the architecture question + to the user, do not attempt Fix #4. +- **RED first** (project-local, from `CLAUDE.md`): the failing test + is committed before any fix is attempted. Bug fix without a + regression test is a code change, not a fix. +- **Cross-skill anchor:** "Violating the letter of these rules is + violating the spirit." Lifted verbatim from the upstream skill, + printed at the top of every SKILL.md. + +### From `superpowers:writing-skills` → adopted by every skill (meta) + +- **TDD for skills.** Every SKILL.md is built RED → GREEN → REFACTOR: + pressure scenarios with a fresh subagent first (RED, baseline), + minimal SKILL.md addressing the documented rationalisations second + (GREEN), loophole-closing iterations third (REFACTOR). +- **CSO (Claude Search Optimization).** Description starts with + "Use when…" and lists triggers, not workflow. No process summary in + the description. +- **Cross-references** to other skills use explicit requirement markers + ("REQUIRED SUB-SKILL: …") rather than `@`-loads (which burn context + immediately). + ## Components ### CLAUDE.md migration CLAUDE.md splits into **orchestrator identity** (stays) and **discipline -detail** (moves into skills, with a one-line reference back from CLAUDE.md). +detail** (moves into skills, with a one-line reference back from +CLAUDE.md). **Stays in CLAUDE.md:** @@ -115,13 +209,13 @@ detail** (moves into skills, with a one-line reference back from CLAUDE.md). - "Direction freedom" + "Notifications" - "Roles of JOURNAL.md and DESIGN.md" -**Moves into skills (CLAUDE.md keeps a one-line reference):** +**Moves into skills (CLAUDE.md keeps a one-line pointer):** | CLAUDE.md section | Destination skill | |-------------------|-------------------| | "Bug fixes — TDD, always" (RED first / GREEN second / keep the test) | `debug` (Iron Law) | -| "Tidy-iter at family boundaries" (mandatory, drift review) | `audit` (trigger logic + escalation) | -| "Performance regressions" (bench/check.py + compile_check.py + cross_lang.py, exit codes 0/1/2) | `audit` (bench discipline) | +| "Tidy-iteration at milestone boundaries" (mandatory, drift review) | `audit` (trigger logic + escalation) | +| "Performance regressions" (`bench/check.py` + `bench/compile_check.py` + `bench/cross_lang.py`, exit codes 0/1/2) | `audit` (bench discipline) | | "Feature acceptance: LLM utility" (full criterion, beyond the CLAUDE.md summary) | `brainstorm` (feature gate during spec writing) | CLAUDE.md keeps a short pointer in each migrated section, e.g.: @@ -136,11 +230,12 @@ the headline rule and a pointer to the binding source. Agent definitions move via `git mv`. Frontmatter (`name`, `description`, `tools`) is preserved unchanged. The "mandatory reading order" sections -inside each agent stay — they are agent discipline, not skill discipline. +inside each agent stay — they are agent discipline, not skill +discipline. The dirigierende skill provides the **task context** (plan extract, bug -symptom, drift item) so the agent does not have to rediscover it. This is -the controller-curates-context pattern from +symptom, drift item) so the agent does not have to rediscover it. This +is the controller-curates-context pattern from `superpowers:subagent-driven-development`. Migration map: @@ -150,61 +245,67 @@ 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 -agents/ailang-docwriter.md -> agents/ailang-docwriter.md (no move) -agents/README.md -> agents/README.md (rewritten as skills+orphans roster) +agents/README.md -> agents/README.md (rewritten as a + pointer roster) ``` +After migration, `agents/` contains only `README.md`. The README is +rewritten to point into `skills//agents/` and to explain the +project convention (agents live next to their skill). + ## Data flow -### Pipeline 1: family happy path +### Pipeline 1: milestone happy path ``` -[orchestrator: new family starting] +[orchestrator: new milestone starting] | v brainstorm Q&A dialogue with user (one question at a time, 2-3 approaches, design) - write docs/specs/.md - commit: "spec: " + write docs/specs/.md + commit: "spec: " | v -[orchestrator: first iter of family] +[orchestrator: first iteration of milestone] | v plan - read docs/specs/.md - write docs/plans/.md (header references parent spec) - commit: "plan: " + read docs/specs/.md + write docs/plans/.md (header references parent spec) + commit: "plan: " | v implement - read docs/plans/.md + read docs/plans/.md dispatch implementer (per task) -> spec-review -> code-quality-review dispatch tester (E2E coverage) - per-task commits: "iter .: " - JOURNAL entry: "## YYYY-MM-DD — Iter : " + per-task commits: "iteration <iteration>.<n>: <subject>" + JOURNAL entry: "## YYYY-MM-DD — Iteration <iteration>: <title>" ``` -### Pipeline 2: family close path +### Pipeline 2: milestone close path ``` -[orchestrator: family-tidy due] +[orchestrator: milestone-tidy due] | v audit dispatch architect -> drift report run bench/check.py && bench/compile_check.py && bench/cross_lang.py + dispatch docwriter (optional, if rustdoc drift suspected) classify: 0 (clean) | 1 (drift/regression) | 2 (infra failure) report to orchestrator | - +--- exit 0 (clean) -------> JOURNAL: "Family-<X> tidy-iter (clean)" + +--- exit 0 (clean) -------> JOURNAL: "Milestone-<X> tidy (clean)" | +--- exit 1 (drift/regression) | | | v - | plan + implement (tidy-iter) OR ratify in DESIGN.md - | commit: "iter <X>.tidy: <fix>" OR JOURNAL ratify entry + | plan + implement (tidy-iteration) OR ratify in DESIGN.md + | commit: "iteration <X>.tidy: <fix>" OR JOURNAL ratify entry | +--- exit 2 (infra failure) | @@ -228,7 +329,8 @@ debug | v implement (mini-mode, no docs/plans/ file for trivial fixes) - dispatch implementer with RED-test as goal: "make this test pass, minimal change" + dispatch implementer with RED-test as goal: + "make this test pass, minimal change" commit: "fix: <symptom>" JOURNAL entry: "## YYYY-MM-DD — Bug fix: <symptom>" ``` @@ -240,8 +342,8 @@ skill knows what to do": | Handoff | Carrier | |---------|---------| -| `brainstorm` -> `plan` | path to `docs/specs/<family>.md` + iter scope ("the section X+Y of the spec is what this iter covers") | -| `plan` -> `implement` | path to `docs/plans/<iter>.md` + optional task focus ("only Tasks 1-3 this run") | +| `brainstorm` -> `plan` | path to `docs/specs/<milestone>.md` + iteration scope ("section X+Y of the spec is what this iteration covers") | +| `plan` -> `implement` | path to `docs/plans/<iteration>.md` + optional task focus ("only Tasks 1-3 this run") | | `debug` -> `implement` | RED-test path + 1-2-sentence cause summary + hard constraint ("minimal fix, no surrounding cleanup") | | `audit` -> orchestrator | prioritised drift items + bench exit code + raw bench numbers + recommendation ("fix N", "ratify M", "carry on") | @@ -249,10 +351,10 @@ skill knows what to do": | Skill | May be skipped when | Never skipped when | |-------|---------------------|--------------------| -| `brainstorm` | Iter is tidy / bug fix / trivial mechanic (≤1 file, ≤30 LOC, no design judgement) | New family starts | -| `plan` | Bug fix where RED-test is sufficient as plan; trivial mechanic | Standard iter within an active family | +| `brainstorm` | Iteration is tidy / bug fix / trivial mechanic (≤1 file, ≤30 LOC, no design judgement) | New milestone starts | +| `plan` | Bug fix where RED-test is sufficient as plan; trivial mechanic | Standard iteration within an active milestone | | `implement` | — | Always required when there is code to ship | -| `audit` | — | **Always** at family close; deferral requires a JOURNAL entry naming the reason and the re-run date | +| `audit` | — | **Always** at milestone close; deferral requires a JOURNAL entry naming the reason and the re-run date | | `debug` | — | **Always** for any observable bug; trivial bugs still get RED first | Each skill's `SKILL.md` repeats the relevant skipping clause from this @@ -261,11 +363,11 @@ table verbatim — the rule lives in the skill, not just here. ### Commit-per-stage invariant Each pipeline stage commits its own artefact before handing off. Specs, -plans, RED-tests, and per-task implementation diffs are separate commits. -This makes every stage independently revertable: `git revert <plan-commit>` -discards the plan only, leaving the spec intact. The convention also -gives `audit` clean drift-review boundaries (commit ranges per family -correspond to spec ranges). +plans, RED-tests, and per-task implementation diffs are separate +commits. This makes every stage independently revertable: `git revert +<plan-commit>` discards the plan only, leaving the spec intact. The +convention also gives `audit` clean drift-review boundaries (commit +ranges per milestone correspond to spec ranges). ## Error handling @@ -283,7 +385,7 @@ Common across all five skills: ### Skill-specific stop conditions - **`brainstorm`** — After 3 approach iterations with no convergence, - STOP. User decides whether the family is dropped (commit message + STOP. User decides whether the milestone is dropped (commit message `wip: drop spec, scope unclear`) or paused. - **`plan`** — Spec containing a placeholder ("TBD", "implement later") bounces back to `brainstorm`. The plan itself MUST contain no @@ -297,8 +399,8 @@ Common across all five skills: architecture question to the user. No bug fix without a RED-test first; no "I'll write the test after I've confirmed the fix". - **`audit`** — Bench exit code 2 (infrastructure failure) means fix - infrastructure FIRST and never report it as a regression. Drift items - where fix-vs-ratify is genuinely unclear escalate to the user. + infrastructure FIRST and never report it as a regression. Drift + items where fix-vs-ratify is genuinely unclear escalate to the user. ### Cross-skill rule @@ -307,7 +409,7 @@ Common across all five skills: This single sentence (lifted verbatim from `superpowers:systematic-debugging`) lives at the top of every SKILL.md. "It's obvious, so we can skip the spec/plan/audit step" is not a valid -argument — the codified skipping rules in Section 3 are the only +argument — the codified skipping rules in *Data flow* are the only sanctioned way to skip. Ad-hoc judgement that a step is unnecessary is exactly the failure mode the system exists to prevent. @@ -320,11 +422,11 @@ baseline first, GREEN minimal skill second, REFACTOR loopholes third. | Skill | Scenarios | |-------|-----------| -| `brainstorm` | (a) "Idea is clear, write the plan now" — must hold the spec hard-gate. (b) "This family is trivial, no spec needed" — must cite the skipping rule or run anyway. (c) "Just sketch a one-paragraph spec, full design is overkill" — must produce a real spec or block. | -| `plan` | (a) "TBD steps are fine, I'll fill them in later" — No-Placeholders rule. (b) "Bundle these as one big step, faster" — bite-sized rule. (c) "Skip the spec, I know the family already" — bounce to `brainstorm`. | +| `brainstorm` | (a) "Idea is clear, write the plan now" — must hold the spec hard-gate. (b) "This milestone is trivial, no spec needed" — must cite the skipping rule or run anyway. (c) "Just sketch a one-paragraph spec, full design is overkill" — must produce a real spec or block. | +| `plan` | (a) "TBD steps are fine, I'll fill them in later" — No-Placeholders rule. (b) "Bundle these as one big step, faster" — bite-sized rule. (c) "Skip the spec, I know the milestone already" — bounce to `brainstorm`. | | `implement` | (a) "Skip spec-review, the implementer self-reviewed" — both reviews still required. (b) "Commit straight to main" — never without explicit user consent. (c) "Implementer says DONE_WITH_CONCERNS, move on" — must read concerns first. | | `debug` | (a) "Cause is obvious, fix it directly" — reproduce + RED first. (b) "Bug is trivial, no test needed" — TDD anyway. (c) "Fix #3 failed, one more try" — Phase 4.5 architecture question, no Fix #4. | -| `audit` | (a) "Tidy-iter later, we're in a hurry" — mandatory at family close. (b) "Bench is red, just bump the baseline" — only with `--update-baseline` AND a JOURNAL ratify entry. (c) "Drift item doesn't matter, ignore it" — must be either fixed or ratified. | +| `audit` | (a) "Tidy-iteration later, we're in a hurry" — mandatory at milestone close. (b) "Bench is red, just bump the baseline" — only with `--update-baseline` AND a JOURNAL ratify entry. (c) "Drift item doesn't matter, ignore it" — must be either fixed or ratified. | ### Verification sequence per skill @@ -360,24 +462,24 @@ built without a working `brainstorm` skill upstream of it), but the test discipline does not require the dependency chain to be live for testing — the pressure scenarios are self-contained. -Recommended order, scoped as iter increments under a new family: +The initial ordering choice is at the orchestrator's discretion; the +recommended sequence is the one that ships independent, testable +artefacts first: -1. **22c.1** — `debug` skill (smallest scope, clearest Iron Law, no - upstream dependency since bugs do not flow through brainstorm/plan). -2. **22c.2** — `audit` skill (also independent of brainstorm/plan; - migrates the existing tidy-iter discipline). -3. **22c.3** — `implement` skill (consumes plans, dispatches - implementer + tester; depends on plan format being defined). -4. **22c.4** — `plan` skill (produces what `implement` consumes). -5. **22c.5** — `brainstorm` skill (top of the pipeline). -6. **22c.6** — CLAUDE.md split + agent migration + `.claude/agents/` - symlink setup. -7. **22c.tidy** — first audit on the new infrastructure itself. +1. `debug` skill (smallest scope, clearest Iron Law, no upstream + dependency since bugs do not flow through brainstorm/plan). +2. `audit` skill (also independent of brainstorm/plan; migrates the + existing tidy-iteration discipline). +3. `implement` skill (consumes plans, dispatches implementer + tester; + depends on plan format being defined). +4. `plan` skill (produces what `implement` consumes). +5. `brainstorm` skill (top of the pipeline). +6. CLAUDE.md split + agent migration + `.claude/agents/` symlink setup. +7. First audit on the new infrastructure itself. -Each iter ships its skill behind the existing discipline (CLAUDE.md -rules apply during the build of the new system; the new skills do not -self-apply until 22c.6 lands). The first family to use the new system -end-to-end is the next family after 22c. +The first milestone to use the new system end-to-end is the next +milestone after the build-out. Iteration numbering for the build-out +is fixed by the orchestrator at plan time. ## Acceptance criteria for the system as a whole @@ -391,11 +493,12 @@ The skill system is considered shipped when: carry one-line pointers to the relevant skill. - `docs/specs/` and `docs/plans/` exist with at least this spec and the implementation plan derived from it as their first inhabitants. -- A JOURNAL entry records the system as live and names the next family - as the first end-to-end consumer. +- A JOURNAL entry records the system as live and names the next + milestone as the first end-to-end consumer. -The headline test is: **the next family after 22c is brainstormed, -planned, implemented, and audited entirely through the skill system, -with no ad-hoc orchestrator improvisation.** If the orchestrator -catches themselves bypassing a skill mid-family, that is a skill bug -to be fixed in a follow-up iter — not a permitted shortcut. +The headline test is: **the next milestone after the build-out is +brainstormed, planned, implemented, and audited entirely through the +skill system, with no ad-hoc orchestrator improvisation.** If the +orchestrator catches themselves bypassing a skill mid-milestone, that +is a skill bug to be fixed in a follow-up iteration — not a permitted +shortcut.