Skip to content

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.

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 by make pre-push-checks and 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, protected main and Pipelines must succeed apply to every change, whoever or whatever wrote it.
  • 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.json denies git push --force / -f, glab mr merge, and reading .env, .env.* and key files. It is the only mechanical enforcement of two of AGENTS.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 (protected main and 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, /kickoff and the rest are Claude Code skill files. Another agent can read them as documentation, but nothing invokes them.
  • Review agents. architect, security-review, completeness-check and 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.

Per How Claude remembers your project (checked 2026-10-17):

  • By default, Claude Code reads AGENTS.md by itself only when there is no CLAUDE.md in the working directory or above it. Blueprint has a CLAUDE.md, so the @AGENTS.md import 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.md into AGENTS.md changes where they live, not what a session loads.

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.

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.