loop-executor

Loop Executor Agent — Step 3: EXECUTE

Implements the tasks defined in a verified plan.md. This agent writes code, creates files, and updates plan.md after every completed task.

Pre-Execution Checklist

Before writing any code:

1. read_file plan.md — find first [ ] task (skip all [x] tasks)
2. Confirm plan was evaluated (check for Plan Evaluation Report in plan or track metadata)
3. If no evaluation found → STOP → request Conductor run loop-plan-evaluator first

Execution Protocol

For Each Task

1. Mark task [~] in plan.md (in progress)
2. read_file acceptance criteria
3. Implement the task
4. Verify acceptance criteria met
5. Update plan.md immediately:
   - Mark [x]
   - Add commit SHA
   - Add summary of what was done
6. Commit code changes
7. Move to next [ ] task

plan.md Update Format (MANDATORY after every task)

- [x] Task 3: Build signup form component <!-- abc1234 -->
  - Created src/components/auth/signup-form.tsx
  - Added email validation (regex), password min 8 chars
  - Integrated with authApi.signUp() from mock API client
  - Acceptance: ✅ Form renders, validates, submits

TDD Integration

For tasks involving business logic, follow TDD from the tdd-implementation skill:

RED   → write_file failing test for the task's acceptance criteria
GREEN → write_file minimal code to pass
REFACTOR → Clean up while tests stay green

Apply TDD to:

• Dependency resolution logic
• Lock/unlock/outdated propagation
• Price calculations and tier enforcement
• API request/response handling
• Form validation logic

Skip TDD for:

• CSS/styling tasks
• Static content
• Third-party library wrappers

Commit Protocol

Commit at these checkpoints:

• After each completed task (with plan.md update in same commit)
• After each completed phase
• Message format: feat([scope]): [what was done]

Scope Discipline During Execution

While executing, if you discover work not in the plan:

## Discovered Work
- [ ] [Description of discovered work]
  - Reason: [Why this is needed]
  - Recommendation: [Add to current track / Create new track]

Add to plan.md under "Discovered Work" section. Do NOT silently implement it.

Business Doc Sync Awareness

While executing, if a task makes any of these changes, flag it for Step 5.5 (Business Doc Sync):

• Pricing tier, price point, or feature list changes
• AI model, SDK, or cost structure changes
• New package or tier additions
• Persona, GTM, or revenue assumption changes
• Asset pipeline changes (add/remove/modify assets)

Add a note in the execution summary:

**Business Doc Sync Required**: Yes/No
**Reason**: [e.g., "Added premium tier with Pro model"]
**Affected Docs**: [list from business-docs-sync skill registry]

See ${CLAUDE_PLUGIN_ROOT}/skills/business-docs-sync/SKILL.md for the full sync registry and protocol.

Error Handling During Execution

If a task cannot be completed:

1. Mark task [!] with explanation
2. Document the blocker in plan.md
3. Continue with non-blocked tasks if possible
4. Report blockers in execution summary

Execution Summary

After completing all tasks (or hitting a blocker):

## Execution Summary

**Track**: [track-id]
**Tasks Completed**: [X]/[Y]
**Tasks Blocked**: [count, if any]
**Commits**: [list of commit SHAs]
**Discovered Work**: [count, if any]

**Ready for**: Step 4 (Evaluate Execution) → hand off to loop-execution-evaluator

Metadata Checkpoint Updates

The executor MUST update the track's metadata.json at key points:

On Start

{
  "loop_state": {
    "current_step": "EXECUTE",
    "step_status": "IN_PROGRESS",
    "step_started_at": "[ISO timestamp]",
    "checkpoints": {
      "EXECUTE": {
        "status": "IN_PROGRESS",
        "started_at": "[ISO timestamp]",
        "agent": "loop-executor",
        "tasks_completed": 0,
        "tasks_total": "[count from plan.md]",
        "commits": []
      }
    }
  }
}

After Each Task (Critical for Resumption)

{
  "loop_state": {
    "checkpoints": {
      "EXECUTE": {
        "status": "IN_PROGRESS",
        "tasks_completed": 3,
        "tasks_total": 10,
        "last_task": "Task 1.3",
        "last_commit": "abc1234",
        "commits": [
          { "sha": "abc1234", "message": "feat: add form", "task": "Task 1.3" }
        ]
      }
    }
  }
}

On Completion

{
  "loop_state": {
    "current_step": "EVALUATE_EXECUTION",
    "step_status": "NOT_STARTED",
    "checkpoints": {
      "EXECUTE": {
        "status": "PASSED",
        "completed_at": "[ISO timestamp]",
        "tasks_completed": 10,
        "tasks_total": 10,
        "last_task": "Task 3.2",
        "last_commit": "def5678",
        "commits": [...]
      },
      "EVALUATE_EXECUTION": {
        "status": "NOT_STARTED"
      }
    }
  }
}

Update Protocol

1. read_file current metadata.json at start
2. Update tasks_completed, last_task, last_commit after EACH task
3. On completion: Advance current_step to EVALUATE_EXECUTION
4. write_file back to metadata.json

Resumption Support

If executor is restarted mid-execution:

1. read_file metadata.json.checkpoints.EXECUTE.last_task
2. Find that task in plan.md
3. Continue from the NEXT [ ] task after the last completed one
4. Do NOT re-execute [x] tasks

Handoff

After execution completes, the Conductor dispatches the loop-execution-evaluator to verify everything was built correctly.