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 critically neccesary or you are done! Avoid asking questions until it is critically neccesary! Launch implementation agent, judges, iterate till issues are fixed and then move to next step!

Execute task implementation steps with automated quality verification using LLM-as-Judge for critical artifacts.

User Input

$ARGUMENTS

---

Command Arguments

Parse the following arguments from $ARGUMENTS:

Argument Definitions

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

# Parse --target-quality (supports single value or two comma-separated values)
if --target-quality has single value X.X:
    THRESHOLD_FOR_STANDARD_COMPONENTS = X.X
    THRESHOLD_FOR_CRITICAL_COMPONENTS = X.X
elif --target-quality has two values X.X,Y.Y:
    THRESHOLD_FOR_STANDARD_COMPONENTS = X.X
    THRESHOLD_FOR_CRITICAL_COMPONENTS = Y.Y
else:
    THRESHOLD_FOR_STANDARD_COMPONENTS = 4.0  # default
    THRESHOLD_FOR_CRITICAL_COMPONENTS = 4.5  # default

# Initialize other defaults
MAX_ITERATIONS = --max-iterations || 3  # default is 3 iterations 
HUMAN_IN_THE_LOOP_STEPS = --human-in-the-loop || [] (empty = none, "*" = all)
SKIP_JUDGES = --skip-judges || false
REFINE_MODE = --refine || false
CONTINUE_MODE = --continue || false

# Special handling for --human-in-the-loop without step list
if --human-in-the-loop present without step numbers:
    HUMAN_IN_THE_LOOP_STEPS = "*" (all steps)

Context Resolution for --continue

When --continue is used:

1. Step Resolution:

   • Parse the task file for [DONE] markers on step titles
   • Identify the last incompleted step
   • Launch judge to verify the last INCOMPLETE step's artifacts
   • If judge PASS: Mark step as done and resume from the next step
   • If judge FAIL: Re-implement the step and iterate until PASS

2. 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 implementation steps to determine what needs re-verification.

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 Implementation Steps:

   • Read the task file to get the list of implementation steps
   • For each changed file, determine which step created/modified it:
     • Check step's "Expected Output" section for file paths
     • Check step's subtasks for file references
     • Check step's artifacts in #### Verification section
   • Build a mapping: {changed_file → step_number}

3. Determine Affected Steps:

   • Find all steps that have associated changed files
   • The earliest affected step is the starting point
   • All steps from that point onwards need re-verification
   • Earlier steps (unaffected) are preserved as-is

4. Refine Execution:

   • For each affected step (in order):
     • Launch judge agent to verify the step's artifacts (including user's changes)
     • If judge PASS: Mark step done, proceed to next
     • If judge FAIL: Launch implementation agent with user's changes as context, then re-verify
   • User's manual fixes are preserved - implementation agent should build upon them, not overwrite

5. Example:

   # User manually fixed src/validation/validation.service.ts
   # (This file was created in Step 2)
   
   /implement my-task.feature.md --refine
   
   # Detects: src/validation/validation.service.ts modified
   # Maps to: Step 2 (Create ValidationService)
   # Action: Launch judge for Step 2
   #   - If PASS: User's fix is good, proceed to Step 3
   #   - If FAIL: Implementation agent align rest of the code with user changes, without overwriting user's changes
   # Continues: Step 3, Step 4... (re-verify all subsequent steps)
   

6. Multiple Files Changed:

   # User edited files from Step 2 AND Step 4
   
   /implement my-task.feature.md --refine
   
   # Detects: Files from Step 2 and Step 4 modified
   # Earliest affected: Step 2
   # Re-verifies: Step 2, Step 3, Step 4, Step 5...
   # (Step 3 re-verified even though no direct changes, because it depends on Step 2)
   

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
   # Staged changes are preserved, not re-verified
   
   # --
   
   # 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
   # validation.service.ts changes are verified
   

Human-in-the-Loop Behavior

Human verification checkpoints occur:

1. Trigger Conditions:

   • After implementation + judge verification PASS for a step in HUMAN_IN_THE_LOOP_STEPS
   • After implementation + judge + implementation retry (before the next judge retry)
   • If HUMAN_IN_THE_LOOP_STEPS is "*", triggers after every step

