> ## Documentation Index
> Fetch the complete documentation index at: https://sdlc-rstack.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Stage 04 — Planning

> Senior project manager agent. Produces plan.json with a work breakdown structure, milestone schedule, risk register, and dependency map.

<Info>
  **File:** `agents/sdlc/04-planning.md` · **Model:** Opus · **Tools:** Bash, Read, Write
</Info>

## Purpose

The planning agent turns approved requirements into an executable project plan: a work breakdown structure (WBS) with owners and durations, milestones that deliver testable value, a dependency map between tasks, and a risk register with real mitigations. Its own framing: a plan with vague tasks is a plan that will be misunderstood, re-estimated, and missed.

## Core principle

> Every task has an owner role, a duration in days, and a one-sentence definition of done that does not use the word "implement." Every top risk has a mitigation — not "monitor the situation," but a specific action with a trigger.

The stage prompt frames the stakes directly: the architecture agent (stage 06) sizes a system for this plan, and the Jira agent (stage 05) creates tickets straight from this WBS — a badly structured plan produces tickets nobody can execute and a risk register nobody reads.

## What it does

1. Reads `requirement_spec.json` (stage 02's output)
2. Builds the WBS — breaks requirements into 1–5 day tasks, each with one owner and one deliverable, grouped into milestones (phases that deliver testable value), with dependencies mapped between tasks
3. Builds the risk register — each risk scored H/M/L on probability and impact, with a mitigation and a trigger; flags the top 3 risks that could block delivery
4. Writes `plan.json`

Before writing the first task, the agent is instructed to identify the two tasks most likely to be underestimated and the single biggest external dependency.

## Inputs and where it sits in the pipeline

Planning is stage 4 of 15, sitting directly between **[Requirements](/sdlc-pipeline/requirements)** (stage 02 — via stage 03 documentation) and **Jira** (stage 05), and it feeds forward into **[Architecture](/sdlc-pipeline/architecture)** (stage 06):

* **Reads:** `requirement_spec.json` from stage 02
* **Consumed by:** stage 05 (Jira tickets generated from the WBS) and stage 06 (system sized against this plan)

## Output

Per the canonical stage registry (`src/core/harness/stages.js`), stage `04-planning` produces the artifact `plan.json`:

```json theme={null}
// .rstack/runs/<run_id>/artifacts/plan.json
{
  "milestones": [
    { "name": "...", "deliverable": "...", "target_date": "..." }
  ],
  "tasks": [
    { "id": "T-001", "name": "...", "milestone": "M1", "days": 3, "depends_on": [] }
  ],
  "risks": [
    {
      "id": "R-001",
      "description": "...",
      "probability": "H",
      "impact": "H",
      "mitigation": "..."
    }
  ],
  "status": "PASS"
}
```

## Brownfield behavior

`rstack-agents adopt` deliberately **skips this stage entirely** — plans belong to new work, not to a system that already exists. On an adopted run that later triggers a real planning pass (a new change against an existing baseline), the agent is instructed to plan *only the new change*, sized against the adopted baseline, reading the harvested `00-environment` and `06-architecture` artifacts (each marked `source: "brownfield-adoption"`) as ground truth rather than re-scaffolding anything that already ships. Risks in that mode should include brownfield-specific ones: untested legacy paths, implicit API contracts, and the study-before-modify cost.

## Quality self-check and completion

Before reporting done, the agent verifies every task has an owner role, a duration, and a one-sentence definition of done; that dependencies are mapped; and that every top-3 risk has a specific mitigation (not "monitor"). It also asks itself, as an operational self-improvement step, whether any estimates felt unreliable due to ambiguous scope, or whether a risk was found with no clear mitigation — logging genuine discoveries via `rstack memory append`.

Completion status follows the standard Task Contract vocabulary:

| Status               | Meaning                                                            |
| -------------------- | ------------------------------------------------------------------ |
| `DONE`               | `plan.json` written with WBS, milestones, risks, and dependencies  |
| `DONE_WITH_CONCERNS` | Plan written but top risks have no clear mitigation — flagged      |
| `BLOCKED`            | `requirement_spec.json` missing or empty                           |
| `NEEDS_CONTEXT`      | One focused question about a critical scope or resource assumption |

<Note>
  Escalation rule: after 3 failed attempts to build a coherent WBS, or if resource/timeline constraints make the plan obviously undeliverable, the agent stops and escalates rather than producing a plan it doesn't believe in.
</Note>

## Related

* [Requirements](/sdlc-pipeline/requirements)
* [Architecture](/sdlc-pipeline/architecture)
* [Pipeline overview](/sdlc-pipeline/overview)