Standardize AGENTS.md with CLAUDE.md symlink

[javdl]

Make AGENTS.md the primary file and CLAUDE.md a symlink pointing to it.

🤖 Generated with Claude Code

[claude]

Pull Request Review: Standardize AGENTS.md with CLAUDE.md symlink

Summary

This PR attempts to standardize on AGENTS.md as the primary instructions file by making CLAUDE.md a symlink pointing to it. However, there are several critical issues that need to be addressed.

---

Critical Issues

1. Incorrect Implementation - Symlink Direction is Backwards

The PR creates CLAUDE.md as a symlink pointing to AGENTS.md, but the content was moved into AGENTS.md. This means:

• AGENTS.md now contains the full CLAUDE.md content (189 lines)
• The original AGENTS.md content (84 lines of Beads-focused workflow) was completely replaced
• CLAUDE.md becomes a symlink to AGENTS.md

Problem: This loses the original AGENTS.md content entirely. If the goal is to make AGENTS.md primary, you should:

1. Keep the combined/merged content in AGENTS.md
2. Make CLAUDE.md symlink to it

But you need to merge the unique content from both files, not just replace one with the other.

2. Content Loss - Original AGENTS.md Workflow Missing

The original AGENTS.md had valuable workflow-specific content that's now lost:

• Session start/end procedures ("Landing the Plane")
• Explicit rules about not using bd edit
• Quality checks workflow
• More concise Beads command reference

The new AGENTS.md only has the detailed project documentation from CLAUDE.md but lacks the concise workflow guidance that AGENTS.md provided.

3. Beads Sync State Should Not Be Committed

The PR includes changes to .beads/sync-state.json:

-  "failure_count": 2,
+  "failure_count": 3,
+  "needs_manual_sync": true,

This file tracks local sync failures and should be in .gitignore. It's transient state, not project configuration.

---

Recommendations

Must Fix Before Merge

1. Merge Content Properly

   • Combine the unique workflow sections from original AGENTS.md with the detailed project docs from CLAUDE.md
   • Consider structure: start with project overview (from CLAUDE.md), then add workflow/Beads instructions (from AGENTS.md)
   • Keep both the detailed Beads documentation AND the concise workflow steps

2. Verify Symlink Direction

   • Confirm that CLAUDE.md -> AGENTS.md is the intended direction
   • Test that tools reading CLAUDE.md will follow the symlink correctly

3. Add .beads/sync-state.json to .gitignore

   echo '.beads/sync-state.json' >> .gitignore

   Then remove it from this commit:

   git restore --staged .beads/sync-state.json

Suggested Approach

Here's what I'd recommend for the file merge:

# AGENTS.md (or CLAUDE.md - whichever is the primary file)

[Keep full CLAUDE.md project overview and documentation sections]

## Working with This Repository - AI Agent Workflow

[Insert the concise workflow sections from original AGENTS.md]

### Session Start
1. Run `bd ready` to see unblocked tasks
...

### Session End (Landing the Plane)
**Critical: Work is NOT complete until `git push` succeeds.**
...

[Keep the existing detailed "Issue Tracking with Beads" section from CLAUDE.md]

---

Good Aspects

✅ The idea to standardize on one file is good - reduces duplication
✅ Symlink approach allows tools expecting either filename to work
✅ Commit message clearly explains intent

---

Security & Performance

• No security concerns with this change
• Symlinks work well in Git but verify your deployment pipeline supports them
• No performance impact

---

Next Steps

1. Recover original AGENTS.md content from git history
2. Properly merge both files' unique content
3. Gitignore .beads/sync-state.json
4. Update commit to exclude sync-state changes
5. Consider adding a comment at top of symlink target explaining the setup

Let me know if you'd like help with the content merge!