AILang/skills

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 six skills

Skill	Trigger	Output	Mandatory?
brainstorm	New milestone starting	docs/specs/<milestone>.md	Hard-gate before plan
planner	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
fieldtest	After audit closes a milestone that touched user-visible surface	2-4 .ailx example fixtures + docs/specs/<date>-fieldtest-<milestone>.md	Standard milestone-close path; skipped only for purely internal milestones
debug	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  --(drift)--> plan + implement (tidy iteration)
                       --(ratify)-> JOURNAL + --update-baseline
                       --(clean)--v
                              fieldtest  --(bug)------> debug -> implement (mini)
                                         --(friction)-> brainstorm OR plan (tidy)
                                         --(spec_gap)-> ratify OR tighten DESIGN.md
                                         --(clean)----> next milestone

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)
ailang-fieldtester	fieldtest/agents/	fieldtest (writes real-world examples in .ailx Surface form against DESIGN.md only — never the compiler source)

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/planner    -> skills/planner
.claude/skills/implement  -> skills/implement
.claude/skills/audit      -> skills/audit
.claude/skills/fieldtest  -> skills/fieldtest
.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/fieldtest  -> skills/fieldtest/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.