AILang/skills/README.md

# AILang Skill System

This directory holds the project-local development skills. A *skill*
is a `SKILL.md` plus the agents that skill primarily dispatches.
Skills formalise the AILang development cycle into named, trigger-bound
discipline so the orchestrator (me) cannot accidentally diverge from
established practice without explicitly violating a named rule.

The system was bootstrapped on 2026-05-09. See
`docs/specs/2026-05-09-skill-system.md` for the design and
`docs/JOURNAL.md` ("Skill system live") for the rationale.

## The five skills

| Skill | Trigger | Output | Mandatory? |
|-------|---------|--------|------------|
| [`brainstorm`](brainstorm/SKILL.md) | New milestone starting | `docs/specs/<milestone>.md` | Hard-gate before plan |
| [`plan`](plan/SKILL.md) | New iteration within an open milestone | `docs/plans/<iteration>.md` | Hard-gate before implement |
| [`implement`](implement/SKILL.md) | Plan exists | Code + tests + per-task commits + JOURNAL entry | Standard iteration path |
| [`audit`](audit/SKILL.md) | Milestone closing OR baseline drift suspected | Drift report + bench-regression report + rustdoc audit | **Mandatory** at milestone close |
| [`debug`](debug/SKILL.md) | Bug encountered (failing test, segfault, wrong stdout) | RED-test commit + cause analysis | **Mandatory RED-first** for any bug |

## Pipeline

```
[new milestone]                        [bug observed]
       |                                      |
       v                                      v
 brainstorm  ->  plan  ->  implement      debug -> implement (mini)
       (per iteration loop)
                  |
       [milestone close]
                  |
                  v
                audit  --(clean)-->  next milestone
                       --(drift)-->  plan + implement (tidy iteration)
                                     OR ratify in DESIGN.md
```

Skipping rules are codified in each `SKILL.md`. Ad-hoc skipping is
forbidden by design.

## Agent roster

Agents live next to the skill that primarily dispatches them. There
are no orphan agents (an anti-pattern after the 2026-05-09 build-out).

| Agent | Path | Dispatched by skill |
|-------|------|---------------------|
| `ailang-implementer`     | `implement/agents/` | `implement` (Step 2.1; carries TDD as an independent layer) |
| `ailang-spec-reviewer`   | `implement/agents/` | `implement` (Step 2.3; did the diff match the task text?) |
| `ailang-quality-reviewer`| `implement/agents/` | `implement` (Step 2.4; is the diff well-built? — only after spec is `compliant`) |
| `ailang-tester`          | `implement/agents/` | `implement` (Step 3; E2E coverage) |
| `ailang-architect`       | `audit/agents/`     | `audit` (Step 1; drift review against DESIGN.md + spec) |
| `ailang-bencher`         | `audit/agents/`     | `audit` (regression diagnostics — hypothesis-driven) |
| `ailang-docwriter`       | `audit/agents/`     | `audit` (Step 3; rustdoc cleanup, optional) |
| `ailang-debugger`        | `debug/agents/`     | `debug` (RED-first; hands off GREEN to `implement` mini-mode) |

Each agent file has YAML frontmatter (`name`, `description`, `tools`)
plus a system-prompt body. The `description` field is the one-sentence
summary the orchestrator (or a skill) reads to decide whether to
dispatch.

### Agent structure

Every agent file follows the same superpowers-derived template:

- **Frontmatter:** `name`, `description` (third-person, "Use when…" or
  description of role), `tools`.
- **Spirit-letter lead-in:** `> Violating the letter of these rules is
  violating the spirit.`
- **What this role is for:** one short paragraph naming the failure mode
  the agent exists to prevent.
- **Standing reading list:** the always-binding documents (CLAUDE.md,
  DESIGN.md, JOURNAL.md tail, plus role-specific anchors).
- **Carrier contract:** what the controller hands the agent (`task_text`,
  `diff`, `hypothesis`, etc.). Agents do NOT open `docs/plans/` or
  `docs/specs/` directly — context curation lives at the skill level.
- **Iron Law:** the non-negotiable rules of the role.
- **The Process:** numbered steps.
- **Status protocol:** structured terminal status the controller acts on.
  For implementer / tester / debugger / bencher / docwriter: `DONE` /
  `DONE_WITH_CONCERNS` / `NEEDS_CONTEXT` / `BLOCKED`. For reviewers:
  role-specific (`compliant` / `non_compliant` / `unclear` / `infra_blocked`
  for spec; `approved` / `changes_requested` / `infra_blocked` for quality).
- **Output format:** word-budgeted, structured.
- **Common Rationalisations:** excuse → reality table, calibrated to past
  failure modes.
- **Red Flags — STOP:** bullet list of "if you're about to do this,
  stop" signals.

### TDD as an independent layer

Note that `ailang-implementer` carries Test-Driven Development as an
*independent* discipline, not just as plan-template fallout. Even if the
plan task forgot to script a RED-first step, the implementer adds it
inline before writing production code. This mirrors the
superpowers split: `subagent-driven-development` (orchestration, outer
loop) is in `skills/implement/SKILL.md`; `test-driven-development` (per-
task, inner loop) is in `skills/implement/agents/ailang-implementer.md`.
The two skills exist at different layers and stack.

## Discovery

Two symlink sets, both tracked in git, no setup needed after clone:

**Skills** are reachable under `.claude/skills/` so Claude Code's
`Skill` tool can invoke them:

```
.claude/skills/brainstorm -> skills/brainstorm
.claude/skills/plan       -> skills/plan
.claude/skills/implement  -> skills/implement
.claude/skills/audit      -> skills/audit
.claude/skills/debug      -> skills/debug
```

**Agents** are reachable under `.claude/agents/` so subagent
dispatch can find them by `subagent_type`:

```
.claude/agents/implement  -> skills/implement/agents
.claude/agents/audit      -> skills/audit/agents
.claude/agents/debug      -> skills/debug/agents
```

## Conventions

- **No orphan agents.** Every agent lives under the skill that
  dispatches it. If a recurring need does not fit any skill, raise
  the question in `docs/JOURNAL.md` before adding the agent.
- **Agents do not call other agents.** The dirigierende skill
  composes (e.g. `implement` dispatches implementer, then a separate
  spec-compliance reviewer, then a code-quality reviewer).
- **Standing reading list stays in the agent file.** The skill provides
  the carrier (task text, bug symptom, drift focus, hypothesis) on top
  of the agent's standing reading list (CLAUDE.md, DESIGN.md, JOURNAL.md
  tail, role-specific anchors). Agents do NOT open `docs/plans/` or
  `docs/specs/` directly — context curation lives at the skill level.
- **Skill and agent definitions are reviewable code.** Edits go
  through git. Commit messages name why the role shifted.

## Adding a new skill

1. Decide what triggers it and what it produces.
2. Write `skills/<name>/SKILL.md` with frontmatter (`name`,
   `description` starting "Use when…"). Keep the description
   trigger-focused; never a workflow summary.
3. If the skill dispatches subagents, add them under
   `skills/<name>/agents/` and create
   `.claude/agents/<name>` as a symlink to that directory.
4. Update this file (skill table + agent roster).
5. If the skill replaces or supersedes a CLAUDE.md section,
   migrate that section: leave a one-line pointer in CLAUDE.md.

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