plan-executor

What this skill does

# Plan Executor Skill

This skill executes and coordinates work on existing PLAN files. It handles progress tracking, worker coordination (in worker mode), commit management, and phase advancement.

## When to Use This Skill

Use this skill when:
- User references an existing PLAN file (e.g., `@PLAN-auth.md`)
- User asks to "continue the plan" or "execute the plan"
- User asks to "work on" or "resume" a project with a PLAN file
- User wants to see plan status or progress

Do NOT use this skill when:
- User wants to CREATE a new plan (use `plan-generator` skill instead)
- User wants to modify the plan structure (add/remove phases)

## CRITICAL RULES

**These rules MUST be followed at all times:**

### 1. ALWAYS Respect Execution Mode

The execution mode is defined in the JSON state block (`execution.mode`). **You MUST follow it:**

- **If `mode` is `"worker"`**: You are a COORDINATOR. Do NOT execute steps directly. Launch `plan-worker` sub-agents to do the work. NEVER perform implementation work yourself in worker mode.
- **If `mode` is `"direct"`**: Execute steps directly in the main session.

**On resume**: Re-read the JSON state and respect the mode. Do not switch modes.

### 2. ALWAYS Update State Immediately

State updates MUST happen in real-time, not batched:

- **BEFORE starting ANY step**: Run `scripts/plan-tool start <file> <step-id>`
- **IMMEDIATELY after completing a step**: Run `scripts/plan-tool complete <file> <step-id> --summary "..."`
- **Never skip state updates** - if the session is interrupted, state should reflect reality

This ensures that if execution is interrupted, the plan can resume from the correct point.

---

## Understanding Plan State

PLAN files contain a JSON state block at the end wrapped in HTML comment markers:

```
<!--PLAN-STATE
{
  "schema_version": "1.0",
  "execution": {
    "mode": "direct",           // or "worker"
    "auto_continue": false,     // auto-advance to next phase when current completes
    "commit_after_phase": false,
    "include_plan_in_commit": true
  },
  "current_phase": 0,           // -1 means all complete
  "phases": [
    {
      "id": 0,
      "name": "Setup",
      "steps": [
        { "id": "0.1", "status": "pending" },
        { "id": "0.2", "status": "completed", "summary": "..." }
      ]
    }
  ]
}
PLAN-STATE-->
```

### Step Status Values

- `pending` - Not started
- `in_progress` - Currently being worked on (only ONE at a time)
- `completed` - Finished successfully
- `blocked` - Cannot proceed (includes `blocker` field with reason)

### Initializing Plan State

When a PLAN file does not have a JSON state block, initialize it before starting execution:

```bash
scripts/plan-tool init <file> [--mode direct|worker] [--auto-continue] [--commit] [--no-plan-in-commit]
```

The `init` command parses the markdown headings to discover phases and steps, then generates the JSON state block at the end of the file.

**Options:**
- `--mode direct|worker`: Execution mode (default: direct)
- `--auto-continue`: Enable auto-advancement between phases
- `--commit`: Enable commits after each phase
- `--no-plan-in-commit`: Exclude PLAN file from commits

Example:
```bash
scripts/plan-tool init PLAN-auth.md --mode worker --auto-continue --commit --no-plan-in-commit
```

### Reading Plan State

When starting execution:
1. Read the entire PLAN file
2. Check if JSON state block exists (look for `<!--PLAN-STATE` marker)
3. **If no JSON state block exists**: Initialize it using `scripts/plan-tool init` with options based on the execution preferences in the Instructions section
4. Parse the JSON state block to understand:
   - Which execution mode is active (`direct` or `worker`)
   - Which phase is current (`current_phase`)
   - Which steps are `pending`, `in_progress`, `completed`, or `blocked`
5. Check for any `blocked` steps that need resolution
6. Identify the next actionable step(s)

## Progress Tracking Commands

Use the `scripts/plan-tool` script (relative to this skill directory) to manage JSON state updates.

### Starting a Step

Before beginning work on a step:

```bash
scripts/plan-tool start <file> <step-id>
```

Example:
```bash
scripts/plan-tool start PLAN-auth.md 1.2
```

**Note:** Only ONE step can be `in_progress` at a time. Starting a new step automatically resets any previously in-progress step to `pending`.

### Completing a Step

After successfully finishing a step:

```bash
scripts/plan-tool complete <file> <step-id> [--summary "..."]
```

Example:
```bash
scripts/plan-tool complete PLAN-auth.md 1.2 --summary "Added JWT validation middleware with RS256 support"
```

**Auto-advancement:** If all steps in the current phase are completed and `auto_continue` is enabled, the phase automatically advances.

### Blocking a Step

When a step cannot proceed due to an issue:

```bash
scripts/plan-tool block <file> <step-id> --reason "..."
```

Example:
```bash
scripts/plan-tool block PLAN-auth.md 1.3 --reason "Redis not configured - refresh tokens need persistent storage"
```

### Unblocking a Step

To clear a blocked status after resolving the issue:

```bash
scripts/plan-tool unblock <file> <step-id>
```

### Advancing Phase

To manually advance to the next phase:

```bash
scripts/plan-tool next-phase <file> [--force]
```

Use `--force` to advance even if some steps are incomplete or blocked (not recommended).

## Direct Mode Execution

In direct mode, execute steps directly in the main Claude Code session.

### Execution Flow

1. **Identify next step**: Find the first `pending` step in the current phase
2. **Mark as in-progress**: Run `scripts/plan-tool start`
3. **Execute the step**: Perform all work described in the step
4. **Document completion**: Add notes under the step heading in markdown:
   ```markdown
   ### Step 1.2: Implement user validation
   Original step description...
   - **Completed:** Added email regex validation and password strength check
   - **Decision:** Used zxcvbn library for password scoring
   ```
5. **Update state**: Run `scripts/plan-tool complete` with a brief summary
6. **Repeat**: Continue with next pending step

### Stopping Conditions

Only stop when:
- An entire phase is complete AND `auto_continue` is disabled (ask user if they want to continue)
- An actual error or blocker occurs
- User explicitly requests to pause
- All phases are complete

**If `auto_continue` is enabled:** Do NOT stop between phases. Immediately proceed to the next phase.

### Adding Implementation Notes

After completing steps, add detailed notes to the **Notes & Decisions** section:

```markdown
## Notes & Decisions

### Phase 1: Core Implementation (Completed)
- Implemented JWT generation using RS256 algorithm
- Chose 15-minute expiry for access tokens based on security best practices
- Added refresh token rotation to prevent token reuse
```

## Worker Mode Execution

In worker mode, delegate step execution to `plan-worker` sub-agents. The main session acts as a coordinator.

### Coordinator Protocol

#### 1. Identify Next Work Batch

Parse the JSON state block to find steps with `"status": "pending"` in the current phase. Determine batch size by considering:

- **Step dependencies**: If step N+1 needs output from step N, batch them together
- **Complexity**: Steps involving multiple files, tests, or debugging -> smaller batches (1-2 steps)
- **Independence**: Simple, independent steps -> can batch more (3-5 steps)
- **Default**: 2-4 related steps per worker, or an entire phase if steps are simple

#### 2. Prepare Worker Context

Gather the information the worker needs:

- **Project goal**: 1-2 sentences from Project Overview
- **Specific steps**: Full descriptions from the plan
- **Relevant files**: List of files the worker will need to read or modify
- **Success criteria**: Derived from step descriptions
- **Inline examples**: Any relevant examples from the plan

#### 3. Mark Steps and Launch Worker

**BEFORE launching the worker**, mark all assigned steps as in-progress:

`