---
name: implement-task
description: Implement a task step by step with automated LLM-as-Judge verification at the end of each phase
---

# Implement Task with Verification

Your job is to implement solution in best quality using task specification and sub-agents. You MUST NOT stop until it is critically necessary or you are done! Avoid asking questions until it is critically necessary! Dispatch one implementation agent per step, then — when every step of an implementation phase is done — launch ONE `sdd:code-reviewer` for that phase, iterate till issues are fixed, then move to the next phase!

Execute task implementation steps with automated quality verification using a single `sdd:code-reviewer` agent per implementation phase.

## User Input

```text
$ARGUMENTS
```

---

## Vocabulary (read this first — two different things are called "phase")

| Term | Meaning |
|------|---------|
| **Workflow Phase 0-5** | The stages of THIS skill (select task, load, execute, DoD, move, report). |
| **Implementation phase** / `Phase N` | A milestone in the TASK file's `### Phase Overview`. It groups steps, names a `Reviewer model`, and lists the acceptance criteria due at that milestone. This is the unit of code review. |
| **Step** | One sub-task file at `.specs/sub-tasks/<task-name>/<NN>-<step-slug>.md`. This is the unit of implementation dispatch. The **step name** is that file's basename without `.md`. |

---

## Command Arguments

Parse the following arguments from `$ARGUMENTS`:

### Argument Definitions

