Skip to main content

Agent Instructions

This project uses Kata for AI work orchestration. Kata wraps beads for work-item storage, but agents should use the kata commands for normal filing, dispatch, PR, and reactor workflows.

Use direct bd commands only for read-only inspection or when a Kata skill explicitly asks for metadata updates. Do not run bd dolt push as part of normal agent closeout; Kata owns the beads sync and lifecycle behavior.

Quick Reference​

kata file "fix: concise title"   # File work using the default quick workflow
kata status                      # Show agents, queued work, and PRs
kata peek -f                     # Tail the most recent agent log
kata pause                       # Stop dispatching new work
kata resume                      # Resume dispatching work

Kata Workflow​

  • Use kata file to create work. Pick a workflow with -w cowboy, -w quick, -w standard, -w hotfix, or -w plan when the default is not appropriate.
  • Follow .claude/skills/kata-file/SKILL.md when turning an ambiguous request into a well-scoped bead with acceptance criteria.
  • Use kata.toml for the workflow definitions that the dispatcher and reactor follow in this repository.
  • Let the Kata dispatcher, review agent, and reactor handle claiming, PR policy, merge policy, and bead closure unless a human explicitly asks otherwise.
  • This repository is human-merge only. Agents and Kata automation should open PRs, request review, and wait for a human to merge them.

Read-Only Bead Queries​

Kata stores work in beads. These bd commands are useful for inspection:

bd ready                    # Beads waiting to be dispatched
bd list --status=in_progress # Active beads
bd show <bead-id>           # Full details for one bead
bd search <keyword>         # Search bead metadata

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

Session Completion​

Before ending a coding session:

  1. File follow-up work with kata file if something discovered needs a separate pass.
  2. Run relevant tests, linters, or builds when code changed.
  3. Commit the intended changes.
  4. Pull/rebase and push the branch:
git pull --rebase
git push
git status

git status should show the branch is up to date with origin. Do not add a manual bd dolt push step.