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:
@@ -10,3 +10,58 @@
|
|||||||
- Do not forget that debugging will also be done by LLMs.
|
- 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.
|
- 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.
|
||||||
|
|||||||
Reference in New Issue
Block a user