feat: add Copilot CLI setup recipe (#3839)

Adds `bd setup copilot` as a recipe-driven integration that installs a native Copilot CLI plugin manifest (.copilot-plugin/plugin.json) with SessionStart/PreCompact hooks and repository instructions (.github/copilot-instructions.md).

Co-authored-by: Julian Palmerio <julianpalmerio@hotmail.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
This commit is contained in:
Julian Palmerio 2026-05-14 14:51:38 -03:00 • committed by GitHub
commit 25703f8635
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
19 changed files with 402 additions and 38 deletions

View file

@ -203,5 +203,5 @@ For daemon mode without git, use `bd daemon start --local`
## 📝 Documentation
* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/INSTALLING.md) | [Sync Concepts](docs/SYNC_CONCEPTS.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot Setup](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
* [Documentation site](https://gastownhall.github.io/beads/) (versioned) | [Installing](docs/INSTALLING.md) | [Sync Concepts](docs/SYNC_CONCEPTS.md) | [Agent Workflow](AGENT_INSTRUCTIONS.md) | [Copilot CLI Setup](docs/COPILOT_CLI_INTEGRATION.md) | [Copilot VS Code MCP](docs/COPILOT_INTEGRATION.md) | [Articles](ARTICLES.md) | [Sync Branch Mode](docs/PROTECTED_BRANCHES.md) | [Troubleshooting](docs/TROUBLESHOOTING.md) | [FAQ](docs/FAQ.md)
* [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/gastownhall/beads)

View file

@ -621,12 +621,12 @@ func runDiagnostics(path string) doctorResult {
result.Checks = append(result.Checks, bdPrimeOutputCheck)
// Don't fail overall check for prime output issues, just warn
// Check 11e: bd in PATH (needed for Claude hooks to work)
// Check 11d: bd in PATH (needed for Claude hooks and other integrations)
bdPathCheck := convertWithCategory(doctor.CheckBdInPath(), doctor.CategoryIntegration)
result.Checks = append(result.Checks, bdPathCheck)
// Don't fail overall check for missing bd in PATH, just warn
// Check 11f: Documentation bd prime references match installed version
// Check 11e: Documentation bd prime references match installed version
bdPrimeDocsCheck := convertWithCategory(doctor.CheckDocumentationBdPrimeReference(path), doctor.CategoryIntegration)
result.Checks = append(result.Checks, bdPrimeDocsCheck)
// Don't fail overall check for doc mismatch, just warn

View file

@ -21,6 +21,7 @@ func agentDocFiles(repoPath string) []string {
files := []string{
filepath.Join(repoPath, agentsFile),
filepath.Join(repoPath, "CLAUDE.md"),
filepath.Join(repoPath, ".github", "copilot-instructions.md"),
filepath.Join(repoPath, ".claude", "CLAUDE.md"),
// Local-only variants (not committed to repo)
filepath.Join(repoPath, "claude.local.md"),

View file

@ -32,12 +32,13 @@ var setupCmd = &cobra.Command{
Long: `Setup integration files for AI editors and coding assistants.
Recipes define where beads workflow instructions are written. Built-in recipes
include cursor, claude, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
Examples:
bd setup cursor # Install Cursor IDE integration
bd setup codex # Install Codex skill + AGENTS.md guidance
bd setup codex --global # Install global Codex skill + global AGENTS.md guidance
bd setup copilot # Install Copilot CLI plugin + repository instructions
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
bd setup mux --project --global # Install both Mux layers
@ -238,29 +239,56 @@ func runRecipe(name string) {
FatalErrorWithHint(fmt.Sprintf("%v", err), "Use 'bd setup --list' to see available recipes.")
}
if recipe.Type != recipes.TypeFile {
if recipe.Type != recipes.TypeFile && recipe.Type != recipes.TypeMultiFile {
FatalError("recipe '%s' has type '%s' which requires special handling", name, recipe.Type)
}
paths := recipe.Paths
if recipe.Type == recipes.TypeFile {
paths = []string{recipe.Path}
}
// Handle --check
if setupCheck {
if _, err := os.Stat(recipe.Path); os.IsNotExist(err) {
var missing []string
for _, path := range paths {
if _, err := os.Stat(path); os.IsNotExist(err) {
missing = append(missing, path)
}
}
if len(missing) > 0 {
fmt.Printf("✗ %s integration not installed\n", recipe.Name)
fmt.Printf(" Run: bd setup %s\n", name)
for _, path := range missing {
fmt.Printf(" Missing: %s\n", path)
}
os.Exit(1)
}
fmt.Printf("✓ %s integration installed: %s\n", recipe.Name, recipe.Path)
fmt.Printf("✓ %s integration installed\n", recipe.Name)
for _, path := range paths {
fmt.Printf(" File: %s\n", path)
}
return
}
// Handle --remove
if setupRemove {
if err := os.Remove(recipe.Path); err != nil {
if os.IsNotExist(err) {
fmt.Println("No integration file found")
return
removed := false
for _, path := range paths {
if err := os.Remove(path); err != nil {
if os.IsNotExist(err) {
continue
}
FatalError("%v", err)
}
FatalError("%v", err)
removed = true
// Best-effort cleanup for recipe-created parent directories. This only
// succeeds when the directory became empty after removing this file.
_ = os.Remove(filepath.Dir(path))
}
if !removed {
fmt.Println("No integration files found")
return
}
fmt.Printf("✓ Removed %s integration\n", recipe.Name)
return
@ -269,20 +297,28 @@ func runRecipe(name string) {
// Install
fmt.Printf("Installing %s integration...\n", recipe.Name)
// Ensure parent directory exists
dir := filepath.Dir(recipe.Path)
if dir != "." && dir != "" {
if err := os.MkdirAll(dir, 0o755); err != nil {
FatalError("create directory: %v", err)
for _, path := range paths {
// Ensure parent directory exists
dir := filepath.Dir(path)
if dir != "." && dir != "" {
if err := os.MkdirAll(dir, 0o755); err != nil {
FatalError("create directory: %v", err)
}
}
content, err := recipes.ContentForPath(*recipe, path)
if err != nil {
FatalError("%v", err)
}
if err := os.WriteFile(path, []byte(content), 0o644); err != nil { // #nosec G306 -- config files need to be readable
FatalError("write file: %v", err)
}
}
if err := os.WriteFile(recipe.Path, []byte(recipes.Template), 0o644); err != nil { // #nosec G306 -- config files need to be readable
FatalError("write file: %v", err)
}
fmt.Printf("\n✓ %s integration installed\n", recipe.Name)
fmt.Printf(" File: %s\n", recipe.Path)
for _, path := range paths {
fmt.Printf(" File: %s\n", path)
}
}
// Legacy recipe handlers that delegate to existing implementations

View file

@ -104,6 +104,9 @@ func TestListRecipes_NoWorkspaceShowsBuiltinOnlyNote(t *testing.T) {
if !strings.Contains(out, "cursor") {
t.Fatalf("expected built-in recipes in output, got:\n%s", out)
}
if !strings.Contains(out, "copilot") {
t.Fatalf("expected copilot recipe in output, got:\n%s", out)
}
if strings.Contains(out, "myeditor") {
t.Fatalf("unexpected orphan custom recipe in output:\n%s", out)
}
@ -185,3 +188,76 @@ func TestRunRecipe_BuiltinFileRecipeWorksWithoutWorkspace(t *testing.T) {
t.Fatalf("expected no local .beads directory to be created, got err=%v", err)
}
}
func TestRunRecipe_CopilotWorksWithoutWorkspace(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
t.Setenv("BEADS_DIR", "")
resetSetupResolutionCaches(t)
resetSetupGlobals(t)
out := captureStdout(t, func() error {
runRecipe("copilot")
return nil
})
if !strings.Contains(out, "GitHub Copilot CLI integration installed") {
t.Fatalf("expected copilot install output, got:\n%s", out)
}
if _, err := os.Stat(filepath.Join(tmpDir, ".copilot-plugin", "plugin.json")); err != nil {
t.Fatalf("expected copilot plugin manifest: %v", err)
}
if _, err := os.Stat(filepath.Join(tmpDir, ".github", "copilot-instructions.md")); err != nil {
t.Fatalf("expected copilot instructions: %v", err)
}
}
func TestRunRecipe_CopilotCheckWorksWithoutWorkspace(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
t.Setenv("BEADS_DIR", "")
resetSetupResolutionCaches(t)
resetSetupGlobals(t)
runRecipe("copilot")
resetSetupGlobals(t)
setupCheck = true
out := captureStdout(t, func() error {
runRecipe("copilot")
return nil
})
if !strings.Contains(out, ".copilot-plugin/plugin.json") {
t.Fatalf("expected plugin manifest in check output, got:\n%s", out)
}
if !strings.Contains(out, ".github/copilot-instructions.md") {
t.Fatalf("expected instructions file in check output, got:\n%s", out)
}
}
func TestRunRecipe_CopilotRemoveWorksWithoutWorkspace(t *testing.T) {
tmpDir := t.TempDir()
t.Chdir(tmpDir)
t.Setenv("BEADS_DIR", "")
resetSetupResolutionCaches(t)
resetSetupGlobals(t)
runRecipe("copilot")
resetSetupGlobals(t)
setupRemove = true
runRecipe("copilot")
if _, err := os.Stat(filepath.Join(tmpDir, ".copilot-plugin", "plugin.json")); !os.IsNotExist(err) {
t.Fatalf("expected plugin manifest to be removed, got err=%v", err)
}
if _, err := os.Stat(filepath.Join(tmpDir, ".github", "copilot-instructions.md")); !os.IsNotExist(err) {
t.Fatalf("expected copilot instructions to be removed, got err=%v", err)
}
}

View file

@ -3574,12 +3574,13 @@ bd remember "<insight>" [flags]
Setup integration files for AI editors and coding assistants.
Recipes define where beads workflow instructions are written. Built-in recipes
include cursor, claude, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
Examples:
bd setup cursor # Install Cursor IDE integration
bd setup codex # Install Codex skill + AGENTS.md guidance
bd setup codex --global # Install global Codex skill + global AGENTS.md guidance
bd setup copilot # Install Copilot CLI plugin + repository instructions
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
bd setup mux --project --global # Install both Mux layers

View file

@ -0,0 +1,83 @@
# GitHub Copilot CLI Integration Design
This document explains design decisions for GitHub Copilot CLI integration in beads.
For **VS Code + MCP**, see [COPILOT_INTEGRATION.md](COPILOT_INTEGRATION.md).
## Integration Approach
**Recommended: Copilot CLI plugin + repository instructions** - Beads uses Copilot CLI's native plugin manifest plus repository instructions:
- `.copilot-plugin/plugin.json` registers `bd prime` hooks natively
- `.github/copilot-instructions.md` provides repository-specific workflow guidance
- Direct CLI commands with `--json` flags remain the primary operational interface
**Alternative: VS Code MCP** - For Copilot Chat in the editor:
- Native tool calling through MCP
- Higher context overhead from tool schemas
- Use when you want editor-native tool access instead of terminal-first workflow
## Why Plugin + Instructions Over Custom Setup Code?
**The plugin manifest already models the behavior we want:**
1. **Hooks belong in the tool's native format**
- Copilot CLI understands plugin manifests directly
- `SessionStart` and `PreCompact` can be declared as data instead of custom Go logic
- This keeps beads core smaller and easier to maintain
2. **Instructions stay explicit and reviewable**
- Repository guidance still lives in `.github/copilot-instructions.md`
- Teams can review the instructions like any other project documentation
- The hook behavior and the human-readable guidance stay separate
3. **Lower maintenance burden**
- No Copilot-specific install/check/remove implementation in core
- No Copilot-specific doctor checks
- The recipe just writes the native plugin file and the instruction file
## Why Copilot CLI Over MCP for Terminal Work?
**Context efficiency still matters**, even with large context windows:
1. **Compute cost scales with tokens** - Every token in context is processed on every inference
2. **Latency increases with context** - Smaller prompts keep the CLI more responsive
3. **Energy consumption** - Lean prompts are more sustainable over long sessions
4. **Attention quality** - Models generally perform better with tighter, more relevant context
**The math:**
- MCP tool schemas can add 10-50k tokens to context
- `bd prime` adds ~1-2k tokens of workflow context
- That is an order-of-magnitude reduction in overhead
## Installation
```bash
# Install the Copilot CLI plugin manifest + repository instructions
bd setup copilot
# Check installation status
bd setup copilot --check
# Remove the integration
bd setup copilot --remove
```
**What it installs:**
- `.copilot-plugin/plugin.json`
- `SessionStart` hook: Runs `bd prime` when Copilot CLI starts a session
- `PreCompact` hook: Runs `bd prime` before context compaction
- `.github/copilot-instructions.md`
- Repository workflow guidance for Copilot CLI
## Related Files
- `plugins/beads/.copilot-plugin/plugin.json` - Source plugin manifest for the shared plugin package
- `plugins/beads/copilot_manifest.go` - Embedded manifest source used by `bd setup copilot`
- `internal/recipes/recipes.go` - Lightweight `copilot` recipe definition
- `internal/recipes/template.go` - Static Copilot instructions template used by `bd setup`
- `docs/COPILOT_INTEGRATION.md` - VS Code MCP integration
## References
- [GitHub Copilot CLI docs](https://docs.github.com/en/copilot/how-tos/use-copilot-agents/use-copilot-cli)
- [Adding repository custom instructions for GitHub Copilot CLI](https://docs.github.com/en/copilot/how-tos/copilot-cli/add-custom-instructions)

View file

@ -1,6 +1,8 @@
# GitHub Copilot Integration Guide
# GitHub Copilot VS Code MCP Integration Guide
This guide explains how to use beads with GitHub Copilot in VS Code.
This guide explains how to use beads with GitHub Copilot in **VS Code via MCP**.
For the **GitHub Copilot CLI** integration installed by `bd setup copilot`, see [COPILOT_CLI_INTEGRATION.md](COPILOT_CLI_INTEGRATION.md).
## Overview

View file

@ -277,7 +277,8 @@ cd your-project
bd init --quiet
# 3. Setup editor integration (choose one)
bd setup claude # Claude Code - installs SessionStart hooks
bd setup claude # Claude Code - installs SessionStart/PreCompact hooks
bd setup copilot # GitHub Copilot CLI - creates .copilot-plugin/plugin.json + .github/copilot-instructions.md
bd setup cursor # Cursor IDE - creates .cursor/rules/beads.mdc
bd setup aider # Aider - creates .aider.conf.yml
bd setup codex # Codex CLI - installs Beads skill, AGENTS.md guidance, and native hooks
@ -303,6 +304,7 @@ bd setup mux # Mux - creates/updates AGENTS.md
**Verify installation:**
```bash
bd setup claude --check # Check Claude Code integration
bd setup copilot --check # Check GitHub Copilot CLI project integration
bd setup cursor --check # Check Cursor integration
bd setup aider --check # Check Aider integration
bd setup codex --check # Check Codex integration
@ -375,6 +377,24 @@ For VS Code with GitHub Copilot:
See [COPILOT_INTEGRATION.md](COPILOT_INTEGRATION.md) for complete setup guide.
### GitHub Copilot CLI
For the GitHub Copilot CLI terminal integration:
```bash
bd setup copilot # Install project Copilot plugin + repository instructions
bd setup copilot --check # Verify the project integration files exist
```
This setup is currently project-scoped only. It writes:
- `.copilot-plugin/plugin.json`
- `.github/copilot-instructions.md`
There is no separate `--global` or `--project` mode for Copilot today, and it does not manage `~/.copilot/...` paths.
See [COPILOT_CLI_INTEGRATION.md](COPILOT_CLI_INTEGRATION.md) for the full guide.
### MCP Server (Alternative - for MCP-only environments)
**Use MCP only when CLI is unavailable** (Claude Desktop, Sourcegraph Amp without shell):

View file

@ -18,14 +18,14 @@ The `bd setup` command uses a **recipe-based architecture** to configure beads i
### Profiles
Each integration uses one of two **profiles** that control how much content is written to tool instruction files (`AGENTS.md`, `CLAUDE.md`, or `GEMINI.md`):
Each integration uses one of two **profiles** that control how much content is written to tool instruction files (`AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, or `.github/copilot-instructions.md`):
| Profile | Used By | Content |
|---------|---------|---------|
| `full` | Factory, Mux, OpenCode | Complete command reference, issue types, priorities, workflow |
| `minimal` | Claude Code, Gemini CLI | Pointer to `bd prime`, quick reference only (~60% smaller) |
| `full` | Factory, Codex, Mux, OpenCode | Complete command reference, issue types, priorities, workflow |
| `minimal` | Claude Code, GitHub Copilot CLI, Gemini CLI | Pointer to `bd prime`, quick reference only (~60% smaller) |
Hook-enabled agents (Claude, Gemini) use the `minimal` profile because `bd prime` injects full context at session start. AGENTS-first agents use the `full` profile because their instruction file remains the primary integration surface. Skill-aware agents use `.agents/skills/beads/SKILL.md`, with project `AGENTS.md` or global `$CODEX_HOME/AGENTS.md`/`~/.codex/AGENTS.md` telling Codex when to use the skill.
Hook-enabled agents (Claude, Copilot CLI, Gemini) use the `minimal` profile because `bd prime` injects full context at session start. AGENTS-first agents use the `full` profile because their instruction file remains the primary integration surface. Skill-aware agents use `.agents/skills/beads/SKILL.md`, with project `AGENTS.md` or global `$CODEX_HOME/AGENTS.md`/`~/.codex/AGENTS.md` telling Codex when to use the skill.
**Profile precedence:** If a file already has a `full` profile section and a `minimal` profile tool installs to the same file (e.g., via symlinks), the `full` profile is preserved to avoid information loss.
@ -37,8 +37,9 @@ Hook-enabled agents (Claude, Gemini) use the `minimal` profile because `bd prime
| `windsurf` | `.windsurf/rules/beads.md` | Rules file |
| `cody` | `.cody/rules/beads.md` | Rules file |
| `kilocode` | `.kilocode/rules/beads.md` | Rules file |
| `claude` | `~/.claude/settings.json` + `CLAUDE.md` | SessionStart hook + minimal section |
| `gemini` | `~/.gemini/settings.json` + `GEMINI.md` | SessionStart hook + minimal section |
| `claude` | `~/.claude/settings.json` + `CLAUDE.md` | SessionStart/PreCompact hooks + minimal section |
| `copilot` | `.copilot-plugin/plugin.json` + `.github/copilot-instructions.md` | native Copilot plugin hooks + repository instructions |
| `gemini` | `~/.gemini/settings.json` + `GEMINI.md` | SessionStart/PreCompress hooks + minimal section |
| `factory` | `AGENTS.md` | Marked section |
| `codex` | `.agents/skills/beads/SKILL.md` + `AGENTS.md` | Beads agent skill + generated skill guidance |
| `mux` | `AGENTS.md` | Marked section |
@ -55,6 +56,7 @@ bd setup cursor # Cursor IDE
bd setup windsurf # Windsurf
bd setup kilocode # Kilo Code
bd setup claude # Claude Code
bd setup copilot # GitHub Copilot CLI plugin + instructions
bd setup gemini # Gemini CLI
bd setup factory # Factory.ai Droid
bd setup codex # Beads agent skill + AGENTS.md guidance

View file

@ -9,6 +9,7 @@ import (
"strings"
"github.com/BurntSushi/toml"
beadsplugin "github.com/steveyegge/beads/plugins/beads"
)
// RecipeType indicates how the recipe is installed.
@ -31,10 +32,12 @@ type Recipe struct {
Path string `toml:"path"` // Primary file path (for TypeFile)
Type RecipeType `toml:"type"` // How to install
Description string `toml:"description"` // Brief description
Content string `toml:"-"` // Optional static content for TypeFile
// Optional fields for complex recipes
GlobalPath string `toml:"global_path"` // Global settings path (for hooks)
ProjectPath string `toml:"project_path"` // Project settings path (for hooks)
Paths []string `toml:"paths"` // Multiple paths (for multifile)
GlobalPath string `toml:"global_path"` // Global settings path (for hooks)
ProjectPath string `toml:"project_path"` // Project settings path (for hooks)
Paths []string `toml:"paths"` // Multiple paths (for multifile)
Contents map[string]string `toml:"-"` // Optional static contents for TypeMultiFile
}
// BuiltinRecipes contains the default recipe definitions.
@ -78,6 +81,19 @@ var BuiltinRecipes = map[string]Recipe{
GlobalPath: "~/.gemini/settings.json",
ProjectPath: ".gemini/settings.json",
},
"copilot": {
Name: "GitHub Copilot CLI",
Type: TypeMultiFile,
Description: "Copilot CLI plugin manifest + instructions",
Paths: []string{
".copilot-plugin/plugin.json",
".github/copilot-instructions.md",
},
Contents: map[string]string{
".copilot-plugin/plugin.json": beadsplugin.CopilotPluginManifest(),
".github/copilot-instructions.md": CopilotInstructionsTemplate,
},
},
"factory": {
Name: "Factory.ai (Droid)",
Path: "AGENTS.md",

View file

@ -4,11 +4,13 @@ import (
"os"
"path/filepath"
"testing"
beadsplugin "github.com/steveyegge/beads/plugins/beads"
)
func TestBuiltinRecipes(t *testing.T) {
// Ensure all expected built-in recipes exist
expected := []string{"cursor", "windsurf", "cody", "kilocode", "claude", "gemini", "factory", "codex", "mux", "aider", "junie"}
expected := []string{"cursor", "windsurf", "cody", "kilocode", "claude", "copilot", "gemini", "factory", "codex", "mux", "aider", "junie"}
for _, name := range expected {
recipe, ok := BuiltinRecipes[name]
@ -171,6 +173,26 @@ func TestTemplate(t *testing.T) {
}
}
func TestContentForPathCopilot(t *testing.T) {
recipe := BuiltinRecipes["copilot"]
manifest, err := ContentForPath(recipe, ".copilot-plugin/plugin.json")
if err != nil {
t.Fatalf("ContentForPath(plugin.json): %v", err)
}
if manifest != beadsplugin.CopilotPluginManifest() {
t.Fatalf("copilot manifest does not match embedded shared plugin manifest")
}
instructions, err := ContentForPath(recipe, ".github/copilot-instructions.md")
if err != nil {
t.Fatalf("ContentForPath(copilot-instructions.md): %v", err)
}
if !containsAll(instructions, "GitHub Copilot Instructions", "bd ready", "bd prime") {
t.Fatalf("unexpected Copilot instructions:\n%s", instructions)
}
}
func containsAll(s string, substrs ...string) bool {
for _, sub := range substrs {
found := false

View file

@ -1,5 +1,7 @@
package recipes
import "fmt"
// Template is the universal beads workflow template.
// This content is written to all file-based recipes.
const Template = `# Beads Issue Tracking
@ -58,3 +60,47 @@ Run ` + "`bd prime`" + ` to get complete workflow documentation in AI-optimized
For detailed docs: see AGENTS.md, QUICKSTART.md, or run ` + "`bd --help`" + `
`
// CopilotInstructionsTemplate is the repository instructions file used by the
// lightweight Copilot CLI plugin recipe.
const CopilotInstructionsTemplate = `# GitHub Copilot Instructions
This repository uses **Beads (bd)** for issue tracking.
## Core Workflow
- Use ` + "`bd ready`" + ` to find unblocked work
- Use ` + "`bd create`" + ` to track new work
- Use ` + "`bd update <id> --claim`" + ` before starting
- Use ` + "`bd close <id>`" + ` when work is complete
- Use ` + "`bd dolt push`" + ` at the end of the session
## Context Loading
Run ` + "`bd prime`" + ` for the full workflow context.
If the Beads Copilot plugin is installed, Copilot CLI will automatically run
` + "`bd prime`" + ` on session start and before compaction.
`
// ContentForPath returns the file content that should be written for a recipe path.
func ContentForPath(recipe Recipe, path string) (string, error) {
switch recipe.Type {
case TypeFile:
if recipe.Content != "" {
return recipe.Content, nil
}
return Template, nil
case TypeMultiFile:
if len(recipe.Contents) == 0 {
return "", fmt.Errorf("recipe %q has no file contents", recipe.Name)
}
content, ok := recipe.Contents[path]
if !ok {
return "", fmt.Errorf("recipe %q has no content for %s", recipe.Name, path)
}
return content, nil
default:
return "", fmt.Errorf("recipe %q has unsupported type %q", recipe.Name, recipe.Type)
}
}

View file

@ -0,0 +1,42 @@
{
"name": "beads",
"description": "AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.",
"version": "1.0.4",
"author": {
"name": "Steve Yegge",
"url": "https://github.com/steveyegge"
},
"repository": "https://github.com/gastownhall/beads",
"license": "MIT",
"homepage": "https://github.com/gastownhall/beads",
"keywords": [
"issue-tracker",
"task-management",
"ai-workflow",
"agent-memory"
],
"hooks": {
"SessionStart": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bd prime"
}
]
}
],
"PreCompact": [
{
"matcher": "",
"hooks": [
{
"type": "command",
"command": "bd prime"
}
]
}
]
}
}

View file

@ -0,0 +1,13 @@
package beadsplugin
import _ "embed"
// all: is required because the manifest lives under a dot-directory.
//
//go:embed all:.copilot-plugin/plugin.json
var copilotPluginManifest string
// CopilotPluginManifest returns the checked-in Copilot plugin manifest content.
func CopilotPluginManifest() string {
return copilotPluginManifest
}

View file

@ -72,6 +72,7 @@ update_file "cmd/bd/version.go" "Version = \"$CURRENT_VERSION\"" "Version = \"$N
echo " • plugin metadata"
update_file "plugins/beads/.claude-plugin/plugin.json" "\"version\": \"$CURRENT_VERSION\"" "\"version\": \"$NEW_VERSION\""
update_file "plugins/beads/.codex-plugin/plugin.json" "\"version\": \"$CURRENT_VERSION\"" "\"version\": \"$NEW_VERSION\""
update_file "plugins/beads/.copilot-plugin/plugin.json" "\"version\": \"$CURRENT_VERSION\"" "\"version\": \"$NEW_VERSION\""
update_file ".claude-plugin/marketplace.json" "\"version\": \"$CURRENT_VERSION\"" "\"version\": \"$NEW_VERSION\""
# 3. MCP Python package

View file

@ -13,12 +13,13 @@ Generated from `bd help --doc setup`
Setup integration files for AI editors and coding assistants.
Recipes define where beads workflow instructions are written. Built-in recipes
include cursor, claude, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
Examples:
bd setup cursor # Install Cursor IDE integration
bd setup codex # Install Codex skill + AGENTS.md guidance
bd setup codex --global # Install global Codex skill + global AGENTS.md guidance
bd setup copilot # Install Copilot CLI plugin + repository instructions
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
bd setup mux --project --global # Install both Mux layers

View file

@ -13,12 +13,13 @@ Generated from `bd help --doc setup`
Setup integration files for AI editors and coding assistants.
Recipes define where beads workflow instructions are written. Built-in recipes
include cursor, claude, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
Examples:
bd setup cursor # Install Cursor IDE integration
bd setup codex # Install Codex skill + AGENTS.md guidance
bd setup codex --global # Install global Codex skill + global AGENTS.md guidance
bd setup copilot # Install Copilot CLI plugin + repository instructions
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
bd setup mux --project --global # Install both Mux layers

View file

@ -13,12 +13,13 @@ Generated from `bd help --doc setup`
Setup integration files for AI editors and coding assistants.
Recipes define where beads workflow instructions are written. Built-in recipes
include cursor, claude, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
include cursor, claude, copilot, gemini, aider, factory, codex, mux, opencode, junie, windsurf, cody, and kilocode.
Examples:
bd setup cursor # Install Cursor IDE integration
bd setup codex # Install Codex skill + AGENTS.md guidance
bd setup codex --global # Install global Codex skill + global AGENTS.md guidance
bd setup copilot # Install Copilot CLI plugin + repository instructions
bd setup mux --project # Install Mux workspace layer (.mux/AGENTS.md)
bd setup mux --global # Install Mux global layer (~/.mux/AGENTS.md)
bd setup mux --project --global # Install both Mux layers