{"owner":"gastownhall","repo":"beads","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md","CLAUDE.md",".github/copilot-instructions.md"],"skills":{"AGENTS.md":"# Agent Instructions\n\n\n\nSee [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.\n\nThis file exists for compatibility with tools that look for AGENTS.md.\n\nThe marker above tells `bd doctor` that the intentional divergence between\nthis file and `CLAUDE.md` (different audiences, different reading orders) is\nexpected and should not be flagged.\n\n## Key Sections\n\n- **Issue Tracking** - How to use bd for work management\n- **Development Guidelines** - Code standards and testing\n- **Project Scope** - Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding new feature surface area\n- **Visual Design System** - Status icons, colors, and semantic styling for CLI output\n- **Contributor Protection** - Read [CONTRIBUTING.md](CONTRIBUTING.md) before handling external PRs\n- **Maintainer PR Guidelines** - Read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md) before triaging, landing, or closing PRs\n\n## Project Scope\n\nBefore adding new feature surface area, read\n[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md). Beads owns issue tracking\nprimitives and should not encode orchestration-layer policy, become a storage\nengine, or casually expand the database schema when metadata would work.\n\n## PR Safety for Agents\n\nBefore triaging, reviewing, landing, closing, or otherwise maintaining PRs, read\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing work, opening a PR, or merging/closing a PR, run the PR\npreflight:\n```bash\nscripts/pr-preflight.sh --search \"\" --repo gastownhall/beads\nscripts/pr-preflight.sh --repo gastownhall/beads\n```\n\nExternal contributor PRs have priority. Review and build on their branch when\npossible, preserve their tests and attribution, and never close or supersede\ntheir PR silently. If a rewrite is unavoidable, explain why on the original PR\nand credit their design/tests.\n\n## Visual Design Anti-Patterns\n\n**NEVER use emoji-style icons** (šŸ”“šŸŸ šŸŸ”šŸ”µāšŖ) in CLI output. They cause cognitive overload.\n\n**ALWAYS use small Unicode symbols** with semantic colors (status uses symbols; priority uses labels):\n- Status: `ā—‹ ā— ā— āœ“ ā„`\n- Priority: `P0`ā€“`P4` label with color (no status glyph)\n\nSee [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines.\n\n## Storage Boundary\n\nThe canonical storage boundary is in\n[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md#storage-boundary). In short:\nBeads talks to storage through a driver interface (`dolthub/driver` for Dolt).\nDo not add beads-side flocks, engine introspection, storage-specific retry or\ncrash-recovery logic, or public SDK return types that leak driver internals.\nIf the boundary is too narrow, widen the interface or route the issue to the\ndriver instead of patching around it in beads.\n\nA live application of this rule: `bd doctor` support for embedded mode is\nenabled one subcommand at a time, each human-vetted (GH#3794). Do not lift the\nembedded-mode gate in `cmd/bd/doctor.go` wholesale, and keep database-layer\nchecks and fixes server-gated until the driver interface covers them.\n\n## Agent Warning: Interactive Commands\n\n**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.\n\nUse `bd update` with flags instead:\n```bash\nbd update --description \"new description\"\nbd update --title \"new title\"\nbd update --design \"design notes\"\nbd update --notes \"additional notes\"\nbd update --acceptance \"acceptance criteria\"\n\n# Use stdin for descriptions with special characters (backticks, !, nested quotes)\necho 'Description with `backticks` and \"quotes\"' | bd create \"Title\" --description=-\necho 'Updated text' | bd update --description=-\n```\n\n## Testing\n\nUse [engdocs/TESTING.md](engdocs/TESTING.md) for the canonical commands,\ntest-design guidance, and PR-readiness gates.\n\n## Non-Interactive Shell Commands\n\n**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.\n\nShell 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.\n\n**Use these forms instead:**\n```bash\n# Force overwrite without prompting\ncp -f source dest # NOT: cp source dest\nmv -f source dest # NOT: mv source dest\nrm -f file # NOT: rm file\n\n# For recursive operations\nrm -rf directory # NOT: rm -r directory\ncp -rf source dest # NOT: cp -r source dest\n```\n\n**Other commands that may prompt:**\n- `scp` - use `-o BatchMode=yes` for non-interactive\n- `ssh` - use `-o BatchMode=yes` to fail instead of prompting\n- `apt-get` - use `-y` flag\n- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var\n\n## Landing the Plane (Session Completion)\n\n**When ending a work session** (or when the user says \"let's land the\nplane\"), you MUST complete ALL steps below. Work is NOT complete until\n`git push` succeeds.\n\n**MANDATORY WORKFLOW:**\n\n1. **File issues for remaining work** - Create issues for anything that needs follow-up\n2. **Run quality gates** (if code changed):\n - `make ci-pr-lint` (required zero-finding formatting and lint wrapper)\n - `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path)\n - File a P0 issue if quality gates are broken\n3. **Update issue status** - Close finished work, update in-progress items\n4. **PUSH TO REMOTE** - This is MANDATORY:\n ```bash\n git pull --rebase\n git push\n git status # MUST show \"up to date with origin\"\n ```\n5. **Clean up**:\n ```bash\n git stash clear # Remove old stashes\n git remote prune origin # Clean up deleted remote branches\n ```\n6. **Verify** - All changes committed AND pushed, no untracked files remain\n7. **Hand off** - Choose a follow-up issue and give the user a prompt for\n the next session, e.g. \"Continue work on bd-X: [issue title]. [Brief\n context about what's been done and what's next]\"\n\n**CRITICAL RULES:**\n- Work is NOT complete until `git push` succeeds\n- NEVER stop before pushing - that leaves work stranded locally\n- NEVER say \"ready to push when you are\" - YOU must push\n- If push fails, resolve and retry until it succeeds\n\nClose with a summary for the user: what was completed this session, issues\nfiled for follow-up, quality-gate status, confirmation everything is pushed,\nand the recommended prompt for the next session.\n\n\n## Issue Tracking with bd (beads)\n\n**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.\n\n### Why bd?\n\n- Dependency-aware: Track blockers and relationships between issues\n- Git-friendly: Dolt-powered version control with native sync\n- Agent-optimized: JSON output, ready work detection, discovered-from links\n- Prevents duplicate tracking systems and confusion\n\n### Quick Start\n\n**Check for ready work:**\n\n```bash\nbd ready --json\n```\n\n**Create new issues:**\n\n```bash\nbd create \"Issue title\" --description=\"Detailed context\" -t bug|feature|task -p 0-4 --json\nbd create \"Issue title\" --description=\"What this issue is about\" -p 1 --deps discovered-from:bd-123 --json\n```\n\n**Claim and update:**\n\n```bash\nbd update --claim --json\nbd update bd-42 --priority 1 --json\n```\n\n**Complete work:**\n\n```bash\nbd close bd-42 --reason \"Completed\" --json\n```\n\n### Issue Types\n\n- `bug` - Something broken\n- `feature` - New functionality\n- `task` - Work item (tests, docs, refactoring)\n- `epic` - Large feature with subtasks\n- `chore` - Maintenance (dependencies, tooling)\n\n### Priorities\n\n- `0` - Critical (security, data loss, broken builds)\n- `1` - High (major features, important bugs)\n- `2` - Medium (default, nice-to-have)\n- `3` - Low (polish, optimization)\n- `4` - Backlog (future ideas)\n\n### Workflow for AI Agents\n\n1. **Check ready work**: `bd ready` shows unblocked issues\n2. **Claim your task atomically**: `bd update --claim`\n3. **Work on it**: Implement, test, document\n4. **Discover new work?** Create linked issue:\n - `bd create \"Found bug\" --description=\"Details about what was found\" -p 1 --deps discovered-from:`\n5. **Complete**: `bd close --reason \"Done\"`\n\n### Quality\n- Use `--acceptance` and `--design` fields when creating issues\n- Use `--validate` to check description completeness\n\n### Lifecycle\n- `bd defer ` / `bd supersede ` for issue management\n- `bd stale` / `bd orphans` / `bd lint` for hygiene\n- `bd human ` to flag for human decisions\n- `bd formula list` / `bd mol pour ` for structured workflows\n\n### Sync\n\nbd stores issue history in Dolt:\n\n- Each write auto-commits to Dolt history\n- Use `bd dolt push`/`bd dolt pull` for remote sync\n- Do not treat `.beads/issues.jsonl` as the sync protocol\n\n**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.\n\n### Important Rules\n\n- āœ… Use bd for ALL task tracking\n- āœ… Always use `--json` flag for programmatic use\n- āœ… Link discovered work with `discovered-from` dependencies\n- āœ… Check `bd ready` before asking \"what should I work on?\"\n- āŒ Do NOT create markdown TODO lists\n- āŒ Do NOT use external issue trackers\n- āŒ Do NOT duplicate tracking systems\n\nFor more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md.\n\n## Agent Context Profiles\n\nThe managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.\n\n- **Conservative (default)**: Use `bd` for 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.\n- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.\n- **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.\n\n## Session Completion\n\nThis protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.\n\n1. **File issues for remaining work** - Create beads for anything that needs follow-up\n2. **Run quality gates** (if code changed) - Tests, linters, builds\n3. **Update issue status** - Close finished work, update in-progress items\n4. **Handle git/sync by active profile**:\n ```bash\n # Conservative/minimal/default: report status and proposed commands; wait for approval.\n git status\n\n # Team-maintainer opt-in only, unless current instructions forbid it:\n git pull --rebase\n bd dolt push\n git push\n git status\n ```\n5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step\n\n**Critical rules:**\n- Explicit user or orchestrator instructions override this Beads block.\n- Do not commit or push without clear authority from the active profile or the current user request.\n- If a required sync or push is blocked, stop and report the exact command and error.\n\n\n","CLAUDE.md":"# Claude Code Entry Point for Beads\n\nThis file is intentionally short. Do not copy workflow, build, storage, or UI\nrules here; those details drift quickly when repeated across agent entrypoints.\n\n## Read First\n\n- **Workflow and safety**: [AGENTS.md](AGENTS.md)\n- **Detailed agent operations**: [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md)\n- **Architecture orientation**: [engdocs/CLAUDE.md](engdocs/CLAUDE.md)\n- **PR maintenance policy**: [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md)\n\n## Current Ground Rules\n\n- Run `bd prime` before doing tracked work.\n- Follow `go.mod` and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for build\n and test commands; do not hard-code toolchain versions here.\n- Beads uses Dolt as the issue database. Use `bd dolt push` / `bd dolt pull`\n for issue data sync; do not use export/import as a routine git workflow.\n- The CLI Visual Design System lives in\n [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md#visual-design-system).\n- If this file conflicts with a linked source, trust the linked source and fix\n this file by removing the duplicate.\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for Beads\n\n## Project Overview\n\n**beads** (command: `bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. Git integration is optional. We dogfood our own tool for all task tracking.\n\n**Key Features:**\n- Dependency-aware issue tracking\n- Auto-sync via Dolt-native replication\n- AI-optimized CLI with JSON output\n- Dolt server mode for background operations\n- MCP server integration for Claude and other AI assistants\n\n## Tech Stack\n\n- **Language**: Go 1.21+\n- **Storage**: Dolt (version-controlled SQL database)\n- **CLI Framework**: Cobra\n- **Testing**: Go standard testing + table-driven tests\n- **CI/CD**: GitHub Actions\n- **MCP Server**: Python (integrations/beads-mcp/)\n\n## Coding Guidelines\n\n### Testing\n- Always write tests for new features\n- Use `t.TempDir() in Go tests` to avoid polluting production database\n- Run `go test -short ./...` before committing\n- Never create test issues in production DB (use temporary DB)\n\n### Code Style\n- Run `make ci-pr-lint` before committing changes to Go or lint-controlled files\n- Follow existing patterns in `cmd/bd/` for new commands\n- Add `--json` flag to all commands for programmatic use\n- Update docs when changing behavior\n\n### Git Workflow\n- Install git hooks: `bd hooks install`\n- Use `bd dolt push` / `bd dolt pull` for remote sync\n- Before implementing related work, opening a PR, or merging/closing a PR, run:\n `scripts/pr-preflight.sh --search \"\" --repo gastownhall/beads` or\n `scripts/pr-preflight.sh --repo gastownhall/beads`\n- External contributor PRs have priority: build on them when possible, preserve\n tests and attribution, and never close or replace them silently.\n\n## Issue Tracking with bd\n\n**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.\n\n### Essential Commands\n\n```bash\n# Find work\nbd ready --json # Unblocked issues\nbd stale --days 30 --json # Forgotten issues\n\n# Create and manage (ALWAYS include --description)\nbd create \"Title\" --description=\"Detailed context\" -t bug|feature|task -p 0-4 --json\nbd update --claim --json\nbd close --reason \"Done\" --json\n\n# Search\nbd list --status open --priority 1 --json\nbd show --json\n\n# Sync (if remote configured)\nbd dolt push # Push to Dolt remote\nbd dolt pull # Pull from Dolt remote\n```\n\n### Workflow\n\n1. **Check ready work**: `bd ready --json`\n2. **Claim task**: `bd update --claim`\n3. **Work on it**: Implement, test, document\n4. **Discover new work?** `bd create \"Found bug\" --description=\"What was found and why\" -p 1 --deps discovered-from: --json`\n5. **Complete**: `bd close --reason \"Done\" --json`\n6. **Sync**: `bd dolt push` (push to Dolt remote if configured)\n\n**IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work.\n\n### Priorities\n\n- `0` - Critical (security, data loss, broken builds)\n- `1` - High (major features, important bugs)\n- `2` - Medium (default, nice-to-have)\n- `3` - Low (polish, optimization)\n- `4` - Backlog (future ideas)\n\n## Project Structure\n\n```\nbeads/\nā”œā”€ā”€ cmd/bd/ # CLI commands (add new commands here)\nā”œā”€ā”€ internal/\nā”‚ ā”œā”€ā”€ types/ # Core data types\nā”‚ ā””ā”€ā”€ storage/ # Storage layer\nā”‚ ā””ā”€ā”€ dolt/ # Dolt implementation\nā”œā”€ā”€ integrations/\nā”‚ ā””ā”€ā”€ beads-mcp/ # MCP server (Python)\nā”œā”€ā”€ examples/ # Integration examples\nā”œā”€ā”€ docs/ # Documentation\nā””ā”€ā”€ .beads/\n ā””ā”€ā”€ dolt/ # Dolt database (source of truth)\n```\n\n## Available Resources\n\n### MCP Server (Recommended)\nUse the beads MCP server for native function calls instead of shell commands:\n- Install: `pip install beads-mcp`\n- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.\n- See `integrations/beads-mcp/README.md`\n\n### Scripts\n- `./scripts/bump-version.sh --commit` - Update all version files atomically\n- `./scripts/release.sh ` - Complete release workflow\n- `./scripts/update-homebrew.sh ` - Update Homebrew formula\n\n### Key Documentation\n- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)\n- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases\n- **README.md** - User-facing documentation\n- **docs/CLI_REFERENCE.md** - Complete command reference\n\n## Important Rules\n\n- āœ… Use bd for ALL task tracking\n- āœ… Always use `--json` flag for programmatic use\n- āœ… Use `bd dolt push` / `bd dolt pull` for remote sync\n- āœ… Test with `t.TempDir() in Go tests`\n- āŒ Do NOT create markdown TODO lists\n- āŒ Do NOT create test issues in production DB\n- āŒ Do NOT manually modify `.beads/dolt/`\n\n---\n\n**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**\n"},"files":{"AGENTS.md":"# Agent Instructions\n\n\n\nSee [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.\n\nThis file exists for compatibility with tools that look for AGENTS.md.\n\nThe marker above tells `bd doctor` that the intentional divergence between\nthis file and `CLAUDE.md` (different audiences, different reading orders) is\nexpected and should not be flagged.\n\n## Key Sections\n\n- **Issue Tracking** - How to use bd for work management\n- **Development Guidelines** - Code standards and testing\n- **Project Scope** - Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding new feature surface area\n- **Visual Design System** - Status icons, colors, and semantic styling for CLI output\n- **Contributor Protection** - Read [CONTRIBUTING.md](CONTRIBUTING.md) before handling external PRs\n- **Maintainer PR Guidelines** - Read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md) before triaging, landing, or closing PRs\n\n## Project Scope\n\nBefore adding new feature surface area, read\n[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md). Beads owns issue tracking\nprimitives and should not encode orchestration-layer policy, become a storage\nengine, or casually expand the database schema when metadata would work.\n\n## PR Safety for Agents\n\nBefore triaging, reviewing, landing, closing, or otherwise maintaining PRs, read\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing work, opening a PR, or merging/closing a PR, run the PR\npreflight:\n```bash\nscripts/pr-preflight.sh --search \"\" --repo gastownhall/beads\nscripts/pr-preflight.sh --repo gastownhall/beads\n```\n\nExternal contributor PRs have priority. Review and build on their branch when\npossible, preserve their tests and attribution, and never close or supersede\ntheir PR silently. If a rewrite is unavoidable, explain why on the original PR\nand credit their design/tests.\n\n## Visual Design Anti-Patterns\n\n**NEVER use emoji-style icons** (šŸ”“šŸŸ šŸŸ”šŸ”µāšŖ) in CLI output. They cause cognitive overload.\n\n**ALWAYS use small Unicode symbols** with semantic colors (status uses symbols; priority uses labels):\n- Status: `ā—‹ ā— ā— āœ“ ā„`\n- Priority: `P0`ā€“`P4` label with color (no status glyph)\n\nSee [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines.\n\n## Storage Boundary\n\nThe canonical storage boundary is in\n[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md#storage-boundary). In short:\nBeads talks to storage through a driver interface (`dolthub/driver` for Dolt).\nDo not add beads-side flocks, engine introspection, storage-specific retry or\ncrash-recovery logic, or public SDK return types that leak driver internals.\nIf the boundary is too narrow, widen the interface or route the issue to the\ndriver instead of patching around it in beads.\n\nA live application of this rule: `bd doctor` support for embedded mode is\nenabled one subcommand at a time, each human-vetted (GH#3794). Do not lift the\nembedded-mode gate in `cmd/bd/doctor.go` wholesale, and keep database-layer\nchecks and fixes server-gated until the driver interface covers them.\n\n## Agent Warning: Interactive Commands\n\n**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.\n\nUse `bd update` with flags instead:\n```bash\nbd update --description \"new description\"\nbd update --title \"new title\"\nbd update --design \"design notes\"\nbd update --notes \"additional notes\"\nbd update --acceptance \"acceptance criteria\"\n\n# Use stdin for descriptions with special characters (backticks, !, nested quotes)\necho 'Description with `backticks` and \"quotes\"' | bd create \"Title\" --description=-\necho 'Updated text' | bd update --description=-\n```\n\n## Testing\n\nUse [engdocs/TESTING.md](engdocs/TESTING.md) for the canonical commands,\ntest-design guidance, and PR-readiness gates.\n\n## Non-Interactive Shell Commands\n\n**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.\n\nShell 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.\n\n**Use these forms instead:**\n```bash\n# Force overwrite without prompting\ncp -f source dest # NOT: cp source dest\nmv -f source dest # NOT: mv source dest\nrm -f file # NOT: rm file\n\n# For recursive operations\nrm -rf directory # NOT: rm -r directory\ncp -rf source dest # NOT: cp -r source dest\n```\n\n**Other commands that may prompt:**\n- `scp` - use `-o BatchMode=yes` for non-interactive\n- `ssh` - use `-o BatchMode=yes` to fail instead of prompting\n- `apt-get` - use `-y` flag\n- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var\n\n## Landing the Plane (Session Completion)\n\n**When ending a work session** (or when the user says \"let's land the\nplane\"), you MUST complete ALL steps below. Work is NOT complete until\n`git push` succeeds.\n\n**MANDATORY WORKFLOW:**\n\n1. **File issues for remaining work** - Create issues for anything that needs follow-up\n2. **Run quality gates** (if code changed):\n - `make ci-pr-lint` (required zero-finding formatting and lint wrapper)\n - `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path)\n - File a P0 issue if quality gates are broken\n3. **Update issue status** - Close finished work, update in-progress items\n4. **PUSH TO REMOTE** - This is MANDATORY:\n ```bash\n git pull --rebase\n git push\n git status # MUST show \"up to date with origin\"\n ```\n5. **Clean up**:\n ```bash\n git stash clear # Remove old stashes\n git remote prune origin # Clean up deleted remote branches\n ```\n6. **Verify** - All changes committed AND pushed, no untracked files remain\n7. **Hand off** - Choose a follow-up issue and give the user a prompt for\n the next session, e.g. \"Continue work on bd-X: [issue title]. [Brief\n context about what's been done and what's next]\"\n\n**CRITICAL RULES:**\n- Work is NOT complete until `git push` succeeds\n- NEVER stop before pushing - that leaves work stranded locally\n- NEVER say \"ready to push when you are\" - YOU must push\n- If push fails, resolve and retry until it succeeds\n\nClose with a summary for the user: what was completed this session, issues\nfiled for follow-up, quality-gate status, confirmation everything is pushed,\nand the recommended prompt for the next session.\n\n\n## Issue Tracking with bd (beads)\n\n**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.\n\n### Why bd?\n\n- Dependency-aware: Track blockers and relationships between issues\n- Git-friendly: Dolt-powered version control with native sync\n- Agent-optimized: JSON output, ready work detection, discovered-from links\n- Prevents duplicate tracking systems and confusion\n\n### Quick Start\n\n**Check for ready work:**\n\n```bash\nbd ready --json\n```\n\n**Create new issues:**\n\n```bash\nbd create \"Issue title\" --description=\"Detailed context\" -t bug|feature|task -p 0-4 --json\nbd create \"Issue title\" --description=\"What this issue is about\" -p 1 --deps discovered-from:bd-123 --json\n```\n\n**Claim and update:**\n\n```bash\nbd update --claim --json\nbd update bd-42 --priority 1 --json\n```\n\n**Complete work:**\n\n```bash\nbd close bd-42 --reason \"Completed\" --json\n```\n\n### Issue Types\n\n- `bug` - Something broken\n- `feature` - New functionality\n- `task` - Work item (tests, docs, refactoring)\n- `epic` - Large feature with subtasks\n- `chore` - Maintenance (dependencies, tooling)\n\n### Priorities\n\n- `0` - Critical (security, data loss, broken builds)\n- `1` - High (major features, important bugs)\n- `2` - Medium (default, nice-to-have)\n- `3` - Low (polish, optimization)\n- `4` - Backlog (future ideas)\n\n### Workflow for AI Agents\n\n1. **Check ready work**: `bd ready` shows unblocked issues\n2. **Claim your task atomically**: `bd update --claim`\n3. **Work on it**: Implement, test, document\n4. **Discover new work?** Create linked issue:\n - `bd create \"Found bug\" --description=\"Details about what was found\" -p 1 --deps discovered-from:`\n5. **Complete**: `bd close --reason \"Done\"`\n\n### Quality\n- Use `--acceptance` and `--design` fields when creating issues\n- Use `--validate` to check description completeness\n\n### Lifecycle\n- `bd defer ` / `bd supersede ` for issue management\n- `bd stale` / `bd orphans` / `bd lint` for hygiene\n- `bd human ` to flag for human decisions\n- `bd formula list` / `bd mol pour ` for structured workflows\n\n### Sync\n\nbd stores issue history in Dolt:\n\n- Each write auto-commits to Dolt history\n- Use `bd dolt push`/`bd dolt pull` for remote sync\n- Do not treat `.beads/issues.jsonl` as the sync protocol\n\n**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.\n\n### Important Rules\n\n- āœ… Use bd for ALL task tracking\n- āœ… Always use `--json` flag for programmatic use\n- āœ… Link discovered work with `discovered-from` dependencies\n- āœ… Check `bd ready` before asking \"what should I work on?\"\n- āŒ Do NOT create markdown TODO lists\n- āŒ Do NOT use external issue trackers\n- āŒ Do NOT duplicate tracking systems\n\nFor more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md.\n\n## Agent Context Profiles\n\nThe managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.\n\n- **Conservative (default)**: Use `bd` for 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.\n- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.\n- **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.\n\n## Session Completion\n\nThis protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.\n\n1. **File issues for remaining work** - Create beads for anything that needs follow-up\n2. **Run quality gates** (if code changed) - Tests, linters, builds\n3. **Update issue status** - Close finished work, update in-progress items\n4. **Handle git/sync by active profile**:\n ```bash\n # Conservative/minimal/default: report status and proposed commands; wait for approval.\n git status\n\n # Team-maintainer opt-in only, unless current instructions forbid it:\n git pull --rebase\n bd dolt push\n git push\n git status\n ```\n5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step\n\n**Critical rules:**\n- Explicit user or orchestrator instructions override this Beads block.\n- Do not commit or push without clear authority from the active profile or the current user request.\n- If a required sync or push is blocked, stop and report the exact command and error.\n\n\n","CLAUDE.md":"# Claude Code Entry Point for Beads\n\nThis file is intentionally short. Do not copy workflow, build, storage, or UI\nrules here; those details drift quickly when repeated across agent entrypoints.\n\n## Read First\n\n- **Workflow and safety**: [AGENTS.md](AGENTS.md)\n- **Detailed agent operations**: [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md)\n- **Architecture orientation**: [engdocs/CLAUDE.md](engdocs/CLAUDE.md)\n- **PR maintenance policy**: [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md)\n\n## Current Ground Rules\n\n- Run `bd prime` before doing tracked work.\n- Follow `go.mod` and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for build\n and test commands; do not hard-code toolchain versions here.\n- Beads uses Dolt as the issue database. Use `bd dolt push` / `bd dolt pull`\n for issue data sync; do not use export/import as a routine git workflow.\n- The CLI Visual Design System lives in\n [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md#visual-design-system).\n- If this file conflicts with a linked source, trust the linked source and fix\n this file by removing the duplicate.\n",".github/copilot-instructions.md":"# GitHub Copilot Instructions for Beads\n\n## Project Overview\n\n**beads** (command: `bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. Git integration is optional. We dogfood our own tool for all task tracking.\n\n**Key Features:**\n- Dependency-aware issue tracking\n- Auto-sync via Dolt-native replication\n- AI-optimized CLI with JSON output\n- Dolt server mode for background operations\n- MCP server integration for Claude and other AI assistants\n\n## Tech Stack\n\n- **Language**: Go 1.21+\n- **Storage**: Dolt (version-controlled SQL database)\n- **CLI Framework**: Cobra\n- **Testing**: Go standard testing + table-driven tests\n- **CI/CD**: GitHub Actions\n- **MCP Server**: Python (integrations/beads-mcp/)\n\n## Coding Guidelines\n\n### Testing\n- Always write tests for new features\n- Use `t.TempDir() in Go tests` to avoid polluting production database\n- Run `go test -short ./...` before committing\n- Never create test issues in production DB (use temporary DB)\n\n### Code Style\n- Run `make ci-pr-lint` before committing changes to Go or lint-controlled files\n- Follow existing patterns in `cmd/bd/` for new commands\n- Add `--json` flag to all commands for programmatic use\n- Update docs when changing behavior\n\n### Git Workflow\n- Install git hooks: `bd hooks install`\n- Use `bd dolt push` / `bd dolt pull` for remote sync\n- Before implementing related work, opening a PR, or merging/closing a PR, run:\n `scripts/pr-preflight.sh --search \"\" --repo gastownhall/beads` or\n `scripts/pr-preflight.sh --repo gastownhall/beads`\n- External contributor PRs have priority: build on them when possible, preserve\n tests and attribution, and never close or replace them silently.\n\n## Issue Tracking with bd\n\n**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.\n\n### Essential Commands\n\n```bash\n# Find work\nbd ready --json # Unblocked issues\nbd stale --days 30 --json # Forgotten issues\n\n# Create and manage (ALWAYS include --description)\nbd create \"Title\" --description=\"Detailed context\" -t bug|feature|task -p 0-4 --json\nbd update --claim --json\nbd close --reason \"Done\" --json\n\n# Search\nbd list --status open --priority 1 --json\nbd show --json\n\n# Sync (if remote configured)\nbd dolt push # Push to Dolt remote\nbd dolt pull # Pull from Dolt remote\n```\n\n### Workflow\n\n1. **Check ready work**: `bd ready --json`\n2. **Claim task**: `bd update --claim`\n3. **Work on it**: Implement, test, document\n4. **Discover new work?** `bd create \"Found bug\" --description=\"What was found and why\" -p 1 --deps discovered-from: --json`\n5. **Complete**: `bd close --reason \"Done\" --json`\n6. **Sync**: `bd dolt push` (push to Dolt remote if configured)\n\n**IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work.\n\n### Priorities\n\n- `0` - Critical (security, data loss, broken builds)\n- `1` - High (major features, important bugs)\n- `2` - Medium (default, nice-to-have)\n- `3` - Low (polish, optimization)\n- `4` - Backlog (future ideas)\n\n## Project Structure\n\n```\nbeads/\nā”œā”€ā”€ cmd/bd/ # CLI commands (add new commands here)\nā”œā”€ā”€ internal/\nā”‚ ā”œā”€ā”€ types/ # Core data types\nā”‚ ā””ā”€ā”€ storage/ # Storage layer\nā”‚ ā””ā”€ā”€ dolt/ # Dolt implementation\nā”œā”€ā”€ integrations/\nā”‚ ā””ā”€ā”€ beads-mcp/ # MCP server (Python)\nā”œā”€ā”€ examples/ # Integration examples\nā”œā”€ā”€ docs/ # Documentation\nā””ā”€ā”€ .beads/\n ā””ā”€ā”€ dolt/ # Dolt database (source of truth)\n```\n\n## Available Resources\n\n### MCP Server (Recommended)\nUse the beads MCP server for native function calls instead of shell commands:\n- Install: `pip install beads-mcp`\n- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.\n- See `integrations/beads-mcp/README.md`\n\n### Scripts\n- `./scripts/bump-version.sh --commit` - Update all version files atomically\n- `./scripts/release.sh ` - Complete release workflow\n- `./scripts/update-homebrew.sh ` - Update Homebrew formula\n\n### Key Documentation\n- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)\n- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases\n- **README.md** - User-facing documentation\n- **docs/CLI_REFERENCE.md** - Complete command reference\n\n## Important Rules\n\n- āœ… Use bd for ALL task tracking\n- āœ… Always use `--json` flag for programmatic use\n- āœ… Use `bd dolt push` / `bd dolt pull` for remote sync\n- āœ… Test with `t.TempDir() in Go tests`\n- āŒ Do NOT create markdown TODO lists\n- āŒ Do NOT create test issues in production DB\n- āŒ Do NOT manually modify `.beads/dolt/`\n\n---\n\n**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Agent Instructions\n\n\n\nSee [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full instructions.\n\nThis file exists for compatibility with tools that look for AGENTS.md.\n\nThe marker above tells `bd doctor` that the intentional divergence between\nthis file and `CLAUDE.md` (different audiences, different reading orders) is\nexpected and should not be flagged.\n\n## Key Sections\n\n- **Issue Tracking** - How to use bd for work management\n- **Development Guidelines** - Code standards and testing\n- **Project Scope** - Read [engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md) before adding new feature surface area\n- **Visual Design System** - Status icons, colors, and semantic styling for CLI output\n- **Contributor Protection** - Read [CONTRIBUTING.md](CONTRIBUTING.md) before handling external PRs\n- **Maintainer PR Guidelines** - Read [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md) before triaging, landing, or closing PRs\n\n## Project Scope\n\nBefore adding new feature surface area, read\n[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md). Beads owns issue tracking\nprimitives and should not encode orchestration-layer policy, become a storage\nengine, or casually expand the database schema when metadata would work.\n\n## PR Safety for Agents\n\nBefore triaging, reviewing, landing, closing, or otherwise maintaining PRs, read\n[PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md). The maintainer\npolicy is to maximize community throughput: find useful contributor value,\nabsorb or transform it locally when practical, preserve attribution, and use\nrequest-changes only as a last resort.\n\nBefore implementing work, opening a PR, or merging/closing a PR, run the PR\npreflight:\n```bash\nscripts/pr-preflight.sh --search \"\" --repo gastownhall/beads\nscripts/pr-preflight.sh --repo gastownhall/beads\n```\n\nExternal contributor PRs have priority. Review and build on their branch when\npossible, preserve their tests and attribution, and never close or supersede\ntheir PR silently. If a rewrite is unavoidable, explain why on the original PR\nand credit their design/tests.\n\n## Visual Design Anti-Patterns\n\n**NEVER use emoji-style icons** (šŸ”“šŸŸ šŸŸ”šŸ”µāšŖ) in CLI output. They cause cognitive overload.\n\n**ALWAYS use small Unicode symbols** with semantic colors (status uses symbols; priority uses labels):\n- Status: `ā—‹ ā— ā— āœ“ ā„`\n- Priority: `P0`ā€“`P4` label with color (no status glyph)\n\nSee [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for full development guidelines.\n\n## Storage Boundary\n\nThe canonical storage boundary is in\n[engdocs/PROJECT_CHARTER.md](engdocs/PROJECT_CHARTER.md#storage-boundary). In short:\nBeads talks to storage through a driver interface (`dolthub/driver` for Dolt).\nDo not add beads-side flocks, engine introspection, storage-specific retry or\ncrash-recovery logic, or public SDK return types that leak driver internals.\nIf the boundary is too narrow, widen the interface or route the issue to the\ndriver instead of patching around it in beads.\n\nA live application of this rule: `bd doctor` support for embedded mode is\nenabled one subcommand at a time, each human-vetted (GH#3794). Do not lift the\nembedded-mode gate in `cmd/bd/doctor.go` wholesale, and keep database-layer\nchecks and fixes server-gated until the driver interface covers them.\n\n## Agent Warning: Interactive Commands\n\n**DO NOT use `bd edit`** - it opens an interactive editor ($EDITOR) which AI agents cannot use.\n\nUse `bd update` with flags instead:\n```bash\nbd update --description \"new description\"\nbd update --title \"new title\"\nbd update --design \"design notes\"\nbd update --notes \"additional notes\"\nbd update --acceptance \"acceptance criteria\"\n\n# Use stdin for descriptions with special characters (backticks, !, nested quotes)\necho 'Description with `backticks` and \"quotes\"' | bd create \"Title\" --description=-\necho 'Updated text' | bd update --description=-\n```\n\n## Testing\n\nUse [engdocs/TESTING.md](engdocs/TESTING.md) for the canonical commands,\ntest-design guidance, and PR-readiness gates.\n\n## Non-Interactive Shell Commands\n\n**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.\n\nShell 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.\n\n**Use these forms instead:**\n```bash\n# Force overwrite without prompting\ncp -f source dest # NOT: cp source dest\nmv -f source dest # NOT: mv source dest\nrm -f file # NOT: rm file\n\n# For recursive operations\nrm -rf directory # NOT: rm -r directory\ncp -rf source dest # NOT: cp -r source dest\n```\n\n**Other commands that may prompt:**\n- `scp` - use `-o BatchMode=yes` for non-interactive\n- `ssh` - use `-o BatchMode=yes` to fail instead of prompting\n- `apt-get` - use `-y` flag\n- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var\n\n## Landing the Plane (Session Completion)\n\n**When ending a work session** (or when the user says \"let's land the\nplane\"), you MUST complete ALL steps below. Work is NOT complete until\n`git push` succeeds.\n\n**MANDATORY WORKFLOW:**\n\n1. **File issues for remaining work** - Create issues for anything that needs follow-up\n2. **Run quality gates** (if code changed):\n - `make ci-pr-lint` (required zero-finding formatting and lint wrapper)\n - `make test` (and `make test-icu-path` only if you intentionally need the ICU regex path)\n - File a P0 issue if quality gates are broken\n3. **Update issue status** - Close finished work, update in-progress items\n4. **PUSH TO REMOTE** - This is MANDATORY:\n ```bash\n git pull --rebase\n git push\n git status # MUST show \"up to date with origin\"\n ```\n5. **Clean up**:\n ```bash\n git stash clear # Remove old stashes\n git remote prune origin # Clean up deleted remote branches\n ```\n6. **Verify** - All changes committed AND pushed, no untracked files remain\n7. **Hand off** - Choose a follow-up issue and give the user a prompt for\n the next session, e.g. \"Continue work on bd-X: [issue title]. [Brief\n context about what's been done and what's next]\"\n\n**CRITICAL RULES:**\n- Work is NOT complete until `git push` succeeds\n- NEVER stop before pushing - that leaves work stranded locally\n- NEVER say \"ready to push when you are\" - YOU must push\n- If push fails, resolve and retry until it succeeds\n\nClose with a summary for the user: what was completed this session, issues\nfiled for follow-up, quality-gate status, confirmation everything is pushed,\nand the recommended prompt for the next session.\n\n\n## Issue Tracking with bd (beads)\n\n**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.\n\n### Why bd?\n\n- Dependency-aware: Track blockers and relationships between issues\n- Git-friendly: Dolt-powered version control with native sync\n- Agent-optimized: JSON output, ready work detection, discovered-from links\n- Prevents duplicate tracking systems and confusion\n\n### Quick Start\n\n**Check for ready work:**\n\n```bash\nbd ready --json\n```\n\n**Create new issues:**\n\n```bash\nbd create \"Issue title\" --description=\"Detailed context\" -t bug|feature|task -p 0-4 --json\nbd create \"Issue title\" --description=\"What this issue is about\" -p 1 --deps discovered-from:bd-123 --json\n```\n\n**Claim and update:**\n\n```bash\nbd update --claim --json\nbd update bd-42 --priority 1 --json\n```\n\n**Complete work:**\n\n```bash\nbd close bd-42 --reason \"Completed\" --json\n```\n\n### Issue Types\n\n- `bug` - Something broken\n- `feature` - New functionality\n- `task` - Work item (tests, docs, refactoring)\n- `epic` - Large feature with subtasks\n- `chore` - Maintenance (dependencies, tooling)\n\n### Priorities\n\n- `0` - Critical (security, data loss, broken builds)\n- `1` - High (major features, important bugs)\n- `2` - Medium (default, nice-to-have)\n- `3` - Low (polish, optimization)\n- `4` - Backlog (future ideas)\n\n### Workflow for AI Agents\n\n1. **Check ready work**: `bd ready` shows unblocked issues\n2. **Claim your task atomically**: `bd update --claim`\n3. **Work on it**: Implement, test, document\n4. **Discover new work?** Create linked issue:\n - `bd create \"Found bug\" --description=\"Details about what was found\" -p 1 --deps discovered-from:`\n5. **Complete**: `bd close --reason \"Done\"`\n\n### Quality\n- Use `--acceptance` and `--design` fields when creating issues\n- Use `--validate` to check description completeness\n\n### Lifecycle\n- `bd defer ` / `bd supersede ` for issue management\n- `bd stale` / `bd orphans` / `bd lint` for hygiene\n- `bd human ` to flag for human decisions\n- `bd formula list` / `bd mol pour ` for structured workflows\n\n### Sync\n\nbd stores issue history in Dolt:\n\n- Each write auto-commits to Dolt history\n- Use `bd dolt push`/`bd dolt pull` for remote sync\n- Do not treat `.beads/issues.jsonl` as the sync protocol\n\n**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.\n\n### Important Rules\n\n- āœ… Use bd for ALL task tracking\n- āœ… Always use `--json` flag for programmatic use\n- āœ… Link discovered work with `discovered-from` dependencies\n- āœ… Check `bd ready` before asking \"what should I work on?\"\n- āŒ Do NOT create markdown TODO lists\n- āŒ Do NOT use external issue trackers\n- āŒ Do NOT duplicate tracking systems\n\nFor more details, see README.md and https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md.\n\n## Agent Context Profiles\n\nThe managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions.\n\n- **Conservative (default)**: Use `bd` for 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.\n- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise.\n- **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.\n\n## Session Completion\n\nThis protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions.\n\n1. **File issues for remaining work** - Create beads for anything that needs follow-up\n2. **Run quality gates** (if code changed) - Tests, linters, builds\n3. **Update issue status** - Close finished work, update in-progress items\n4. **Handle git/sync by active profile**:\n ```bash\n # Conservative/minimal/default: report status and proposed commands; wait for approval.\n git status\n\n # Team-maintainer opt-in only, unless current instructions forbid it:\n git pull --rebase\n bd dolt push\n git push\n git status\n ```\n5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step\n\n**Critical rules:**\n- Explicit user or orchestrator instructions override this Beads block.\n- Do not commit or push without clear authority from the active profile or the current user request.\n- If a required sync or push is blocked, stop and report the exact command and error.\n\n\n","category":"root","tokens":2917},{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude Code Entry Point for Beads\n\nThis file is intentionally short. Do not copy workflow, build, storage, or UI\nrules here; those details drift quickly when repeated across agent entrypoints.\n\n## Read First\n\n- **Workflow and safety**: [AGENTS.md](AGENTS.md)\n- **Detailed agent operations**: [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md)\n- **Architecture orientation**: [engdocs/CLAUDE.md](engdocs/CLAUDE.md)\n- **PR maintenance policy**: [PR_MAINTAINER_GUIDELINES.md](PR_MAINTAINER_GUIDELINES.md)\n\n## Current Ground Rules\n\n- Run `bd prime` before doing tracked work.\n- Follow `go.mod` and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md) for build\n and test commands; do not hard-code toolchain versions here.\n- Beads uses Dolt as the issue database. Use `bd dolt push` / `bd dolt pull`\n for issue data sync; do not use export/import as a routine git workflow.\n- The CLI Visual Design System lives in\n [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md#visual-design-system).\n- If this file conflicts with a linked source, trust the linked source and fix\n this file by removing the duplicate.\n","category":"root","tokens":274},{"name":"copilot-instructions.md","path":".github/copilot-instructions.md","title":"copilot-instructions.md","content":"# GitHub Copilot Instructions for Beads\n\n## Project Overview\n\n**beads** (command: `bd`) is a Dolt-powered issue tracker designed for AI-supervised coding workflows. Git integration is optional. We dogfood our own tool for all task tracking.\n\n**Key Features:**\n- Dependency-aware issue tracking\n- Auto-sync via Dolt-native replication\n- AI-optimized CLI with JSON output\n- Dolt server mode for background operations\n- MCP server integration for Claude and other AI assistants\n\n## Tech Stack\n\n- **Language**: Go 1.21+\n- **Storage**: Dolt (version-controlled SQL database)\n- **CLI Framework**: Cobra\n- **Testing**: Go standard testing + table-driven tests\n- **CI/CD**: GitHub Actions\n- **MCP Server**: Python (integrations/beads-mcp/)\n\n## Coding Guidelines\n\n### Testing\n- Always write tests for new features\n- Use `t.TempDir() in Go tests` to avoid polluting production database\n- Run `go test -short ./...` before committing\n- Never create test issues in production DB (use temporary DB)\n\n### Code Style\n- Run `make ci-pr-lint` before committing changes to Go or lint-controlled files\n- Follow existing patterns in `cmd/bd/` for new commands\n- Add `--json` flag to all commands for programmatic use\n- Update docs when changing behavior\n\n### Git Workflow\n- Install git hooks: `bd hooks install`\n- Use `bd dolt push` / `bd dolt pull` for remote sync\n- Before implementing related work, opening a PR, or merging/closing a PR, run:\n `scripts/pr-preflight.sh --search \"\" --repo gastownhall/beads` or\n `scripts/pr-preflight.sh --repo gastownhall/beads`\n- External contributor PRs have priority: build on them when possible, preserve\n tests and attribution, and never close or replace them silently.\n\n## Issue Tracking with bd\n\n**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists.\n\n### Essential Commands\n\n```bash\n# Find work\nbd ready --json # Unblocked issues\nbd stale --days 30 --json # Forgotten issues\n\n# Create and manage (ALWAYS include --description)\nbd create \"Title\" --description=\"Detailed context\" -t bug|feature|task -p 0-4 --json\nbd update --claim --json\nbd close --reason \"Done\" --json\n\n# Search\nbd list --status open --priority 1 --json\nbd show --json\n\n# Sync (if remote configured)\nbd dolt push # Push to Dolt remote\nbd dolt pull # Pull from Dolt remote\n```\n\n### Workflow\n\n1. **Check ready work**: `bd ready --json`\n2. **Claim task**: `bd update --claim`\n3. **Work on it**: Implement, test, document\n4. **Discover new work?** `bd create \"Found bug\" --description=\"What was found and why\" -p 1 --deps discovered-from: --json`\n5. **Complete**: `bd close --reason \"Done\" --json`\n6. **Sync**: `bd dolt push` (push to Dolt remote if configured)\n\n**IMPORTANT**: Always include `--description` when creating issues. Issues without descriptions lack context for future work.\n\n### Priorities\n\n- `0` - Critical (security, data loss, broken builds)\n- `1` - High (major features, important bugs)\n- `2` - Medium (default, nice-to-have)\n- `3` - Low (polish, optimization)\n- `4` - Backlog (future ideas)\n\n## Project Structure\n\n```\nbeads/\nā”œā”€ā”€ cmd/bd/ # CLI commands (add new commands here)\nā”œā”€ā”€ internal/\nā”‚ ā”œā”€ā”€ types/ # Core data types\nā”‚ ā””ā”€ā”€ storage/ # Storage layer\nā”‚ ā””ā”€ā”€ dolt/ # Dolt implementation\nā”œā”€ā”€ integrations/\nā”‚ ā””ā”€ā”€ beads-mcp/ # MCP server (Python)\nā”œā”€ā”€ examples/ # Integration examples\nā”œā”€ā”€ docs/ # Documentation\nā””ā”€ā”€ .beads/\n ā””ā”€ā”€ dolt/ # Dolt database (source of truth)\n```\n\n## Available Resources\n\n### MCP Server (Recommended)\nUse the beads MCP server for native function calls instead of shell commands:\n- Install: `pip install beads-mcp`\n- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc.\n- See `integrations/beads-mcp/README.md`\n\n### Scripts\n- `./scripts/bump-version.sh --commit` - Update all version files atomically\n- `./scripts/release.sh ` - Complete release workflow\n- `./scripts/update-homebrew.sh ` - Update Homebrew formula\n\n### Key Documentation\n- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features)\n- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases\n- **README.md** - User-facing documentation\n- **docs/CLI_REFERENCE.md** - Complete command reference\n\n## Important Rules\n\n- āœ… Use bd for ALL task tracking\n- āœ… Always use `--json` flag for programmatic use\n- āœ… Use `bd dolt push` / `bd dolt pull` for remote sync\n- āœ… Test with `t.TempDir() in Go tests`\n- āŒ Do NOT create markdown TODO lists\n- āŒ Do NOT create test issues in production DB\n- āŒ Do NOT manually modify `.beads/dolt/`\n\n---\n\n**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**\n","category":".github","tokens":1209}]}