2. At Checkpoint:

   • Display current step results summary
   • Display generated artifacts with paths
   • Display judge score and feedback
   • Ask user: "Review step output. Continue? [Y/n/feedback]"
   • If user provides feedback, incorporate into next iteration or step
   • If user says "n", pause workflow

3. Checkpoint Message Format:

   ---
   ## 🔍 Human Review Checkpoint - Step X
   
   **Step:** {step title}
   **Step Type:** {standard/critical}
   **Judge Score:** {score}/{threshold for step type} threshold
   **Status:** ✅ PASS / 🔄 ITERATING (attempt {n})
   
   **Artifacts Created/Modified:**
   - {artifact_path_1}
   - {artifact_path_2}
   
   **Judge Feedback:**
   {feedback summary}
   
   **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

Status Transitions

---

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 (implementation and evaluation), you need to provide:

• Task file path
• Step number
• Item number (if applicable)
• Artifact path (if applicable)
• Value of ${CLAUDE_PLUGIN_ROOT} so agents can resolve paths like @${CLAUDE_PLUGIN_ROOT}/scripts/create-scratchpad.sh

What You DO

• Read the task file ONCE (Phase 1 only)
• Launch sub-agents via Task tool
• Receive reports from sub-agents
• Mark stages complete after judge confirmation
• Aggregate results and report to user

What You NEVER Do

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 judge agent. That's not your job.

If you think: "This is too simple to need verification" → STOP. If the task specifies verification, launch the judge. No exceptions.

If you think: "I need to read the reference file to write a good prompt" → STOP. Put the reference file PATH in the sub-agent prompt. 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 judge agents = quality collapse = failed artifacts.

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

---

CRITICAL

Configuration Rules

• Use THRESHOLD_FOR_STANDARD_COMPONENTS (default 4.0) for standard steps!
• Use THRESHOLD_FOR_CRITICAL_COMPONENTS (default 4.5) for steps marked as critical in task file!
• Default is 3 iterations - stop after 3 fix→verify cycles and proceed to next step (with warning)!
• If MAX_ITERATIONS is set to unlimited: Iterate until quality threshold is met (no limit)
• Trigger human-in-the-loop checkpoints ONLY after steps in HUMAN_IN_THE_LOOP_STEPS (or all steps if "*")!
• If SKIP_JUDGES is true: Skip ALL judge validation - proceed directly to next step after each implementation completes!
• If CONTINUE_MODE is true: Skip to RESUME_FROM_STEP - do not re-implement already completed steps!
• If REFINE_MODE is true: Detect changed project files, map to steps, re-verify from REFINE_FROM_STEP - preserve user's fixes!

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.

Relaunch judge till you get valid results, of following happens:

• Reject Long Reports: If an agent 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.
• Judge Score 5.0 is a Hallucination: If a judge returns a score of 5.0/5.0, treat it as a hallucination or lazy evaluation. Reject it and re-run the judge. Perfect scores are practically impossible in this rigorous framework.
• Reject Missing Scores: If a judge report is missing the numerical score, reject it. This indicates the judge failed to read or follow the rubric instructions.

---

Overview

This command orchestrates multi-step task implementation with:

1. Sequential execution respecting step dependencies
2. Parallel execution where dependencies allow
3. Automated verification using judge agents for critical steps
4. Panel of LLMs (PoLL) for high-stakes artifacts
5. Aggregated voting with position bias mitigation
6. Stage tracking with confirmation after each judge passes

---

Complete Workflow Overview

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/
    │
    ▼
Phase 1: Load Task
    │
    ▼
Phase 2: Execute Steps
    │
    ├─── For each step in dependency order:
    │    │
    │    ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ Launch sdd:developer agent                          │
    │    │ (implementation)                                │
    │    └─────────────────┬───────────────────────────────┘
    │                      │
    │                      ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ Launch judge agent(s)                           │
    │    │ (verification per #### Verification section)    │
    │    └─────────────────┬───────────────────────────────┘
    │                      │
    │                      ▼
    │    ┌─────────────────────────────────────────────────┐
    │    │ Judge PASS? → Mark step complete in task file   │
    │    │ Judge FAIL? → Fix and re-verify (max 2 retries) │
    │