docs: agents/README.md — rewritten as roster of skill-bound agents

agents/README.md

@@ -1,45 +1,61 @@
-# AILang agents
+# AILang agents — roster
 
-These agent definitions are part of the project toolchain. They bundle the
+Agent definitions are part of the project toolchain. They bundle the
-discipline and context that every task in this repo needs (which design
+discipline and context that every task in this repo needs (which
-documents to read first, which tests must run, which output format comes
+design documents to read first, which tests must run, which output
-back). They are versioned, reviewable, and changeable like any other part of
+format comes back). They are versioned, reviewable, and changeable
-the repo.
+like any other part of the repo.
 
-## What lives here
+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.
 
-| Agent                    | Role                                                              |
+## Where to find each agent
-|--------------------------|-------------------------------------------------------------------|
-| `ailang-implementer.md`  | Carries out tightly scoped implementation tasks.                  |
-| `ailang-architect.md`    | Read-only reviewer; checks for drift against DESIGN.md after iterations. |
-| `ailang-tester.md`       | Writes examples and E2E tests.                                    |
-| `ailang-debugger.md`     | Diagnoses compiler or codegen bugs.                               |
-| `ailang-docwriter.md`    | Writes and maintains rustdoc on the Rust crates.                  |
-| `ailang-bencher.md`      | Hypothesis-driven memory-management benchmarker; ships evidence, not features. |
 
-## Invocation scheme
+| 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` |
 
-Each `.md` file consists of YAML frontmatter (`name`, `description`, `tools`)
+## Subagent-type discovery
-and a system-prompt body. There are two ways to invoke them:
 
-1. **As a subagent (preferred, when the tooling supports it).** When the file
+Subagent dispatch needs the agent files reachable under
-   sits under `~/.claude/agents/` or `.claude/agents/`, Claude Code loads it
+`.claude/agents/`. The repo provides one symlink per skill:
-   as a `subagent_type` and calls it as a native agent. The files here are
-   deliberately NOT in `.claude/` because they belong to the project
-   toolchain and should be visible. Anyone who wants to enable subagent
-   loading can symlink: `ln -s $(pwd)/agents .claude/agents`.
 
-2. **As a prompt prefix (always available).** The body of the `.md` file is
+```
-   prepended to the concrete task description and handed to a
+.claude/agents/implement -> skills/implement/agents
-   `general-purpose` agent. Functionally identical to the subagent call,
+.claude/agents/audit     -> skills/audit/agents
-   except the caller has to send the body explicitly.
+.claude/agents/debug     -> skills/debug/agents
+```
 
-## Extending or changing agents
+These symlinks are tracked in git. After cloning, no extra setup is
+needed.
 
-- New agent: another `.md` file with frontmatter (`name`, `description`,
+## Convention
-  `tools`) and system-prompt body.
+
-- Existing agent: edit directly, like any other code file. Changes show up
+- Each agent is a `.md` file with YAML frontmatter
-  in git history.
+  (`name`, `description`, `tools`) and a system-prompt body.
-- Convention: the frontmatter `description` field is the one-sentence
+- The `description` field is the one-sentence summary the
-  description an orchestrator reads to decide whether to call the agent.
+  orchestrator (or a skill) reads to decide whether to dispatch.
-  Keep it short and specific.
+- 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.