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-archive.md ("Skill system live") for the rationale.

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 + per-iter journal entry, 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)-> JOURNAL + --update-baseline
                       --(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, latest per-iter journals, 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, journal files, stats files, updated baselines) 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.
• 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 the question via a per-iter journal entry 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 and docs/journals/2026-05-11-iter-or.2.md for the revision history.
• 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, latest per-iter journals, 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 via a per-iter journal entry first.