# Implement Task

> Implement a task step by step with automated LLM-as-Judge verification at the end of each phase

- Skill: `neolabhq/implement-task` (Agent Skill)
- Install (CLI): `npx skillmds@latest add neolabhq/implement-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/neolabhq/implement-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: neolabhq (https://skillmd.com/u/neolabhq)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/neolabhq/implement-task

---


# 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-reviewer returns a very long report instead of using the scratchpad as requested, reject the result. This indicates the agent failed to follow the "use scratchpad" instruction.
- Combined Score 5.0 is a Hallucination: If the code-reviewer returns a `combined_score` of exactly 5.0/5.0, treat it as a hallucination or lazy evaluation. Reject it and re-run the agent. This applies to the **weighted aggregate only** — an individual criterion may legitimately score 5 and no score is rationed, but every criterion across spec compliance, code quality and Muda waste analysis landing strictly past its `score_4` anchor at once is not a plausible review outcome. Never use it as a reason to question a single high criterion score.
- Reject Missing Scores: If the code-reviewer's report is missing the `combined_score` (or any sub-score: `spec_compliance_score`, `builtin_score`), reject it. This indicates the agent failed to follow the rubric instructions.
- Reject PASS/FAIL Verdicts in Report: If the code-reviewer's output contains a PASS/FAIL verdict or references a threshold, reject it. The orchestrator owns that decision; the agent must remain threshold-blind.
- Reject Out-of-Scope Findings: If the reviewer penalizes acceptance criteria that the phase's `#### Phase N` block does NOT list — reporting work a LATER phase delivers as "missing" or "incomplete" — reject the report and re-run the agent, restating that a phase is a checkpoint, not the finish line.

#### Iteration Discretion Rule

Your main task is to COMPLETE the task within target quality. Two failure modes are equally real:

- Burning iterations and context on nitpicks so the overall task never completes → **the task is failed**.
- Accepting a result whose quality is genuinely too poor to be considered complete → **an even worse failure**.

Apply to every implementation phase's `combined_score`:

- **`combined_score < 3.0` → FAIL, unconditionally. No discretion.** Iterate with reviewer feedback until the phase passes or `MAX_ITERATIONS` is reached.
- **`3.0 <= combined_score < THRESHOLD` → discretion band.** ONLY inside this band MAY you decide that a phase below the target is acceptable. The fixed floor is `3.0` and the band ceiling is `THRESHOLD`. If `--target-quality` set `THRESHOLD <= 3.0` the band is empty: every score is either an unconditional FAIL (`< 3.0`) or a PASS, and there is no discretion to exercise.
- Inside the band, when the outstanding issues are ONLY `Low`/`Medium` priority (any `High` or `Critical` finding removes discretion entirely) AND none of them breaks an acceptance criterion the phase is responsible for or causes a meaningful defect (i.e. they are nitpicks), you MUST reason FIRST — before dispatching another iteration — about whether iterating (or marking the phase failed) is worth the time and context cost.
- **At most ONE nitpick-driven iteration**, and it counts against `MAX_ITERATIONS`. If it again surfaces only nitpicks, you MUST mark the phase PASS (☑️ ACCEPTED in the summary table), report the outstanding issues in the final report, and continue with the next phase. If it returns a `combined_score` below `3.0`, the FAIL path applies instead.
- **A phase that does not build, lint or test green is NEVER inside the discretion band**, whatever the score says. Each phase must leave a working, committable, CI-green state.
- You MUST be critical, NOT lenient. Stopping short of target MUST be an intentional decision grounded in the absence of real, requirement-breaking issues. A genuine blocking issue that prevents completing the phase within `MAX_ITERATIONS` MUST be reported as a failure, never papered over.
- **If `STRICT_MODE` is true, this whole rule is DISABLED**: stop only when `combined_score >= THRESHOLD` or `MAX_ITERATIONS` is reached. `--strict` changes nothing else — `THRESHOLD`, `MAX_ITERATIONS`, the `< 3.0` unconditional FAIL, human-in-the-loop checkpoints, code-reviewer dispatch and `--skip-reviews` are unaffected. With `--skip-reviews` no `combined_score` is produced at all, so both this rule and `--strict` are inert.

