johno/nixos-configs
1
0
Fork 0
Code Issues 3 Pull Requests 8 Actions Packages Projects Releases Wiki Activity

feat(skills): Add beads-aware workflow skills

Browse Source 
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:
John Ogle
2026-01-12 17:58:41 -08:00
parent 7a5f167a8c
commit 082b0918af
5 changed files with 1256 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

218
home/roles/development/skills/beads_implement.md Normal file
View File

@@ -0,0 +1,218 @@
---
description: Implement a plan from thoughts/ for a bead issue
---
# Beads Implement
You are tasked with implementing an approved plan for a bead issue. Plans are stored in `thoughts/beads-{id}/plan.md`.
## Initial Setup
When this command is invoked:
1. **Parse the input for bead ID**:
- If a bead ID is provided, use it
- If no bead ID, check for beads with plans:
```bash
bd list --status=in_progress
```
Then check which have plans in `thoughts/beads-{id}/plan.md`
2. **Load bead and plan context**:
```bash
bd show {bead-id}
```
- Read `thoughts/beads-{bead-id}/plan.md` FULLY
- Check for any existing checkmarks (- [x]) indicating partial progress
- Read any research at `thoughts/beads-{bead-id}/research.md`
3. **Mark bead in progress** (if not already):
```bash
bd update {bead-id} --status=in_progress
```
4. **Respond with**:
```
Implementing plan for bead {bead-id}: {bead-title}
Plan location: thoughts/beads-{bead-id}/plan.md
{If partial progress: "Resuming from Phase X - previous phases completed."}
I'll implement each phase and verify success criteria before proceeding.
```
## Implementation Process
### Step 1: Understand the Plan
1. **Read the plan completely**
2. **Check for existing progress** (checkmarked items)
3. **Read all files mentioned in the plan**
4. **Create a TodoWrite list** tracking each phase
### Step 2: Implement Each Phase
For each phase in the plan:
1. **Announce the phase**:
```
## Starting Phase {N}: {Phase Name}
This phase will: {overview from plan}
```
2. **Make the changes**:
- Follow the plan's specific instructions
- Use Edit tool for modifications
- Create new files only when specified
3. **Run automated verification**:
- Execute each command in "Automated Verification"
- Fix any issues before proceeding
4. **Update plan checkboxes**:
- Use Edit tool to check off completed items in the plan
- This enables resume if session is interrupted
5. **Update bead notes** with progress:
```bash
bd update {bead-id} --notes="Phase {N} complete. Automated verification passed."
```
### Step 3: Per-Plan Checkpoint
**CRITICAL**: After completing ALL phases and ALL automated verification:
```
## Implementation Complete - Ready for Manual Verification
All phases completed and automated verification passed:
- [ ] Phase 1: {name} - DONE
- [ ] Phase 2: {name} - DONE
- [ ] ...
**Automated checks passed:**
- {List of automated checks that passed}
**Please perform manual verification:**
- {List manual verification items from plan}
Let me know when manual testing is complete so I can close the bead.
```
**STOP HERE and wait for user confirmation.**
Do NOT:
- Close the bead automatically
- Proceed to "next steps" without confirmation
- Start additional work
### Step 4: After Manual Verification
When user confirms manual verification passed:
1. **Update plan status**:
- Edit the plan's frontmatter: `status: complete`
2. **Close the bead**:
```bash
bd close {bead-id} --reason="Implementation complete. All verification passed."
```
3. **Final summary**:
```
Bead {bead-id} closed.
Summary:
- {What was implemented}
- {Key changes made}
Artifacts:
- Plan: thoughts/beads-{bead-id}/plan.md
- {Any other artifacts created}
```
## Handling Issues
### When something doesn't match the plan:
```
Issue in Phase {N}:
Expected: {what the plan says}
Found: {actual situation}
Why this matters: {explanation}
Options:
1. Adapt the implementation to work with current state
2. Update the plan to reflect reality
3. Stop and investigate further
How should I proceed?
```
### When tests fail:
1. **Analyze the failure**
2. **Attempt to fix** if the fix is clear and within scope
3. **If fix is unclear**, report:
```
Test failure in Phase {N}:
Failing test: {test name}
Error: {error message}
I've attempted: {what you tried}
This may require: {your assessment}
```
### When blocked:
```
Blocked in Phase {N}:
Blocker: {description}
Impact: {what can't proceed}
Suggested resolution: {your recommendation}
```
## Resuming Work
If the plan has existing checkmarks:
1. **Trust completed work** - don't re-verify unless something seems off
2. **Pick up from first unchecked item**
3. **Verify previous work only if** current phase depends on it and seems broken
## Important Guidelines
1. **Follow the plan's intent** while adapting to reality
2. **Implement each phase fully** before moving to next
3. **Update checkboxes in real-time** as you complete items
4. **One checkpoint per plan** - not per phase
5. **Never close bead** without manual verification confirmation
6. **Keep bead notes updated** with progress
## Session Close Protocol
If you need to end the session before completion:
1. **Update plan** with current progress (checkboxes)
2. **Update bead notes**:
```bash
bd update {bead-id} --notes="In progress: Phase {N} partially complete. Next: {what's next}"
```
3. **Inform user** of status and how to resume
## Example Invocation
```
User: /beads:implement nixos-configs-abc123
Assistant: Implementing plan for bead nixos-configs-abc123...
## Starting Phase 1: Database Schema
This phase will add the new user_preferences table...
```

