Agent portability
The big picture: Blueprint’s rules live in two files. The root AGENTS.md is the
project contract: what correct work means here, written for any coding agent or
person. CLAUDE.md imports it and adds the Claude Code workflow on top: review
agents, skills, hooks, and the order the gates run in.
Why it matters: a team that adds a second coding agent, or moves off Claude Code,
keeps the contract instead of forking it. Tools that follow the AGENTS.md convention
(Codex among them) read the file directly, with no adapter.
The bottom line: another agent gets the rules and the gate scripts. It does not get the review agents, the skills, the hooks that enforce the rules inside a session, or the Claude Code deny list that blocks force-pushes and MR merges. CI, the git hooks and the GitLab project settings still enforce what they always did, whoever wrote the change; two of the forbidden operations have no other mechanical guard.
How the two files split
Section titled “How the two files split”AGENTS.md — any agent |
CLAUDE.md — Claude Code only |
|---|---|
| Project name, stack and versions | Personas (used by /voc) |
Build, test and lint commands (make targets) |
Skills, agents and when each runs |
| Before-push checks and the branch → MR → green-pipeline flow | The Fast paths by change class table and the pre-MR gate batch |
Forbidden operations: committing to main, an agent merging an MR, force-pushing a shared branch, editing CHANGELOG.md, committing secrets |
Hooks and .claude/settings.json |
| Secure-code rules, conventions, git workflow and git traps | Subagent fan-out ceiling |
| Milestone labels, documentation tense, CI-failure triage | Memory, cost and Claude Code configuration rules |
Where the gates live (scripts/check-*) and how to run them |
The security invariants registry and path-scoped rule files |
CLAUDE.md starts with the line @AGENTS.md, so a Claude Code session loads both files.
A rule lives in exactly one of them. make check-single-fastpath-table (pre-push and CI)
fails when a sentinel rule heading opens a section in both (or in neither, which means
a typo in its list), when AGENTS.md names .claude, or when CLAUDE.md’s first line
is not the import. make doctor and
make customize flag a missing file or a missing import too.
What another agent gets from AGENTS.md alone
Section titled “What another agent gets from AGENTS.md alone”- The rules. Everything in the left column above: the same invariants, conventions and forbidden operations a Claude Code session follows.
- The gates, as scripts. Every
scripts/check-*gate is shell or Python, run bymake pre-push-checksand by CI. Each takes--self-test. None depends on Claude Code. - The same safety net. The pre-commit and pre-push git hooks (
make setup), the CI pipeline, protectedmainand Pipelines must succeed apply to every change, whoever or whatever wrote it.
What it does not get
Section titled “What it does not get”- Gates enforced by hooks. The Claude Code hooks in
.claude/settings.json(the pre-tool safety guard, post-edit reminders, the pre-MR security gate) run only inside Claude Code. Another agent can edit a lock file or open an MR without those prompts; the git hooks and CI catch what they check, after the fact. - The permission deny list.
.claude/settings.jsondeniesgit push --force/-f,glab mr merge, and reading.env,.env.*and key files. It is the only mechanical enforcement of two ofAGENTS.md’s forbidden operations: nothing else stops an agent from force-pushing a feature branch, and once the pipeline is green, nothing else stops it from merging an MR (protectedmainand Pipelines must succeed stop only a direct push and a red merge). For another agent, those two rules are written down, not enforced. Configure that tool’s own command restrictions, or give it a forge token that cannot merge. - Skills.
/mr,/wave,/release,/kickoffand the rest are Claude Code skill files. Another agent can read them as documentation, but nothing invokes them. - Review agents.
architect,security-review,completeness-checkand the other agents in.claude/agents/are Claude Code subagents. Their review step, and the fast-path table that orders them, have no equivalent in another tool yet. - Personas, memory and cost rules. These are Claude Code workflow and stay in
CLAUDE.md.
What Claude Code does and does not read
Section titled “What Claude Code does and does not read”Per How Claude remembers your project (checked 2026-10-17):
- By default, Claude Code reads
AGENTS.mdby itself only when there is noCLAUDE.mdin the working directory or above it. Blueprint has aCLAUDE.md, so the@AGENTS.mdimport is what loads the contract. Delete the import and Claude Code stops reading it. - Claude Code never reads
AGENTS.local.md,AGENTS.override.md, or anything under a.agents/directory. Blueprint ships none of them; do not put project rules there and expect Claude to follow them. - An imported file loads at launch with the file that imports it, so moving rules from
CLAUDE.mdintoAGENTS.mdchanges where they live, not what a session loads.
Using Blueprint without Claude Code
Section titled “Using Blueprint without Claude Code”Delete .claude/ and global-claude-md.example, and remove the
@.claude/operating-rules.md import line from CLAUDE.md. Keep AGENTS.md, and keep
the root CLAUDE.md as well: scripts/gate-yield.py --check-fastpath, which CI runs,
reads the fast-paths table from it and fails when the file is missing. The nested
scripts/CLAUDE.md and ci/CLAUDE.md are plain Markdown guides for writing gates and
CI jobs; keep them as reading material.
Not built yet
Section titled “Not built yet”A per-agent adapter layer (a Codex equivalent of the hooks, skills and review agents)
waits until a second agent is actually in use. Hooks, agent tools: frontmatter and
skill invocation are Claude Code mechanics with no one-to-one equivalent elsewhere.