nixos-configs/home/roles/development/skills/beads_implement.md

description

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:

     bd list --status=in_progress
     

     Then check which have plans in thoughts/beads-{id}/plan.md

2. Load bead context:

   bd show {bead-id}
   

   Note the bead type (bug, feature, task) from the output.

3. Check for plan and handle by type:

   Check if plan exists:

   ls thoughts/beads-{bead-id}/plan.md 2>/dev/null
   

   If plan exists: Proceed normally (skip to step 4)

   If no plan:

   • type=bug: Proceed without plan (simple bugs can implement directly)
   • type=feature or type=task: Warn and ask:

     No plan found for this {type}.
     
     Plans help ensure complex work is well-designed and verifiable.
     Location expected: thoughts/beads-{bead-id}/plan.md
     
     Options:
     1. Create a plan first (recommended) - Run /beads_plan {bead-id}
     2. Proceed without a plan (for simple changes)
     
     How would you like to proceed?
     

     Wait for user response before continuing.

4. Load plan and research context (if plan exists):

   • 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
   • If plan's Success Criteria references contribution guidelines (e.g., "Per CONTRIBUTING.md:"), verify the original CONTRIBUTING.md still exists and requirements are current

5. Mark bead in progress (if not already):

   bd update {bead-id} --status=in_progress
   

6. 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:

   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.

**Contribution guidelines compliance:**
- {List any contribution guideline requirements that were part of Success Criteria}
- {Note if any requirements could not be automated and need manual review}

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:

   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:

   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...