Agent Instructions

This project uses bd (beads) for issue tracking. Run bd onboard to get started.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work atomically
bd close <id>         # Complete work
bd dolt push          # Push beads data to remote

Non-Interactive Shell Commands

ALWAYS use non-interactive flags with file operations to avoid hanging on confirmation prompts.

Shell commands like cp, mv, and rm may be aliased to include -i (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.

Use these forms instead:

# Force overwrite without prompting
cp -f source dest           # NOT: cp source dest
mv -f source dest           # NOT: mv source dest
rm -f file                  # NOT: rm file

# For recursive operations
rm -rf directory            # NOT: rm -r directory
cp -rf source dest          # NOT: cp -r source dest

Other commands that may prompt:

• scp - use -o BatchMode=yes for non-interactive
• ssh - use -o BatchMode=yes to fail instead of prompting
• apt-get - use -y flag
• brew - use HOMEBREW_NO_AUTO_UPDATE=1 env var

Beads Issue Tracker

This project uses bd (beads) for issue tracking. Run bd prime to see full workflow context and commands.

Quick Reference

bd ready              # Find available work
bd show <id>          # View issue details
bd update <id> --claim  # Claim work
bd close <id>         # Complete work

Rules

• Use bd for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists
• Run bd prime for detailed command reference and session close protocol
• Use bd remember for persistent knowledge — do NOT use MEMORY.md files

Triage Markers

An open bead is not automatically workable. Status is the whole marker — titles NEVER carry a prefix. needs-plan is in the wip category, so a marked bead never appears in bd ready.

A ◇ bead does not name its own next skill; you pick by reading it. /investigate writes an Investigation: path into --notes and leaves the bead needs-plan — a proven cause is not a plan, and an Investigation: line is not a plan reference. /plan writes a Plan: path and flips the bead to open. Never debug, plan or claim a ◇ bead by hand.

New beads default to needs-plan. One exception: a mechanical refactor whose title is the whole spec may be open with no path. Everything else that is open must carry a Plan:/Slice:/Master: path, or the marker is lying.

bd create "Landing page hero flickers on load" -t bug -p 2 --deps discovered-from:<current-id> --json
bd update <id> --status needs-plan   # bd create takes no --status
bd list -s needs-plan                # the triage queue
# drift: open beads with no plan path — an Investigation: line does not count
bd list -s open --json | jq -r '.[]|select((.notes//"")|test("(Plan|Slice|Master):\\s*/")|not)|.id'

Status and the plan path move together. A bead whose plan exists must never stay needs-plan; an open bead with no plan path is broken unless it is the refactor case above.

Session Completion

When ending a work session, you MUST complete ALL steps below. Work is NOT complete until git push succeeds.

MANDATORY WORKFLOW:

1. File issues for remaining work - Create issues for anything that needs follow-up
2. Run quality gates (if code changed) - Tests, linters, builds
3. Update issue status - Close finished work, update in-progress items
4. PUSH TO REMOTE - This is MANDATORY:

   git pull --rebase
   bd dolt push
   git push
   git status  # MUST show "up to date with origin"
   

5. Clean up - Clear stashes, prune remote branches
6. Verify - All changes committed AND pushed
7. Hand off - Provide context for next session

CRITICAL RULES:

• Work is NOT complete until git push succeeds
• NEVER stop before pushing - that leaves work stranded locally
• NEVER say “ready to push when you are” - YOU must push
• If push fails, resolve and retry until it succeeds