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

$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.
--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 - 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: mark it [REVIEWED] and resume at the next implementation phase.
       • Otherwise: enter the Failure Handling 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:

   # 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: mark it [REVIEWED], proceed to the next phase
     • Otherwise: enter the Failure Handling flow, then re-review
   • User's manual fixes are preserved - implementation agents should build upon them, not overwrite

5. Example:

   # 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:

   # 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:

   # 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:

   ---
   ## 🔍 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 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 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: