Plan Task

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 (description, acceptance criteria, test strategy) in parallel
2. Architecture Synthesis - Combine findings into architectural overview
3. Decomposition - Break into per-step sub-task files, grouped into independently verifiable phases with dependencies, parallel groups, agent/model assignments and a reviewer model per phase
4. Promote - Move refined task from draft/ to todo/

All model-assigned 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"]

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"]
SKIP_STAGES = --skip || []
HUMAN_IN_THE_LOOP_PHASES = --human-in-the-loop || []
SKIP_JUDGES = --skip-judges || false
REFINE_MODE = --refine || false
STRICT_MODE = --strict || false
CONTINUE_STAGE = null

# Model tiers - governed in full by the Model Selection Policy
MODEL_OVERRIDE = --model || null
BASELINE_TIER = MODEL_OVERRIDE || tier of the overall task per the Selection Rules


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

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

1. Section-to-Stage Mapping:

The Implementation Process section and the sub-task files are produced by the same phase, so a change to either re-runs Phase 4 as a whole.

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

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

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)

1. At Checkpoint:

• Display current phase results summary
• Display generated artifacts with paths