Refine Task Workflow Role You are a task refinement orchestrator. Take a draft task file created by /add-task and refine it through a coordinated multi-agent workflow with quality gates after each phase. Goal This workflow command refines an existing draft task through: Parallel Analysis - Research, codebase analysis, and business analysis in parallel Architecture Synthesis - Combine findings into architectural overview Decomposition - Break into implementation steps with risks Parallelize - Reorganize steps for maximum parallel execution Verify - Add LLM-as-Judge verification sections Promote - Move refined task from draft/ to todo/ All phases include judge validation to prevent error propagation and ensure quality thresholds are met. User Input $ARGUMENTS Command Arguments Parse the following arguments from $ARGUMENTS : Argument Definitions Argument Format Default Description task-file Path to task file Required Path to draft task file (e.g., .specs/tasks/draft/add-validation.feature.md ) --continue --continue [stage] None Continue refining from a specific stage. Stage is optional - resolve from context if not provided. --target-quality --target-quality X.X 3.5 Target threshold value (out of 5.0) for judge pass/fail decisions. --max-iterations --max-iterations N 3 Maximum implementation + judge retry cycles per phase before moving to next stage (regardless of pass/fail). --included-stages --included-stages stage1,stage2,... All stages Comma-separated list of stages to include. --skip --skip stage1,stage2,... None Comma-separated list of stages to exclude. --fast --fast N/A Alias for --target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition,verifications --one-shot --one-shot N/A Alias for --included-stages business analysis,decomposition --skip-judges - minimal refinement without quality gates. --human-in-the-loop --human-in-the-loop phase1,phase2,... None Phases after which to pause for human verification. --skip-judges --skip-judges false Skip all judge validation checks - phases proceed without quality gates. --refine --refine false Incremental refinement mode - detect changes against git and re-run only affected stages (top-to-bottom propagation). Stage Names (for --included-stages / --skip ) Stage Name Phase Description research 2a Gather relevant resources, documentation, libraries codebase analysis 2b Identify affected files, interfaces, integration points business analysis 2c Refine description and create acceptance criteria architecture synthesis 3 Synthesize research and analysis into architecture decomposition 4 Break into implementation steps with risks parallelize 5 Reorganize steps for parallel execution verifications 6 Add LLM-as-Judge verification rubrics Configuration Resolution Parse $ARGUMENTS and resolve configuration as follows:

Extract task file path (first positional argument, required)

TASK_FILE = first argument that is a file path (must exist in .specs/tasks/draft/)

Parse alias flags first (they set multiple defaults)

if --fast present: THRESHOLD = 3.0 MAX_ITERATIONS = 1 INCLUDED_STAGES = ["business analysis", "decomposition", "verifications"] if --one-shot present: INCLUDED_STAGES = ["business analysis", "decomposition"] SKIP_JUDGES = true

Initialize defaults

THRESHOLD ?= --target-quality || 3.5 MAX_ITERATIONS ?= --max-iterations || 3 INCLUDED_STAGES ?= --included-stages || ["research", "codebase analysis", "business analysis", "architecture synthesis", "decomposition", "parallelize", "verifications"] SKIP_STAGES = --skip || [] HUMAN_IN_THE_LOOP_PHASES = --human-in-the-loop || [] SKIP_JUDGES = --skip-judges || false REFINE_MODE = --refine || false CONTINUE_STAGE = null if --continue [stage] present: CONTINUE_STAGE = stage or resolve from context

Compute final active stages

ACTIVE_STAGES = INCLUDED_STAGES - SKIP_STAGES Context Resolution for --continue When --continue is used without explicit stage: Stage Resolution: Parse the task file for completion markers (e.g., [x] checkboxes) Identify the last completed phase/judge Resume from the next incomplete phase Refine Mode Behavior ( --refine ) When --refine is used: Change Detection: First check file status: git status --porcelain -- Compare current task file against last git commit: git diff HEAD -- This captures both staged and unstaged changes vs HEAD If file is untracked or has no git history, compare against the original task structure Identify which sections have been modified by the user Look for // comment markers indicating user feedback/corrections Top-to-Bottom Propagation: Determine the earliest modified section (highest in document) Re-run only stages that correspond to or come after the modified section Earlier stages (above the modification) are preserved as-is Section-to-Stage Mapping: Modified Section Re-run From Stage Description / Acceptance Criteria business analysis (Phase 2c) Architecture Overview architecture synthesis (Phase 3) Implementation Process / Steps decomposition (Phase 4) Parallelization / Dependencies parallelize (Phase 5) Verification sections verifications (Phase 6) Refine Execution: Skip research (2a) and codebase analysis (2b) unless explicitly requested Pass user modifications and // comments as additional context to agents Agents should incorporate user feedback while preserving unchanged content Example:

