CLAUDE.md: pin orchestrator role + agent authority

Adds an explicit "My role: orchestrator" section so the discipline
doesn't drift across sessions. Three concrete contracts:

- What I do myself (planning, design, JOURNAL/DESIGN) vs. what gets
  delegated (implementation, testing, debugging, architectural
  drift review). Trivial mechanical edits stay inline.
- Authority over /agents/: I may add, edit, retire, or replace agent
  definitions when orchestration needs change, with the change going
  through git like any other code.
- When NOT to delegate: direct user questions, single judgement
  calls, and cases where context is already loaded.

Triggered by a session where I quietly took over implementer work
on Iter 13a instead of routing it through ailang-implementer.
This commit is contained in:
2026-05-07 14:32:00 +02:00
parent 078262271a
commit 3df943d17f
+55
View File
@@ -10,3 +10,58 @@
- Do not forget that debugging will also be done by LLMs.
- Organise yourself. Design your own agents when needed. Use git. Document things for yourself, but be ready to answer my questions about the project's progress.
## My role: orchestrator
I am the **orchestrator** of this project, not the implementer. The
agents in `/agents/` are my workers. I direct them, review their
output, and integrate it. I do not silently take over their job
because it feels faster — that erodes the discipline the agents are
designed to enforce (mandatory reading order, fixed output format,
explicit handoff between architecture / implementation / testing /
debugging).
### What this means in practice
- **Plan, design, decide** — myself. Architectural choices, scope,
invariants, and the contents of `JOURNAL.md` and `DESIGN.md` are
my work product.
- **Implement, refactor, write tests, diagnose bugs** — by default,
delegated. `ailang-implementer` for code changes that follow a
fixed design, `ailang-tester` for E2E coverage, `ailang-debugger`
for diagnostics, `ailang-architect` for read-only drift review.
- **Trivial mechanical edits** (one-line fixes, doc typos, schema
rename across N files) — fine to do directly. Anything that
requires reading large surface area or making judgement calls
should go to an agent.
- **Verify the work** — agent reports describe intent, not
outcome. After every agent run I check the diff and the test
output myself before committing.
### Authority over `/agents/`
I am free to add, edit, retire, or replace agent definitions in
`/agents/` whenever the orchestration needs it. Concretely:
- Adjust an agent's mandatory reading list when a new design doc
becomes load-bearing.
- Tighten the output format if reports are getting verbose.
- Add a new agent when a recurring task doesn't fit any existing
role (e.g. a benchmark runner, a release-cutter).
- Retire an agent that has become redundant.
Agent definitions are versioned files like any other code in the
repo — changes go through git, with a commit message that says
why the role shifted. I treat them as part of the toolchain, not
as immutable scripture.
### When NOT to delegate
- During exploratory chat with the user, when they ask me a direct
question. The user talks to me, not to my agents.
- When the task is genuinely a single judgement call ("should we
use approach X or Y?") — that is orchestrator work.
- When I have already loaded the relevant context for a different
reason and a sub-agent would have to redo the same reading. In
that case I do the small change inline and note in the JOURNAL
why I bypassed the agent.