Priority used the filled circle also mapped to status-blocked, so agents misread ready work as blocked (GH#4996). Render P-labels only; document the convention for agents; keep ● for blocked status alone. Co-authored-by: Steve Yegge <steve.yegge@gmail.com>
11 KiB
Agent Instructions
See AGENT_INSTRUCTIONS.md for full instructions.
This file exists for compatibility with tools that look for AGENTS.md.
The marker above tells bd doctor that the intentional divergence between
this file and CLAUDE.md (different audiences, different reading orders) is
expected and should not be flagged.
Key Sections
- Issue Tracking - How to use bd for work management
- Development Guidelines - Code standards and testing
- Project Scope - Read engdocs/PROJECT_CHARTER.md before adding new feature surface area
- Visual Design System - Status icons, colors, and semantic styling for CLI output
- Contributor Protection - Read CONTRIBUTING.md before handling external PRs
- Maintainer PR Guidelines - Read PR_MAINTAINER_GUIDELINES.md before triaging, landing, or closing PRs
Project Scope
Before adding new feature surface area, read engdocs/PROJECT_CHARTER.md. Beads owns issue tracking primitives and should not encode orchestration-layer policy, become a storage engine, or casually expand the database schema when metadata would work.
PR Safety for Agents
Before triaging, reviewing, landing, closing, or otherwise maintaining PRs, read PR_MAINTAINER_GUIDELINES.md. The maintainer policy is to maximize community throughput: find useful contributor value, absorb or transform it locally when practical, preserve attribution, and use request-changes only as a last resort.
Before implementing work, opening a PR, or merging/closing a PR, run the PR preflight:
scripts/pr-preflight.sh --search "<topic keywords>" --repo gastownhall/beads
scripts/pr-preflight.sh <pr-number> --repo gastownhall/beads
External contributor PRs have priority. Review and build on their branch when possible, preserve their tests and attribution, and never close or supersede their PR silently. If a rewrite is unavoidable, explain why on the original PR and credit their design/tests.
Visual Design Anti-Patterns
NEVER use emoji-style icons (🔴🟠🟡🔵⚪) in CLI output. They cause cognitive overload.
ALWAYS use small Unicode symbols with semantic colors (status uses symbols; priority uses labels):
- Status:
○ ◐ ● ✓ ❄ - Priority:
P0–P4label with color (no status glyph)
See AGENT_INSTRUCTIONS.md for full development guidelines.
Storage Boundary
The canonical storage boundary is in
engdocs/PROJECT_CHARTER.md. In short:
Beads talks to storage through a driver interface (dolthub/driver for Dolt).
Do not add beads-side flocks, engine introspection, storage-specific retry or
crash-recovery logic, or public SDK return types that leak driver internals.
If the boundary is too narrow, widen the interface or route the issue to the
driver instead of patching around it in beads.
A live application of this rule: bd doctor support for embedded mode is
enabled one subcommand at a time, each human-vetted (GH#3794). Do not lift the
embedded-mode gate in cmd/bd/doctor.go wholesale, and keep database-layer
checks and fixes server-gated until the driver interface covers them.
Agent Warning: Interactive Commands
DO NOT use bd edit - it opens an interactive editor ($EDITOR) which AI agents cannot use.
Use bd update with flags instead:
bd update <id> --description "new description"
bd update <id> --title "new title"
bd update <id> --design "design notes"
bd update <id> --notes "additional notes"
bd update <id> --acceptance "acceptance criteria"
# Use stdin for descriptions with special characters (backticks, !, nested quotes)
echo 'Description with `backticks` and "quotes"' | bd create "Title" --description=-
echo 'Updated text' | bd update <id> --description=-
Testing
Use engdocs/TESTING.md for the canonical commands, test-design guidance, and PR-readiness gates.
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=yesfor non-interactivessh- use-o BatchMode=yesto fail instead of promptingapt-get- use-yflagbrew- useHOMEBREW_NO_AUTO_UPDATE=1env var
Landing the Plane (Session Completion)
When ending a work session (or when the user says "let's land the
plane"), 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):
make ci-pr-lint(required zero-finding formatting and lint wrapper)make test(andmake test-icu-pathonly if you intentionally need the ICU regex path)- File a P0 issue if quality gates are broken
- 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:
git stash clear # Remove old stashes git remote prune origin # Clean up deleted remote branches - Verify - All changes committed AND pushed, no untracked files remain
- Hand off - Choose a follow-up issue and give the user a prompt for the next session, e.g. "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]"
CRITICAL RULES:
- Work is NOT complete until
git pushsucceeds - 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
Close with a summary for the user: what was completed this session, issues filed for follow-up, quality-gate status, confirmation everything is pushed, and the recommended prompt for the next session.
Issue Tracking with bd (beads)
IMPORTANT: This project uses bd (beads) for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
Why bd?
- Dependency-aware: Track blockers and relationships between issues
- Git-friendly: Dolt-powered version control with native sync
- Agent-optimized: JSON output, ready work detection, discovered-from links
- Prevents duplicate tracking systems and confusion
Quick Start
Check for ready work:
bd ready --json
Create new issues:
bd create "Issue title" --description="Detailed context" -t bug|feature|task -p 0-4 --json
bd create "Issue title" --description="What this issue is about" -p 1 --deps discovered-from:bd-123 --json
Claim and update:
bd update <id> --claim --json
bd update bd-42 --priority 1 --json
Complete work:
bd close bd-42 --reason "Completed" --json
Issue Types
bug- Something brokenfeature- New functionalitytask- Work item (tests, docs, refactoring)epic- Large feature with subtaskschore- Maintenance (dependencies, tooling)
Priorities
0- Critical (security, data loss, broken builds)1- High (major features, important bugs)2- Medium (default, nice-to-have)3- Low (polish, optimization)4- Backlog (future ideas)
Workflow for AI Agents
- Check ready work:
bd readyshows unblocked issues - Claim your task atomically:
bd update <id> --claim - Work on it: Implement, test, document
- Discover new work? Create linked issue:
bd create "Found bug" --description="Details about what was found" -p 1 --deps discovered-from:<parent-id>
- Complete:
bd close <id> --reason "Done"
Quality
- Use
--acceptanceand--designfields when creating issues - Use
--validateto check description completeness
Lifecycle
bd defer <id>/bd supersede <id>for issue managementbd stale/bd orphans/bd lintfor hygienebd human <id>to flag for human decisionsbd formula list/bd mol pour <name>for structured workflows
Sync
bd stores issue history in Dolt:
- Each write auto-commits to Dolt history
- Use
bd dolt push/bd dolt pullfor remote sync - Do not treat
.beads/issues.jsonlas the sync protocol
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/core-concepts/sync-concepts.md for details and anti-patterns.
Important Rules
- ✅ Use bd for ALL task tracking
- ✅ Always use
--jsonflag for programmatic use - ✅ Link discovered work with
discovered-fromdependencies - ✅ Check
bd readybefore asking "what should I work on?" - ❌ Do NOT create markdown TODO lists
- ❌ Do NOT use external issue trackers
- ❌ Do NOT duplicate tracking systems
For more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md.
Agent Context Profiles
The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.
- Conservative (default): Use
bdfor task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. - Minimal: Keep tool instruction files as pointers to
bd prime; use the same conservative git policy unless active instructions say otherwise. - Team-maintainer: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins.
Session Completion
This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.
- File issues for remaining work - Create beads 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
- Handle git/sync by active profile:
# Conservative/minimal/default: report status and proposed commands; wait for approval. git status # Team-maintainer opt-in only, unless current instructions forbid it: git pull --rebase bd dolt push git push git status - Hand off - Summarize changes, validation, issue status, and any blocked sync/commit/push step
Critical rules:
- Explicit user or orchestrator instructions override this Beads block.
- Do not commit or push without clear authority from the active profile or the current user request.
- If a required sync or push is blocked, stop and report the exact command and error.