---
name: step-03-execute
description: Todo-driven implementation - execute the plan file by file
prev_step: steps/step-02-plan.md
next_step: steps/step-04-validate.md
---

# Step 3: Execute (Implementation)

## MANDATORY EXECUTION RULES:

- NEVER deviate from the approved plan
- NEVER add features not in the plan (scope creep)
- NEVER modify files without reading them first
- ALWAYS follow the plan file-by-file
- ALWAYS mark todos complete immediately after each task
- ALWAYS read files BEFORE editing them
- YOU ARE AN IMPLEMENTER following a plan, not a designer
- FORBIDDEN to add "improvements" not in the plan

## YOUR TASK:

Execute the approved implementation plan file-by-file, tracking progress with todos.

---

<available_state>
From previous steps:

| Variable | Description |
|----------|-------------|
| `{task_description}` | What to implement |
| `{task_id}` | Kebab-case identifier |
| `{auto_mode}` | Skip confirmations |
| `{save_mode}` | Save outputs to files |
| `{output_dir}` | Path to output (if save_mode) |
| Implementation plan | File-by-file changes from step-02 |
| Patterns | How to implement from step-01 |
</available_state>

---

## EXECUTION SEQUENCE:

### 1. Create Todos from Plan

Convert each file change from the plan into todos:

```
Plan entry:
#### `src/auth/handler.ts`
- Add `validateToken` function
- Handle error case: expired token

Becomes:
- [ ] src/auth/handler.ts: Add validateToken function
- [ ] src/auth/handler.ts: Handle expired token error
```

Use TodoWrite to create the full list.

### 2. Execute File by File

For each todo:

**2.1 Mark In Progress**
- Only ONE todo in_progress at a time

**2.2 Read Before Edit**
```
ALWAYS read the file before modifying:
- Understand current structure
- Find exact insertion points
- Verify patterns match expectations
```

**2.3 Implement Changes**
```
Make changes specified in the plan:
- Follow patterns from step-01 analysis
- Use exact names from plan
- Handle error cases as specified
- NO comments unless truly necessary
```

**2.4 Mark Complete Immediately**
- Mark todo complete RIGHT AFTER finishing
- Don't batch completions

**2.5 Log Progress (if save_mode)**

Append to `{output_dir}/03-execute.md`:
```markdown
### file.ts
- Added `functionName` (lines 45-78)
- Added error handling
```

### 3. Handle Blockers

**If `{auto_mode}` = true:**
Make reasonable decision and continue.

**If `{auto_mode}` = false:**

```yaml
questions:
  - header: "Blocker"
    question: "Encountered an issue. How should we proceed?"
    options:
      - label: "Use alternative approach (Recommended)"
        description: "Description of alternative"
      - label: "Skip this part"
        description: "Continue without this change"
      - label: "Stop for discussion"
        description: "I want to discuss before continuing"
    multiSelect: false
```

### 4. Verify Implementation

After completing all todos:

```bash
pnpm run typecheck && pnpm run lint --fix
```

Fix any errors immediately.

### 5. Implementation Summary

```
**Implementation Complete**

**Files Modified:**
- `src/auth/handler.ts` - Added validateToken, error handling
- `src/api/auth/route.ts` - Integrated token validation

**New Files:**
- `src/types/auth.ts` - Auth type definitions

**Todos:** {X}/{Y} complete
```

### 6. Save Output (if save_mode)

**If `{save_mode}` = true:**

Finalize `{output_dir}/03-execute.md` with:
- Summary of all changes
- Timestamp
- Update 00-context.md Progress table: 03-execute -> Complete

**Then proceed to validation.**

---

## SUCCESS METRICS:

- All plan items implemented
- All todos marked complete
- No scope creep - only plan items
- Files read before modification
- Typecheck and lint pass

## FAILURE MODES:

- Adding features not in the plan
- Modifying files without reading first
- Not updating todos as you work
- Multiple todos in_progress simultaneously
- Ignoring type or lint errors

---

## NEXT STEP:

After implementation complete, load `./step-04-validate.md`
