---
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 `/beads:ready` or the `ready` MCP tool to see tasks with no blockers.

## 2. Claim Your Task
Claim the issue atomically (assignee + `in_progress` in one step):
- Via command: `/beads:update <id> --claim`
- Via MCP tool: `claim` with `issue_id: "<id>"`

## 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: `/beads: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: `/beads:close <id> "Completed: <summary>"`
- Via MCP tool: `close` with reason

## 6. Check What's Unblocked
After closing, check if other work became ready:
- Use `/beads: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 are stored in Dolt and synced via `bd dolt push` / `bd dolt pull`

## Available Commands
- `/beads:ready` - Find unblocked work
- `/beads:create` - Create new issue
- `/beads:show` - Show issue details
- `/beads:update` - Update issue
- `/beads:close` - Close issue
- `/beads:workflow` - Show this guide (you are here!)

## MCP Tools Available
Use these via the beads MCP server:
- `ready`, `list`, `show`, `create`, `claim`, `update`, `close`
- `dep` (manage dependencies), `blocked`, `stats`
- `init` (initialize bd in a project)

For more details, see the beads README at: https://github.com/gastownhall/beads