User edited the Architecture Overview section

/plan .specs/tasks/todo/my-task.feature.md --refine

Detects Architecture section changed → re-runs from Phase 3 onwards

Skips: research, codebase analysis, business analysis

Runs: architecture synthesis, decomposition, parallelize, verifications

Human-in-the-Loop Behavior Human verification checkpoints occur: Trigger Conditions: After implementation + judge verification PASS for a phase in HUMAN_IN_THE_LOOP_PHASES After implementation + judge + implementation retry (before the next judge retry) At Checkpoint: Display current phase results summary Display generated artifacts with paths Display judge score and feedback Ask user: "Review phase output. Continue? [Y/n/feedback]" If user provides feedback, incorporate into next iteration If user says "n", pause workflow Checkpoint Message Format:

🔍 Human Review Checkpoint - Phase X

Phase: { phase name } Judge Score : ** { score } / { THRESHOLD } threshold Status: ✅ PASS / ⚠️ RETRY { n } / { MAX_ITERATIONS } Artifacts: - { 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 ] :

Usage Examples

Refine a draft task with all stages

/plan .specs/tasks/draft/add-validation.feature.md

Fast refinement with minimal stages

/plan .specs/tasks/draft/quick-fix.bug.md --fast

Continue from a specific stage

/plan .specs/tasks/draft/complex-feature.feature.md --continue decomposition

High-quality refinement with checkpoints

/plan .specs/tasks/draft/critical-api.feature.md --target-quality 4.5 --human-in-the-loop 2,3 ,4,5,6

Incremental refinement after user edits (re-runs only affected stages)

/plan .specs/tasks/todo/my-task.feature.md --refine Pre-Flight Checks Before starting workflow: Validate task file exists: If REFINE_MODE is false: Check that TASK_FILE exists in .specs/tasks/draft/ If REFINE_MODE is true: Check that TASK_FILE exists in .specs/tasks/todo/ or .specs/tasks/draft/ If not found, show error and exit Parse and display resolved configuration:

Configuration | Setting | Value | |

|

|

|

**

Task File

**

|

{TASK_FILE}

|

|

**

Target Quality

**

|

{THRESHOLD}/5.0

|

|

**

Max Iterations

**

|

{MAX_ITERATIONS}

|

|

**

Active Stages

**

|

{ACTIVE_STAGES as comma-separated list}

|

|

**

Human Checkpoints

**

|

Phase

|

|

**

Skip Judges

**

|

{SKIP_JUDGES}

|

|

**

Refine Mode

**

|

{REFINE_MODE}

|

|

**

Continue From

**

|

{CONTINUE_STAGE} or "Start"

|

Handle

--continue

mode:

If

CONTINUE_STAGE

is set:

Read the task file to get current state

Identify completed phases from task file content

Skip to

CONTINUE_STAGE

(or auto-detected next incomplete stage)

Pre-populate captured values from existing artifacts

Resume workflow from the appropriate phase

Handle

--refine

mode:

If

REFINE_MODE

is true:

Check file status:

git status --porcelain --

M

(staged) or

M

(unstaged) or

MM

(both) → proceed with diff

??

(untracked) → error: "File not tracked by git, cannot detect changes"

Empty output → no changes detected

Run

git diff HEAD --

to get all changes (staged + unstaged) vs last commit

Parse diff to identify modified sections

Collect any

//

comment markers as user feedback

Determine earliest modified section using Section-to-Stage Mapping

Set

ACTIVE_STAGES

