Refine a draft task specification into a fully planned, implementation-ready task with acceptance criteria, architecture, per-step sub-task files and verifiable phases

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 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 same stages as one shot , but judges still run, at a lowered threshold with a single retry. one shot one shot N/A Alias for included stages business analysis,decomposition skip judges same stages as fast , but no judge runs at all and no quality gate is applied. 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). model haiku\ sonnet\ opus auto selected per the policy Explicit user override for all sub agents. When omitted, resolve each phase's tier per the [Model Selection Policy]( model selection policy). See [Role Pairing]( role pairing) for the override's effect and the [Escalation Rule]( escalation rule) for how escalation interacts with it. strict strict false Disable the [Iteration Discretion Rule]( iteration discretion rule) a phase passes ONLY when score = THRESHOLD , otherwise retry until MAX ITERATIONS is reached. 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 (checklist, regular checks, rubric, test strategy, definition of done) architecture synthesis 3 Synthesize research and analysis into architecture decomposition 4 Break into per step sub task files grouped into verifiable phases, with dependencies, parallel groups and agent/model assignments Configuration Resolution Parse $ARGUMENTS and resolve configuration as follows: 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 (checklist, regular checks, rubric, test strategy, definition of done) business analysis (Phase 2c) Architecture Overview architecture synthesis (Phase 3) Implementation Process (Parallelization Overview / Phase Overview), or any sub task file under .specs/sub tasks/<task name / decomposition (Phase 4) 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. 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: 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: Usage Examples 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: 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 . Note: Filter todos based on configuration: If SKIP JUDGES is true, omit ALL Judge todos (Judge 2a, 2b, 2c, 3, 4) 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 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: 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/sub tasks/ Per step sub task files written by Phase 4 (tracked in git) .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 Never record a verdict the judge report does not support: no PASS without a passing rubric result, and no ☑️ ACCEPTED without the [Iteration Discretion Rule]( iteration discretion rule) actually permitting it. Otherwise 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! If STRICT MODE is true: The [Iteration Discretion Rule]( iteration discretion rule) is DISABLED a phase passes ONLY on score = THRESHOLD , otherwise retry 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. 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 rubr

plan-task