From 605fff151ee77e69044ffb9491e101cdfc77d2bc Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Fri, 21 Nov 2025 20:51:50 -0500 Subject: [PATCH] feat: Add GitHub Copilot support with .github/copilot-instructions.md Addresses GH #298 - GitHub Copilot inconsistently interpreting AGENTS.md Changes: - Create .github/copilot-instructions.md (132 lines, Copilot-optimized) - Update AGENTS.md with prominent Copilot callout - Enhance bd onboard command to generate copilot-instructions.md Architecture: Two-file approach for different AI agents - AGENTS.md (626 lines): Comprehensive guide for all AI agents - .github/copilot-instructions.md (132 lines): Concise, auto-loaded for Copilot Note: Untested with GitHub Copilot yet. Feedback from Copilot users welcome! Co-authored-by: Claude --- .github/copilot-instructions.md | 132 +++++++++++++++++++++++++ AGENTS.md | 2 + cmd/bd/onboard.go | 165 +++++++++++++++++++++++++++++++- 3 files changed, 297 insertions(+), 2 deletions(-) create mode 100644 .github/copilot-instructions.md diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md new file mode 100644 index 00000000..0c6b3c7a --- /dev/null +++ b/.github/copilot-instructions.md @@ -0,0 +1,132 @@ +# GitHub Copilot Instructions for Beads + +## Project Overview + +**beads** (command: `bd`) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking. + +**Key Features:** +- Dependency-aware issue tracking +- Auto-sync with Git via JSONL +- AI-optimized CLI with JSON output +- Built-in daemon for background operations +- MCP server integration for Claude and other AI assistants + +## Tech Stack + +- **Language**: Go 1.21+ +- **Storage**: SQLite (internal/storage/sqlite/) +- **CLI Framework**: Cobra +- **Testing**: Go standard testing + table-driven tests +- **CI/CD**: GitHub Actions +- **MCP Server**: Python (integrations/beads-mcp/) + +## Coding Guidelines + +### Testing +- Always write tests for new features +- Use `BEADS_DB=/tmp/test.db` to avoid polluting production database +- Run `go test -short ./...` before committing +- Never create test issues in production DB (use temporary DB) + +### Code Style +- Run `golangci-lint run ./...` before committing +- Follow existing patterns in `cmd/bd/` for new commands +- Add `--json` flag to all commands for programmatic use +- Update docs when changing behavior + +### Git Workflow +- Always commit `.beads/issues.jsonl` with code changes +- Run `bd sync` at end of work sessions +- Install git hooks: `bd hooks install` (ensures DB ↔ JSONL consistency) + +## Issue Tracking with bd + +**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists. + +### Essential Commands + +```bash +# Find work +bd ready --json # Unblocked issues +bd stale --days 30 --json # Forgotten issues + +# Create and manage +bd create "Title" -t bug|feature|task -p 0-4 --json +bd update --status in_progress --json +bd close --reason "Done" --json + +# Search +bd list --status open --priority 1 --json +bd show --json + +# Sync (CRITICAL at end of session!) +bd sync # Force immediate export/commit/push +``` + +### Workflow + +1. **Check ready work**: `bd ready --json` +2. **Claim task**: `bd update --status in_progress` +3. **Work on it**: Implement, test, document +4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from: --json` +5. **Complete**: `bd close --reason "Done" --json` +6. **Sync**: `bd sync` (flushes changes to git immediately) + +### 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) + +## Project Structure + +``` +beads/ +├── cmd/bd/ # CLI commands (add new commands here) +├── internal/ +│ ├── types/ # Core data types +│ └── storage/ # Storage layer +│ └── sqlite/ # SQLite implementation +├── integrations/ +│ └── beads-mcp/ # MCP server (Python) +├── examples/ # Integration examples +├── docs/ # Documentation +└── .beads/ + ├── beads.db # SQLite database (DO NOT COMMIT) + └── issues.jsonl # Git-synced issue storage +``` + +## Available Resources + +### MCP Server (Recommended) +Use the beads MCP server for native function calls instead of shell commands: +- Install: `pip install beads-mcp` +- Functions: `mcp__beads__ready()`, `mcp__beads__create()`, etc. +- See `integrations/beads-mcp/README.md` + +### Scripts +- `./scripts/bump-version.sh --commit` - Update all version files atomically +- `./scripts/release.sh ` - Complete release workflow +- `./scripts/update-homebrew.sh ` - Update Homebrew formula + +### Key Documentation +- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features) +- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases +- **README.md** - User-facing documentation +- **docs/CLI_REFERENCE.md** - Complete command reference + +## Important Rules + +- ✅ Use bd for ALL task tracking +- ✅ Always use `--json` flag for programmatic use +- ✅ Run `bd sync` at end of sessions +- ✅ Test with `BEADS_DB=/tmp/test.db` +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT create test issues in production DB +- ❌ Do NOT commit `.beads/beads.db` (JSONL only) + +--- + +**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)** diff --git a/AGENTS.md b/AGENTS.md index 83fad5d3..fe43ee29 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,8 @@ This is **beads** (command: `bd`), an issue tracker designed for AI-supervised coding workflows. We dogfood our own tool! +> **🤖 Using GitHub Copilot?** See [.github/copilot-instructions.md](.github/copilot-instructions.md) for a concise, Copilot-optimized version of these instructions that GitHub Copilot will automatically load. + ## 🆕 What's New? **New to bd or upgrading?** Run `bd info --whats-new` to see agent-relevant changes from recent versions: diff --git a/cmd/bd/onboard.go b/cmd/bd/onboard.go index 47e521bb..84a7ab59 100644 --- a/cmd/bd/onboard.go +++ b/cmd/bd/onboard.go @@ -9,6 +9,139 @@ import ( "github.com/spf13/cobra" ) +const copilotInstructionsContent = `# GitHub Copilot Instructions for Beads + +## Project Overview + +**beads** (command: ` + "`bd`" + `) is a Git-backed issue tracker designed for AI-supervised coding workflows. We dogfood our own tool for all task tracking. + +**Key Features:** +- Dependency-aware issue tracking +- Auto-sync with Git via JSONL +- AI-optimized CLI with JSON output +- Built-in daemon for background operations +- MCP server integration for Claude and other AI assistants + +## Tech Stack + +- **Language**: Go 1.21+ +- **Storage**: SQLite (internal/storage/sqlite/) +- **CLI Framework**: Cobra +- **Testing**: Go standard testing + table-driven tests +- **CI/CD**: GitHub Actions +- **MCP Server**: Python (integrations/beads-mcp/) + +## Coding Guidelines + +### Testing +- Always write tests for new features +- Use ` + "`BEADS_DB=/tmp/test.db`" + ` to avoid polluting production database +- Run ` + "`go test -short ./...`" + ` before committing +- Never create test issues in production DB (use temporary DB) + +### Code Style +- Run ` + "`golangci-lint run ./...`" + ` before committing +- Follow existing patterns in ` + "`cmd/bd/`" + ` for new commands +- Add ` + "`--json`" + ` flag to all commands for programmatic use +- Update docs when changing behavior + +### Git Workflow +- Always commit ` + "`.beads/issues.jsonl`" + ` with code changes +- Run ` + "`bd sync`" + ` at end of work sessions +- Install git hooks: ` + "`bd hooks install`" + ` (ensures DB ↔ JSONL consistency) + +## Issue Tracking with bd + +**CRITICAL**: This project uses **bd** for ALL task tracking. Do NOT create markdown TODO lists. + +### Essential Commands + +` + "```bash" + ` +# Find work +bd ready --json # Unblocked issues +bd stale --days 30 --json # Forgotten issues + +# Create and manage +bd create "Title" -t bug|feature|task -p 0-4 --json +bd update --status in_progress --json +bd close --reason "Done" --json + +# Search +bd list --status open --priority 1 --json +bd show --json + +# Sync (CRITICAL at end of session!) +bd sync # Force immediate export/commit/push +` + "```" + ` + +### Workflow + +1. **Check ready work**: ` + "`bd ready --json`" + ` +2. **Claim task**: ` + "`bd update --status in_progress`" + ` +3. **Work on it**: Implement, test, document +4. **Discover new work?** ` + "`bd create \"Found bug\" -p 1 --deps discovered-from: --json`" + ` +5. **Complete**: ` + "`bd close --reason \"Done\" --json`" + ` +6. **Sync**: ` + "`bd sync`" + ` (flushes changes to git immediately) + +### 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) + +## Project Structure + +` + "```" + ` +beads/ +├── cmd/bd/ # CLI commands (add new commands here) +├── internal/ +│ ├── types/ # Core data types +│ └── storage/ # Storage layer +│ └── sqlite/ # SQLite implementation +├── integrations/ +│ └── beads-mcp/ # MCP server (Python) +├── examples/ # Integration examples +├── docs/ # Documentation +└── .beads/ + ├── beads.db # SQLite database (DO NOT COMMIT) + └── issues.jsonl # Git-synced issue storage +` + "```" + ` + +## Available Resources + +### MCP Server (Recommended) +Use the beads MCP server for native function calls instead of shell commands: +- Install: ` + "`pip install beads-mcp`" + ` +- Functions: ` + "`mcp__beads__ready()`" + `, ` + "`mcp__beads__create()`" + `, etc. +- See ` + "`integrations/beads-mcp/README.md`" + ` + +### Scripts +- ` + "`./scripts/bump-version.sh --commit`" + ` - Update all version files atomically +- ` + "`./scripts/release.sh `" + ` - Complete release workflow +- ` + "`./scripts/update-homebrew.sh `" + ` - Update Homebrew formula + +### Key Documentation +- **AGENTS.md** - Comprehensive AI agent guide (detailed workflows, advanced features) +- **AGENT_INSTRUCTIONS.md** - Development procedures, testing, releases +- **README.md** - User-facing documentation +- **docs/CLI_REFERENCE.md** - Complete command reference + +## Important Rules + +- ✅ Use bd for ALL task tracking +- ✅ Always use ` + "`--json`" + ` flag for programmatic use +- ✅ Run ` + "`bd sync`" + ` at end of sessions +- ✅ Test with ` + "`BEADS_DB=/tmp/test.db`" + ` +- ❌ Do NOT create markdown TODO lists +- ❌ Do NOT create test issues in production DB +- ❌ Do NOT commit ` + "`.beads/beads.db`" + ` (JSONL only) + +--- + +**For detailed workflows and advanced features, see [AGENTS.md](../AGENTS.md)**` + const agentsContent = `## 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. @@ -77,6 +210,11 @@ bd automatically syncs with git: - 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: @@ -190,7 +328,30 @@ func renderOnboardInstructions(w io.Writer) error { return err } - if err := writef("%s\n", bold("2. Update CLAUDE.md (if present)")); err != nil { + if err := writef("%s\n", bold("2. Create .github/copilot-instructions.md (for GitHub Copilot)")); err != nil { + return err + } + if err := writeln(" GitHub Copilot automatically loads instructions from .github/copilot-instructions.md"); err != nil { + return err + } + if err := writeln(" Create the .github directory if it doesn't exist, then add this file:"); err != nil { + return err + } + if err := writeBlank(); err != nil { + return err + } + + if err := writef("%s\n", cyan("--- BEGIN .GITHUB/COPILOT-INSTRUCTIONS.MD CONTENT ---")); err != nil { + return err + } + if err := writeln(copilotInstructionsContent); err != nil { + return err + } + if err := writef("%s\n\n", cyan("--- END .GITHUB/COPILOT-INSTRUCTIONS.MD CONTENT ---")); err != nil { + return err + } + + if err := writef("%s\n", bold("3. Update CLAUDE.md (if present)")); err != nil { return err } if err := writeln(" If CLAUDE.md exists in this directory, add this note at the top:"); err != nil { @@ -212,7 +373,7 @@ func renderOnboardInstructions(w io.Writer) error { return err } - if err := writef("%s\n", bold("3. Remove bootstrap instruction")); err != nil { + if err := writef("%s\n", bold("4. Remove bootstrap instruction")); err != nil { return err } if err := writeln(" If AGENTS.md or CLAUDE.md contains a line like:"); err != nil {