refactor: drop agents/ stub, move roster to skills/README.md
agents/ contained only README.md after the 2026-05-09 migration. The roster information is more naturally located alongside the skills it points into. skills/README.md is now the single index (skill table, pipeline diagram, agent roster, discovery, conventions, how-to-add). CLAUDE.md updated: code-layout entry consolidated, @-reference points to skills/README.md.
This commit is contained in:
@@ -25,8 +25,7 @@
|
||||
| `bench/` | Regression harnesses (`check.py`, `compile_check.py`, `cross_lang.py`) and the throughput-and-latency runner (`run.sh`); `bench/reference/` holds the hand-C corpus for cross-language ratios |
|
||||
| `examples/` | AILang fixtures used by tests and benches |
|
||||
| `docs/` | Canonical specs and decisions log — `docs/DESIGN.md`, `docs/JOURNAL.md`, `docs/specs/` (per-milestone design specs), `docs/plans/` (per-iteration plans), `PROSE_ROUNDTRIP.md` |
|
||||
| `skills/` | Project-local skill definitions: `brainstorm`, `plan`, `implement`, `audit`, `debug`. Each skill bundles its dispatched agents under `skills/<name>/agents/` |
|
||||
| `agents/` | Roster only (`README.md` pointing into `skills/<name>/agents/`); historical home before the 2026-05-09 migration |
|
||||
| `skills/` | Project-local skill definitions: `brainstorm`, `plan`, `implement`, `audit`, `debug`. Each skill bundles its dispatched agents under `skills/<name>/agents/`. `skills/README.md` is the index (skill table + agent roster + discovery). |
|
||||
|
||||
## Skill system
|
||||
|
||||
@@ -53,7 +52,7 @@ agents are designed to enforce (mandatory reading order, fixed output
|
||||
format, explicit handoff between architecture / implementation /
|
||||
testing / debugging).
|
||||
|
||||
See @agents/README.md for the agent roster.
|
||||
See @skills/README.md for the skill + agent roster.
|
||||
|
||||
### What this means in practice
|
||||
|
||||
|
||||
@@ -1,61 +0,0 @@
|
||||
# AILang agents — roster
|
||||
|
||||
Agent definitions are part of the project toolchain. They bundle the
|
||||
discipline and context that every task in this repo needs (which
|
||||
design documents to read first, which tests must run, which output
|
||||
format comes back). They are versioned, reviewable, and changeable
|
||||
like any other part of the repo.
|
||||
|
||||
Since the 2026-05-09 skill-system migration, agents live next to the
|
||||
skill that primarily dispatches them, NOT in a flat `agents/`
|
||||
directory. This file is the roster pointing into the new layout.
|
||||
|
||||
## Where to find each agent
|
||||
|
||||
| Agent | Path | Dispatched by skill |
|
||||
|-------|------|---------------------|
|
||||
| `ailang-implementer` | `skills/implement/agents/` | `implement` |
|
||||
| `ailang-tester` | `skills/implement/agents/` | `implement` (E2E coverage) |
|
||||
| `ailang-architect` | `skills/audit/agents/` | `audit` |
|
||||
| `ailang-bencher` | `skills/audit/agents/` | `audit` (regression diagnostics) |
|
||||
| `ailang-docwriter` | `skills/audit/agents/` | `audit` (rustdoc-drift branch) |
|
||||
| `ailang-debugger` | `skills/debug/agents/` | `debug` |
|
||||
|
||||
## Subagent-type discovery
|
||||
|
||||
Subagent dispatch needs the agent files reachable under
|
||||
`.claude/agents/`. The repo provides one symlink per skill:
|
||||
|
||||
```
|
||||
.claude/agents/implement -> skills/implement/agents
|
||||
.claude/agents/audit -> skills/audit/agents
|
||||
.claude/agents/debug -> skills/debug/agents
|
||||
```
|
||||
|
||||
These symlinks are tracked in git. After cloning, no extra setup is
|
||||
needed.
|
||||
|
||||
## Convention
|
||||
|
||||
- Each agent is a `.md` file with YAML frontmatter
|
||||
(`name`, `description`, `tools`) and a system-prompt body.
|
||||
- The `description` field is the one-sentence summary the
|
||||
orchestrator (or a skill) reads to decide whether to dispatch.
|
||||
- Edits go through git; agent definitions are reviewable code.
|
||||
- Agents do NOT call other agents. The dirigierende skill handles
|
||||
composition (per `skills/implement/SKILL.md` for the
|
||||
implementer + reviewer + tester pattern, etc.).
|
||||
- The agent's "mandatory reading order" stays in the agent file
|
||||
(it's agent discipline). The dirigierende skill provides the
|
||||
task-specific context (plan extract, bug symptom, drift item)
|
||||
on top.
|
||||
|
||||
## 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 table 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 — orphan agents
|
||||
are an anti-pattern after the 2026-05-09 build-out.
|
||||
@@ -0,0 +1,108 @@
|
||||
# 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.
|
||||
|
||||
## Subagent-type discovery
|
||||
|
||||
Subagent dispatch needs the agent files reachable under
|
||||
`.claude/agents/`. The repo provides one symlink per skill (tracked
|
||||
in git, no setup needed after clone):
|
||||
|
||||
```
|
||||
.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.
|
||||
Reference in New Issue
Block a user