implementing-plans

What this skill does

# Implementation Phase

Execute the implementation plan for: **$ARGUMENTS**

## Purpose

Implementation executes an approved plan with discipline and verification. The goal is not just working code, but
verified, documented progress that matches the plan. Implementation follows the plan strictly, verifying each step
before proceeding.

## Process

### 1. Locate the Plan

**If `$ARGUMENTS` is a file path** (starts with `/` or `docs/` or ends with `.md`):

- Read the file at that path directly
- Check if plan is marked approved
- Proceed based on stakes level

**Otherwise, search for plan by topic:**

Look for plan at: `docs/plans/YYYY-MM-DD-<topic>-plan.md`

(Search for files matching `*-<topic>-plan.md` pattern using `$ARGUMENTS` as the topic)

**If plan exists:**

- Read the plan document
- Check if plan is marked approved
- Proceed based on stakes level

**If no plan exists:**

- Check stakes level of the requested work
- Apply enforcement based on stakes

### 2. Apply Stakes-Based Enforcement

**High Stakes** (architectural, security-sensitive, hard to rollback):

```text
Cannot proceed without an approved plan.

High-stakes implementations require:
1. Research phase (rpikit:researching-codebase skill)
2. Approved plan (rpikit:writing-plans skill)

Invoke the Skill tool with skill "rpikit:writing-plans" to create a plan first.
```

Stop and do not proceed.

**Medium Stakes** (multiple files, moderate impact):

```text
Warning: No approved plan found for '$ARGUMENTS'.

Medium-stakes changes benefit from planning.
```

Use AskUserQuestion with options:

- "Create a plan first" (recommended)
- "Proceed with caution"
- "Cancel"

**Low Stakes** (isolated, easy rollback):

```text
Note: Consider rpikit:researching-codebase and rpikit:writing-plans skills for better results.
Proceeding with implementation...
```

Proceed with inline planning.

### 3. Offer Worktree Isolation

Before making changes, offer to create an isolated worktree.

**First, check if already in a worktree:**

```bash
# Check if .git is a file (indicates additional worktree, not main repo)
test -f .git
```

Run this command via the Bash tool:

- Exit code 0 (success): `.git` is a file → already in a worktree → skip
  the prompt and proceed to progress tracking
- Exit code 1 (failure): `.git` is a directory → main repository →
  continue with the worktree offer below

**If not in a worktree, offer based on stakes level:**

**High Stakes:**

Use AskUserQuestion with options:

- "Use worktree (Recommended)" - Create isolated workspace for safer
  changes
- "Continue in current directory" - Proceed without isolation

**Medium Stakes:**

Use AskUserQuestion with options:

- "Use worktree" - Create isolated workspace
- "Continue in current directory" - Proceed without isolation

**Low Stakes:**

Brief mention only:

```text
Tip: For isolation, use EnterWorktree.
Proceeding in current directory...
```

Skip the prompt and continue.

**If user chooses worktree:**

Use EnterWorktree to create the isolated workspace. Implementation
continues in the new worktree directory.

When implementation is complete, use ExitWorktree with action: "keep" to
preserve the branch and return to the main working directory.

If implementation is aborted (user cancels at a checkpoint or
verification fails beyond recovery), use ExitWorktree with
action: "discard" to clean up the worktree without preserving changes.

> **Caution**: EnterWorktree has known active bugs — `bypassPermissions`
> may be ineffective
> ([#29110](https://github.com/anthropics/claude-code/issues/29110)) and
> background agents may not have `pwd` set correctly
> ([#27749](https://github.com/anthropics/claude-code/issues/27749)).
> Always verify the working directory after entering a worktree.

### 4. Initialize Progress Tracking

Create tasks from plan steps using TaskCreate:

Read each step from the plan and create a corresponding task:

- Use step descriptions as the task subject (imperative form)
- Include the step's action and verify criteria in the task description
- Set `activeForm` to a present-continuous description (e.g., "Implementing
  auth middleware")
- All tasks start as pending
- Use `addBlockedBy` via TaskUpdate when plan steps have sequential
  requirements (e.g., Step 1.2 depends on Step 1.1)

### 5. Execute Steps in Order

For each step in the plan:

1. **Mark in_progress** - Update task via TaskUpdate
2. **Locate target files** - If file path is unclear or missing, use file-finder:

   ```text
   Task tool with subagent_type: "file-finder"
   Prompt: "Find [what the step describes]. Need to [action from plan]"
   ```

3. **Read target files** - Always read before modifying
4. **Make the change** - Follow plan specification exactly
5. **Run verification** - Execute the verify criteria
6. **Confirm success** - Only proceed if verification passes
7. **Mark completed** - Update task via TaskUpdate immediately
8. **Update plan** - Mark step complete in plan document

### 6. Checkpoint After Phases

After completing each phase:

Summarize progress:

```text
Phase [N] complete:
- Step N.1: [description]
- Step N.2: [description]
- Step N.3: [description]

Verifications: All passed
```

Use AskUserQuestion:

- "Continue to Phase [N+1]"
- "Review changes so far"
- "Pause implementation"

### 7. Handle Failures

When verification fails:

1. **Stop** - Do not proceed to next step
2. **Report** - Explain what failed and why
3. **Diagnose** - Investigate the cause. If the error involves external
   libraries or unfamiliar issues, use web-researcher:

   ```text
   Task tool with subagent_type: "web-researcher"
   Prompt: "[error message or issue] in [library/context]"
   ```

4. **Propose fix** - Suggest correction based on diagnosis

If fix requires plan changes:

```text
Verification failed for Step [X.Y]: [description]

The planned approach doesn't work because: [reason]

Proposed adjustment: [new approach]
```

Use AskUserQuestion:

- "Approve adjustment and continue"
- "Return to planning"
- "Cancel implementation"

### 8. Complete Implementation

When all steps are done:

1. Mark all tasks completed via TaskUpdate
2. Update plan document status section
3. Run final verification (full test suite if applicable)
4. Run code review:

   ```text
   Task tool with subagent_type: "code-reviewer"
   Prompt: "Review implementation changes for: $ARGUMENTS"
   ```

   If verdict is REQUEST CHANGES (soft gate):

   Use AskUserQuestion:

   - "Address findings first" (recommended)
   - "Proceed anyway"
   - "Cancel implementation"

   If user chooses "Proceed anyway", continue to security review.

5. Run security review:

   ```text
   Task tool with subagent_type: "security-reviewer"
   Prompt: "Review implementation changes for: $ARGUMENTS"
   ```

   If verdict is FAIL, stop and address findings before completing.

6. Summarize results

```text
Implementation complete for '$ARGUMENTS'.

Summary:
- Steps completed: [N]
- Phases completed: [M]
- Files changed: [list]
- Tests: [pass/fail status]

Plan updated: docs/plans/YYYY-MM-DD-<topic>-plan.md

All success criteria met.
```

## Core Principles

### Follow the Plan

The plan is the contract. Deviations require explicit approval:

- Execute steps in order
- Use specified files and approaches
- Meet verification criteria before proceeding
- Document any necessary deviations

### Verify Before Claiming Done

Never claim completion without evidence:

- Run the verification for each step
- Confirm tests pass
- Check that changes match expectations
- Document verification results

### Track Progress Visibly

Use TaskCreate / TaskUpdate / TaskList for real-time progress:

- Create tasks from plan steps via TaskCreate
- Mark in_progress via TaskUpdate when starting
- Mark completed via TaskUpdate only after verification
- Use TaskList to review overall progress
- Update plan document with status

## Progress Documentation

### Task-Based Tracking

Maintain real-time visibility using structured t