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:
218
home/roles/development/skills/beads_implement.md
Normal file
218
home/roles/development/skills/beads_implement.md
Normal 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
214
home/roles/development/skills/beads_iterate.md
Normal 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
281
home/roles/development/skills/beads_plan.md
Normal 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
206
home/roles/development/skills/beads_research.md
Normal 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
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