mache: Instructions file for Codex

Agent Instructions

This project uses rsry for bead tracking.

Quick Reference

rsry bead --repo . list --status ready
rsry bead --repo . review <id>
rsry bead --repo . comment add <id> "progress note"
rsry bead --repo . close <id>
rsry bead --repo . export --status all --jsonl -o .beads/beads.jsonl

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

Issue Tracking with rsry Beads

IMPORTANT: This project uses rsry beads for ALL issue tracking. Do NOT use markdown TODOs, task lists, or external issue trackers.

Why rsry?

• Dependency-aware: Track blockers and relationships between issues
• Version-controlled: bead content is shared through .beads/beads.jsonl
• Agent-optimized: JSON output, ready work detection, discovered-from links
• Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

rsry bead --repo . list --status ready

Create new issues:

rsry bead --repo . create "Issue title" -d "Detailed context" -t bug|feature|task -p 0

Review and update:

rsry bead --repo . review <id>
rsry bead --repo . comment add <id> "What changed / what remains"