The Mental Model — One Source, Two Runtimes
Canonical `.agents/` and the Generated Projections
Author Once, Render Twice
Version 6 introduced a shared layout. Everything shared is authored in one place — .agents/ — and the native folders for each runtime are generated from it:
| Surface | Authored source | Delivered as |
|---|---|---|
| Workflow | skills/{name}/references/workflow.md |
Claude command / Codex $skill-name entry point |
| Roles | roles/{name}.md |
Claude Markdown agent / Codex TOML |
| Helpers and hooks | core/, hooks/ |
Generated wrappers under .claude/ and .codex/ |
| Runtime differences | adapters/{claude,codex}/ |
Model, tool and hook settings per runtime |
| Version | config/version.json |
Native compatibility copy |
The helpers you run depend on the runtime: Claude uses .claude/core/, Codex uses .codex/core/, with identical arguments.
node .claude/core/render-shared-agents.js # regenerate native projections from .agents/
node .claude/core/render-shared-agents.js --check # verify projections match their sources
The One Rule
Edit the canonical source, then render. A generated file carries a header saying so. Editing the projection directly works until the next render, then your change vanishes — or worse, shows up as a conflict.
A conflict in a generated file is a conflict, not a signal to force. Move the intended change to its canonical source under .agents/, then render. render-state.json records ownership hashes so edited managed files get flagged for review instead of silently overwritten.
You want to change a workflow's wording. Where do you make the edit?