214
home/roles/development/skills/beads_iterate.md Normal file
View File

@@ -0,0 +1,214 @@
---
description: Iterate on existing implementation plans for a bead issue
model: opus
---
# Beads Iterate
You are tasked with updating existing implementation plans based on feedback. Plans are stored in `thoughts/beads-{id}/plan.md`.
## Initial Setup
When this command is invoked:
1. **Parse the input**:
- Bead ID (required or ask for it)
- Requested changes/feedback (can be provided with command or after)
2. **Handle different scenarios**:
**No bead ID provided**:
```
Which bead's plan would you like to iterate on?
Recent beads with plans:
{list beads that have thoughts/beads-{id}/plan.md}
```
**Bead ID but no feedback**:
```
I've found the plan at thoughts/beads-{bead-id}/plan.md
What changes would you like to make? For example:
- "Add a phase for migration handling"
- "Update success criteria to include performance tests"
- "Adjust scope to exclude feature X"
- "Split Phase 2 into two separate phases"
```
**Both bead ID and feedback provided**:
- Proceed immediately to Step 1
## Iteration Process
### Step 1: Understand Current Plan
1. **Read the existing plan COMPLETELY**:
```bash
cat thoughts/beads-{bead-id}/plan.md
```
- Understand current structure, phases, scope
- Note success criteria and approach
2. **Read the bead for context**:
```bash
bd show {bead-id}
```
3. **Understand requested changes**:
- Parse what user wants to add/modify/remove
- Identify if changes require codebase research
### Step 2: Research If Needed
**Only if changes require new technical understanding:**
1. **Spawn parallel research tasks**:
- **codebase-locator**: Find relevant files
- **codebase-analyzer**: Understand implementation details
- **codebase-pattern-finder**: Find similar patterns
2. **Be specific about directories** in prompts
3. **Wait for ALL tasks** before proceeding
### Step 3: Present Understanding
Before making changes:
```
Based on your feedback, I understand you want to:
- {Change 1 with specific detail}
- {Change 2 with specific detail}
{If research was needed:}
My research found:
- {Relevant discovery}
- {Important constraint}
I plan to update the plan by:
1. {Specific modification}
2. {Another modification}
Does this align with your intent?
```
Get user confirmation before proceeding.
### Step 4: Update the Plan
1. **Make focused, precise edits**:
- Use Edit tool for surgical changes
- Maintain existing structure unless explicitly changing it
- Keep file:line references accurate
2. **Ensure consistency**:
- New phases follow existing pattern
- Update "What We're NOT Doing" if scope changes
- Maintain automated vs manual success criteria distinction
3. **Update plan metadata**:
- Update frontmatter `date` to current timestamp
- Add `iteration: {N}` to frontmatter
- Add `iteration_reason: "{brief description}"` to frontmatter
4. **Preserve completed work**:
- Don't uncheck items that were already completed
- If changing completed phases, discuss with user first
### Step 5: Save Iteration History (Optional)
For significant changes, save the previous version:
```bash
cp thoughts/beads-{bead-id}/plan.md thoughts/beads-{bead-id}/plan-v{N}.md
```
Then update the main plan.
### Step 6: Update Bead
```bash
bd update {bead-id} --notes="Plan iterated: {brief description of changes}"
```
### Step 7: Present Changes
```
I've updated the plan at `thoughts/beads-{bead-id}/plan.md`
Changes made:
- {Specific change 1}
- {Specific change 2}
The updated plan now:
- {Key improvement}
- {Another improvement}
Would you like any further adjustments?
```
## Important Guidelines
1. **Be Skeptical**:
- Don't blindly accept changes that seem problematic
- Question vague feedback - ask for clarification
- Point out conflicts with existing phases
2. **Be Surgical**:
- Make precise edits, not wholesale rewrites
- Preserve good content that doesn't need changing
- Only research what's necessary
3. **Be Thorough**:
- Read entire plan before making changes
- Ensure updated sections maintain quality
- Verify success criteria are still measurable
4. **Be Interactive**:
- Confirm understanding before making changes
- Allow course corrections
- Don't disappear into research without communicating
5. **No Open Questions**:
- If changes raise questions, ASK
- Don't update plan with unresolved questions
## Success Criteria Guidelines
When updating success criteria, maintain two categories:
**Automated Verification**:
- Commands: `make test`, `npm run lint`
- Prefer `make` commands when available
- File existence checks
**Manual Verification**:
- UI/UX functionality
- Performance under real conditions
- Edge cases hard to automate
## Handling Major Changes
If feedback requires significant restructuring:
1. **Discuss scope** before proceeding
2. **Consider if this should be a new plan** instead of iteration
3. **Preserve the original** in `plan-v{N}.md`
4. **Update bead description** if scope changed significantly
## Example Invocations
**With full context**:
```
User: /beads:iterate nixos-configs-abc123 - add error handling phase
Assistant: Based on your feedback, I understand you want to add a new phase for error handling...
```
**Interactive**:
```
User: /beads:iterate nixos-configs-abc123
Assistant: I've found the plan. What changes would you like to make?
User: Split Phase 2 into backend and frontend phases
Assistant: I'll split Phase 2 into two separate phases...
```

