/workflow

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