---

## Overview

This command orchestrates multi-step task implementation with:

1. **Sequential execution** respecting step dependencies
2. **Parallel execution** where the plan's `Parallel with:` column allows
3. **One implementation agent per step**, dispatched with the task file path AND its sub-task file path
4. **One automated verification per implementation phase**, at that phase's `Reviewer model`
5. **Blast-radius reasoning** to pick the fix and re-review models when a phase review fails
6. **Progress tracking** with confirmation after each orchestrator-level PASS

---

## Complete Workflow Overview

```
Workflow Phase 0: Select Task & Move to In-Progress
    │
    ├─── Use provided task file name or auto-select from todo/ (if only 1 task)
    ├─── Move task: todo/ → in-progress/
    │
    ▼
Workflow Phase 1: Load Task
    │   Parse ### Parallelization Overview (steps, models, agents, sub-task paths)
    │   Parse ### Phase Overview (phases, steps, reviewer models, criteria due)
    │
    ▼
Workflow Phase 2: Execute Implementation Phases
    │
    ├─── For each implementation phase, in order:
    │    │
    │    ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ For each step of the phase, in dependency order │
    │    │ (parallel steps dispatched simultaneously):     │
    │    │   Launch its agent at its Model with            │
    │    │   task file path + sub-task file path           │
    │    └─────────────────┬───────────────────────────────┘
    │                      │  all steps of the phase reported complete
    │                      ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ Launch ONE sdd:code-reviewer for the PHASE      │
    │    │ at the phase's Reviewer model                   │
    │    └─────────────────┬───────────────────────────────┘
    │                      │
    │                      ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ Orchestrator reads combined_score and applies   │
    │    │ THRESHOLD:                                      │
    │    │  PASS → Mark phase [REVIEWED], next phase       │
    │    │  FAIL → Reason about BLAST RADIUS, choose fix   │
    │    │         model + scope + re-review model,        │
    │    │         re-review (max MAX_ITERATIONS)          │
    │    └─────────────────────────────────────────────────┘
    │
    ▼
Workflow Phase 3: Definition of Done Verification
    │
    ├─── Verify all Definition of Done items
    │    │
    │    ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ Launch sdd:developer agent                      │
    │    │ (verify all DoD items)                          │
    │    └─────────────────┬───────────────────────────────┘
    │                      │
    │                      ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ All DoD PASS? → Proceed to Workflow Phase 4     │
    │    │ Any FAIL? → Fix and re-verify (iterate)         │
    │    └─────────────────────────────────────────────────┘
    │
    ▼
Workflow Phase 4: Move Task to Done
    │
    ├─── Move task: in-progress/ → done/
    │
    ▼
Workflow Phase 5: Final Report
```

---

## Workflow Phase 0: Parse User Input and Select Task

Parse user input to get the task file path and arguments.

### Step 0.1: Resolve Task File

**If `$ARGUMENTS` is empty or only contains flags:**

1. **Check in-progress folder first:**

   ```bash
   ls .specs/tasks/in-progress/*.md 2>/dev/null
   ```

   - If exactly 1 file → Set `$TASK_FILE` to that file, `$TASK_FOLDER` to `in-progress`
   - If multiple files → List them and ask user: "Multiple tasks in progress. Which one to continue?"
   - If no files → Continue to step 2

2. **Check todo folder:**

   ```bash
   ls .specs/tasks/todo/*.md 2>/dev/null
   ```

   - If exactly 1 file → Set `$TASK_FILE` to that file, `$TASK_FOLDER` to `todo`
   - If multiple files → List them and ask user: "Multiple tasks in todo. Which one to implement?"
   - If no files → Report "No tasks available. Create one with /add-task first." and STOP

**If `$ARGUMENTS` contains a task file name:**

