Beads Workflow

Proactive task management for projects using beads issue tracker.

Session Start (PROACTIVE)

When starting a session in a project directory:

1. Check for beads

ls -d .beads 2>/dev/null

If .beads/ does not exist — this skill is not applicable.

2. Self-Install in CLAUDE.md (MANDATORY)

YOU MUST ALWAYS CHECK AND OFFER TO CREATE CLAUDE.md:

# Check if CLAUDE.md exists and has Beads Workflow section
if [ -f CLAUDE.md ]; then
  grep -q "## Beads Workflow" CLAUDE.md && echo "configured" || echo "needs_section"
else
  echo "no_claude_md"
fi

If "no_claude_md" or "needs_section":

1. ALWAYS ask user: "В проекте есть beads, но CLAUDE.md не настроен. Создать/обновить?"
2. If agreed, create or append the section below
3. DO NOT SKIP THIS STEP

CLAUDE.md content to add:

# CLAUDE.md

## Beads Workflow

При старте сессии используй скилл `beads-workflow` для:
1. Показать текущую задачу (in_progress) или выбрать из ready
2. Отслеживать прогресс через TodoWrite
3. При завершении — закрыть задачу через bd close

## Project Info

<!-- Add project-specific instructions here -->

3. Get Current Context

bd list --status in_progress --json
bd ready --json

4. Present Status

If task in_progress exists:

"Продолжаем работу над [id] [title]" Show task details with bd show <id>

If no in_progress: Use AskUserQuestion with ready tasks as options (max 4, sorted by priority).

5. Start Selected Task

bd update <id> --status in_progress
bd show <id>

Use TodoWrite to break down the task into subtasks.

During Work

• Track current task ID in conversation context
• Use TodoWrite for subtask tracking within the beads task
• When discovering subtasks that should be tracked separately:
  bashCopy

  bd create "Subtask title" -t task -p 1
  bd dep add <new-id> <parent-id> --type parent-child
  

Task Completion

When user says "готово", "done", "сделал", "закрой задачу":

1. Confirm which task (if ambiguous)

2. Ask for brief reason via AskUserQuestion:

   • "Реализовано" (Implemented)
   • "Исправлено" (Fixed)
   • "Не актуально" (Not relevant)
   • Other (custom input)

3. Close and sync:

   bashCopy

   bd close <id> --reason "<reason>"
   bd sync
   

4. Offer next task from ready list

Creating Tasks

When user says "создай задачу", "новая задача", "create task":

Task description must include:

1. Clear title — what needs to be done (action + object)
2. Recommended skill — if applicable, add label skill:<name>

# With skill recommendation
bd create "Implement user auth API" -t task -p 1 -l "skill:backend-rust"

# Without skill (general task)
bd create "Write documentation" -t task -p 2

Priority: 0=critical, 1=high, 2=medium, 3=low

For subtasks, link to parent:

bd dep add <child-id> <parent-id> --type parent-child

Writing Self-Contained Issues (CRITICAL)

Every issue must be readable without external context. A future session (or different developer) should understand the task completely from the description alone.

Required Sections

Use the template from references/issue-template.md:

## Summary
[What and why — 1-2 sentences]

## Files to Modify
- `path/to/file.ts:123` — what changes

## Implementation Steps
1. Specific step with details
2. Next step

## Acceptance Criteria
- [ ] Criterion 1
- [ ] Tests pass

Quick Quality Check

Before creating, ask yourself:

• Can someone understand this WITHOUT reading chat history?
• Are specific files and line numbers mentioned?
• Are acceptance criteria measurable?

Using Rich Fields

# Edit main description
bd edit <id> --description

# Add technical design notes
bd edit <id> --design

# Add gotchas and warnings
bd edit <id> --notes

Validation

Run before committing:

python3 skills/beads-validation/scripts/validate_beads.py --check-quality

See references/issue-template.md for full template and examples.

Refresh Tasks

When user says "обнови задачи", "refresh", "sync":

bd sync
bd ready --json

Show what changed:

• New tasks added
• Tasks closed by others
• Priority changes

If current in_progress task was modified, warn user.

Switching Tasks

Before showing ready list for next task selection, ALWAYS sync first:

bd sync
bd ready --json

This ensures task list is current before user picks.

Session End

If task is still in_progress when session ends:

1. Ask: keep in_progress or close?
2. Run bd sync to save state
3. Brief summary of what was done

Reference Files

• For detailed session lifecycle: See references/session-lifecycle.md
• For all bd commands: See references/task-operations.md
• For issue template and examples: See references/issue-template.md