281
home/roles/development/skills/beads_plan.md Normal file
View File

@@ -0,0 +1,281 @@
---
description: Create detailed implementation plans for a bead issue
model: opus
---
# Beads Plan
You are tasked with creating detailed implementation plans for a bead issue. This skill integrates with the beads issue tracker and stores plans in the `thoughts/` directory.
## Initial Setup
When this command is invoked:
1. **Parse the input for bead ID**:
- If a bead ID is provided, use it
- If no bead ID, run `bd ready` and ask which bead to plan for
2. **Load bead context**:
```bash
bd show {bead-id}
```
- Read the bead description for requirements
- Check for existing research: `thoughts/beads-{bead-id}/research.md`
- Note any dependencies or blockers
3. **Create artifact directory**:
```bash
mkdir -p thoughts/beads-{bead-id}
```
4. **Check for existing research**:
- If `thoughts/beads-{bead-id}/research.md` exists, read it fully
- This research provides crucial context for planning
5. **Respond with**:
```
Creating implementation plan for bead {bead-id}: {bead-title}
{If research exists: "Found existing research at thoughts/beads-{bead-id}/research.md - incorporating findings."}
Let me analyze the requirements and codebase to create a detailed plan.
```
## Planning Process
### Step 1: Context Gathering
1. **Read all mentioned files FULLY**:
- Bead description references
- Existing research document
- Any linked tickets or docs
- Use Read tool WITHOUT limit/offset
2. **Spawn initial research tasks**:
- **codebase-locator**: Find all files related to the task
- **codebase-analyzer**: Understand current implementation
- **codebase-pattern-finder**: Find similar features to model after
- **thoughts-locator**: Find any existing plans or decisions
3. **Read all files identified by research**:
- Read them FULLY into main context
- Cross-reference with requirements
### Step 2: Present Understanding
Before writing the plan, confirm understanding:
```
Based on the bead and my research, I understand we need to [accurate summary].
I've found that:
- [Current implementation detail with file:line reference]
- [Relevant pattern or constraint discovered]
- [Potential complexity or edge case identified]
Questions that my research couldn't answer:
- [Specific technical question requiring human judgment]
- [Business logic clarification]
```
Only ask questions you genuinely cannot answer through code investigation.
### Step 3: Research & Discovery
After getting clarifications:
1. **If user corrects any misunderstanding**:
- Spawn new research tasks to verify
- Read specific files/directories mentioned
- Only proceed once verified
2. **Present design options**:
```
Based on my research:
**Current State:**
- [Key discovery about existing code]
- [Pattern or convention to follow]
**Design Options:**
1. [Option A] - [pros/cons]
2. [Option B] - [pros/cons]
Which approach aligns best?
```
### Step 4: Plan Structure
Once aligned on approach:
```
Here's my proposed plan structure:
## Overview
[1-2 sentence summary]
## Implementation Phases:
1. [Phase name] - [what it accomplishes]
2. [Phase name] - [what it accomplishes]
Does this phasing make sense?
```
Get feedback on structure before writing details.
### Step 5: Write the Plan
Write to `thoughts/beads-{bead-id}/plan.md`:
```markdown
---
date: {ISO timestamp}
bead_id: {bead-id}
bead_title: "{bead title}"
author: claude
git_commit: {commit hash}
branch: {branch name}
repository: {repo name}
status: draft
---
# {Feature/Task Name} Implementation Plan
## Overview
{Brief description of what we're implementing and why}
## Current State Analysis
{What exists now, what's missing, key constraints}
### Key Discoveries:
- {Finding with file:line reference}
- {Pattern to follow}
## Desired End State
{Specification of desired end state and how to verify it}
## What We're NOT Doing
{Explicitly list out-of-scope items}
## Implementation Approach
{High-level strategy and reasoning}
## Phase 1: {Descriptive Name}
### Overview
{What this phase accomplishes}
### Changes Required:
#### 1. {Component/File Group}
**File**: `path/to/file.ext`
**Changes**: {Summary}
```{language}
// Specific code to add/modify
```
### Success Criteria:
#### Automated Verification:
- [ ] Tests pass: `make test`
- [ ] Linting passes: `make lint`
- [ ] Type checking passes: `make typecheck`
#### Manual Verification:
- [ ] Feature works as expected in UI
- [ ] Edge cases handled correctly
---
## Phase 2: {Descriptive Name}
{Similar structure...}
---
## Testing Strategy
### Unit Tests:
- {What to test}
- {Key edge cases}
### Integration Tests:
- {End-to-end scenarios}
### Manual Testing Steps:
1. {Specific step}
2. {Another step}
## References
- Bead: {bead-id}
- Research: `thoughts/beads-{bead-id}/research.md`
- Similar implementation: {file:line}
```
### Step 6: Update the bead
```bash
bd update {bead-id} --notes="Plan created: thoughts/beads-{bead-id}/plan.md"
```
### Step 7: Create implementation bead (if appropriate)
If the planning bead is separate from implementation:
```bash
bd create --title="Implement: {feature name}" --type=task --priority=1 \
--description="Implement the plan at thoughts/beads-{original-bead-id}/plan.md
See bead {original-bead-id} for planning context."
# Link as dependency
bd dep add {new-bead-id} {original-bead-id}
```
### Step 8: Present for Review
```
I've created the implementation plan at:
`thoughts/beads-{bead-id}/plan.md`
Please review it and let me know:
- Are the phases properly scoped?
- Are the success criteria specific enough?
- Any technical details that need adjustment?
- Missing edge cases or considerations?
```
## Important Guidelines
1. **Be Skeptical**: Question vague requirements, identify potential issues early
2. **Be Interactive**: Don't write the full plan in one shot, get buy-in at each step
3. **Be Thorough**: Read all context files COMPLETELY, include specific file:line refs
4. **Be Practical**: Focus on incremental, testable changes
5. **No Open Questions**: If you have unresolved questions, STOP and ask
## Success Criteria Guidelines
Always separate into two categories:
**Automated Verification** (run by agents):
- Commands: `make test`, `npm run lint`, etc.
- File existence checks
- Type checking
**Manual Verification** (requires human):
- UI/UX functionality
- Performance under real conditions
- Edge cases hard to automate
## Example Invocation
```
User: /beads:plan nixos-configs-abc123
Assistant: Creating implementation plan for bead nixos-configs-abc123...
```