1. Search for the file in order: `in-progress/` → `todo/` → `done/`
2. Set `$TASK_FILE` and `$TASK_FOLDER` accordingly
3. If not found, report error and STOP

### Step 0.2: Move to In-Progress (if needed)

**If task is in `todo/` folder:**

```bash
git mv .specs/tasks/todo/$TASK_FILE .specs/tasks/in-progress/
# Fallback if git not available: mv .specs/tasks/todo/$TASK_FILE .specs/tasks/in-progress/
```

Update `$TASK_PATH` to `.specs/tasks/in-progress/$TASK_FILE`

**If task is already in `in-progress/`:**
Set `$TASK_PATH` to `.specs/tasks/in-progress/$TASK_FILE`

**Do NOT move the sub-task folder.** `.specs/sub-tasks/<task-name>/` stays where planning created it; the `Sub-Task File` paths in the task file already point there.

### Step 0.3: Parse Flags and Initialize Configuration

Parse all flags from `$ARGUMENTS` and initialize configuration.
**Display resolved configuration:**

```markdown
### Configuration

| Setting | Value |
|---------|-------|
| **Task File** | {TASK_PATH} |
| **Model Override** | {MODEL_OVERRIDE or "None (models from task file)"} |
| **Threshold** | {THRESHOLD}/5.0 |
| **Max Iterations** | {MAX_ITERATIONS or "3"} |
| **Human Checkpoints** | {HUMAN_IN_THE_LOOP_PHASES as comma-separated or "All phases" or "None"} |
| **Skip Reviews** | {SKIP_REVIEWS} |
| **Continue Mode** | {CONTINUE_MODE} |
| **Refine Mode** | {REFINE_MODE} |
| **Strict Mode** | {STRICT_MODE} |
```

### Step 0.4: Handle Continue Mode

