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:
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...
|
||||
```
|
||||
Reference in New Issue
Block a user