Project Instructions for AI Agents #

This file provides instructions and context for AI coding agents working on this project.

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

Architecture in one line: issues live in a local Dolt DB; sync uses refs/dolt/data on your git remote; .beads/issues.jsonl is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns.

Session Completion #

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

MANDATORY WORKFLOW:

File issues for remaining work - Create issues for anything that needs follow-up
Run quality gates (if code changed) - Tests, linters, builds
Update issue status - Close finished work, update in-progress items

PUSH TO REMOTE - This is MANDATORY:

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

Clean up - Clear stashes, prune remote branches
Verify - All changes committed AND pushed
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

Build & Test #

Add your build and test commands here

# Example:
# npm install
# npm test

Architecture Overview #

Add a brief overview of your project architecture

Conventions & Patterns #

Add your project-specific conventions here