**If `CONTINUE_MODE` is true:** resolve `RESUME_PHASE` and `RESUME_STEPS` per [Context Resolution for `--continue`](#context-resolution-for---continue), then in Workflow Phase 2 skip every implementation phase before `RESUME_PHASE` and every `[DONE]` step inside it.

### Step 0.5: Handle Refine Mode

**If `REFINE_MODE` is true:**

1. **Detect Changed Project Files:**

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

   **Determine comparison mode:**

   ```
   if STAGED is not empty AND UNSTAGED is not empty:
       # Both staged and unstaged - use unstaged only
       CHANGED_FILES = git diff --name-only  # working dir vs staging
       COMPARISON_MODE = "unstaged_only"
   elif STAGED is not empty OR UNSTAGED is not empty:
       # Only one type - compare against last commit
       CHANGED_FILES = git diff HEAD --name-only
       COMPARISON_MODE = "vs_last_commit"
   else:
       # No changes
       Report: "No project changes detected. Make edits first, then run --refine."
       Exit
   ```

2. **Build the Step→File Mapping:**
   - Read the task file's `### Parallelization Overview` for step names, phases and `Sub-Task File` paths
   - Read those sub-task files' `#### Expected Output` and `#### Subtasks` sections for file paths (the one permitted exception to context protection — see [Refine Mode Behavior](#refine-mode-behavior---refine))
   - Build mapping: `STEP_FILE_MAP = {step name → [file paths]}` and `STEP_PHASE_MAP = {step name → implementation phase}`

3. **Map Changed Files to Steps:**

   ```
   AFFECTED_STEPS = []
   for each changed_file:
       for step_name, file_list in STEP_FILE_MAP:
           if changed_file matches any path in file_list:
               AFFECTED_STEPS.append(step_name)
   ```

   - If no steps matched: "Changed files don't map to any step's Expected Output. Verify manually."

4. **Determine Refine Scope:**
   - `REFINE_FROM_PHASE` = the earliest implementation phase among `STEP_PHASE_MAP[AFFECTED_STEPS]`
   - All implementation phases from `REFINE_FROM_PHASE` onwards need re-verification
   - Phases before `REFINE_FROM_PHASE` are preserved as-is

5. **Store Changed Files Context:**
   - `CHANGED_FILES` = list of changed file paths
   - `USER_CHANGES_CONTEXT` = git diff output for affected files
   - Pass this context to the implementation agents you dispatch for fixes
   - Agents should build upon user's fixes, not overwrite them

## Workflow Phase 1: Load and Analyze Task

**This is the ONLY phase where you read a file** (plus the sub-task `#### Expected Output` sections in `--refine` mode).

### Step 1.1: Load Task Details

Read the task file ONCE:

```bash
Read $TASK_PATH
```

**After this read, you MUST NOT read any other files for the rest of execution.**

### Step 1.2: Parse the Implementation Process

Parse the `## Implementation Process` section into two working structures.

**From `### Parallelization Overview`** — the step table has columns `| Step | Phase | Model | Agent | Depends on | Parallel with | Sub-Task File |`. Build, per step name:

| Field | Source | Used for |
|-------|--------|----------|
| Step name | `Step` column (backtick-quoted sub-task basename) | Identity in all other lists |
| Implementation phase | `Phase` column | Which review gate it belongs to |
| Model | `Model` column | The `model` of its dispatch (unless `MODEL_OVERRIDE`) |
| Agent | `Agent` column | The `sdd:` agent type to dispatch |
| Depends on | `Depends on` column | Ordering |
| Parallel with | `Parallel with` column | Which steps to dispatch in ONE message |
| Sub-Task File | `Sub-Task File` column | The path you pass to the agent |

**From `### Phase Overview`** — for each `#### Phase N` block, record `Steps:`, `Reviewer model:`, the `Checklist items:` list and the `Rubrics:` list. You use `Reviewer model:` to dispatch the review; the criteria lists are the reviewer's business, not yours — do NOT paste them into any prompt.

There is **no threshold, no verification level and no judge count** in the task file. Do not look for them.

### Step 1.3: Create Todo List

Create TodoWrite with one entry per step plus one entry per implementation phase review:

```json
{
  "todos": [
    {"content": "Phase 1 / Step 01-foundation [haiku]", "status": "pending", "activeForm": "Implementing 01-foundation"},
    {"content": "Phase 1 / Step 02a-service [sonnet]", "status": "pending", "activeForm": "Implementing 02a-service"},
    {"content": "Phase 1 review [reviewer: sonnet]", "status": "pending", "activeForm": "Reviewing Phase 1"},
    {"content": "Phase 2 / Step 03-integration [sonnet]", "status": "pending", "activeForm": "Implementing 03-integration"},
    {"content": "Phase 2 review [reviewer: opus]", "status": "pending", "activeForm": "Reviewing Phase 2"}
  ]
}
```

---

## Workflow Phase 2: Execute Implementation Phases

Process implementation phases **in order**. Within a phase, process steps in dependency order, dispatching `Parallel with:` groups simultaneously. When every step of the phase has reported completion, run the phase review — once.

There is exactly ONE dispatch pattern, and it applies to every implementation phase without exception.

### The Phase Review Pattern

```
for each implementation phase P, in order:
    for each dependency-ordered group G of steps in P:
        dispatch every step of G in ONE message (parallel), each with:
            agent type   = its Agent column
            model        = MODEL_OVERRIDE if set, else its Model column
            prompt       = task file path + its sub-task file path
        collect each agent's reported artifact paths

    if SKIP_REVIEWS:
        mark P [REVIEWED-SKIPPED]; continue to the next phase

    dispatch ONE sdd:code-reviewer for P with the 4 inputs
        model = MODEL_OVERRIDE if set, else P's `Reviewer model`

    apply THRESHOLD to combined_score
        PASS      → mark P [REVIEWED]; human checkpoint if due; next phase
        FAIL      → Failure Handling (blast radius) → re-review; up to MAX_ITERATIONS
```

### Step Dispatch (one implementation agent per step)

Use Task tool, one call per step (all steps of a `Parallel with:` group in a single message):

- **Agent Type**: the step's `Agent` column, prefixed `sdd:` (e.g. `sdd:developer`, `sdd:tech-writer`)
- **Model**: `MODEL_OVERRIDE` if set — otherwise the step's `Model` column — otherwise `sonnet`
- **Description**: "Implement step [step-name]"
- **Prompt**:

```
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}

Implement step `[step-name]`.

Task File: $TASK_PATH
Sub-Task File: [the Sub-Task File path from the Parallelization Overview]

Your task:
- Read the sub-task file first — it IS your step
- Read the task file for Description, Acceptance Criteria (including the Test Strategy) and Architecture Overview
- Execute ONLY this step. Do NOT execute any other step, even one you can see in the Parallelization Overview
- Follow the sub-task file's Expected Output, Success Criteria and Subtasks exactly
- Your phase is a checkpoint, not the finish line: implement what this step delivers, and do not pull later phases' work forward
- Leave the tree building, linting and testing green

When complete, report:
1. What files were created/modified (paths)
2. Confirmation that the sub-task's success criteria are met
3. Self-critique summary
4. Any issues encountered
```

**Do NOT** paste the step's goal, expected output, success criteria or subtasks into the prompt. The agent reads its sub-task file. Passing the path is the contract; pasting the content is context bloat and drift.

Collect the artifact paths from each report. **Do NOT read the artifacts.**

### Code-Reviewer Input Contract (NON-NEGOTIABLE)

Every `sdd:code-reviewer` dispatch MUST include exactly these 4 inputs and NOTHING else that resembles a threshold or pass/fail expectation (the Task tool's `model` parameter is a dispatch setting, not a prompt input — see `MODEL_OVERRIDE`):

1. **Task file path**: `$TASK_PATH`
2. **Phase identifier**: the phase being reviewed, exactly as written in `### Phase Overview` (e.g. `Phase 2`)
3. **Artifact path(s)**: every file path the phase's implementation agents reported as created or modified
4. **CLAUDE_PLUGIN_ROOT**: The plugin root path

**Dispatch prompt:**

```
CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}

Apply your full evaluation process (Stages 0-12) and return a single combined report.

Inputs:

1. Task file path:
   $TASK_PATH

2. Phase identifier:
   [e.g. Phase 2]

3. Artifact path(s):
   [every file path reported by this phase's implementation agents]

4. CLAUDE_PLUGIN_ROOT: ${CLAUDE_PLUGIN_ROOT}
```

**You MUST NOT pass to the code-reviewer:**

- Any score threshold, target quality, or passing-line value
- Any PASS/FAIL expectation
- Any rubric or checklist you wrote yourself (only the task file's `## Acceptance Criteria`, narrowed by the Phase Overview, is authoritative)
- The sub-task file paths — **the reviewer resolves them itself** from the Phase Overview's `Steps:` line and the Parallelization Overview's `Sub-Task File` column
- The task description or acceptance criteria text — the agent reads the task file itself

### Threshold Application (Orchestrator-Level Only)

After receiving the code-reviewer's report, the orchestrator (this skill) applies the threshold:

```
combined_score = reviewer.combined_score
all_issues     = reviewer.issues          # each carries the step it belongs to
blast_radius   = reviewer.blast_radius

# PASS rule (orchestrator decides):
if combined_score >= THRESHOLD:
    PASS
elif 3.0 <= combined_score < THRESHOLD and not STRICT_MODE:
    apply the Iteration Discretion Rule → accepted: PASS | declined: FAIL → fix
else:
    FAIL → fix
```

The `combined_score` already incorporates spec_compliance + code_quality + Muda waste analysis (the reviewer aggregates them internally per its STAGE 9). The orchestrator does NOT need to re-aggregate sub-scores; only `combined_score`, `issues` and `blast_radius` matter for the gate decision.

### Failure Handling: Reason About Blast Radius (YOUR MOST CRITICAL JUDGEMENT)

**This is the single most important judgement you make in this workflow. Think thoroughly before you dispatch anything.**

There is no rule table here, and you must not build yourself one. There is a principle:

> **Match the capability of the agent that fixes the ph

…(truncated)