feat: Add Claude Code plugin for beads [addresses #28]

Adds a Claude Code plugin for one-command installation of beads via
/plugin command. The plugin bundles the MCP server, slash commands,
and an autonomous task agent.

Components:
- Plugin metadata with MCP server configuration
- 8 slash commands for core workflow (/bd-ready, /bd-create, etc.)
- Task agent for autonomous execution (@task-agent)
- Comprehensive plugin documentation (PLUGIN.md)

The plugin provides a lower-friction installation path for Claude Code
users who want integrated slash commands rather than direct MCP tools.

Related: https://github.com/steveyegge/beads/issues/28

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>

.claude-plugin/agents/task-agent.md

@@ -0,0 +1,60 @@
+---
+description: Autonomous agent that finds and completes ready tasks
+---
+
+You are a task-completion agent for beads. Your goal is to find ready work and complete it autonomously.
+
+# Agent Workflow
+
+1. **Find Ready Work**
+   - Use the `ready` MCP tool to get unblocked tasks
+   - Prefer higher priority tasks (P0 > P1 > P2 > P3 > P4)
+   - If no ready tasks, report completion
+
+2. **Claim the Task**
+   - Use the `show` tool to get full task details
+   - Use the `update` tool to set status to `in_progress`
+   - Report what you're working on
+
+3. **Execute the Task**
+   - Read the task description carefully
+   - Use available tools to complete the work
+   - Follow best practices from project documentation
+   - Run tests if applicable
+
+4. **Track Discoveries**
+   - If you find bugs, TODOs, or related work:
+     - Use `create` tool to file new issues
+     - Use `dep` tool with `discovered-from` to link them
+   - This maintains context for future work
+
+5. **Complete the Task**
+   - Verify the work is done correctly
+   - Use `close` tool with a clear completion message
+   - Report what was accomplished
+
+6. **Continue**
+   - Check for newly unblocked work with `ready`
+   - Repeat the cycle
+
+# Important Guidelines
+
+- Always update issue status (`in_progress` when starting, close when done)
+- Link discovered work with `discovered-from` dependencies
+- Don't close issues unless work is actually complete
+- If blocked, use `update` to set status to `blocked` and explain why
+- Communicate clearly about progress and blockers
+
+# Available Tools
+
+Via beads MCP server:
+- `ready` - Find unblocked tasks
+- `show` - Get task details
+- `update` - Update task status/fields
+- `create` - Create new issues
+- `dep` - Manage dependencies
+- `close` - Complete tasks
+- `blocked` - Check blocked issues
+- `stats` - View project stats
+
+You are autonomous but should communicate your progress clearly. Start by finding ready work!

.claude-plugin/commands/bd-close.md

@@ -0,0 +1,18 @@
+---
+description: Close a completed issue
+argument-hint: [issue-id] [reason]
+---
+
+Close a beads issue that's been completed.
+
+If arguments are provided:
+- $1: Issue ID
+- $2+: Completion reason (optional)
+
+If the issue ID is missing, ask for it. Optionally ask for a reason describing what was done.
+
+Use the beads MCP `close` tool to close the issue. Show confirmation with the issue details.
+
+After closing, suggest checking for:
+- Dependent issues that might now be unblocked (use `ready` tool)
+- New work discovered during this task (use `create` tool with `discovered-from` link)

.claude-plugin/commands/bd-create.md

@@ -0,0 +1,19 @@
+---
+description: Create a new issue interactively
+argument-hint: [title] [type] [priority]
+---
+
+Create a new beads issue. If arguments are provided:
+- $1: Issue title
+- $2: Issue type (bug, feature, task, epic, chore)
+- $3: Priority (0-4, where 0=critical, 4=backlog)
+
+If arguments are missing, ask the user for:
+1. Issue title (required)
+2. Issue type (default: task)
+3. Priority (default: 2)
+4. Description (optional)
+
+Use the beads MCP `create` tool to create the issue. Show the created issue ID and details to the user.
+
+Optionally ask if this issue should be linked to another issue (discovered-from, blocks, parent-child, related).

.claude-plugin/commands/bd-init.md

@@ -0,0 +1,14 @@
+---
+description: Initialize beads in the current project
+---
+
+Initialize beads issue tracking in the current directory.
+
+Use the beads MCP `init` tool to set up a new beads database.
+
+After initialization:
+1. Show the database location
+2. Explain the basic workflow (or suggest running `/bd-workflow`)
+3. Suggest creating the first issue with `/bd-create`
+
+If beads is already initialized, inform the user and show project stats using the `stats` tool.

.claude-plugin/commands/bd-ready.md

@@ -0,0 +1,15 @@
+---
+description: Find ready-to-work tasks with no blockers
+---
+
+Use the beads MCP server to find tasks that are ready to work on (no blocking dependencies).
+
+Call the `ready` tool to get a list of unblocked issues. Then present them to the user in a clear format showing:
+- Issue ID
+- Title
+- Priority
+- Issue type
+
+If there are ready tasks, ask the user which one they'd like to work on. If they choose one, use the `update` tool to set its status to `in_progress`.
+
+If there are no ready tasks, suggest checking `blocked` issues or creating a new issue with the `create` tool.

.claude-plugin/commands/bd-show.md

@@ -0,0 +1,17 @@
+---
+description: Show detailed information about an issue
+argument-hint: [issue-id]
+---
+
+Display detailed information about a beads issue.
+
+If an issue ID is provided as $1, use it. Otherwise, ask the user for the issue ID.
+
+Use the beads MCP `show` tool to retrieve issue details and present them clearly, including:
+- Issue ID, title, and description
+- Status, priority, and type
+- Creation and update timestamps
+- Dependencies (what this issue blocks or is blocked by)
+- Related issues
+
+If the issue has dependencies, offer to show the full dependency tree.

.claude-plugin/commands/bd-stats.md

@@ -0,0 +1,17 @@
+---
+description: Show project statistics and progress
+---
+
+Display statistics about the current beads project.
+
+Use the beads MCP `stats` tool to retrieve project metrics and present them clearly:
+- Total issues by status (open, in_progress, blocked, closed)
+- Issues by priority level
+- Issues by type (bug, feature, task, epic, chore)
+- Completion rate
+- Recently updated issues
+
+Optionally suggest actions based on the stats:
+- High number of blocked issues? Run `/bd-blocked` to investigate
+- No in-progress work? Run `/bd-ready` to find tasks
+- Many open issues? Consider prioritizing with `/bd-update`

.claude-plugin/commands/bd-update.md

@@ -0,0 +1,22 @@
+---
+description: Update an issue's status, priority, or other fields
+argument-hint: [issue-id] [status]
+---
+
+Update a beads issue.
+
+If arguments are provided:
+- $1: Issue ID
+- $2: New status (open, in_progress, blocked, closed)
+
+If arguments are missing, ask the user for:
+1. Issue ID
+2. What to update (status, priority, assignee, title, description)
+3. New value
+
+Use the beads MCP `update` tool to apply the changes. Show the updated issue to confirm the change.
+
+Common workflows:
+- Start work: Update status to `in_progress`
+- Mark blocked: Update status to `blocked`
+- Reprioritize: Update priority (0-4)

.claude-plugin/commands/bd-workflow.md

@@ -0,0 +1,59 @@
+---
+description: Show the AI-supervised issue workflow guide
+---
+
+Display the beads workflow for AI agents and developers.
+
+# Beads Workflow
+
+Beads is an issue tracker designed for AI-supervised coding workflows. Here's how to use it effectively:
+
+## 1. Find Ready Work
+Use `/bd-ready` or the `ready` MCP tool to see tasks with no blockers.
+
+## 2. Claim Your Task
+Update the issue status to `in_progress`:
+- Via command: `/bd-update <id> in_progress`
+- Via MCP tool: `update` with `status: "in_progress"`
+
+## 3. Work on It
+Implement, test, and document the feature or fix.
+
+## 4. Discover New Work
+As you work, you'll often find bugs, TODOs, or related work:
+- Create issues: `/bd-create` or `create` MCP tool
+- Link them: Use `dep` MCP tool with `type: "discovered-from"`
+- This maintains context and work history
+
+## 5. Complete the Task
+Close the issue when done:
+- Via command: `/bd-close <id> "Completed: <summary>"`
+- Via MCP tool: `close` with reason
+
+## 6. Check What's Unblocked
+After closing, check if other work became ready:
+- Use `/bd-ready` to see newly unblocked tasks
+- Start the cycle again
+
+## Tips
+- **Priority levels**: 0=critical, 1=high, 2=medium, 3=low, 4=backlog
+- **Issue types**: bug, feature, task, epic, chore
+- **Dependencies**: Use `blocks` for hard dependencies, `related` for soft links
+- **Auto-sync**: Changes automatically export to `.beads/issues.jsonl` (5-second debounce)
+- **Git workflow**: After `git pull`, JSONL auto-imports if newer than DB
+
+## Available Commands
+- `/bd-ready` - Find unblocked work
+- `/bd-create` - Create new issue
+- `/bd-show` - Show issue details
+- `/bd-update` - Update issue
+- `/bd-close` - Close issue
+- `/bd-workflow` - Show this guide (you are here!)
+
+## MCP Tools Available
+Use these via the beads MCP server:
+- `ready`, `list`, `show`, `create`, `update`, `close`
+- `dep` (manage dependencies), `blocked`, `stats`
+- `init` (initialize bd in a project)
+
+For more details, see the beads README at: https://github.com/steveyegge/beads

.claude-plugin/marketplace.json

@@ -0,0 +1,15 @@
+{
+  "name": "beads-marketplace",
+  "description": "Local marketplace for beads plugin development",
+  "owner": {
+    "name": "Steve Yegge"
+  },
+  "plugins": [
+    {
+      "name": "beads",
+      "source": ".",
+      "description": "AI-supervised issue tracker for coding workflows",
+      "version": "0.9.0"
+    }
+  ]
+}

.claude-plugin/plugin.json

@@ -0,0 +1,37 @@
+{
+  "name": "beads",
+  "description": "AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple CLI commands.",
+  "version": "0.9.0",
+  "author": {
+    "name": "Steve Yegge",
+    "url": "https://github.com/steveyegge"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/steveyegge/beads"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/steveyegge/beads",
+  "keywords": [
+    "issue-tracker",
+    "task-management",
+    "ai-workflow",
+    "agent-memory",
+    "mcp-server"
+  ],
+  "mcpServers": {
+    "beads": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "${CLAUDE_PLUGIN_ROOT}/integrations/beads-mcp",
+        "run",
+        "beads-mcp"
+      ],
+      "env": {
+        "BEADS_PATH": "bd",
+        "BEADS_ACTOR": "${USER}"
+      }
+    }
+  }
+}

