Stick the following into a CLAUDE.md or AGENTS.md somewhere.

Issue Tracking with Beads

This project uses Beads for issue tracking instead of markdown todos. Key commands:

bd list                    # List all issues
bd ready                   # Show issues ready to work (no blockers)
bd show <issue-id>         # Show issue details
bd update <issue-id> --status in_progress
bd close <issue-id>
bd dep tree <issue-id>     # Visualize dependencies

Current epics are tracked with dependencies. Check bd list to see all issues and bd ready for unblocked work.

Prioritizing Work

Always start by checking for in-progress work:

1. Check for in-progress epics: Run bd list --status in_progress to see which epics are currently being worked on
2. Focus on epic tasks: If an epic is in-progress, prioritize tasks that block that epic
3. Check ready work: Use bd ready to see unblocked tasks, then choose tasks related to in-progress epics
4. Mark epics in-progress: When starting work on an epic's tasks, mark the epic as in_progress if not already marked

Task Workflow

When working on individual issues, follow this workflow:

1. Start work: bd update <issue-id> --status in_progress (for both epics and tasks)
2. Complete the work: Implement the feature/fix
3. Close the issue: bd close <issue-id>
4. Commit immediately: Create a git commit after closing each issue with:
   • Summary of completed issue(s) in the commit message
   • List of changes made
   • Reference to issue IDs that were closed

This ensures a clean audit trail where commits map directly to completed work items.

Discovering Issues During Development

When bugs, inconsistencies, or improvements are discovered during development:

1. Create an issue immediately: Use bd create to document the problem as soon as it's discovered
2. Err on the side of creating issues: Better to have tracked issues than forgotten problems
3. Link to relevant epics: Use bd dep add <epic-id> <issue-id> to link the new issue to related epics
4. Don't let issues block current work: If the discovered issue isn't critical, create it and continue with the current task
5. Document what was found: Include enough detail in the issue description for someone else (or future you) to understand the problem

Examples of when to create issues:

• User testing reveals unexpected behavior
• Inconsistent UI/UX patterns across screens
• Missing functionality that should be added for completeness
• Technical debt or code that needs refactoring
• Documentation that needs updating

Git Workflow

⚠️ NEVER make code changes directly on main. All work happens on branches.

BEFORE making any code changes:

1. Check current state - Run git status and git branch --show-current

   • If there's uncommitted work or you're not on main, ask for instructions

2. Determine the branch strategy:

   • For epic subtasks: Check if an epic branch already exists (format: <epic-id>/<description>). If so, switch to it. If not, create it.
   • For standalone issues (tasks/bugs not part of an epic): Create a branch with format <issue-id>/<description>

   Examples:

   • Epic branch: 64o/repo-setup
   • Standalone issue branch: 1n7/package-installation

3. Create/switch to the branch, then begin implementation

4. Work on the branch - All subtasks of an epic happen on the same epic branch

5. Await approval - When epic/issue is complete, wait for explicit confirmation before merging to main

Whenever you create new branches or worktrees, hold off on merging them until you get my explicit approval.

Working with Beads Epics and Dependencies

When breaking down epics into subtasks, follow this pattern:

Correct Approach:

• Epics should DEPEND ON their subtasks (epic is blocked by subtasks)
• Subtasks should NOT depend on the epic
• Use this command pattern:

  # Create subtask without epic dependency
  bd create "Subtask Title" --priority P1 --type task --description "..."
  
  # Then make epic depend on subtask
  bd dep add <epic-id> <subtask-id>

Dependency Direction:

• bd dep add A B means "A depends on B" (B blocks A)
• For epic/subtask relationship: bd dep add epic subtask
• This makes subtasks show up in bd ready when they have no other blockers

Example:

# Wrong: subtask depends on epic (subtask won't show in bd ready)
bd create "Install SQLite" --deps "blocks:epic-id"  # ❌

# Right: create subtask, then make epic depend on it
bd create "Install SQLite" --priority P1 --type task
bd dep add epic-id subtask-id  # ✅