# plan-task Refine a draft task specification into a fully planned, implementation-ready task through multi-agent analysis, architecture synthesis, and quality-gated verification. * Purpose - Transforms a draft task into a complete specification with architecture, implementation steps, parallelization, and verification rubrics * Output - A refined task file moved to `.specs/tasks/todo/`, plus skill files in `.claude/skills/` and analysis files in `.specs/analysis/` ```bash /plan-task .specs/tasks/draft/add-validation.feature.md [options] ``` ## Arguments | Argument | Format | Default | Description | | --------------------- | ------------------------------- | ------------ | ------------------------------------------------------------------------------------------------------------------- | | `task-file` | Path | **Required** | Path to draft task file (e.g., `.specs/tasks/draft/add-validation.feature.md`) | | `--target-quality` | `--target-quality X.X` | `3.5` | Target threshold (out of 5.0) for judge pass/fail decisions | | `--max-iterations` | `--max-iterations N` | `3` | Maximum retry cycles per phase before moving on | | `--included-stages` | `--included-stages s1,s2,...` | All stages | Comma-separated list of stages to include | | `--skip` | `--skip s1,s2,...` | None | Comma-separated list of stages to exclude | | `--fast` | flag | N/A | Alias for `--target-quality 3.0 --max-iterations 1 --included-stages business analysis,decomposition,verifications` | | `--one-shot` | flag | N/A | Alias for `--included-stages business analysis,decomposition --skip-judges` | | `--human-in-the-loop` | `--human-in-the-loop p1,p2,...` | None | Phases after which to pause for human review | | `--skip-judges` | flag | `false` | Skip all judge validation checks | | `--refine` | flag | `false` | Detect changes via git diff and re-run only affected stages | | `--continue` | `--continue [stage]` | None | Resume from a specific stage (auto-detects if stage not provided) | ## Stage Names | Stage Name | Phase | Description | | ------------------------ | ----- | ------------------------------------------------------------- | | `research` | 2a | Gathers relevant resources, documentation, and libraries | | `codebase analysis` | 2b | Identifies affected files, interfaces, and integration points | | `business analysis` | 2c | Refines the description and creates acceptance criteria | | `architecture synthesis` | 3 | Synthesizes research and analysis into an architecture | | `decomposition` | 4 | Breaks the architecture into implementation steps with risks | | `parallelize` | 5 | Reorganizes steps for parallel execution | | `verifications` | 6 | Adds LLM-as-Judge verification rubrics | ## Workflow Diagram ``` +----------------------------+ | Draft Task File | | .specs/tasks/draft/*.md | +-------------+--------------+ | v +----------------------------------------------------------+ | Phase 2: Parallel Analysis | | | | +----------------+ +------------------+ +-------------+| | | Research | | Codebase | | Business || | | researcher | | Analysis | | Analysis || | | (sonnet) | | code-explorer | | business- || | | | | | (sonnet) | | analyst || | | v | | | | | (opus) || | | Judge 2a | | Judge 2b | | | || | +------+---------+ +--------+---------+ +------+------+| | | | | | +----------------------------------------------------------+ | | | +----------+----------+--------------------+ | v +-----------------------------+ | Phase 3: Architecture | | software-architect (opus) | | | | | v | | Judge 3 | +--------------+--------------+ | v +-----------------------------+ | Phase 4: Decomposition | | tech-lead (opus) | | | | | v | | Judge 4 | +--------------+--------------+ | v +-----------------------------+ | Phase 5: Parallelize | | team-lead (opus) | | | | | v | | Judge 5 | +--------------+--------------+ | v +-----------------------------+ | Phase 6: Verifications | | qa-engineer (opus) | | | | | v | | Judge 6 | +--------------+--------------+ | +-----------------+-----------------+ | | | v v v +--------------+ +--------------+ +---------------+ | Refined Task | | Skill File | | Analysis File | | todo/*.md | | SKILL.md | | analysis-*.md | +--------------+ +--------------+ +---------------+ ``` ## How It Works ### Phase 2: Parallel Analysis Three analysis agents run **in parallel**, each with its own judge validation: * **Phase 2a: Research** (`researcher` agent, sonnet) — Gathers relevant resources, documentation, and libraries. Creates or updates a reusable skill file in `.claude/skills/`. * **Phase 2b: Codebase Impact Analysis** (`code-explorer` agent, sonnet) — Identifies affected files, interfaces, and integration points. Produces an analysis file in `.specs/analysis/`. * **Phase 2c: Business Analysis** (`business-analyst` agent, opus) — Refines the task description, creates acceptance criteria, and documents user scenarios. Each sub-phase is validated by a judge agent. All three must pass before proceeding. ### Phase 3: Architecture Synthesis `software-architect` agent (opus) synthesizes findings from research, codebase analysis, and business analysis into an architectural overview featuring key decisions, a solution strategy, and expected file changes. ### Phase 4: Decomposition `tech-lead` agent (opus) breaks the architecture into ordered implementation steps, including success criteria, subtasks, blockers, risks, and complexity ratings. ### Phase 5: Parallelize Steps `team-lead` agent (opus) reorganizes implementation steps for maximum parallel execution, assigns appropriate agent types, and creates parallelization diagrams. ### Phase 6: Define Verifications `qa-engineer` agent (opus) adds LLM-as-Judge verification sections with custom rubrics, thresholds, and verification levels (None, Single Judge, Panel of 2, or Per-Item) for each implementation step. ### Phase 7: Promote Task Moves the refined task file from `draft/` to `todo/` and stages all generated artifacts with Git. Staging at the end allows you to make manual edits on top and use `--refine`, so the agent can diff your changes against the staged state. ## Quality Gates Every phase includes a judge validation step using LLM-as-Judge: * **PASS** (score >= threshold) — Phase complete; proceed to the next stage. * **FAIL** (score < threshold) — Re-run the phase with judge feedback. * **MAX\_ITERATIONS reached** — Proceed to the next stage automatically (with a warning logged). ## Refine Mode (`--refine`) After reviewing the generated specification, you can edit it directly and re-run the planning process with `--refine`: 1. Compares local (unstaged) changes against staged changes by default. To compare against the last commit instead, specify it explicitly (e.g., `/plan --refine compare with last commit`). 2. Identifies the earliest modified section 3. Re-runs only stages from that point onward (top-to-bottom propagation) 4. Preserves earlier stages that are unaffected 5. Supports `//` comment markers for inline feedback You can also pass a requirement change directly: `/plan --refine `. The agent incorporates your change and re-runs affected stages. | 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) | ## Usage Examples ```bash # Refine a draft task with all stages (default) /plan-task .specs/tasks/draft/add-validation.feature.md # Fast refinement — minimal stages, lower quality bar /plan-task .specs/tasks/draft/quick-fix.bug.md --fast # One-shot — business analysis + decomposition only, no judges /plan-task .specs/tasks/draft/simple-task.feature.md --one-shot # Continue from a specific stage /plan-task .specs/tasks/draft/complex-feature.feature.md --continue decomposition # High-quality refinement with human review checkpoints /plan-task .specs/tasks/draft/critical-api.feature.md --target-quality 4.5 --human-in-the-loop 2,3,4,5,6 # Skip research phase (you already know the tech stack) /plan-task .specs/tasks/draft/my-task.feature.md --skip research # Incremental refinement after editing the spec /plan-task .specs/tasks/todo/my-task.feature.md --refine ``` ## Artifacts Generated ``` .claude/ └── skills/ └── / └── SKILL.md # Reusable skill document (if research stage ran) .specs/ ├── tasks/ │ ├── draft/ # Source (now empty for this task) │ └── todo/ │ └── ..md # Complete task specification (ready for implementation) ├── analysis/ │ └── analysis-.md # Codebase impact analysis (if codebase analysis stage ran) └── scratchpad/ └── .md # Working scratchpads (gitignored) ``` ## Best Practices * Review the generated specification before implementing — human feedback is the most effective quality lever. * Use `--refine` after making edits instead of re-running the full workflow. * Add `//` comment markers to lines that need clarification — agents will incorporate your feedback. * For complex tasks, use `--human-in-the-loop` to verify architecture decisions before decomposition. * Use `--fast` for simple, well-defined tasks where full analysis is unnecessary. * Use `--skip research` when working with familiar technologies.