# AILang agents

These 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.

## What lives here

| Agent                    | Role                                                              |
|--------------------------|-------------------------------------------------------------------|
| `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.                  |

## Invocation scheme

Each `.md` file consists of YAML frontmatter (`name`, `description`, `tools`)
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
   sits under `~/.claude/agents/` or `.claude/agents/`, Claude Code loads it
   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
   `general-purpose` agent. Functionally identical to the subagent call,
   except the caller has to send the body explicitly.

## Extending or changing agents

- New agent: another `.md` file with frontmatter (`name`, `description`,
  `tools`) and system-prompt body.
- Existing agent: edit directly, like any other code file. Changes show up
  in git history.
- Convention: the frontmatter `description` field is the one-sentence
  description an orchestrator reads to decide whether to call the agent.
  Keep it short and specific.