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:

1. Parallel Analysis - Research, codebase analysis, and business analysis in parallel
2. Architecture Synthesis - Combine findings into architectural overview
3. Decomposition - Break into implementation steps with risks
4. Parallelize - Reorganize steps for maximum parallel execution
5. Verify - Add LLM-as-Judge verification sections
6. 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

Stage Names (for --included-stages / --skip)

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:

1. 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:

1. Change Detection:

   • First check file status: git status --porcelain -- <TASK_FILE>
   • Compare current task file against last git commit: git diff HEAD -- <TASK_FILE>
     • 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

2. 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

3. 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)

4. 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

5. 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:

1. 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)

2. 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

3. 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:

1. 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

2. 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 {HUMAN_IN_THE_LOOP_PHASES as comma-separated} |
   | **Skip Judges** | {SKIP_JUDGES} |
   | **Refine Mode** | {REFINE_MODE} |
   | **Continue From** | {CONTINUE_STAGE} or "Start" |
   

3. 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

4. Handle --refine mode:

   If REFINE_MODE is true:

   • Check file status: git status --porcelain -- <TASK_FILE>
     • 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 -- <TASK_FILE> 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

5. Extract task info from file:

   • Read task file to extract title and type from filename
   • Parse frontmatter for title and depends_on

6. 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

7. 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