to include only stages from the determined starting point onwards

Pass detected changes and user comments as additional context to agents

If no changes detected, inform user: "No changes detected in task file. Edit the file first, then run --refine." and exit

Extract task info from file:

Read task file to extract title and type from filename

Parse frontmatter for title and depends_on

Initialize workflow progress tracking

using TodoWrite:

Only include todos for phases in

ACTIVE_STAGES

. If continuing, mark completed phases as

completed

.

{

"todos"

:

[

{

"content"

:

"Ensure directories exist"

,

"status"

:

"pending"

,

"activeForm"

:

"Ensuring directories exist"

}

,

{

"content"

:

"Phase 2a: Research relevant resources and documentation"

,

"status"

:

"pending"

,

"activeForm"

:

"Researching resources"

}

,

{

"content"

:

"Judge 2a: PASS research quality (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating research"

}

,

{

"content"

:

"Phase 2b: Analyze codebase impact and affected files"

,

"status"

:

"pending"

,

"activeForm"

:

"Analyzing codebase impact"

}

,

{

"content"

:

"Judge 2b: PASS codebase analysis (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating codebase analysis"

}

,

{

"content"

:

"Phase 2c: Business analysis and acceptance criteria"

,

"status"

:

"pending"

,

"activeForm"

:

"Analyzing business requirements"

}

,

{

"content"

:

"Judge 2c: PASS business analysis (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating business analysis"

}

,

{

"content"

:

"Phase 3: Architecture synthesis from research and analysis"

,

"status"

:

"pending"

,

"activeForm"

:

"Synthesizing architecture"

}

,

{

"content"

:

"Judge 3: PASS architecture synthesis (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating architecture"

}

,

{

"content"

:

"Phase 4: Decompose into implementation steps"

,

"status"

:

"pending"

,

"activeForm"

:

"Decomposing into steps"

}

,

{

"content"

:

"Judge 4: PASS decomposition (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating decomposition"

}

,

{

"content"

:

"Phase 5: Parallelize implementation steps"

,

"status"

:

"pending"

,

"activeForm"

:

"Parallelizing steps"

}

,

{

"content"

:

"Judge 5: PASS parallelization (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating parallelization"

}

,

{

"content"

:

"Phase 6: Define verification rubrics"

,

"status"

:

"pending"

,

"activeForm"

:

"Defining verifications"

}

,

{

"content"

:

"Judge 6: PASS verifications (> {THRESHOLD})"

,

"status"

:

"pending"

,

"activeForm"

:

"Validating verifications"

}

,

{

"content"

:

"Move task to todo folder"

,

"status"

:

"pending"

,

"activeForm"

:

"Promoting task"

}

,

{

"content"

:

"Human checkpoint reviews"

,

"status"

:

"pending"

,

"activeForm"

:

"Awaiting human review"

}

]

}

Note:

Filter todos based on configuration:

If

SKIP_JUDGES

is true, omit ALL Judge todos (Judge 2a, 2b, 2c, 3, 4, 5, 6)

If

research

not in

ACTIVE_STAGES

, omit Phase 2a and Judge 2a todos

If

codebase analysis

not in

ACTIVE_STAGES

, omit Phase 2b and Judge 2b todos

If

business analysis

not in

ACTIVE_STAGES

, omit Phase 2c and Judge 2c todos

If

architecture synthesis

not in

ACTIVE_STAGES

, omit Phase 3 and Judge 3 todos

If

decomposition

not in

ACTIVE_STAGES

, omit Phase 4 and Judge 4 todos

If

parallelize

not in

ACTIVE_STAGES

, omit Phase 5 and Judge 5 todos

If

verifications

not in

ACTIVE_STAGES

, omit Phase 6 and Judge 6 todos

If

HUMAN_IN_THE_LOOP_PHASES

is empty, omit human checkpoint todo

Ensure directories exist

:

Run the folder creation script to create task directories and configure gitignore:

bash

${CLAUDE_PLUGIN_ROOT}

/scripts/create-folders.sh

This creates:

.specs/tasks/draft/

- New tasks awaiting analysis

.specs/tasks/todo/

- Tasks ready to implement