PLUGIN.md

@@ -0,0 +1,271 @@
+# Beads Claude Code Plugin
+
+AI-supervised issue tracker for coding workflows. Manage tasks, discover work, and maintain context with simple slash commands and MCP tools.
+
+## What is Beads?
+
+Beads (`bd`) is an issue tracker designed specifically for AI-supervised coding workflows. It helps AI agents and developers:
+- Track work with a simple CLI
+- Discover and link related tasks during development
+- Maintain context across coding sessions
+- Auto-sync issues via JSONL for git workflows
+
+## Installation
+
+### Prerequisites
+
+1. Install beads CLI:
+```bash
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/install.sh | bash
+```
+
+2. Install Python and uv (for MCP server):
+```bash
+# Install uv (if not already installed)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+```
+
+### Install Plugin
+
+There are two ways to install the beads plugin:
+
+#### Option 1: From GitHub (Recommended)
+
+```bash
+# In Claude Code
+/plugin marketplace add steveyegge/beads
+/plugin install beads
+```
+
+#### Option 2: Local Development
+
+```bash
+# Clone the repository
+git clone https://github.com/steveyegge/beads
+cd beads
+
+# Add local marketplace
+/plugin marketplace add .
+
+# Install plugin
+/plugin install beads
+```
+
+### Restart Claude Code
+
+After installation, restart Claude Code to activate the MCP server.
+
+## Quick Start
+
+```bash
+# Initialize beads in your project
+/bd-init
+
+# Create your first issue
+/bd-create "Set up project structure" feature 1
+
+# See what's ready to work on
+/bd-ready
+
+# Show full workflow guide
+/bd-workflow
+```
+
+## Available Commands
+
+### Core Workflow Commands
+
+- **`/bd-ready`** - Find tasks with no blockers, ready to work on
+- **`/bd-create [title] [type] [priority]`** - Create a new issue interactively
+- **`/bd-show [issue-id]`** - Show detailed information about an issue
+- **`/bd-update [issue-id] [status]`** - Update issue status or other fields
+- **`/bd-close [issue-id] [reason]`** - Close a completed issue
+
+### Project Management
+
+- **`/bd-init`** - Initialize beads in the current project
+- **`/bd-workflow`** - Show the AI-supervised issue workflow guide
+- **`/bd-stats`** - Show project statistics and progress
+
+### Agents
+
+- **`@task-agent`** - Autonomous agent that finds and completes ready tasks
+
+## MCP Tools Available
+
+The plugin includes a full-featured MCP server with these tools:
+
+- **`init`** - Initialize bd in current directory
+- **`create`** - Create new issue (bug, feature, task, epic, chore)
+- **`list`** - List issues with filters (status, priority, type, assignee)
+- **`ready`** - Find tasks with no blockers ready to work on
+- **`show`** - Show detailed issue info including dependencies
+- **`update`** - Update issue (status, priority, design, notes, etc)
+- **`close`** - Close completed issue
+- **`dep`** - Add dependency (blocks, related, parent-child, discovered-from)
+- **`blocked`** - Get blocked issues
+- **`stats`** - Get project statistics
+
+### MCP Resources
+
+- **`beads://quickstart`** - Interactive quickstart guide
+
+## Workflow
+
+The beads workflow is designed for AI agents but works great for humans too:
+
+1. **Find ready work**: `/bd-ready`
+2. **Claim your task**: `/bd-update <id> in_progress`
+3. **Work on it**: Implement, test, document
+4. **Discover new work**: Create issues for bugs/TODOs found during work
+5. **Complete**: `/bd-close <id> "Done: <summary>"`
+6. **Repeat**: Check for newly unblocked tasks
+
+## Issue Types
+
+- **`bug`** - Something broken that needs fixing
+- **`feature`** - New functionality
+- **`task`** - Work item (tests, docs, refactoring)
+- **`epic`** - Large feature composed of multiple issues
+- **`chore`** - Maintenance work (dependencies, tooling)
+
+## Priority Levels
+
+- **`0`** - Critical (security, data loss, broken builds)
+- **`1`** - High (major features, important bugs)
+- **`2`** - Medium (nice-to-have features, minor bugs)
+- **`3`** - Low (polish, optimization)
+- **`4`** - Backlog (future ideas)
+
+## Dependency Types
+
+- **`blocks`** - Hard dependency (issue X blocks issue Y from starting)
+- **`related`** - Soft relationship (issues are connected)
+- **`parent-child`** - Epic/subtask relationship
+- **`discovered-from`** - Track issues discovered during work
+
+Only `blocks` dependencies affect the ready work queue.
+
+## Configuration
+
+The MCP server supports these environment variables:
+
+- **`BEADS_PATH`** - Path to bd executable (default: `bd` in PATH)
+- **`BEADS_DB`** - Path to beads database file (default: auto-discover from cwd)
+- **`BEADS_ACTOR`** - Actor name for audit trail (default: `$USER`)
+- **`BEADS_NO_AUTO_FLUSH`** - Disable automatic JSONL sync (default: `false`)
+- **`BEADS_NO_AUTO_IMPORT`** - Disable automatic JSONL import (default: `false`)
+
+To customize, edit your Claude Code MCP settings or the plugin configuration.
+
+## Examples
+
+### Basic Task Management
+
+```bash
+# Create a high-priority bug
+/bd-create "Fix authentication" bug 1
+
+# See ready work
+/bd-ready
+
+# Start working on bd-10
+/bd-update bd-10 in_progress
+
+# Complete the task
+/bd-close bd-10 "Fixed auth token validation"
+```
+
+### Discovering Work During Development
+
+```bash
+# Working on bd-10, found a related bug
+/bd-create "Add rate limiting to API" feature 2
+
+# Link it to current work (via MCP tool)
+# Use `dep` tool: issue="bd-11", depends_on="bd-10", type="discovered-from"
+
+# Close original task
+/bd-close bd-10 "Done, discovered bd-11 for rate limiting"
+```
+
+### Using the Task Agent
+
+```bash
+# Let the agent find and complete ready work
+@task-agent
+
+# The agent will:
+# 1. Find ready work with `ready` tool
+# 2. Claim a task by updating status
+# 3. Execute the work
+# 4. Create issues for discoveries
+# 5. Close when complete
+# 6. Repeat
+```
+
+## Auto-Sync with Git
+
+Beads automatically syncs issues to `.beads/issues.jsonl`:
+- **Export**: After any CRUD operation (5-second debounce)
+- **Import**: When JSONL is newer than DB (e.g., after `git pull`)
+
+This enables seamless collaboration:
+```bash
+# Make changes
+bd create "Add feature" -p 1
+
+# Changes auto-export after 5 seconds
+# Commit when ready
+git add .beads/issues.jsonl
+git commit -m "Add feature tracking"
+
+# After pull, JSONL auto-imports
+git pull
+bd ready  # Fresh data from git!
+```
+
+## Troubleshooting
+
+### Plugin not appearing
+
+1. Check installation: `/plugin list`
+2. Restart Claude Code
+3. Verify `bd` is in PATH: `which bd`
+4. Check uv is installed: `which uv`
+
+### MCP server not connecting
+
+1. Check MCP server list: `/mcp`
+2. Look for "beads" server with plugin indicator
+3. Restart Claude Code to reload MCP servers
+4. Check logs for errors
+
+### Commands not working
+
+1. Make sure you're in a project with beads initialized: `/bd-init`
+2. Check if database exists: `ls -la .beads/`
+3. Try direct MCP tool access instead of slash commands
+4. Check the beads CLI works: `bd --help`
+
+### MCP tool errors
+
+1. Verify `bd` executable location: `BEADS_PATH` env var
+2. Check `bd` works in terminal: `bd stats`
+3. Review MCP server logs in Claude Code
+4. Try reinitializing: `/bd-init`
+
+## Learn More
+
+- **GitHub**: https://github.com/steveyegge/beads
+- **Documentation**: See README.md in the repository
+- **Examples**: Check `examples/` directory for integration patterns
+- **MCP Server**: See `integrations/beads-mcp/` for server details
+
+## Contributing
+
+Found a bug or have a feature idea? Create an issue in the beads repository!
+
+## License
+
+MIT License - see LICENSE file in the repository.

