Intent / The Why
Claude Code (Anthropic CLI) is being added as a first-class swarm node alongside Antigravity and Gemini CLI. Unlike Gemini CLI — which the repo wires via .gemini/settings.json to auto-load AGENTS.md — Claude Code has no configuration in this repo, so agents spawned in it boot with no awareness of AGENTS.md. This means the Pre-Commit Hard Gates (§3), Memory Core Protocol (§4), Visual Verification Protocol (§8), and Swarm Fat Ticket Protocol (§9) are all missing from the session-zero context.
Diagnostic test: open a Code tab in this repo and ask "what are your pre-commit gates?" — the agent searches the codebase with Glob/Grep instead of reciting Section 3 from context. That is the tell that AGENTS.md is not wired.
The Architectural Reality
Per the Claude Code memory documentation (code.claude.com/docs/en/memory.md):
- Both
./CLAUDE.md and ./.claude/CLAUDE.md are auto-loaded at session start, with identical precedence. Either works.
- Nested subdirectory
CLAUDE.md files are loaded on-demand (when Claude reads files in the subdirectory), not at boot.
- Precedence order (low→high): managed policy →
~/.claude/CLAUDE.md → project CLAUDE.md/.claude/CLAUDE.md → CLAUDE.local.md → on-demand subdirectory files.
Claude Code also natively injects model identity (name, model ID, family, knowledge cutoff) into every session's system prompt — so agents know they are e.g. claude-opus-4-7[1m] without external scaffolding. This is relevant for correctly populating the model field when calling Memory Core add_memory.
Separately, Claude Code uses git worktrees for isolated agent branches, landing them under .claude/worktrees/<name>/. These checkouts are per-branch, ephemeral, and must not be tracked in the parent repo — otherwise git status on the main checkout shows every worktree as nested untracked files.
The repo already has an un-committed .claude/skills/ directory in the main working tree containing symlinks to ../../.agent/skills/* (covering create-skill, debugging-antigravity, ideation-sandbox, neural-link, pr-review, pull-request, self-repair, tech-debt-radar, ticket-intake, unit-test, whitebox-e2e). These should be committed so Claude Code's skill discovery picks up the same swarm skills Gemini CLI sees via .agent/skills/.
Scope (Single Atomic Commit — Standard Request, not Epic)
Three changes, one PR, one commit:
.claude/CLAUDE.md → ../AGENTS.md (symlink). Placed inside .claude/ rather than repo root — keeps root uncluttered and documented-equivalent per Claude Code docs. AGENTS.md is ~22KB, so every Claude Code session pays ~22KB of cache overhead per turn in exchange for the gates being always-present.
.gitignore addition: .claude/worktrees/ — prevents Claude Code's per-agent worktree checkouts from polluting git status in the main checkout.
Commit .claude/skills/* symlinks to ../../.agent/skills/* — promotes the ten existing local symlinks to tracked repo assets so Claude Code has feature parity with Gemini CLI's skill library.
Avoided Gold Standards / Traps
- Rejected: place CLAUDE.md at repo root. Tidier inside
.claude/; identical auto-load behavior per the docs. Root already has AGENTS.md + AGENTS_STARTUP.md — adding a root-level CLAUDE.md would mislead contributors into thinking it's a separate document.
- Rejected: copy
AGENTS.md content into a standalone CLAUDE.md. Creates drift. Symlink guarantees single source of truth.
- Rejected: the
@AGENTS.md import directive (Claude Code's memory-file include syntax). Valid, but adds indirection without benefit when content is literally identical. Reserve for future if Claude-specific additions become necessary.
- Rejected: commit
.claude/worktrees/. Tracking transient per-agent local state would pollute git history with branch ephemera.
- Rejected: duplicate skill files into
.claude/skills/. Symlinks preserve a single source under .agent/skills/, keeping Claude and Gemini skill libraries in lock-step.
- Rejected: adding a user-level
~/.claude/CLAUDE.md for model self-identification. Claude Code injects model identity (name, ID, family, knowledge cutoff) into every session's system prompt natively. The Gemini.md-style workaround used for Antigravity/Gemini CLI is unnecessary here and would add contributor-experience friction with no benefit.
Verification
After merge to dev, open a fresh Code tab in a cloned checkout and ask: "what are your pre-commit gates?" — expected: Section 3 recital with no codebase search. Cross-check via Windows contributor: symlinks in git survive git clone on Windows as symlinks when core.symlinks=true; otherwise they appear as text files containing the target path (acceptable fallback since content is still AGENTS.md).
Follow-ups (Out of Scope Here — Referenced for Graph Connectivity)
- Optimize
AGENTS.md / AGENTS_STARTUP.md startup-cache footprint (~47KB combined per session).
- Optimize MCP tool descriptions for token economy.
- Optimize turn-based Memory Core memory serialization overhead.
These exist as separate known concerns and are not addressed by this ticket.
Origin Session ID: f018be49-cbf9-4f99-9119-2510fc5bb8d8
Intent / The Why
Claude Code (Anthropic CLI) is being added as a first-class swarm node alongside Antigravity and Gemini CLI. Unlike Gemini CLI — which the repo wires via
.gemini/settings.jsonto auto-loadAGENTS.md— Claude Code has no configuration in this repo, so agents spawned in it boot with no awareness ofAGENTS.md. This means the Pre-Commit Hard Gates (§3), Memory Core Protocol (§4), Visual Verification Protocol (§8), and Swarm Fat Ticket Protocol (§9) are all missing from the session-zero context.Diagnostic test: open a Code tab in this repo and ask "what are your pre-commit gates?" — the agent searches the codebase with Glob/Grep instead of reciting Section 3 from context. That is the tell that
AGENTS.mdis not wired.The Architectural Reality
Per the Claude Code memory documentation (code.claude.com/docs/en/memory.md):
./CLAUDE.mdand./.claude/CLAUDE.mdare auto-loaded at session start, with identical precedence. Either works.CLAUDE.mdfiles are loaded on-demand (when Claude reads files in the subdirectory), not at boot.~/.claude/CLAUDE.md→ projectCLAUDE.md/.claude/CLAUDE.md→CLAUDE.local.md→ on-demand subdirectory files.Claude Code also natively injects model identity (name, model ID, family, knowledge cutoff) into every session's system prompt — so agents know they are e.g.
claude-opus-4-7[1m]without external scaffolding. This is relevant for correctly populating themodelfield when calling Memory Coreadd_memory.Separately, Claude Code uses git worktrees for isolated agent branches, landing them under
.claude/worktrees/<name>/. These checkouts are per-branch, ephemeral, and must not be tracked in the parent repo — otherwisegit statuson the main checkout shows every worktree as nested untracked files.The repo already has an un-committed
.claude/skills/directory in the main working tree containing symlinks to../../.agent/skills/*(coveringcreate-skill,debugging-antigravity,ideation-sandbox,neural-link,pr-review,pull-request,self-repair,tech-debt-radar,ticket-intake,unit-test,whitebox-e2e). These should be committed so Claude Code's skill discovery picks up the same swarm skills Gemini CLI sees via.agent/skills/.Scope (Single Atomic Commit — Standard Request, not Epic)
Three changes, one PR, one commit:
.claude/CLAUDE.md→../AGENTS.md(symlink). Placed inside.claude/rather than repo root — keeps root uncluttered and documented-equivalent per Claude Code docs.AGENTS.mdis ~22KB, so every Claude Code session pays ~22KB of cache overhead per turn in exchange for the gates being always-present..gitignoreaddition:.claude/worktrees/— prevents Claude Code's per-agent worktree checkouts from polluting git status in the main checkout.Commit
.claude/skills/*symlinks to../../.agent/skills/*— promotes the ten existing local symlinks to tracked repo assets so Claude Code has feature parity with Gemini CLI's skill library.Avoided Gold Standards / Traps
.claude/; identical auto-load behavior per the docs. Root already hasAGENTS.md+AGENTS_STARTUP.md— adding a root-level CLAUDE.md would mislead contributors into thinking it's a separate document.AGENTS.mdcontent into a standalone CLAUDE.md. Creates drift. Symlink guarantees single source of truth.@AGENTS.mdimport directive (Claude Code's memory-file include syntax). Valid, but adds indirection without benefit when content is literally identical. Reserve for future if Claude-specific additions become necessary..claude/worktrees/. Tracking transient per-agent local state would pollute git history with branch ephemera..claude/skills/. Symlinks preserve a single source under.agent/skills/, keeping Claude and Gemini skill libraries in lock-step.~/.claude/CLAUDE.mdfor model self-identification. Claude Code injects model identity (name, ID, family, knowledge cutoff) into every session's system prompt natively. The Gemini.md-style workaround used for Antigravity/Gemini CLI is unnecessary here and would add contributor-experience friction with no benefit.Verification
After merge to
dev, open a fresh Code tab in a cloned checkout and ask: "what are your pre-commit gates?" — expected: Section 3 recital with no codebase search. Cross-check via Windows contributor: symlinks in git survive git clone on Windows as symlinks whencore.symlinks=true; otherwise they appear as text files containing the target path (acceptable fallback since content is still AGENTS.md).Follow-ups (Out of Scope Here — Referenced for Graph Connectivity)
AGENTS.md/AGENTS_STARTUP.mdstartup-cache footprint (~47KB combined per session).These exist as separate known concerns and are not addressed by this ticket.
Origin Session ID: f018be49-cbf9-4f99-9119-2510fc5bb8d8