/plan-task - Task Refinement & Planning

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/

/plan-task .specs/tasks/draft/add-validation.feature.md [options]

Arguments

Stage Names

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 <requirement change>. The agent incorporates your change and re-runs affected stages.

Usage Examples

# 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-name>/
        └── SKILL.md               # Reusable skill document (if research stage ran)

.specs/
├── tasks/
│   ├── draft/                     # Source (now empty for this task)
│   └── todo/
│       └── <name>.<type>.md       # Complete task specification (ready for implementation)
├── analysis/
│   └── analysis-<name>.md         # Codebase impact analysis (if codebase analysis stage ran)
└── scratchpad/
    └── <hex-id>.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.