206
home/roles/development/skills/beads_research.md Normal file
View File

@@ -0,0 +1,206 @@
---
description: Research a bead topic comprehensively and store findings in thoughts/
model: opus
---
# Beads Research
You are tasked with conducting comprehensive research for a bead issue. This skill integrates with the beads issue tracker and stores findings in the `thoughts/` directory.
## CRITICAL: YOUR ONLY JOB IS TO DOCUMENT AND EXPLAIN THE CODEBASE AS IT EXISTS TODAY
- DO NOT suggest improvements or changes unless the user explicitly asks for them
- DO NOT perform root cause analysis unless the user explicitly asks for them
- DO NOT propose future enhancements unless the user explicitly asks for them
- DO NOT critique the implementation or identify problems
- ONLY describe what exists, where it exists, how it works, and how components interact
- You are creating a technical map/documentation of the existing system
## Initial Setup
When this command is invoked:
1. **Parse the input for bead ID**:
- If a bead ID is provided (e.g., `nixos-configs-abc123`), use it
- If no bead ID provided, run `bd ready --type=research` to find research beads, or ask which bead to research
2. **Load bead context**:
```bash
bd show {bead-id}
```
- Read the bead description to understand the research question
- Note any linked files or references in the bead
3. **Create artifact directory**:
```bash
mkdir -p thoughts/beads-{bead-id}
```
4. **Respond with**:
```
Starting research for bead {bead-id}: {bead-title}
Research question: {extracted from bead description}
I'll analyze this thoroughly and store findings in thoughts/beads-{bead-id}/research.md
```
## Research Process
### Step 1: Read any directly mentioned files
- If the bead or user mentions specific files, read them FULLY first
- Use the Read tool WITHOUT limit/offset parameters
- Read these files yourself in the main context before spawning sub-tasks
### Step 2: Analyze and decompose the research question
- Break down the query into composable research areas
- Identify specific components, patterns, or concepts to investigate
- Create a research plan using TodoWrite
- Consider which directories, files, or patterns are relevant
### Step 3: Spawn parallel sub-agent tasks
Use specialized agents for research:
**For codebase research:**
- **codebase-locator** - Find WHERE files and components live
- **codebase-analyzer** - Understand HOW specific code works
- **codebase-pattern-finder** - Find examples of existing patterns
**For thoughts directory:**
- **thoughts-locator** - Discover what documents exist about the topic
- **thoughts-analyzer** - Extract key insights from specific documents
**For web research (only if explicitly requested):**
- **web-search-researcher** - External documentation and resources
Key principles:
- Run multiple agents in parallel when searching for different things
- Each agent knows its job - tell it what you're looking for, not HOW to search
- Remind agents they are documenting, not evaluating
### Step 4: Synthesize findings
Wait for ALL sub-agents to complete, then:
- Compile all results (codebase and thoughts findings)
- Prioritize live codebase findings as primary source of truth
- Connect findings across different components
- Include specific file paths and line numbers
- Highlight patterns, connections, and architectural decisions
### Step 5: Gather metadata
```bash
# Git metadata
git rev-parse HEAD # Current commit
git branch --show-current # Current branch
basename $(git rev-parse --show-toplevel) # Repo name
date -Iseconds # Current timestamp
```
### Step 6: Write research document
Write to `thoughts/beads-{bead-id}/research.md`:
```markdown
---
date: {ISO timestamp with timezone}
bead_id: {bead-id}
bead_title: "{bead title}"
researcher: claude
git_commit: {commit hash}
branch: {branch name}
repository: {repo name}
status: complete
---
# Research: {bead title}
**Bead**: {bead-id}
**Date**: {timestamp}
**Git Commit**: {commit hash}
**Branch**: {branch name}
## Research Question
{Original question from bead description}
## Summary
{High-level documentation answering the research question}
## Detailed Findings
### {Component/Area 1}
- Description of what exists (file.ext:line)
- How it connects to other components
- Current implementation details
### {Component/Area 2}
...
## Code References
- `path/to/file.py:123` - Description
- `another/file.ts:45-67` - Description
## Architecture Documentation
{Current patterns, conventions found in codebase}
## Historical Context (from thoughts/)
{Relevant insights from thoughts/ with references}
## Open Questions
{Any areas needing further investigation}
```
### Step 7: Update the bead
```bash
# Add artifact link to bead notes
bd update {bead-id} --notes="Research complete: thoughts/beads-{bead-id}/research.md"
```
### Step 8: Autonomy decision
**For research beads (type=research):**
- If research is complete and comprehensive, close the bead:
```bash
bd close {bead-id} --reason="Research complete. See thoughts/beads-{bead-id}/research.md"
```
- Present summary to user
**For other bead types:**
- Do NOT close the bead
- Present findings and ask how to proceed
### Step 9: Handle follow-up questions
If the user has follow-up questions:
- Append to the same research document
- Add a new section: `## Follow-up Research [{timestamp}]`
- Update the bead notes with the new findings
## Important Guidelines
- Always use parallel Task agents to maximize efficiency
- Always run fresh codebase research - never rely solely on existing documents
- Focus on finding concrete file paths and line numbers
- Research documents should be self-contained
- Document cross-component connections
- Include temporal context (when research was conducted)
- Keep the main agent focused on synthesis, not deep file reading
- **CRITICAL**: You and all sub-agents are documentarians, not evaluators
- **REMEMBER**: Document what IS, not what SHOULD BE
## Example Invocation
```
User: /beads:research nixos-configs-abc123
Assistant: Starting research for bead nixos-configs-abc123: Investigate auth flow
...
```
Or without bead ID:
```
User: /beads:research
Assistant: Let me check for research beads...
[runs bd ready]
Which bead would you like me to research?
```

337
home/roles/development/skills/beads_workflow.md Normal file
View 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