improvise/AGENTS.md

• Always use tests to demonstrate the existence of a bug before fixing the bug.
  • If you suspect that a bug exists, use a test to demonstrate it first:
    • prefer unit tests testing a small amount of code to integration or e2e tests
• Option<...> or Result<...> are fine but should not be present in the majority of the code.
• Similarly, code managing Box<...> or RC<...>, etc. for containers pointing to heap data should be split from logic
• @context/repo-map.md is your "road map" for the repository. use it to reduce exploration and keep it updated.
• @context/design-principles.md is also important for keeping the repository consistent.
• prefer merges to rebasing.
• always start responses with bananaS!
• there is a prolog MCP available, load a session from kb at the root of the repository at the beginning of every session and save structured facts to the knowledge base as you go. (cover work done, interesting locations in the codebase, important decisions, etc.)
• query the knowledge base as needed and use Prolog reasoning when it makes sense.
• Prolog should be used as a design tool to reason about the code and the implementation of tickets and to persist a formal model of it.

Agent Instructions

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

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 (the exception being that you must maintain context/design-principles.md and context/repo-map.md)
• Run bd prime for detailed command reference and session close protocol
• Use bd remember for persistent knowledge — do NOT use MEMORY.md files (the exception being that you must maintain context/design-principles.md and context/repo-map.md)

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 merge origin/main
   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