# 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/.md` | Hard-gate before plan | | [`plan`](plan/SKILL.md) | New iteration within an open milestone | `docs/plans/.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//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//agents/` and create `.claude/agents/` 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.