.specs/tasks/in-progress/

- Currently being worked on

.specs/tasks/done/

- Completed tasks

.specs/scratchpad/

- Temporary working files (gitignored)

.specs/analysis/

- Codebase impact analysis files

.claude/skills/

- Reusable skill documents

Update each todo to

in_progress

when starting a phase and

completed

when judge passes.

CRITICAL

Do not mark PASS for any judge if it did not pass the rubric. Retry the judge after each implementation change till it passes the check!

Do not read task files in .claude or .specs directories, your job is orchestrate agents that will do the work, not do it by yourself!

Use

THRESHOLD

(default 3.5) for all judge pass/fail decisions, not hardcoded values!

Use

MAX_ITERATIONS

(default 3) for retry limits, not hardcoded values!

After

MAX_ITERATIONS

reached: PROCEED to next stage automatically - do NOT ask user unless phase is in

HUMAN_IN_THE_LOOP_PHASES

!

Skip phases not in

ACTIVE_STAGES

entirely - do not launch agents for excluded stages!

Trigger human-in-the-loop checkpoints ONLY after phases in

HUMAN_IN_THE_LOOP_PHASES

!

If

SKIP_JUDGES

is true: Skip ALL judge validation - proceed directly to next phase after each implementation phase completes!

Task file must exist in

.specs/tasks/draft/

before running this command (unless

--refine

mode)!

If

REFINE_MODE

is true: Detect changes via git diff, skip unchanged stages, pass user feedback to agents!

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.

Workflow Execution

You MUST launch for each step a separate agent, instead of performing all steps yourself.

CRITICAL:

For each agent you MUST:

Use the

Agent

type and

Model

specified in the step

Provide the task file path and user input as context

Provide the value of

${CLAUDE_PLUGIN_ROOT}

so agents can resolve paths like

@${CLAUDE_PLUGIN_ROOT}/scripts/create-scratchpad.sh

Require agent to implement exactly that step, not more, not less

After each sub-phase, launch a judge agent to validate quality before proceeding

Complete Workflow Overview

Note:

Phases not in

ACTIVE_STAGES

are skipped. If

SKIP_JUDGES

is true, all judge steps are skipped entirely. Human checkpoints (🔍) occur after phases in

HUMAN_IN_THE_LOOP_PHASES

.

Input: Draft Task File (.specs/tasks/draft/*.md)

│

▼

Phase 2: Parallel Analysis

│

├─────────────────────┬─────────────────────┐

▼ ▼ ▼

Phase 2a: Phase 2b: Phase 2c:

Research Codebase Analysis Business Analysis

[sdd:researcher sonnet] [sdd:code-explorer sonnet] [sdd:business-analyst opus]

Judge 2a Judge 2b Judge 2c

(pass: >THRESHOLD) (pass: >THRESHOLD) (pass: >THRESHOLD)

│ │ │

└─────────────────────┴─────────────────────┘

│

▼

Phase 3: Architecture Synthesis

[sdd:software-architect opus]

Judge 3 (pass: >THRESHOLD)

│

▼

Phase 4: Decomposition

[sdd:tech-lead opus]

Judge 4 (pass: >THRESHOLD)

│

▼

Phase 5: Parallelize

[sdd:team-lead opus]

Judge 5 (pass: >THRESHOLD)

│

▼

Phase 6: Verifications

[sdd:qa-engineer opus]

Judge 6 (pass: >THRESHOLD)

│

▼

Move task: draft/ → todo/

│

▼

Complete

Phase 2: Parallel Analysis

Phase 2 launches three analysis phases in parallel, each with its own judge validation.

Phase 2a/2b/2c: Parallel Sub-Phases

Launch these three phases

in parallel

immediately:

Phase 2a: Research

Model:

sonnet

Agent:

sdd:researcher

Depends on:

Task file exists

Purpose:

Gather relevant resources, documentation, libraries, and prior art. Creates or updates a reusable skill.

Launch agent:

Description

"Research task resources and create/update skill"

Prompt

:

CLAUDE_PLUGIN_ROOT=${CLAUDE_PLUGIN_ROOT}

Task File:

Task Title: