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/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