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 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 + per-iter 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-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 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, 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/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/planner    -> skills/planner/agents
.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 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, then docwriter). 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.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.