Brummel
176821c2e7
The 3020-line docs/DESIGN.md is replaced by the design/ ledger:
design/INDEX.md (sole addressable spine, typed Contracts+Models tables,
polymorphic links — prose file OR authoritative source //!), 14
design/contracts/*.md test-linked invariants + 3 source-link-only
contracts (mangling/env-construction/qualified-xref, no prose file —
code is SoT), 5 design/models/*.md whitepapers, and
docs/journals/2026-05-19-design-decision-records.md (the
relitigation-guard archive — every why/rejected/does-not-do/rollback/
empirical ### moved out at ###-granularity). Clean cut: git rm
docs/DESIGN.md, no stub.
RED-first crates/ailang-core/tests/design_index_pin.rs — the 4-clause
anti-regrowth spine (DESIGN.md-gone / every-INDEX-link-resolves /
every-contract-names-a-resolvable-ratifier /
contracts-carry-no-decision-record-prose) — demonstrably RED before,
GREEN after. Build-atomic by task ordering: design_schema_drift.rs's
include_str! (the only compile-time consumer) retargeted to
design/contracts/data-model.md BEFORE the deletion; its
## Data model/## Pipeline slicer dropped (a simplification the split
enables). 2 NoInstance diagnostics + 2 lockstep E2Es retargeted to
design/contracts/{float-semantics,typeclasses}.md. ~12 agent reading
lists + 5 SKILL bodies + CLAUDE.md + skills/README.md + ~25
code/C/.ail/spec comment xrefs retargeted; OQ7 dangling 'Iter 13b'
cite deleted (no forward target — a pointer would be fiction).
honesty-rule.md rewritten so the rule names the new home
(rationale->journals), resolving the recon-found internal
contradiction; the two docs_honesty_pin.rs:70,72 pinned phrases kept
verbatim+contiguous.
Boss-verified independently: cargo test --workspace 646 passed /
0 failed; design_index_pin 4/4; acceptance grep CLEAN of live
DESIGN.md refs (residuals = only the spec-mandated clause-4
deletion-enforcer). 2 DONE_WITH_CONCERNS routed to the mandatory
milestone-close audit: (a) str-abi.md:23 '(iter str-concat,
2026-05-13)' provenance stamp trips advisory architect_sweeps Sweep-1
— Boss-confirmed byte-identical to DESIGN.md@deeffb1:2062-2065, a
faithfully-migrated PRE-EXISTING anchor (regexes verbatim, only path
retargeted), NOT split-introduced — RATIFY-or-tidy at audit; (b) a
now stale-direction intra-prose 'see Str ABI below' cross-ref in
float-semantics.md — audit-adjudication candidate. Plan defect noted:
Task 9 Step 4's verbatim acceptance grep used a ^./ anchor not
matching the system's grep -rIn output; substance re-verified CLEAN.
Spec grounding-check PASS x2. Journals INDEX + decision-records
pointer appended (Boss-only).
216 lines
12 KiB
Markdown
216 lines
12 KiB
Markdown
# 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`](brainstorm/SKILL.md) | New milestone starting | `docs/specs/<milestone>.md` | Hard-gate before plan |
|
|
| [`planner`](planner/SKILL.md) | New iteration within an open milestone | `docs/plans/<iteration>.md` | Hard-gate before implement |
|
|
| [`implement`](implement/SKILL.md) | Plan exists | Code + tests + per-iter journal entry, all uncommitted in the working tree | Standard iteration path |
|
|
| [`audit`](audit/SKILL.md) | Milestone closing OR baseline drift suspected | Drift report + bench-regression report | **Mandatory** at milestone close |
|
|
| [`docwriter`](docwriter/SKILL.md) | API surface stabilized; rustdoc lag suspected | rustdoc updates in `///` and `//!`, uncommitted in the working tree | No — Boss-dispatched only |
|
|
| [`fieldtest`](fieldtest/SKILL.md) | 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`](debug/SKILL.md) | Bug encountered (failing test, segfault, wrong stdout) | RED-test in the working tree (uncommitted) + cause analysis | **Mandatory RED-first** for any bug |
|
|
| [`boss`](boss/SKILL.md) | 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.
|