Skip to content

AGENTS.md

Latest commit

 

History

History
97 lines (69 loc) · 3.23 KB

AGENTS.md

File metadata and controls

97 lines (69 loc) · 3.23 KB

Repository Guidelines

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: Auto-syncs to JSONL for version control
  • Agent-optimized: JSON output, ready work detection, discovered-from links
  • Prevents duplicate tracking systems and confusion

Quick Start

Read skills/bd-issue-tracking

Check for ready work:

Use filters to stay focused.

bd ready [--label ... ] [--limit 10]

Create new issues:

bd create "Issue title" -t bug|feature|task -p 0-4 [--parent epic] [--design "hOW"] [--acceptance "WHAT success looks like" ]
bd create "Issue title" -p 1 --deps discovered-from:bd-123

Claim and update:

bd update bd-42 --status in_progress
bd update bd-42 --priority 1

Document information discovered during implementation:

bd comments add bd-42 "zitadel/oidc requires key generation and key ID to sign"

Complete work:

bd close bd-42 --reason "Completed"

Issue Types

  • bug - Something broken
  • feature - New functionality
  • task - Work item (tests, docs, refactoring)
  • epic - Large feature with subtasks
  • chore - 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

  1. Check ready work: bd ready shows unblocked issues
  2. Claim your task: bd update <id> --status in_progress
  3. Work on it: Implement, test, document
  4. Discover new work? Create linked issue:
    • bd create "Found bug" -p 1 --deps discovered-from:<parent-id>
  5. Complete: bd close <id> --reason "Done"
  6. Commit together: Always commit the .beads/issues.jsonl file together with the code changes so issue state stays in sync with code state

Auto-Sync

bd automatically syncs with git:

  • Exports to .beads/issues.jsonl after changes (5s debounce)
  • Imports from JSONL when newer (e.g., after git pull)
  • No manual export/import needed!

Important Rules

  • ✅ Use bd for ALL task tracking
  • ✅ Always use --json flag for programmatic use
  • ✅ Link discovered work with discovered-from dependencies
  • ✅ Check bd ready before 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 QUICKSTART.md.

Commit & Pull Request Guidelines

Follow the existing conventional prefixes (feat:, fix:, chore:, docs:) and keep messages imperative and under 72 characters. Reference related issues in the body and mention migrations, proto changes, or new binaries explicitly. PRs should include a concise summary, testing evidence (make test-unit, make test-integration, etc.), and screenshots or CLI transcripts when behavior changes. Request reviews from domain owners and ensure generated artifacts and docs stay in sync with code changes.