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!
|
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?
|
## 🆕 What's New?
|
||||||
|
|
||||||
**New to bd or upgrading?** Run `bd info --whats-new` to see agent-relevant changes from recent versions:
|
**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"
|
"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)
|
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.
|
**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`" + `)
|
- Imports from JSONL when newer (e.g., after ` + "`git pull`" + `)
|
||||||
- No manual export/import needed!
|
- 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)
|
### MCP Server (Recommended)
|
||||||
|
|
||||||
If using Claude or MCP-compatible clients, install the beads MCP server:
|
If using Claude or MCP-compatible clients, install the beads MCP server:
|
||||||
@@ -190,7 +328,30 @@ func renderOnboardInstructions(w io.Writer) error {
|
|||||||
return err
|
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
|
return err
|
||||||
}
|
}
|
||||||
if err := writeln(" If CLAUDE.md exists in this directory, add this note at the top:"); err != nil {
|
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
|
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
|
return err
|
||||||
}
|
}
|
||||||
if err := writeln(" If AGENTS.md or CLAUDE.md contains a line like:"); err != nil {
|
if err := writeln(" If AGENTS.md or CLAUDE.md contains a line like:"); err != nil {
|
||||||
|
|||||||
Reference in New Issue
Block a user