#3346 repo init --tool claude writes a CLAUDE.md that shadows an existing AGENTS.md

Summary

swamp init / swamp repo init with --tool claude (also the default when --tool is omitted) always scaffolds and maintains a root CLAUDE.md. The built-in claude tool config hard-codes instructionsFile: "CLAUDE.md". Now that Claude Code reads AGENTS.md natively, this creates a duplicate instructions file and — worse — causes Claude Code to ignore the repository's existing AGENTS.md.

Environment

• swamp 20261013.032621.0-sha.fc312a85 (macOS arm64)

Steps to reproduce

1. mkdir demo && cd demo && git init
2. Create an AGENTS.md (repository already standardised on the shared standard)
3. swamp init --tool claude --no-vault
4. ls -> a CLAUDE.md is created alongside AGENTS.md

Current behaviour

• Built-in claude tool config: skillsDir: ".claude/skills", instructionsFile: "CLAUDE.md", instructionsMode: "shared".
• Verified: in an empty git repo, swamp init --tool claude --no-vault creates CLAUDE.md (6113 bytes, carrying the <!-- BEGIN swamp managed section --> marker).
• claude is the default tool when --tool is omitted.
• This is inconsistent with the other agent built-ins (amp, opencode, codex, copilot, pi, antigravity), which all use AGENTS.md.

Expected behaviour

For a repository that already has an AGENTS.md, --tool claude should use that existing AGENTS.md (or require explicit opt-in) instead of unconditionally creating a duplicate CLAUDE.md.

Impact

Per Anthropic's Claude Code memory docs (https://code.claude.com/docs/en/memory#agents-md), Claude Code reads AGENTS.md as project instructions when there is no CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in the working directory or above it (requires Claude Code v2.1.277 or later). When a CLAUDE.md IS present, Claude Code reads CLAUDE.md only and does not read AGENTS.md. So swamp's claude scaffolding causes the repository's canonical AGENTS.md to be ignored by Claude, and leaves a second instructions file that can drift out of sync.

Why this is a bug rather than a feature

The claude tool's purpose is to give the agent the project rules. Now that Claude Code natively reads the shared AGENTS.md, unconditionally emitting CLAUDE.md produces an incorrect result (a duplicate that shadows the canonical file) rather than adding a missing capability. This matches earlier init/upgrade tool bugs: #1754 (repo init/upgrade --tool kiro references the wrong skills path) and #3322 (repo init --help omits built-in tools).

Proposed fix

• Prefer an existing AGENTS.md for the built-in claude tool (shared instructions mode); fall back to CLAUDE.md only when no AGENTS.md exists.
• Optionally add an explicit override, e.g. swamp init --tool claude --instructions-file AGENTS.md.
• Make swamp repo upgrade / swamp update idempotent so it does not (re)create CLAUDE.md in repositories that have adopted AGENTS.md.

Workarounds

There is no CLI option to make the built-in claude tool target AGENTS.md: swamp init exposes no instructionsFile option, and a custom tool cannot shadow the built-in because validateCustomToolName rejects names that collide with built-ins (claude). The following workarounds were verified against swamp 20261013.032621.0-sha.fc312a85.

swamp repo upgrade behaviour (important for any workaround)

• If CLAUDE.md is missing while claude is enrolled, swamp repo upgrade recreates it (fresh 6113-byte managed section). Deleting CLAUDE.md is therefore not durable on its own.
• Content placed outside the <!-- BEGIN/END swamp managed section --> markers is preserved across swamp repo upgrade (reported as Instructions: unchanged).
• swamp repo upgrade --tool <tool> replaces the enrolled tool list. Dropping a tool warns that its files (e.g. .claude/, .agents/skills/) are left behind and must be removed by hand.

Options

1. Keep --tool claude and append @AGENTS.md to CLAUDE.md, after the managed block. Claude reads CLAUDE.md and imports AGENTS.md; survives swamp repo upgrade. (Duplicates swamp rules if the repo's AGENTS.md also carries a swamp managed section.)
2. Have Claude read both files via the Project instructions setting (claude-md-and-agents-md) — no file edits needed.
3. Delete CLAUDE.md (stopgap). Claude falls back to AGENTS.md, but the next swamp repo upgrade recreates the file.
4. Stop enrolling claude (swamp repo upgrade --tool opencode, etc.) and delete CLAUDE.md. Durable, but the AGENTS.md-based tools sync skills to .agents/skills, which Claude Code does not read, so a custom tool (skillsDir .claude/skills, instructionsFile AGENTS.md) would be needed to keep swamp skills working.

References

• Anthropic, "How Claude remembers your project" — AGENTS.md resolution table and the v2.1.277 requirement: https://code.claude.com/docs/en/memory#agents-md
• Same doc, "When AGENTS.md support is unavailable": https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable
• Same doc, troubleshooting "My AGENTS.md isn't loading": https://code.claude.com/docs/en/memory#my-agentsmd-isnt-loading

Notes

Reading AGENTS.md requires Claude Code v2.1.277 or later. Before v2.1.281, some sessions — notably those on Amazon Bedrock or with telemetry disabled — read CLAUDE.md files only (https://code.claude.com/docs/en/memory#when-agents-md-support-is-unavailable); the documented remedy there is to update Claude Code, or to import AGENTS.md from a CLAUDE.md. Any fix should preserve a supported path for those environments.