nixos-configs/home/roles/development/skills/beads_workflow.md

---
description: Comprehensive guide for the beads + humanlayer integrated workflow
---

# Beads Workflow Guide

This document describes the integrated workflow combining **beads** (issue tracking) with **humanlayer-style skills** (deep research, planning, implementation).

## Philosophy

### Two Systems, Complementary Purposes

| System | Purpose | Storage |
|--------|---------|---------|
| **Beads** | Track WHAT work exists | `.beads/` (git-synced) |
| **Thoughts** | Store HOW to do the work | `thoughts/` (local or symlinked) |

### Autonomy Model

| Bead Type | Agent Autonomy | Checkpoint |
|-----------|----------------|------------|
| `research` | **Full** - agent closes when satisfied | None |
| `feature`, `task`, `bug` | **Checkpointed** - pause for validation | Per-plan |

**Key insight**: Research produces artifacts. Implementation produces commits. Commits are the review boundary.

## Directory Structure

```
project/
├── .beads/                              # Beads database (git-synced)
│   ├── beads.db
│   ├── config.yaml
│   └── issues.jsonl
├── thoughts/                            # Artifacts (local or symlink)
│   ├── beads-{id}/                      # Per-bead artifacts
│   │   ├── research.md
│   │   ├── plan.md
│   │   └── plan-v1.md                   # Iteration history
│   └── shared/                          # Legacy/non-bead artifacts
│       ├── research/
│       └── plans/
└── home/roles/development/skills/       # Skill definitions
    ├── beads_research.md
    ├── beads_plan.md
    ├── beads_implement.md
    └── beads_iterate.md
```

## When to Use What

### Use Beads When:
- Work spans multiple sessions
- Work has dependencies or blockers
- You need to track status across interruptions
- Multiple related tasks need coordination
- Context recovery after compaction matters

### Use TodoWrite When:
- Single-session execution tracking
- Breaking down work within a session
- Tracking progress on a single bead

### Use Both Together:
- Beads track the overall work items
- TodoWrite tracks progress within a session
- Example: Bead for "Implement auth", TodoWrite for each file being edited

## Workflow Patterns

### Pattern 1: Research-First Approach

```
1. Create research bead
   bd create --title="Research auth patterns" --type=research --priority=1

2. Run research
   /beads:research {bead-id}
   → Agent researches, writes to thoughts/beads-{id}/research.md
   → Agent closes bead when satisfied

3. Create implementation bead
   bd create --title="Implement auth" --type=feature --priority=1

4. Plan the implementation
   /beads:plan {bead-id}
   → Agent reads prior research, creates plan
   → Plan saved to thoughts/beads-{id}/plan.md

5. Implement
   /beads:implement {bead-id}
   → Agent follows plan, pauses for manual verification
   → You validate, agent closes bead
```

### Pattern 2: Direct Implementation

For well-understood tasks without research:

```
1. Create bead
   bd create --title="Fix login bug" --type=bug --priority=0

2. Plan and implement
   /beads:plan {bead-id}
   → Quick planning based on bead description

   /beads:implement {bead-id}
   → Follow plan, pause at checkpoint
```

### Pattern 3: Iterative Planning

When requirements evolve:

```
1. Initial plan
   /beads:plan {bead-id}

2. Iterate based on feedback
   /beads:iterate {bead-id} - add error handling phase

3. Iterate again if needed
   /beads:iterate {bead-id} - split phase 2 into backend/frontend

4. Implement when plan is solid
   /beads:implement {bead-id}
```

### Pattern 4: Parallel Work

Using parallel_beads skill for multiple independent tasks:

```
1. Check what's ready
   bd ready

2. Select multiple beads
   /parallel_beads
   → Select beads to work on
   → Each gets worktree, PR, review

3. Reconcile after PRs merge
   /reconcile_beads
```

## Skills Reference

### /beads:research {bead-id}
- Conducts comprehensive codebase research
- Uses parallel sub-agents for efficiency
- Outputs to `thoughts/beads-{id}/research.md`
- **Autonomy**: Can close research beads automatically

### /beads:plan {bead-id}
- Creates detailed implementation plans
- Interactive process with checkpoints
- Outputs to `thoughts/beads-{id}/plan.md`
- Can create dependent implementation beads

### /beads:implement {bead-id}
- Follows plans from thoughts/
- Updates plan checkboxes for resumability
- **Checkpoint**: Pauses after plan completion for manual verification
- Only closes bead after human confirms

### /beads:iterate {bead-id}
- Updates existing plans based on feedback
- Preserves plan structure while making targeted changes
- Saves iteration history as `plan-v{N}.md`

### /parallel_beads
- Orchestrates parallel bead processing
- Creates worktrees, PRs, reviews for multiple beads
- Good for batching independent work

### /reconcile_beads
- Closes beads whose PRs have merged
- Run after merging PRs to keep beads in sync

## Session Protocols

### Starting a Session

```bash
# Check what's available
bd ready

# Pick work and start
bd update {bead-id} --status=in_progress
```

### Ending a Session

```bash
# Always run this checklist:
[ ] git status                    # Check changes
[ ] git add <files>               # Stage code changes
[ ] bd sync                       # Sync beads
[ ] git commit -m "..."           # Commit code
[ ] git push                      # Push to remote
```

