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; the bootstrap rationale lives in the commits from that week.

The eight 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 (and BLOCKED.md on PARTIAL/BLOCKED), all uncommitted in the working tree	Standard iteration path
audit	Milestone closing OR baseline drift suspected	Drift report + bench-regression report	Mandatory at milestone close
docwriter	API surface stabilized; rustdoc lag suspected	rustdoc updates in /// and //!, uncommitted in the working tree	No — Boss-dispatched only
fieldtest	Boss-dispatched post-audit field test on a milestone that touched user-visible surface	2-4 .ail example fixtures + docs/specs/<date>-fieldtest-<milestone>.md, all uncommitted in the working tree	No — Boss-dispatched only
debug	Bug encountered (failing test, segfault, wrong stdout)	RED-test in the working tree (uncommitted) + cause analysis	Mandatory RED-first for any bug
boss	User-invoked only (/boss)	Autonomous orchestration session — dispatches existing skills until done-state or bounce-back	No — user-gated

Pipeline

Inside a /boss session the orchestrator walks this pipeline autonomously. Outside /boss, the pipeline runs only when the user explicitly invokes a skill.

[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)-> --update-baseline + ratify paragraph in audit commit body
                       --(clean)-+
                                 |
                       [Boss: iter complete? if surface-touch:]
                                 v
                            fieldtest --(bug)------> debug -> implement (mini)
                                      --(friction)-> brainstorm OR plan (tidy)
                                      --(spec_gap)-> ratify OR tighten design/ ledger
                                      --(clean)----+
                                                   |
                                       [Boss: surface stable across N milestones?]
                                                   v
                                              docwriter (rustdoc sweep)
                                                   |
                                                   v
                                            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-grounding-check	brainstorm/agents/	brainstorm (Step 7.5; spec grounding hard-gate)
ailang-plan-recon	planner/agents/	planner (Step 2; read-only file-structure mapping); brainstorm (ad-hoc Step 1 in unfamiliar territory)
ailang-implement-orchestrator	implement/agents/	implement (the dispatched agent; runs the entire per-task loop inline in its own context)
ailang-implementer	implement/agents/	phase reference for ailang-implement-orchestrator Phase 2.1 (implementer mindset, carries TDD as an independent layer); not dispatched as a separate subagent
ailang-spec-reviewer	implement/agents/	phase reference for ailang-implement-orchestrator Phase 2.2 (spec-compliance mindset); not dispatched as a separate subagent
ailang-quality-reviewer	implement/agents/	phase reference for ailang-implement-orchestrator Phase 2.3 (quality-review mindset); not dispatched as a separate subagent
ailang-tester	implement/agents/	phase reference for ailang-implement-orchestrator Phase 3 (E2E coverage); not dispatched as a separate subagent
ailang-architect	audit/agents/	audit (Step 1; drift review against the design/ ledger + spec)
ailang-bencher	audit/agents/	audit (regression diagnostics — hypothesis-driven)
ailang-docwriter	docwriter/agents/	docwriter (Boss-dispatched rustdoc sweep post-stability)
ailang-debugger	debug/agents/	debug (RED-first; hands off GREEN to implement mini-mode)
ailang-fieldtester	fieldtest/agents/	fieldtest (writes real-world examples in .ail Surface form against the design/ ledger 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/INDEX.md, git log --format=full for recent state, 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/docwriter  -> skills/docwriter
.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/brainstorm  -> skills/brainstorm/agents
.claude/agents/planner    -> skills/planner/agents
.claude/agents/implement  -> skills/implement/agents
.claude/agents/audit      -> skills/audit/agents
.claude/agents/docwriter  -> skills/docwriter/agents
.claude/agents/fieldtest  -> skills/fieldtest/agents
.claude/agents/debug      -> skills/debug/agents

Conventions

• Only the Boss commits. No skill agent — implementer, brainstormer, planner, debugger, fieldtester, docwriter, architect, bencher — performs git commit. Agents write their artefacts (spec, plan, code, tests, fixtures, rustdoc edits, RED tests, stats files, updated baselines, BLOCKED.md on PARTIAL/ BLOCKED) to the working tree as unstaged changes. The Boss inspects with git status / git diff and commits when there is something consistent to commit. Per-task or per-phase commits are not a goal; the iter (or the cohesive change) is the unit of commit. BLOCKED.md is never committed by convention.
• main HEAD is sacrosanct. No actor (Boss or agent) runs git reset or git revert on main. main moves forward only via Boss commits; bad work stays in the working tree where it is still discardable via git checkout -- <path> (Boss-side, not on main HEAD).
• No orphan agents. Every agent lives under the skill that dispatches it. If a recurring need does not fit any skill, raise it with the user (or in a /boss session, surface the question via notify) before adding the agent.
• Agents do not call other agents. The dispatching skill composes (e.g. audit dispatches architect, then bencher). No agent receives the Agent tool in its frontmatter — Claude Code does not permit a subagent to spawn other subagents. The ailang-implement-orchestrator, which historically was framed as a named exception, runs its per-task phases as sequential role-switches inside its own context (implementer phase → spec check → quality check); see skills/implement/SKILL.md for the mechanism.
• 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/INDEX.md, git log --format=full for recent state, 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 with the user first.