Symlink CLAUDE.md to AGENTS.md

[urda]

Summary

• Add CLAUDE.md -> AGENTS.md as a symlink so Claude Code picks up the same repository guidelines already documented for agents.
• Avoids maintaining two copies of build/test/coding-style guidance that would drift out of sync.
• Fix hanging *** spotted in AGENTS.md.

Test plan

• Update local repo to commit in PR to "create" symlink.
  • Tested OK.
• Start a claude session.
  • Tested OK.
• Invoke /context and confirm we see CLAUDE.md in context.
  • Tested OK - CLAUDE.md: 2.4k tokens.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed August 4, 2026, 9:31 PM ET / August 5, 2026, 01:31 UTC.

ClawSweeper review

What this changes

The PR adds a CLAUDE.md symlink to the repository’s existing agent guidance and removes an accidental trailing marker from that guidance.

Merge readiness

⚠️ Ready for maintainer review - 2 items remain

Keep open for ordinary maintainer review: the focused guidance change is correct and directly proven, but the branch should be refreshed against current main and receive a clean check run.

Priority: P3
Reviewed head: 250ffaa48b24ddaca27dfeba500bb5a2b51ce600

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, low-risk documentation integration with direct after-fix proof, pending a clean check run against current main.
Proof confidence	🦞 diamond lobster (5/6) ✨ media proof bonus	Sufficient (screenshot): The PR body includes after-fix Claude Code context output showing that CLAUDE.md was loaded.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Verified	Sufficient (screenshot): The PR body includes after-fix Claude Code context output showing that CLAUDE.md was loaded.
Evidence reviewed	4 items	Real Git symlink: The proposed file is mode 120000 and contains ./AGENTS.md, so it is a symlink rather than a copied second guidance file. Focused cleanup: The second commit only removes the stray trailing marker from the provider-data guidance line. Current-main merge compatibility: The PR merge base is its stated base, and the checked-out current-main three-way merge has no conflicts.
Findings	None	None.
Security	None	None.

How this fits together

Repository guidance files tell coding agents how to build, test, and modify CodexBar. Claude Code consumes CLAUDE.md, while other coding agents use AGENTS.md; the symlink gives both one shared source of instructions.

flowchart LR
  A[Repository guidance] --> B[AGENTS.md]
  B --> C[CLAUDE.md symlink]
  C --> D[Claude Code]
  B --> E[Other coding agents]
  D --> F[Consistent workflow]
  E --> F

Loading

Before merge

• Resolve merge risk (P1) - The branch predates current main and its Linux ARM check is still failing; the discussion links that failure to the separate test-race work in Fix ETXTBSY race in claude-swap CLI card test #2644, but a refreshed clean run is still needed before merge.
• Complete next step (P2) - A maintainer should review the refreshed branch and its clean current-base checks; there is no concrete automated repair to dispatch.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Patch size	2 files affected; 2 added, 1 removed	The patch is tightly constrained to repository guidance and its shared entrypoint.

Merge-risk options

Maintainer options:

1. Decide the mitigation before merge
   Merge a refreshed, clean-current-main branch that keeps agent guidance in one canonical file through the Git symlink.
2. Pause or close
   Do not merge this PR until maintainers decide whether the risk is worth taking.

Technical review

Best possible solution:

Merge a refreshed, clean-current-main branch that keeps agent guidance in one canonical file through the Git symlink.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a repository-guidance integration, and the PR body provides after-fix Claude Code context output showing that CLAUDE.md was loaded.

Is this the best way to solve the issue?

Yes: a Git symlink is the narrowest maintainable way to make Claude Code consume the existing guidance without allowing duplicated files to drift.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 8c37c20a43d6.

Labels

Label justifications:

• P3: This is a low-risk repository-guidance cleanup with no runtime product behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR body includes after-fix Claude Code context output showing that CLAUDE.md was loaded.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix Claude Code context output showing that CLAUDE.md was loaded.
• proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR body includes after-fix Claude Code context output showing that CLAUDE.md was loaded.

Evidence

What I checked:

• Real Git symlink: The proposed file is mode 120000 and contains ./AGENTS.md, so it is a symlink rather than a copied second guidance file. (CLAUDE.md:1, 6da510ea6a23)
• Focused cleanup: The second commit only removes the stray trailing marker from the provider-data guidance line. (AGENTS.md:46, 250ffaa48b24)
• Current-main merge compatibility: The PR merge base is its stated base, and the checked-out current-main three-way merge has no conflicts. (8c37c20a43d6)
• Guidance-file provenance: Current main attributes the relevant existing guidance section to the v0.47.0 documentation update, making Peter Steinberger the clearest current-history routing candidate. (AGENTS.md:46, 6a16c23313a7)

Likely related people:

• Peter Steinberger: Current main attributes the relevant AGENTS.md lines to the v0.47.0 documentation update. (role: recent guidance-file author; confidence: high; commits: 6a16c23313a7; files: AGENTS.md)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Refresh the branch against current main after the independent test-race work is available, then confirm a clean check run.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

History

Review history (5 earlier review cycles)

• reviewed 2026-08-04T06:49:57.515Z sha 250ffaa :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T07:12:25.664Z sha 250ffaa :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T15:03:12.470Z sha 250ffaa :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T16:38:28.820Z sha 250ffaa :: needs maintainer review before merge. :: none
• reviewed 2026-08-04T19:58:55.193Z sha 250ffaa :: needs maintainer review before merge. :: none

[urda]

Note for reviewers: the failing build-linux-cli (linux-arm64) check here is a
pre-existing flake, not this diff. This PR changes two text files, and neither is
compiled, linted, or tested.

Evidence that it is environmental:

• linux-x64 passed in the same run, on the same commit.
• linux-arm64 passed on the base commit 15a855a21.
• Failing job: https://github.com/steipete/CodexBar/actions/runs/30885238832/job/91914882363

Root cause and fix: #2644. CLICardsClaudeSwapTests writes a shell script and
executes it immediately, which races with concurrent Process.run() forks under
swift test --parallel and fails with ETXTBSY. Reproduced on Linux arm64 at
112 failures in 600 attempts, and 0 in 600 with the fix.

I cannot rerun the job, since that needs admin rights on this repository. Once
#2644 merges I will rebase this branch onto main so the checks rerun clean.

[urda]

I think a rebase after #2644 lands will result in less flakes.