README.md

@@ -82,6 +82,24 @@ paru -S beads-git
 
 Thanks to [@v4rgas](https://github.com/v4rgas) for maintaining the AUR package!
 
+### Claude Code Plugin
+
+Prefer a one-command installation in Claude Code? Install the beads plugin for instant access via slash commands and MCP tools:
+
+```bash
+# In Claude Code
+/plugin marketplace add steveyegge/beads
+/plugin install beads
+```
+
+The plugin includes:
+- Slash commands: `/bd-ready`, `/bd-create`, `/bd-show`, `/bd-update`, `/bd-close`, etc.
+- Full MCP server with all bd tools
+- Task agent for autonomous execution
+- Auto-configured for instant use
+
+See [PLUGIN.md](PLUGIN.md) for complete plugin documentation.
+
 #### Windows 11
 For Windows you must build from source.
 Assumes git, go-lang and mingw-64 installed and in path.
@@ -711,7 +729,8 @@ Check out the **[examples/](examples/)** directory for:
 - **[Bash agent](examples/bash-agent/)** - Shell script agent example
 - **[Git hooks](examples/git-hooks/)** - Automatic export/import on git operations
 - **[Branch merge workflow](examples/branch-merge/)** - Handle ID collisions when merging branches
-- **[Claude Desktop MCP](examples/claude-desktop-mcp/)** - MCP server integration (coming soon)
+- **[Claude Desktop MCP](examples/claude-desktop-mcp/)** - MCP server for Claude Desktop
+- **[Claude Code Plugin](PLUGIN.md)** - One-command installation with slash commands and MCP tools
 
 ## FAQ