### Resuming Work

```bash
# Find in-progress work
bd list --status=in_progress

# Check bead notes for context
bd show {bead-id}

# Check for partial plan progress
cat thoughts/beads-{id}/plan.md | grep "\[x\]"
```

## Thoughts Directory Patterns

### For Work Repos (via symlink)
```
project/thoughts → ~/thoughts/repos/{repo-name}/
```
- Syncs via codelayer to work remote
- Shared across projects on same machine

### For Personal Repos (local)
```
project/thoughts/  # Regular directory, not symlink
```
- Stays local to project
- Committed with project or gitignored

### Determining Which Pattern
```bash
# Check if thoughts is a symlink
ls -la thoughts

# If symlink, it points to ~/thoughts/repos/{repo}/
# If directory, it's local to this project
```

## Best Practices

### 1. Bead Descriptions Matter
Write clear descriptions - they're the input for research and planning:
```bash
bd create --title="Implement user preferences" --type=feature \
  --description="Add user preferences storage and UI.

Requirements:
- Store preferences in SQLite
- Expose via REST API
- Add settings page in UI

See related: thoughts/shared/research/preferences-patterns.md"
```

### 2. Link Artifacts in Beads
Always update bead notes with artifact locations:
```bash
bd update {id} --notes="Research: thoughts/beads-{id}/research.md
Plan: thoughts/beads-{id}/plan.md"
```

### 3. Use Dependencies
Structure work with dependencies:
```bash
# Research blocks planning
bd dep add {plan-bead} {research-bead}

# Planning blocks implementation
bd dep add {impl-bead} {plan-bead}
```

### 4. Trust the Checkpoint Model
- Research beads: Let agent close them
- Implementation beads: Always validate before closing
- If in doubt, err on the side of checkpoints

### 5. Keep Plans Updated
- Check off completed items as you go
- Update notes with progress
- This enables seamless resume across sessions

## Troubleshooting

### "What bead should I work on?"
```bash
bd ready  # Shows unblocked work
```

### "Where did the research go?"
```bash
ls thoughts/beads-{id}/
bd show {id}  # Check notes for artifact links
```

### "Plan doesn't match reality"
```bash
/beads:iterate {id}  # Update plan based on findings
```

### "Session ended mid-implementation"
```bash
bd show {id}  # Check notes for progress
cat thoughts/beads-{id}/plan.md | grep "\[x\]"  # See completed items
/beads:implement {id}  # Resume - will pick up from last checkpoint
```

### "Bead is blocked"
```bash
bd show {id}  # See what's blocking
bd blocked    # See all blocked beads
```

## Migration Notes

### From Pure Humanlayer to Beads+Humanlayer

Old pattern:
```
thoughts/shared/research/2025-01-01-topic.md
thoughts/shared/plans/2025-01-01-feature.md
```

New pattern:
```
thoughts/beads-{id}/research.md
thoughts/beads-{id}/plan.md
```

The `shared/` structure still works for non-bead artifacts, but prefer per-bead directories for tracked work.

### Existing Content
- Keep existing `thoughts/shared/` content
- New bead-tracked work uses `thoughts/beads-{id}/`
- Reference old research from bead descriptions when relevant

## Design Decisions

### Phase Tracking: Artifacts vs Statuses

**Current approach**: Skills infer workflow phase from artifact presence:
- Has `research.md` → research done
- Has `plan.md` → planning done
- No artifacts → needs research/planning

**Alternative considered**: Explicit phase statuses (`needs_research`, `needs_plan`, `implementing`, etc.)

**Why artifacts win**:
1. **Single source of truth** - Status can't drift from reality
2. **Less state to maintain** - No need to update status when creating artifacts
3. **Works across repos** - No custom status config needed
4. **Skills already check artifacts** - Natural fit with existing behavior

**When explicit statuses would help**:
- Pipeline visualization (e.g., `bd list --status=needs_plan`)
- Agent self-selection by phase
- Team coordination dashboards

**Recommendation**: Keep artifact-inference as primary mechanism. If pipeline visibility becomes important, consider adding statuses that skills auto-set when creating artifacts (advisory, not enforced).

### One Bead Per Feature (Default)

**Current approach**: File one bead per logical feature. Skills handle phases internally.

**Alternative considered**: Separate beads for research → planning → implementation, linked by dependencies.

**Why single bead wins for most work**:
1. **Lower friction** - Quick idea dump without filing 3 tickets
2. **Simpler tracking** - One status to check
3. **Natural grouping** - Artifacts stay together in `thoughts/beads-{id}/`

**When to split into multiple beads**:
- Research reveals the work should be multiple features
- Different phases need different assignees
- Explicit dependency tracking matters (e.g., "auth must ship before payments")

**The discovered-work pattern**: Start with one bead. If research reveals split work, file additional beads with dependencies. Skills guide this naturally.

### Plan Requirements by Type

**Bug fixes** (`type=bug`): Can proceed without plans - usually well-scoped from bug report.

**Features/tasks** (`type=feature`, `type=task`): Should have plans - helps ensure design is sound before implementation.

This is advisory, not enforced. Skills warn but allow override for simple changes.