Brummel
9b97a862f6
The skills are functionally complete and standalone — superpowers references were attribution-only. Removed so a reader without the superpowers plugin loaded isn't sent chasing dead links. Plus: .claude/skills/<name> symlinks so Claude Code's Skill tool can invoke them by name (analogous to the existing .claude/agents/ symlinks). Discovery section in skills/README.md updated to cover both symlink sets.
121 lines
5.0 KiB
Markdown
121 lines
5.0 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.md` ("Skill system live") for the rationale.
|
|
|
|
## The five skills
|
|
|
|
| Skill | Trigger | Output | Mandatory? |
|
|
|-------|---------|--------|------------|
|
|
| [`brainstorm`](brainstorm/SKILL.md) | New milestone starting | `docs/specs/<milestone>.md` | Hard-gate before plan |
|
|
| [`plan`](plan/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-task commits + JOURNAL entry | Standard iteration path |
|
|
| [`audit`](audit/SKILL.md) | Milestone closing OR baseline drift suspected | Drift report + bench-regression report + rustdoc audit | **Mandatory** at milestone close |
|
|
| [`debug`](debug/SKILL.md) | 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 --(clean)--> next milestone
|
|
--(drift)--> plan + implement (tidy iteration)
|
|
OR ratify in DESIGN.md
|
|
```
|
|
|
|
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` |
|
|
| `ailang-tester` | `implement/agents/` | `implement` (E2E coverage) |
|
|
| `ailang-architect` | `audit/agents/` | `audit` |
|
|
| `ailang-bencher` | `audit/agents/` | `audit` (regression diagnostics) |
|
|
| `ailang-docwriter` | `audit/agents/` | `audit` (rustdoc-drift branch) |
|
|
| `ailang-debugger` | `debug/agents/` | `debug` |
|
|
|
|
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.
|
|
|
|
## 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/plan -> skills/plan
|
|
.claude/skills/implement -> skills/implement
|
|
.claude/skills/audit -> skills/audit
|
|
.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/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).
|
|
- **Mandatory reading order stays in the agent file.** Skills
|
|
provide task-specific context (plan extract, bug symptom, drift
|
|
item) on top of the agent's standing reading list.
|
|
- **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.
|