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

---
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 context**:
   ```bash
   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:
   ```bash
   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`

5. **Mark bead in progress** (if not already):
   ```bash
   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:
   ```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...
```