# AILang Skill System — Design Spec **Date:** 2026-05-09 **Status:** Draft — awaiting user spec review **Authors:** Brummel (orchestrator) + Claude ## Goal Formalise the existing AILang development workflow as a five-skill system that lives under `skills/`. The skills codify discipline that is currently 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-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 milestone starts with a spec under `docs/specs/`, and every iteration starts with a plan under `docs/plans/`. ## Architecture ### Five skills All five skills are project-local under `skills/`. Names are imperative 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 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 ``` skills/ brainstorm/ SKILL.md plan/ SKILL.md implement/ SKILL.md agents/ ailang-implementer.md ailang-tester.md audit/ SKILL.md agents/ ailang-architect.md ailang-bencher.md ailang-docwriter.md debug/ SKILL.md agents/ ailang-debugger.md agents/ README.md # roster: pointers into skills//agents/ docs/ specs/ # NEW — emitted by brainstorm plans/ # NEW — emitted by plan DESIGN.md # unchanged JOURNAL.md # unchanged ``` `brainstorm` and `plan` have no private agents — both run as a dialogue 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` 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 agent directory, created at install time: ``` .claude/agents/implement -> ../../skills/implement/agents .claude/agents/audit -> ../../skills/audit/agents .claude/agents/debug -> ../../skills/debug/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). **Stays in CLAUDE.md:** - Project mission ("Invent your own programming language") - Code layout table - "My role: orchestrator" (delegation rules, when not to delegate) - "Design rationale ≠ implementation effort" - "Direction freedom" + "Notifications" - "Roles of JOURNAL.md and DESIGN.md" **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-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.: > **Bug fixes** are RED-first TDD, autonomous, no orchestrator gate. > Full discipline lives in `skills/debug/SKILL.md`. This way `CLAUDE.md` shrinks but a reader who only opens it still gets the headline rule and a pointer to the binding source. ### Agent migration 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. 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 `superpowers:subagent-driven-development`. Migration map: ``` 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/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: milestone happy path ``` [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: " | v [orchestrator: first iteration of milestone] | v plan read docs/specs/.md write docs/plans/.md (header references parent spec) commit: "plan: " | v implement read docs/plans/.md dispatch implementer (per task) -> spec-review -> code-quality-review dispatch tester (E2E coverage) per-task commits: "iteration .: " JOURNAL entry: "## YYYY-MM-DD — Iteration : " ``` ### Pipeline 2: milestone close path ``` [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: "Milestone-<X> tidy (clean)" | +--- exit 1 (drift/regression) | | | v | plan + implement (tidy-iteration) OR ratify in DESIGN.md | commit: "iteration <X>.tidy: <fix>" OR JOURNAL ratify entry | +--- exit 2 (infra failure) | v fix infrastructure FIRST, re-run audit ``` ### Pipeline 3: bug autonomous TDD path ``` [orchestrator: bug observed] | v debug dispatch debugger reproduce + isolate write RED test (failing on current code) commit: "test: red for <symptom>" diagnosis report (Symptom, Cause, Fix-Vorschlag) hand-off: bug-context + RED-test path | v implement (mini-mode, no docs/plans/ file for trivial fixes) dispatch implementer with RED-test as goal: "make this test pass, minimal change" commit: "fix: <symptom>" JOURNAL entry: "## YYYY-MM-DD — Bug fix: <symptom>" ``` ### Handoff contracts Every handoff carries an explicit, named context. No implicit "the next skill knows what to do": | Handoff | Carrier | |---------|---------| | `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") | ### Skipping rules (codified in the skills, not ad-hoc) | Skill | May be skipped when | Never skipped when | |-------|---------------------|--------------------| | `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 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 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 milestone correspond to spec ranges). ## Error handling ### Escalation ladder Common across all five skills: | Level | Decider | Trigger | |-------|---------|---------| | L1 — skill-internal recovery | The skill itself | Subagent reports `NEEDS_CONTEXT` -> provide more context, redispatch (max 2x with same model) | | L2 — bounce to previous skill | The skill | `plan` cannot decompose spec -> back to `brainstorm`; implementer finds spec/code contradiction -> back to `plan` | | L3 — orchestrator decision | Me | Task too large to fit one plan -> split; reasoning insufficient -> stronger model; design-rationale fork | | L4 — user decision | User | Spec/DESIGN.md conflict; 3+ failed fix attempts in `debug` (architecture question); `audit` drift item where fix vs ratify is unclear | ### Skill-specific stop conditions - **`brainstorm`** — After 3 approach iterations with no convergence, 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 placeholders (writing-plans Iron Rule, adopted verbatim). - **`implement`** — implementer status `BLOCKED` with reason "task too large" -> split + new plan. Status `BLOCKED` with reason "design conflict" -> escalate to user. Never push past `BLOCKED` by hand (context pollution). - **`debug`** — Phase 4.5 trigger: 3+ failed fix attempts mean the pattern is wrong, not the latest hypothesis. STOP, surface the 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. ### Cross-skill rule > **Violating the letter of these rules is violating the spirit.** 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 *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. ## Testing strategy Skills are developed under TDD per `superpowers:writing-skills`: RED baseline first, GREEN minimal skill second, REFACTOR loopholes third. ### Per-skill pressure scenarios (for the RED phase) | Skill | Scenarios | |-------|-----------| | `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-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 1. **RED** — A general-purpose subagent receives the pressure scenario without the skill's content. Document its rationalisations and shortcuts verbatim. 2. **GREEN** — Write the SKILL.md with the documented rationalisations as explicit counters in a "Common Rationalisations" table. Hand the skill content + scenario to a fresh subagent. It must comply. 3. **REFACTOR** — A third subagent run, same scenario plus minor variations, looking for new loopholes. Add explicit counters for each found loophole. Re-test until bulletproof. Minimum **3 independent subagent runs** in the GREEN+REFACTOR phases per skill. A single passing run is not evidence — random compliance is possible. ### Acceptance criterion per skill A skill ships (= is committed to `skills/`) only after: - 3 RED scenarios have been run and the rationalisations documented in the skill's `Common Rationalisations` table. - 3+ GREEN/REFACTOR runs all pass without further amendment. - The skill's `description` frontmatter is technology-agnostic and trigger-focused (no workflow summary — see CSO section in `superpowers:writing-skills`). ## Implementation order The skills depend on each other transitively (a `plan` skill cannot be 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. The initial ordering choice is at the orchestrator's discretion; the recommended sequence is the one that ships independent, testable artefacts first: 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. 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 The skill system is considered shipped when: - All five SKILL.md files exist under `skills/<name>/SKILL.md` with passing pressure tests. - Agent definitions have moved to their target locations and `.claude/agents/` symlinks resolve. - CLAUDE.md is split: orchestrator-identity stays, migrated sections 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 milestone as the first end-to-end consumer. 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.