From 082b0918afe506a2ec98044d49b5c6e1ef9e4223 Mon Sep 17 00:00:00 2001 From: John Ogle Date: Mon, 12 Jan 2026 17:58:41 -0800 Subject: [PATCH] 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 --- .../development/skills/beads_implement.md | 218 +++++++++++ .../roles/development/skills/beads_iterate.md | 214 +++++++++++ home/roles/development/skills/beads_plan.md | 281 +++++++++++++++ .../development/skills/beads_research.md | 206 +++++++++++ .../development/skills/beads_workflow.md | 337 ++++++++++++++++++ 5 files changed, 1256 insertions(+) create mode 100644 home/roles/development/skills/beads_implement.md create mode 100644 home/roles/development/skills/beads_iterate.md create mode 100644 home/roles/development/skills/beads_plan.md create mode 100644 home/roles/development/skills/beads_research.md create mode 100644 home/roles/development/skills/beads_workflow.md diff --git a/home/roles/development/skills/beads_implement.md b/home/roles/development/skills/beads_implement.md new file mode 100644 index 0000000..e1e2a70 --- /dev/null +++ b/home/roles/development/skills/beads_implement.md @@ -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... +``` diff --git a/home/roles/development/skills/beads_iterate.md b/home/roles/development/skills/beads_iterate.md new file mode 100644 index 0000000..3120519 --- /dev/null +++ b/home/roles/development/skills/beads_iterate.md @@ -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... +``` diff --git a/home/roles/development/skills/beads_plan.md b/home/roles/development/skills/beads_plan.md new file mode 100644 index 0000000..2286b8c --- /dev/null +++ b/home/roles/development/skills/beads_plan.md @@ -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... +``` diff --git a/home/roles/development/skills/beads_research.md b/home/roles/development/skills/beads_research.md new file mode 100644 index 0000000..cce1fcc --- /dev/null +++ b/home/roles/development/skills/beads_research.md @@ -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? +``` diff --git a/home/roles/development/skills/beads_workflow.md b/home/roles/development/skills/beads_workflow.md new file mode 100644 index 0000000..21017e1 --- /dev/null +++ b/home/roles/development/skills/beads_workflow.md @@ -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 # 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