From ad6e4119a077cf41a0845a3f4d34523ad2022560 Mon Sep 17 00:00:00 2001 From: Brummel Date: Sat, 9 May 2026 15:54:21 +0200 Subject: [PATCH] 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. --- CLAUDE.md | 5 +-- agents/README.md | 61 -------------------------- skills/README.md | 108 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 110 insertions(+), 64 deletions(-) delete mode 100644 agents/README.md create mode 100644 skills/README.md diff --git a/CLAUDE.md b/CLAUDE.md index 786e01a..232127a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -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//agents/` | -| `agents/` | Roster only (`README.md` pointing into `skills//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//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 diff --git a/agents/README.md b/agents/README.md deleted file mode 100644 index 276bf73..0000000 --- a/agents/README.md +++ /dev/null @@ -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. diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 0000000..792b858 --- /dev/null +++ b/skills/README.md @@ -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/.md` | Hard-gate before plan | +| [`plan`](plan/SKILL.md) | New iteration within an open milestone | `docs/plans/.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//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//agents/` and create + `.claude/agents/` 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.