agentic-os / control-plane
AGENTS.md2 starsChanged 5 months agoMITView on GitHub
This file is the Codex-facing control-plane contract. It mirrors control-plane/CLAUDE.md where the architecture is runtime-neutral and narrows behavior where Codex differs mechanically from Claude Code. The principal is the CEO. The interface agent is the single operator voice. Domain specialists and entity guardians execute through the interface agent. The senior advisor validates substantive output internally before it reaches the principal. Canonical flow: Claude Code is still the reference runtime for deterministic hook execution. Codex support means the repo has clear…
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 31,439 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 repository24 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- control-plane/CLAUDE.mdCLAUDE.md
- agentic-os-reference-syncSkill
- branch-cleanupSkill
- capture-triageSkill
- darwin-housekeepingSkill
- darwin-path-modeSkill
- decision-log-entrySkill
- eodSkill
- expert-interview-guideSkill
- feedback-intakeSkill
- harness-onboardingSkill
- ingest-contentSkill
- meeting-to-work-itemsSkill
- memory-consolidateSkill
- morning-briefSkill
- os-bootstrap-extendSkill
- os-bootstrapSkill
- pr-reviewSkill
- scheduleSkill
- spec-cross-checkSkill
- ux-critiqueSkill
- weekly-retroSkill
The file
We split this AGENTS.md into the rules it gives an agent
8 rules. About 0 are common, 7 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 38
Before editing a covered path, read the narrowest applicable rule:
- Distinctive: line 49
Use subagents/spokes when active guidance implies a specialist.
- Distinctive: line 51
Do not invoke a subagent for:
- Distinctive: line 66
Default to lean context. Do not preload every memory, agent spec, skill body, and historical decision.
- Very specific: line 68
Read state.md fast paths before full agent specs when possible.
- Distinctive: line 69
Use routing indexes and references before loading entire directories.
- Distinctive: line 71
Stop broad searches early when the answer is already bounded.
- Distinctive: line 72
Prefer verification commands over long transcript reconstruction.
≈ “Common” is an estimate: at least 1 in 5 of the 40,246 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
Control Plane - AGENTS.md (Codex Runtime)
This file is the Codex-facing control-plane contract. It mirrors control-plane/CLAUDE.md where the architecture is runtime-neutral and narrows behavior where Codex differs mechanically from Claude Code.
Identity And Flow
The principal is the CEO. The interface agent is the single operator voice. Domain specialists and entity guardians execute through the interface agent. The senior advisor validates substantive output internally before it reaches the principal.
Canonical flow:
Principal -> interface agent -> specialists/entities -> interface agent -> senior advisor -> interface agent -> PrincipalRuntime Surfaces
| Surface | Claude Code | Codex |
| Root orientation | CLAUDE.md | AGENTS.md |
| Control-plane contract | control-plane/CLAUDE.md | control-plane/AGENTS.md |
| Agent specs | .claude/agents/ | read .claude/agents/ unless a fork creates .codex/agents/ |
| Skills | .claude/skills/ | read .claude/skills/ unless a fork creates .codex/skills/ |
| Hook config | .claude/settings.json | no automatic parity unless wired by the fork |
Claude Code is still the reference runtime for deterministic hook execution. Codex support means the repo has clear orientation, path rules, and context-budget discipline for Codex sessions; it does not imply all Claude hooks fire inside Codex.
Source Of Truth
| Category | Owner |
| Operational projects, tasks, notes, reviews | External system chosen by the operator |
| Structural identity, rules, memory, specs, templates | Local control plane |
| Code, scripts, config | Git repositories |
| Raw evidence | Original files |
Path-Scoped Rules
Before editing a covered path, read the narrowest applicable rule:
| Path | Rule |
control-plane/**, root CLAUDE.md, root AGENTS.md, runtime contracts, hook config | control-plane/rules/engineering-standards.md + senior-advisor pressure-test for structural changes |
.claude/agents/** | control-plane/agent-patterns/README.md and the specific pattern file |
.claude/skills/** | existing skill frontmatter conventions + control-plane/best-practices/progressive-disclosure.md |
| code or scripts | control-plane/rules/engineering-standards.md |
Agentic-By-Default
Use subagents/spokes when active guidance implies a specialist. The principal does not need to repeat "use an agent" when the OS routing already says a spoke owns the work.
Do not invoke a subagent for:
- A factual question about a file already read this session.
- A single mechanical operation.
- A conversational response with no decision weight.
- A one-line sanity check.
Senior Advisor And Guardians
Senior-advisor review is required for substantive plans, structural changes, prioritization with tradeoffs, governance changes, and output with reputational or strategic weight.
Entity guardians are required before concrete proposals that consume protected time or violate a declared non-negotiable.
Context Budget
Default to lean context. Do not preload every memory, agent spec, skill body, and historical decision.
- Read
state.mdfast paths before full agent specs when possible. - Use routing indexes and references before loading entire directories.
- Move bulky evidence into scratchpads or artifacts and summarize only the fields needed for the current decision.
- Stop broad searches early when the answer is already bounded.
- Prefer verification commands over long transcript reconstruction.
Output Standard
Return: direct answer -> recommendation -> so what -> brief rationale -> open questions only if needed.
Separate what is implemented, locally tested, CI-green, reviewed, mergeable, and merged.
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.