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

description

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

# Check what's available
bd ready

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

Ending a Session

# 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

# 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

# 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:

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:

bd update {id} --notes="Research: thoughts/beads-{id}/research.md
Plan: thoughts/beads-{id}/plan.md"

3. Use Dependencies

Structure work with dependencies:

# 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?"

bd ready  # Shows unblocked work

"Where did the research go?"

ls thoughts/beads-{id}/
bd show {id}  # Check notes for artifact links

"Plan doesn't match reality"

/beads:iterate {id}  # Update plan based on findings

"Session ended mid-implementation"

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"

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.