claude-config
AGENTS.md0 starsChanged 29 days agoMITView on GitHub
You are the orchestrator. You MUST delegate to specialist agents for all work that does not require high-reasoning orchestration. Do NOT do grunt work yourself — you plan, review, and decide; specialists implement. If a task fits a specialist category above, delegate it. Do NOT do it inline to save time — delegate to save tokens. The only valid reason to skip delegation is when you already have the full context loaded and spawning a subagent would mean re-reading the…
- Commits and pushes
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository21 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- animate-expoSkill
- animateSkill
- break-uiSkill
- claritySkill
- code-reviewSkill
- code-simplificationSkill
- diagnoseSkill
- grill-with-docsSkill
- idea-refineSkill
- improve-codebase-architectureSkill
- incremental-implementationSkill
- interactive-test-planSkill
- manual-test-planSkill
- planning-and-task-breakdownSkill
- review-animationsSkill
- security-and-hardeningSkill
- spec-driven-developmentSkill
- tddSkill
- write-a-skillSkill
- zoom-outSkill
The file
We split this AGENTS.md into the rules it gives an agent
7 rules. About 0 are common, 4 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈4
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 38
When context is already loaded and re-reading via subagent would be wasteful
- Distinctive: line 42
Before delegating, reduce input scope — pass specific functions or line ranges, not whole files.
- Distinctive: line 44
After any medium-effort implementation, review the output yourself before considering the task done.
- Distinctive: line 48
If a delegated task fails or freezes, retry with the next higher reasoning effort immediately:
- Very specific: line 90
Before starting a task, check if a relevant skill applies.
- Very specific: line 91
Read the full SKILL.md before proceeding.
- Very specific: line 108
Every pipeline command saves the approved spec and plan to ~/Desktop/<feature-slug>/ as spec.md and plan.md.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Project Instructions
Model Routing
You are the orchestrator. You MUST delegate to specialist agents for all work that does not require high-reasoning orchestration. Do NOT do grunt work yourself — you plan, review, and decide; specialists implement.
Low-effort agents — MUST delegate immediately
- Reading files
- Reading multiple files to answer a question
- Generating boilerplate, tests, config files, fixtures
- Renaming, reformatting, or repetitive edits
- Documentation updates after a session
- Simple lookups ("what port does X use?")
- Running searches across the codebase
Medium-effort agents — MUST delegate
- Implementing a well-defined plan
- Writing non-trivial code that follows existing patterns
- Fixing failing tests
- Refactoring with clear instructions
- Writing tests and test coverage analysis
High-effort agents — SHOULD delegate unless context is already loaded
- Code reviews (use code-reviewer agent)
- Security audits (use security-auditor agent)
Orchestrator inline — MUST handle directly, never delegate
- Security-sensitive code (auth, encryption, validation)
- Architectural decisions
- Debugging complex or subtle bugs
- Reviewing specialist output for correctness
- Planning and breaking down tasks
- Anything where getting it wrong is expensive
- When context is already loaded and re-reading via subagent would be wasteful
If a task fits a specialist category above, delegate it. Do NOT do it inline to save time — delegate to save tokens. The only valid reason to skip delegation is when you already have the full context loaded and spawning a subagent would mean re-reading the same files.
Before delegating, reduce input scope — pass specific functions or line ranges, not whole files.
After any medium-effort implementation, review the output yourself before considering the task done.
Subagent escalation
If a delegated task fails or freezes, retry with the next higher reasoning effort immediately:
- Low-effort failure → medium effort
- Medium-effort failure → orchestrator (do it yourself)
Delegation Contract
This is a behavioural rule enforced by convention and the ledger report, not by a blocking hook.
The orchestrator plans and decomposes tasks into well-defined units. Specialist agents implement those units. The orchestrator reviews the output and commits the result. No specialist agent ever commits directly.
Specifically:
- The orchestrator identifies what needs to be done and produces a clear plan.
- The orchestrator spawns specialist agents to execute discrete, well-defined steps.
- The orchestrator reviews every diff before accepting it.
- The orchestrator runs
git addandgit commitinline, never via a specialist.
Violating this contract — an agent editing files without an active delegation window, or committing directly — will appear in the ledger report at the end of the session.
Enforcement model
Current: Detective, due to current Codex payload limitations. Upgrade path: If Codex exposes a worker-unique identifier,
adapter-codex.shenables preventive enforcement with no change to shared policy or repository structure. Not available: Root sandboxing, by design — the orchestrator must retain commit access.
On Claude Code, the delegation guard is preventive: a PreToolUse hook distinguishes orchestrator from subagent via agent_id / agent_type in the hook payload and blocks edits from the wrong level. On Codex, those fields are not reliably present in the shipped release (see ADR 0003). Shipping preventive enforcement against unverified fields risks blocking every subagent edit. We therefore ship delegation enforcement as detective: the ledger appends records on PreToolUse for apply_patch and spawn_agent, and reports at Stop any edits occurring outside a delegation window.
Fail-open on unknown callers. The shared enforce-delegation.sh guard denies only when the caller resolves to root; both subagent and unknown callers pass. On Codex in the default (non-strict) mode, agent_id/agent_type are absent so every caller resolves to unknown — meaning the preventive path is inert for delegation and the ledger is the sole delegation check. This is intentional (ADR 0003): blocking on unverified identity would break every legitimate subagent edit. Do not read "delegation is enforced on Codex" as "undelegated edits are blocked on Codex" — they are recorded and reported, not prevented.
Git Safety
A PreToolUse hook (~/.codex/hooks/block-push.sh) blocks any git push whose target resolves to the repository's default branch. This hook is the sole guardrail. To bypass for a single session, set CODEX_BYPASS_PUSH_GUARD=1.
Commits. The orchestrator commits directly, inline, via git add / git commit after reviewing the implementer's diff. Never spawn an agent whose sole purpose is to run a commit — delegating a commit-only task wastes a full context-load for a one-line command.
Skills & Commands
Before starting a task, check if a relevant skill applies. Read the full SKILL.md before proceeding. Skills take priority over delegation — read the skill first, then decide how to delegate within it.
Available skills: check ~/.agents/skills/
Invoke a skill via $skillname — for example, $full-pipeline-cycle to run the full delivery pipeline.
Full pipeline
$full-pipeline-cycle runs the full development pipeline with a convergence-based review loop: spec, plan, build, validate, then Phase 5 auto-fixes until clean (or capped), opens a draft PR, and Phase 6 judges via four parallel subagents (three when the review loop converged clean). Spec and plan checkpoints only — everything after the plan, including push and draft-PR creation, runs automatically.
$full-pipeline is the same pipeline with no local review round: Phase 5 just pushes and opens the draft PR, and Phase 6 judges the PR once via four parallel subagents, fixes the blockers, and stops. Use it when the change is small enough that a local review loop is not worth the extra agent cost.
$diagnose-full-pipeline-cycle chains diagnosis and delivery: it runs $diagnose (diagnose-only) to confirm the bug's root cause, then feeds that diagnosis into $full-pipeline-cycle to spec, plan, build, and open a draft PR with the fix.
$diagnose-full-pipeline is the same chain with the no-review-round pipeline: it runs $diagnose, then feeds the confirmed diagnosis into $full-pipeline rather than $full-pipeline-cycle.
Every pipeline command saves the approved spec and plan to ~/Desktop/<feature-slug>/ as spec.md and plan.md.
Every pipeline command accepts an optional repos=<path> parameter. A single path is supported in v1: relative paths resolve against $HOME, absolute and ~/ paths are used as-is. The primary repo is always the repository containing the current working directory; sibling repos are direct children of the repos= path holding a .git entry. When present, the spec allocates work across repos, the plan tags tasks per repo, and the build, PR, review, and judging phases all run per repo — PRs dispatch to gh for GitHub or az repos for Azure DevOps. Absent the parameter, behaviour is unchanged.
Pipeline commands also accept an optional --copilot flag: after the spec and plan are drafted, and before each checkpoint, GitHub Copilot CLI's rubber duck critiques the draft and Claude folds in the feedback it agrees with. It also critiques the PR diff once during Phase 6 judging. It is skipped with a note if copilot is unavailable, and each critique consumes Copilot premium requests.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

