AILang/docs/specs/0001-skill-system.md

# 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/<milestone>.md` | Hard-gate before plan |
| `plan` | New iteration within an open milestone | `docs/plans/<iteration>.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/<name>/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/<name>/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/<milestone>.md
   commit: "spec: <milestone> <topic>"
        |
        v
[orchestrator: first iteration of milestone]
        |
        v
plan
   read docs/specs/<milestone>.md
   write docs/plans/<iteration>.md (header references parent spec)
   commit: "plan: <iteration> <subject>"
        |
        v
implement
   read docs/plans/<iteration>.md
   dispatch implementer (per task) -> spec-review -> code-quality-review
   dispatch tester (E2E coverage)
   per-task commits: "iteration <iteration>.<n>: <subject>"
   JOURNAL entry: "## YYYY-MM-DD — Iteration <iteration>: <title>"
```

### 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.