Agent Guidelines

Commands

• Typecheck: bun run typecheck
• Install deps: bun install
• No tests configured

Code Style

• TypeScript strict mode with ESM modules
• Use import type for type-only imports (verbatimModuleSyntax)
• Node.js imports use node: prefix (e.g., node:fs/promises)
• Handle undefined from indexed access (noUncheckedIndexedAccess enabled)
• camelCase for functions/variables, PascalCase for types/interfaces
• JSDoc comments for function documentation
• Async/await for async operations

Project Structure

• src/plugin.ts - Main plugin entry point
• src/vendor.ts - Vendor file loaders
• vendor/ - Synced content from upstream beads repo (commands, agents)

Notes

• This is an OpenCode plugin integrating the beads issue tracker
• Vendor files are synced via scripts/sync-beads.sh - don't edit directly

Releasing a New Version

Triggers: User says "bump the version", "cut a new release", "release a new version", "let's do a release", or similar.

Determining the Version

If the user specifies a version number (e.g., "bump to 0.4.0") or bump type (major/minor/patch), use that. Otherwise:

1. Find the current version in package.json
2. Fetch tags from remote: git fetch origin --tags
3. Get commits since last release: git log v<current>..HEAD --oneline
4. Read the actual diffs - don't rely solely on commit messages:
   • git diff v<current>..HEAD -- src/ for source changes
   • git diff v<current>..HEAD -- vendor/ for vendor syncs
5. Apply semver:
   • patch (0.0.x): Bug fixes, dependency updates, vendor syncs with no breaking changes
   • minor (0.x.0): New features, new commands, non-breaking enhancements
   • major (x.0.0): Breaking changes to plugin API or behavior

Files to Update

1. package.json - Update "version" field
2. CHANGELOG.md:
   • Move content from ## [Unreleased] to new version section
   • Add new version heading: ## [X.Y.Z]
   • Update [unreleased] compare link at bottom to compare from new version
   • Add new version release link at the end of the reference links list
3. README.md - Update version in the installation example JSON

Commit Convention

Use this exact format:

:bookmark: bump version X.Y.Z -> A.B.C

Checklist

• All three files updated with consistent version
• CHANGELOG has actual changes listed (not empty)
• CHANGELOG links point to correct versions
• Single commit with all version bump changes
• User will cut the GitHub release after merge

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

Check for ready work:

bd ready --json

Create new issues:

bd create "Issue title" -t bug|feature|task -p 0-4 --json
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
bd create "Subtask" --parent <epic-id> --json  # Hierarchical subtask (gets ID like epic-id.1)

Claim and update:

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

Complete work:

bd close bd-42 --reason "Completed" --json

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

Writing Self-Contained Issues

Issues must be fully self-contained - readable without any external context (plans, chat history, etc.). A future session should understand the issue completely from its description alone.

Required elements:

• Summary: What and why in 1-2 sentences
• Files to modify: Exact paths (with line numbers if relevant)
• Implementation steps: Numbered, specific actions
• Example: Show before → after transformation when applicable

Optional but helpful:

• Edge cases or gotchas to watch for
• Test references (point to test files or test_data examples)
• Dependencies on other issues

Bad example:

Implement the refactoring from the plan

Good example:

Add timeout parameter to fetchUser() in src/api/users.ts

1. Add optional timeout param (default 5000ms)
2. Pass to underlying fetch() call
3. Update tests in src/api/users.test.ts

Example: fetchUser(id) → fetchUser(id, { timeout: 3000 })
Depends on: bd-abc123 (fetch wrapper refactor)

Dependencies: Think "Needs", Not "Before"

bd dep add X Y = "X needs Y" = Y blocks X

TRAP: Temporal words ("Phase 1", "before", "first") invert your thinking!

WRONG: "Phase 1 before Phase 2" → bd dep add phase1 phase2
RIGHT: "Phase 2 needs Phase 1" → bd dep add phase2 phase1

Verify: bd blocked - tasks blocked by prerequisites, not dependents.

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!

GitHub Copilot Integration

If using GitHub Copilot, also create .github/copilot-instructions.md for automatic instruction loading. Run bd onboard to get the content, or see step 2 of the onboard instructions.

MCP Server (Recommended)

If using Claude or MCP-compatible clients, install the beads MCP server:

pip install beads-mcp

Add to MCP config (e.g., ~/.config/claude/config.json):

{
  "beads": {
    "command": "beads-mcp",
    "args": []
  }
}

Then use mcp__beads__* functions instead of CLI commands.

Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

• PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
• DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
• TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

Best Practice: Use a dedicated directory for these ephemeral files

Recommended approach:

• Create a history/ directory in the project root
• Store ALL AI-generated planning/design docs in history/
• Keep the repository root clean and focused on permanent project files
• Only access history/ when explicitly asked to review past planning

Example .gitignore entry (optional):

# AI planning documents (ephemeral)
history/

Benefits:

• ✅ Clean repository root
• ✅ Clear separation between ephemeral and permanent documentation
• ✅ Easy to exclude from version control if desired
• ✅ Preserves planning history for archeological research
• ✅ Reduces noise when browsing the project

CLI Help

Run bd <command> --help to see all available flags for any command. For example: bd create --help shows --parent, --deps, --assignee, etc.

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?"
• ✅ Store AI planning docs in history/ directory
• ✅ Run bd <cmd> --help to discover available flags
• ❌ Do NOT create markdown TODO lists
• ❌ Do NOT use external issue trackers
• ❌ Do NOT duplicate tracking systems
• ❌ Do NOT clutter repo root with planning documents

For more details, see README.md and QUICKSTART.md.