agentic_ssh: Instructions file for Codex

---

Beads Workflow Integration

This project uses beads_rust (br/bd) for issue tracking. Issues are stored in .beads/ and tracked in git.

Essential Commands

# View ready issues (open, unblocked, not deferred)
br ready              # or: bd ready

# List and search
br list --status=open # All open issues
br show <id>          # Full issue details with dependencies
br search "keyword"   # Full-text search

# Create and update
br create --title="..." --description="..." --type=task --priority=2
br update <id> --status=in_progress
br close <id> --reason="Completed"
br close <id1> <id2>  # Close multiple issues at once

# Sync with git
br sync --flush-only  # Export DB to JSONL
br sync --status      # Check sync status

Workflow Pattern

1. Start: Run br ready to find actionable work
2. Claim: Use br update <id> --status=in_progress
3. Work: Implement the task
4. Complete: Use br close <id>
5. Sync: Always run br sync --flush-only at session end

Key Concepts

• Dependencies: Issues can block other issues. br ready shows only open, unblocked work.
• Priority: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers 0-4, not words)
• Types: task, bug, feature, epic, chore, docs, question
• Blocking: br dep add <issue> <depends-on> to add dependencies

Session Protocol

Before ending any session, run this checklist:

1. Static Verification: Run cargo clippy --all-targets and fix any warnings to ensure compliance with the coding standards.
2. Commit Checklist:

   git status              # Check what changed
   git add <files>         # Stage code changes
   br sync --flush-only    # Export beads changes to JSONL
   git commit -m "..."     # Commit everything
   git push                # Push to remote
   

Best Practices

• Check br ready at session start to find available work
• Consult and adhere to rust-guidelines.txt for project-wide coding standards (e.g. error handling, mimalloc usage, and static checking).
• Update status as you work (in_progress → closed)
• Create new issues with br create when you discover tasks
• Use descriptive titles and set appropriate priority/type
• Always sync before ending session