feat(skills): Add beads-aware workflow skills
New skills for integrated beads + humanlayer workflow:
- beads_research.md: Research with per-bead artifact storage
- beads_plan.md: Planning with bead linking
- beads_implement.md: Implementation with per-plan checkpoints
- beads_iterate.md: Plan iteration with version history
- beads_workflow.md: Comprehensive workflow documentation
Skills output to thoughts/beads-{id}/ for artifact storage
and automatically update bead notes with artifact links.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
337
home/roles/development/skills/beads_workflow.md
Normal file
337
home/roles/development/skills/beads_workflow.md
Normal file
@@ -0,0 +1,337 @@
|
||||
---
|
||||
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
|
||||
Reference in New Issue
Block a user