| Argument | Format | Default | Description |
|----------|--------|---------|-------------|
| `task-file` | Path or filename | Auto-detect | Task file name or path (e.g., `add-validation.feature.md`) |
| `--continue` | `--continue` | None | Continue implementation from the last completed step: resolves the implementation phase in progress, completes its outstanding steps, then reviews that phase — see [Context Resolution for `--continue`](#context-resolution-for---continue). |
| `--refine` | `--refine` | `false` | Incremental refinement mode - detect changes against git, map them to steps, and re-verify from the implementation phase that owns the earliest affected step. |
| `--human-in-the-loop` | `--human-in-the-loop [Phase 1,Phase 3,...]` | None | Implementation phases after whose review to pause for human verification. If no phases specified, pauses after every implementation phase. |
| `--target-quality` | `--target-quality X.X` | `4.0` | Single target threshold value (out of 5.0) applied to every implementation phase review. |
| `--max-iterations` | `--max-iterations N` | `3` | Maximum fix→re-review cycles per implementation phase. Default is 3 iterations. Set to `unlimited` for no limit. |
| `--skip-reviews` | `--skip-reviews` | `false` | Skip all phase reviews - steps proceed without quality gates. |
| `--model` | `opus\|sonnet\|haiku` | Unset | Model for **all** sub-agents (implementation agents AND `sdd:code-reviewer`) that **overrides** every model in the task file; when omitted, step models come from the Parallelization Overview and reviewer models from the Phase Overview. |
| `--strict` | `--strict` | `false` | Disable the [Iteration Discretion Rule](#iteration-discretion-rule) - a phase is marked PASS ONLY when `combined_score >= THRESHOLD`, otherwise iterate until `MAX_ITERATIONS` is reached. |

### Configuration Resolution

Parse `$ARGUMENTS` and resolve configuration as follows:

```
# Extract task file (first positional argument, optional - auto-detect if not provided)
TASK_FILE = first argument that is a file path or filename

# Single quality threshold — there is exactly one, and it is NEVER read from the task file
THRESHOLD = --target-quality value || 4.0

# Initialize other defaults
MODEL_OVERRIDE = --model value (opus|sonnet|haiku) || none  # none = no override; models come from the task file
MAX_ITERATIONS = --max-iterations || 3  # default is 3 iterations
HUMAN_IN_THE_LOOP_PHASES = --human-in-the-loop || [] (empty = none, "*" = all implementation phases)
SKIP_REVIEWS = --skip-reviews || false
REFINE_MODE = --refine || false
CONTINUE_MODE = --continue || false
STRICT_MODE = --strict || false

# Special handling for --human-in-the-loop without a phase list
if --human-in-the-loop present without phase identifiers:
    HUMAN_IN_THE_LOOP_PHASES = "*" (all implementation phases)
```

**`THRESHOLD` is the ONLY quality threshold in this workflow.** There is no separate standard/critical/lenient value, no comma-separated form, and no threshold anywhere in the task file — the planning agents are forbidden from writing one.

### Context Resolution for `--continue`

When `--continue` is used, state is resolved by **implementation phase, then step**:

1. **Phase and Step Resolution:**
   - Read the task file's `### Parallelization Overview` step table and `### Phase Overview`.
   - A step is complete when its row in the step table is marked `[DONE]`.
   - An implementation phase is complete when its `#### Phase N` heading carries **either** marker: `[REVIEWED]` (its review ran and passed) or `[REVIEWED-SKIPPED]` (its steps finished and its review was deliberately suppressed by an earlier `--skip-reviews` run).
   - `RESUME_PHASE` = the first implementation phase marked **neither** `[REVIEWED]` **nor** `[REVIEWED-SKIPPED]`. Treating `[REVIEWED-SKIPPED]` as unfinished would re-run exactly the review the user suppressed.
   - `RESUME_STEPS` = the steps of `RESUME_PHASE` that are not `[DONE]`, in dependency order.
2. **Verify the resumed phase's existing work:**
   - If `RESUME_PHASE` already has some `[DONE]` steps but neither marker, and `RESUME_STEPS` is empty (all steps done, review never ran):
     - **If `SKIP_REVIEWS` is true: launch nothing.** Mark the phase `[REVIEWED-SKIPPED]` and resume at the next implementation phase.
     - Otherwise: launch the `sdd:code-reviewer` for `RESUME_PHASE` (passing the 4 inputs documented in Workflow Phase 2) — **Model**: `MODEL_OVERRIDE` if set — otherwise that phase's `Reviewer model`.
       - If the phase PASSES per the [Iteration Discretion Rule](#iteration-discretion-rule): mark it `[REVIEWED]` and resume at the next implementation phase.
       - Otherwise: enter the [Failure Handling](#failure-handling-reason-about-blast-radius-your-most-critical-judgement) flow for that phase.
   - If `RESUME_STEPS` is non-empty: dispatch those steps first, then review the phase as normal — and `SKIP_REVIEWS` still suppresses that review, marking the phase `[REVIEWED-SKIPPED]` instead.
3. **State Recovery:**
   - Check task file location (`in-progress/`, `todo/`, `done/`)
   - If in `todo/`, move to `in-progress/` before continuing
   - Pre-populate captured values from existing artifacts

### Refine Mode Behavior (`--refine`)

When `--refine` is used, it detects changes to **project files** (not the task file) and maps them to steps, then re-verifies from the implementation phase that owns the earliest affected step.

1. **Detect Changed Project Files:**

   First, determine what to compare against based on git state:

   ```bash
   # Check for staged changes
   STAGED=$(git diff --cached --name-only)

   # Check for unstaged changes
   UNSTAGED=$(git diff --name-only)
   ```

   **Comparison logic:**

   | Staged | Unstaged | Compare Against | Command |
   |--------|----------|-----------------|---------|
   | Yes | Yes | Staged (unstaged only) | `git diff --name-only` |
   | Yes | No | Last commit | `git diff HEAD --name-only` |
   | No | Yes | Last commit | `git diff HEAD --name-only` |
   | No | No | No changes | Exit with message |

   - If **both staged AND unstaged**: Compare working directory vs staging area (unstaged changes only)
   - If **only staged OR only unstaged**: Compare against last commit
   - This ensures refine operates on the most recent work in progress

2. **Map Changes to Steps:**
   - Read the task file's `### Parallelization Overview` to get every step name, its implementation phase, and its `Sub-Task File` path.
   - **Refine mode is the ONE case where you may read sub-task files**: they are specification artifacts (like the task file), not implementation outputs, and their `#### Expected Output` sections are the only place file paths per step are recorded. Read ONLY the `#### Expected Output` and `#### Subtasks` sections you need.
   - Build a mapping: `{changed_file → step name → implementation phase}`

3. **Determine Affected Scope:**
   - Find all steps that have associated changed files
   - `REFINE_FROM_PHASE` = the earliest implementation phase containing an affected step
   - All implementation phases from that point onwards need re-verification
   - Earlier phases (unaffected) are preserved as-is

4. **Refine Execution:**
   - For each affected implementation phase (in order):
     - Launch ONE **`sdd:code-reviewer` agent** to verify the phase (including the user's changes), passing the 4 standard inputs — **Model**: `MODEL_OVERRIDE` if set — otherwise that phase's `Reviewer model`
     - If the phase PASSES per the [Iteration Discretion Rule](#iteration-discretion-rule): mark it `[REVIEWED]`, proceed to the next phase
     - Otherwise: enter the [Failure Handling](#failure-handling-reason-about-blast-radius-your-most-critical-judgement) flow, then re-review
   - User's manual fixes are preserved - implementation agents should build upon them, not overwrite

5. **Example:**

   ```bash
   # User manually fixed src/validation/validation.service.ts
   # (This file is the Expected Output of step `02-validation-service`, in Phase 1)

   /implement my-task.feature.md --refine

   # Detects: src/validation/validation.service.ts modified
   # Maps to: step `02-validation-service` → Phase 1
   # Action: Launch ONE sdd:code-reviewer for Phase 1
   #   - If PASS: User's fix is good, proceed to Phase 2
   #   - If FAIL: reason about blast radius, dispatch fixes for the affected
   #     steps only, without overwriting the user's changes, then re-review
   # Continues: Phase 2, Phase 3... (re-verify all subsequent phases)
   ```

6. **Multiple Files Changed:**

   ```bash
   # User edited an output of a Phase 1 step AND an output of a Phase 3 step

   /implement my-task.feature.md --refine

   # Earliest affected phase: Phase 1
   # Re-verifies: Phase 1, Phase 2, Phase 3...
   # (Phase 2 re-verified even though no direct changes, because it builds on Phase 1)
   ```

7. **Staged vs Unstaged Changes:**

   ```bash
   # Scenario: User staged some changes, then made more edits
   # Staged: src/validation/validation.service.ts (git add done)
   # Unstaged: src/validation/validators/email.validator.ts (still editing)

   /implement my-task.feature.md --refine

   # Detects: Both staged AND unstaged changes exist
   # Mode: Compares unstaged only (working dir vs staging)
   # Only email.validator.ts is considered for refine

   # --

   # Scenario: User only has staged changes (ready to commit)
   # Staged: src/validation/validation.service.ts
   # Unstaged: none

   /implement my-task.feature.md --refine

   # Detects: Only staged changes
   # Mode: Compares against last commit
   ```

### Human-in-the-Loop Behavior

Human verification checkpoints are keyed on **implementation phases**, never on individual steps.

1. **Trigger Conditions:**
   - After an orchestrator-level **PASS** on the review of an implementation phase in `HUMAN_IN_THE_LOOP_PHASES`
   - After a fix iteration completes for such a phase (before the next re-review)
   - If `HUMAN_IN_THE_LOOP_PHASES` is `"*"`, triggers after every implementation phase

2. **At Checkpoint:**
   - Display the phase's step results summary
   - Display generated artifacts with paths
   - Display the reviewer's `combined_score` and consolidated issues
   - Ask user: "Review phase output. Continue? [Y/n/feedback]"
   - If user provides feedback, incorporate into the next iteration or phase
   - If user says "n", pause workflow

3. **Checkpoint Message Format:**

   ```markdown
   ---
   ## 🔍 Human Review Checkpoint - Phase N

   **Phase:** {phase heading}
   **Steps:** {step names}
   **Reviewer model:** {model used}
   **Combined Score:** {combined_score}/5.0 (threshold: {THRESHOLD})
   **Status:** ✅ PASS / ☑️ ACCEPTED / 🔄 ITERATING (attempt {n})

   **Artifacts Created/Modified:**
   - {artifact_path_1}
   - {artifact_path_2}

   **Reviewer Feedback (top issues):**
   {feedback summary — High/Medium issues from reviewer.issues, with the step each belongs to}

   **Action Required:** Review the above artifacts and provide feedback or continue.

   > Continue? [Y/n/feedback]:
   ---
   ```

---

## Task Selection and Status Management

### Task Status Folders

Task status is managed by folder location:

- `.specs/tasks/todo/` - Tasks waiting to be implemented
- `.specs/tasks/in-progress/` - Tasks currently being worked on
- `.specs/tasks/done/` - Completed tasks

The task's sub-task folder `.specs/sub-tasks/<task-name>/` **never moves** while the task file travels between these folders, so the `Sub-Task File` paths recorded in the task file stay valid.

### Status Transitions

| When | Action |
|------|--------|
| Start implementation | Move task from `todo/` to `in-progress/` |
| Final verification PASS | Move task from `in-progress/` to `done/` |
| Implementation failure (user aborts) | Keep in `in-progress/` |

---

## CRITICAL: You Are an ORCHESTRATOR ONLY

**Your role is DISPATCH and AGGREGATE. You do NOT do the work.**

Properly build context of sub agents!

CRITICAL: For each sub-agent you dispatch, you MUST provide:

**For an implementation agent (one per step):**

- Task file path
- **That step's sub-task file path** — exactly one, taken from the `Sub-Task File` column of the Parallelization Overview
- **Value of `${CLAUDE_PLUGIN_ROOT}` so agents can resolve paths like `@${CLAUDE_PLUGIN_ROOT}/scripts/create-scratchpad.sh`**

**For the `sdd:code-reviewer` (one per implementation phase):**

- Task file path
- Phase identifier
- Artifact path(s) reported by that phase's implementation agents
- `CLAUDE_PLUGIN_ROOT`

### What You DO

- Read the task file ONCE (Workflow Phase 1 only)
- Launch sub-agents via Task tool
- Receive reports from sub-agents
- Mark steps and implementation phases complete after the orchestrator-level PASS rule on reviewer output as [DONE]
- Reason about blast radius when a phase review fails, and choose fix / re-review models accordingly
- Aggregate results and report to user

### What You NEVER Do

| Prohibited Action | Why | What To Do Instead |
|-------------------|-----|-------------------|
| Read implementation outputs | Context bloat → command loss | Sub-agent reports what it created |
| Read sub-task files (except `--refine` mapping) | The implementation agent reads its own sub-task file | Pass the path from the Parallelization Overview |
| Read reference files | Sub-agent's job to understand patterns | Include path in sub-agent prompt |
| Read artifacts to "check" them | Context bloat → forget verifications | Launch `sdd:code-reviewer` agent |
| Evaluate code quality yourself | Not your job, causes forgetting | Launch `sdd:code-reviewer` agent |
| Review a step individually | Review is a PHASE-level gate | Review once, at the end of the phase |
| Skip a phase review "because simple" | Every phase review is mandatory unless `--skip-reviews` | Launch `sdd:code-reviewer` anyway |
| Never add comments/marks/notes about results of review, scratchpads, iterations, etc. to the task file. | The task file is a specification artifact, not a log. If task not done, it should be visible from code only! | You can write only [DONE] mark ever, or nothing at all! |

### Anti-Rationalization Rules

**If you think:** "I should read this file to understand what was created"
**→ STOP.** The sub-agent's report tells you what was created. Use that information.

**If you think:** "I'll quickly verify this looks correct"
**→ STOP.** Launch a `sdd:code-reviewer` agent. That's not your job.

**If you think:** "This phase is too simple to need verification"
**→ STOP.** Unless `SKIP_REVIEWS` is true, every implementation phase gets exactly one review. No exceptions.

**If you think:** "This step looks risky, I'll review it before the phase ends"
**→ STOP.** Reviewing per step is exactly what this workflow removed. Wait for the phase to complete.

**If you think:** "I need to read the sub-task file to write a good prompt"
**→ STOP.** Put the sub-task file PATH in the sub-agent prompt. The sub-agent reads it.

### Why This Matters

Orchestrators who read files themselves = context overflow = command loss = forgotten steps. Every time.

Orchestrators who "quickly verify" = skip `sdd:code-reviewer` agents = quality collapse = failed artifacts.

**Your context window is precious. Protect it. Delegate everything.**

---

## CRITICAL

### Configuration Rules

- **Model precedence (`MODEL_OVERRIDE`): if `--model` was given, that model WINS over the task file and over every default in this skill — dispatch EVERY sub-agent with it (implementation agents of any type AND `sdd:code-reviewer`), ignoring the Parallelization Overview's `Model` column and the Phase Overview's `Reviewer model`. It is an override, NOT a fallback. If `--model` was NOT given (`MODEL_OVERRIDE = none`), model selection is unchanged: each step uses the `Model` its Parallelization Overview row names, and each phase review uses that phase's `Reviewer model`, falling back to the default named in each dispatch block.**
- Use the single `THRESHOLD` (default 4.0) for every implementation phase review. There is no per-component, per-criticality or lenient variant.
- **Never read a threshold from the task file.** The planning agents write none; if one somehow appears, ignore it.
- The threshold is applied at THIS orchestrator layer against `combined_score` returned by code-reviewer. **NEVER pass any threshold to the code-reviewer agent — or he will try to reach target score and as result become subjective.**
- A phase PASSES if `combined_score >= THRESHOLD`. If `3.0 <= combined_score < THRESHOLD`, the phase passes ONLY when the [Iteration Discretion Rule](#iteration-discretion-rule) says so — never below the fixed floor of `3.0`. If `combined_score < 3.0`, the phase FAILS unconditionally.
- **Default is 3 iterations** - stop after 3 fix→re-review cycles for an implementation phase and proceed to the next phase (with warning)!
- If `MAX_ITERATIONS` is set to `unlimited`: Iterate until the quality threshold is met (no limit)
- Trigger human-in-the-loop checkpoints ONLY after implementation phases in `HUMAN_IN_THE_LOOP_PHASES` (or all phases if `"*"`)!
- **If `SKIP_REVIEWS` is true: Skip ALL code-reviewer dispatches - proceed directly to the next implementation phase after its steps complete!**
- **If `CONTINUE_MODE` is true: Skip to `RESUME_PHASE` / `RESUME_STEPS` - do not re-implement already completed steps!**
- **If `REFINE_MODE` is true: Detect changed project files, map to steps, re-verify from `REFINE_FROM_PHASE` - preserve user's fixes!**
- **If `STRICT_MODE` is true: The [Iteration Discretion Rule](#iteration-discretion-rule) is DISABLED - a phase passes ONLY on `combined_score >= THRESHOLD`, otherwise iterate until `MAX_ITERATIONS`!**

### Execution & Evaluation Rules

- **Use foreground agents only**: Do not use background agents. Launch parallel agents when possible. Background agents constantly run in permissions issues and other errors.
- **Parallelism comes from the task file**: steps whose `Parallel with:` column names each other MUST be dispatched simultaneously in one message. Never serialize what the plan says is parallel.
- **Never cross a phase boundary in parallel**: a step of `Phase N+1` may only start after `Phase N` has been reviewed and marked `[REVIEWED]` (or marked `[REVIEWED-SKIPPED]` when `SKIP_REVIEWS` is true).

Relaunch the code-reviewer till you get valid results, if following happens:

- Reject Long Reports: If the code-re