Workflows Plan

---
name: workflows-plan
description: Transform spec (with frontmatter claims) into an implementation plan with task decomposition and sub-agent assignment. Stage 3 of the development workflow.
argument-hint: "[spec path or feature description]"
user-invocable: true
---

Create an implementation plan for: $ARGUMENTS

## Purpose

You are executing Stage 3 (Planning) of the development workflow. The spec with frontmatter claims exists from Stage 2. Your job is to decompose the work into sub-agent-sized tasks, identify dependencies, and produce a plan file that Stage 4 can execute.

## Pre-Conditions

Before starting, verify:
1. `.workflow/state.json` exists and `currentStage` is `"planning"`
2. A spec exists (check `stages.dev-docs.artifacts.spec` in state)
3. Spec frontmatter includes at least one claim (check `stages.dev-docs.artifacts.spec` in state)

If pre-conditions are not met, report what's missing and halt.

## Process

### Step 1: Gather Context

Read the spec (frontmatter + body) from Stage 2, then investigate the codebase:

1. **Read the spec**: Understand what needs to be built
2. **Read spec claims**: Understand falsifiable claims and required evidence
3. **Map the affected code**: Use Glob/Grep to find files that will need changes
4. **Check for prior learnings**: Search agent memory and compound learnings for relevant patterns
5. **Check existing tests**: Identify test files that will need updates

### Step 2: Decompose into Tasks

Break the implementation into discrete, sub-agent-sized units of work. Each task must be:

- **Atomic**: One task = one logical change = one commit
- **Testable**: Each task has clear acceptance criteria
- **Ordered**: Dependencies between tasks are explicit

For each task, define:

```markdown
### Task N: <title>

**Files**: [list of files to create/modify]
**Depends on**: [task numbers, or "none"]
**Acceptance criteria**:
- [ ] [specific, verifiable condition]
- [ ] [specific, verifiable condition]

**Notes**: [implementation hints, gotchas from codebase investigation]
```

### Step 3: Identify Risks

For each task, flag:
- Files with high churn or complexity
- Areas where the spec's assumptions may not hold
- External dependencies or integration points
- Tests that may need significant rework

### Step 4: Write the Plan File

Write the plan to `.workflow/plan.md`:

```markdown
# Implementation Plan: <title>

**Workflow**: <id>
**Spec**: <spec path>
**ADR**: <adr path>
**Branch**: <branch>
**Created**: <ISO timestamp>

## Overview

[1-2 paragraph summary of what's being built and the approach]

## Task Breakdown

[Task definitions from Step 2]

## Dependency Graph

[Simple text diagram showing task ordering]

## Risks

[From Step 3]

## Estimated Scope

- Tasks: N
- Files affected: N
- New files: N
- Tests to write: N
```

### Step 5: Get User Approval

Present the plan summary and ask the user to approve:

```
PLAN READY FOR REVIEW
======================

<title>
Tasks: N | Files: N | Risks: N flagged

[task list with 1-line summaries]

Approve this plan? (The conductor will dispatch /workflows-work to execute it)
```

Wait for user approval before proceeding.

### Step 6: Record and Handoff

After user approves:

1. **Update workflow state** (`.workflow/state.json`):
   - Set `stages.planning.status` to `"completed"`
   - Set `stages.planning.completedAt` to current ISO timestamp
   - Set `stages.planning.artifacts.plan` to `.workflow/plan.md`
   - Set `currentStage` to `"implementation"`
   - Update `updatedAt`

2. **Present the handoff**:
   ```
   PLANNING COMPLETE
   ==================

   Plan: .workflow/plan.md
   Tasks: N
   Dependencies: [summary]

   Next: Stage 4 - Implementation (/workflows-work)
   ```

## Anti-Patterns

- Do NOT start implementing during planning — that's Stage 4's job
- Do NOT create tasks smaller than one meaningful commit
- Do NOT create tasks larger than one sub-agent can handle in a single session
- Do NOT skip codebase investigation — plans based on assumptions fail
- Do NOT ignore the ADR's hypotheses — the plan must be designed to test them