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}"
+      }
+    }
+  }
+}