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 <noreply@anthropic.com>
This commit is contained in:
Steve Yegge
132
.github/copilot-instructions.md
vendored
Normal file
132
.github/copilot-instructions.md
vendored
Normal file
@@ -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 <id> --status in_progress --json
|
||||
bd close <id> --reason "Done" --json
|
||||
|
||||
# Search
|
||||
bd list --status open --priority 1 --json
|
||||
bd show <id> --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 <id> --status in_progress`
|
||||
3. **Work on it**: Implement, test, document
|
||||
4. **Discover new work?** `bd create "Found bug" -p 1 --deps discovered-from:<parent-id> --json`
|
||||
5. **Complete**: `bd close <id> --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 <version> --commit` - Update all version files atomically
|
||||
- `./scripts/release.sh <version>` - Complete release workflow
|
||||
- `./scripts/update-homebrew.sh <version>` - 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)**
|
||||
@@ -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:
|
||||
|
||||
@@ -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 <id> --status in_progress --json
|
||||
bd close <id> --reason "Done" --json
|
||||
|
||||
# Search
|
||||
bd list --status open --priority 1 --json
|
||||
bd show <id> --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 <id> --status in_progress`" + `
|
||||
3. **Work on it**: Implement, test, document
|
||||
4. **Discover new work?** ` + "`bd create \"Found bug\" -p 1 --deps discovered-from:<parent-id> --json`" + `
|
||||
5. **Complete**: ` + "`bd close <id> --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 <version> --commit`" + ` - Update all version files atomically
|
||||
- ` + "`./scripts/release.sh <version>`" + ` - Complete release workflow
|
||||
- ` + "`./scripts/update-homebrew.sh <version>`" + ` - 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 {
|
||||
|
||||
Reference in New Issue
Block a user