Add Beads issue tracking system

[javdl]

• Add Beads instructions to CLAUDE.md with installation and usage guide
• Create AGENTS.md with agent-specific task tracking workflow
• Create .beads/ directory for issue tracker storage
• Update .gitignore to exclude Beads SQLite cache files

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.

[claude]

Pull Request Review: Add Beads Issue Tracking System

Summary

This PR adds Beads issue tracking integration to the project with documentation in both CLAUDE.md and a new AGENTS.md file. Overall, this is a well-structured addition that introduces a Git-backed issue tracking system designed for AI agent workflows.

---

✅ Strengths

1. Clear Documentation Structure

   • Comprehensive installation instructions covering multiple platforms (macOS/Linux, Homebrew, npm)
   • Well-organized command reference with practical examples
   • Excellent separation of concerns: CLAUDE.md for general project info, AGENTS.md for agent-specific workflows

2. Good .gitignore Practices

   • Correctly excludes SQLite cache files (.beads/*.db, .beads/*.db-*)
   • Includes helpful comment explaining what should/shouldn't be tracked
   • Follows existing .gitignore patterns in the file

3. Thoughtful Agent Workflow

   • "Landing the Plane" section in AGENTS.md is excellent - provides clear session end checklist
   • Emphasis on git push requirement is critical for distributed workflows
   • Warning about bd edit shows awareness of interactive tool limitations in automated contexts

4. No Code Changes

   • Zero risk to existing functionality - purely additive documentation

---

🔍 Issues & Recommendations

1. Directory Initialization Not Complete

The .beads/.gitkeep file mentions running bd init, but the directory doesn't contain issues.jsonl.

Recommendation: Either:

• Run bd init to create the issues.jsonl file and commit it (even if empty), OR
• Update documentation to clarify that bd init must be run by the first user/agent

2. Duplicate Content in CLAUDE.md and AGENTS.md

Both files contain nearly identical Beads documentation. This violates DRY principles and creates maintenance burden.

Recommendation:

# In CLAUDE.md
## Issue Tracking with Beads
This project uses Beads for issue tracking. See [AGENTS.md](./AGENTS.md) for complete agent workflow documentation.

Quick reference:
- Installation: `brew install steveyegge/beads/bd`
- Ready tasks: `bd ready`
- Create issue: `bd create "Title" -p 1`
- Full docs: [Beads GitHub](https://github.com/steveyegge/beads)

Keep detailed workflow, rules, and session management in AGENTS.md only.

3. Missing Context on When to Use Beads

Documentation doesn't explain when to use Beads vs. GitHub Issues.

Recommendation: Add a section:

### Beads vs. GitHub Issues
- **Use Beads for**: Agent work tracking, temporary tasks, session management
- **Use GitHub Issues for**: User-reported bugs, feature requests, public roadmap items

4. No Example Issues or Workflow Demo

Would be helpful to show what an actual Beads workflow looks like.

Recommendation: Consider adding a "Example Workflow" section in AGENTS.md:

# Example: Implementing a new feature
$ bd create "Add GraphQL playground embed" -p 2
Created issue bd-abc

$ bd update bd-abc --status in_progress
$ # ... do work ...
$ git commit -m "Add GraphQL playground component (bd-abc)"
$ bd close bd-abc --reason "Implemented and tested"
$ bd sync && git push

5. Beads Installation Verification Missing

No guidance on how to verify Beads is installed correctly.

Recommendation: Add to installation section:

# Verify installation
bd --version

6. No Mention of Beads Requirements

The PR description and docs don't mention system requirements (Node.js, Git, etc.).

Recommendation: Add prerequisites section in AGENTS.md:

### Prerequisites
- Git 2.0+
- Node.js (if installing via npm)
- Unix-like environment (macOS/Linux/WSL)

---

🔒 Security Considerations

✅ No security concerns - this is documentation-only with appropriate .gitignore rules.

---

🧪 Testing Considerations

✅ No tests needed - documentation changes only.

However, consider:

• Manually verifying bd init works in this project
• Testing the workflow with an actual agent session
• Checking that .gitignore patterns work correctly with git status

---

📊 Performance Considerations

✅ No performance impact - documentation only.

Note: Beads uses SQLite which is fast, but if issues.jsonl grows very large (thousands of issues), consider periodic archiving strategies.

---

🎯 Overall Assessment

Verdict: ✅ Approve with minor suggestions

This is a solid foundation for integrating Beads into the project. The documentation is clear and the .gitignore configuration is correct. The main improvements needed are:

1. Critical: Initialize the .beads/ directory properly or document the initialization step
2. Important: Reduce duplication between CLAUDE.md and AGENTS.md
3. Nice to have: Add example workflows and clearer context on when to use Beads

The PR is safe to merge as-is, but addressing the duplication and initialization issues would make it production-ready.

---

📝 Suggested Next Steps

If you choose to iterate:

1. Run bd init and commit the resulting issues.jsonl
2. Refactor CLAUDE.md to reference AGENTS.md instead of duplicating content
3. Add example workflow section to AGENTS.md
4. Add prerequisites and verification steps

Otherwise, this can merge and be refined in follow-up PRs.

---

Great work on integrating a modern issue tracking system designed for AI workflows! 🎉