---
name: plan
description: Generate PRD (prd.json) with user stories and sprint contracts for the agent loop. Requires .loop/ directory (run /agent-loop:init first).
---

# /plan — Generate PRD and Sprint Contracts

Produces all artifacts needed for the autonomous agent loop.

## Prerequisites

- `.loop/` directory must exist with `config.json` (run `/agent-loop:init` first)

## Instructions

Follow these steps exactly.

### Step 1: Understand the Request

Check if a spec or feature description was passed from `/agent-loop:init`. If so, use it directly.

Otherwise, check for specs in the project:
- `docs/superpowers/specs/*.md`
- `docs/specs/*.md`
- `SPEC.md`, `PRD.md`, `DESIGN.md`

If still nothing, ask: "What would you like to work on? Describe it in 1-3 sentences."

### Step 2: Codebase Analysis

Read key project files to understand existing patterns:
- Relevant source directories
- Existing tests
- Configuration files
- Recent git history (`git log --oneline -20`)

### Step 3: Clarifying Questions

Ask 2-3 targeted questions where human judgment is needed. Do NOT ask questions you can answer from the code or spec.

### Step 4: Generate PRD (`prd.json`)

**CRITICAL: The prd.json MUST use this EXACT schema.** The loop orchestrator parses this structure. Any deviation will break execution.

Write `.loop/prd.json` with this structure:

```json
{
  "project": "<project name>",
  "branchName": "loop/<feature-slug>",
  "description": "<one-line description>",
  "userStories": [
    {
      "id": "US-001",
      "title": "Short descriptive title",
      "description": "What this story delivers",
      "acceptanceCriteria": [
        "Specific, verifiable criterion 1",
        "Specific, verifiable criterion 2"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "rejections": 0
    }
  ]
}
```

**Schema rules — do NOT deviate:**
- Top-level key is `userStories` (array). NOT `sprints`, NOT `stories`, NOT `tasks`.
- Each story has: `id`, `title`, `description`, `acceptanceCriteria`, `priority`, `passes`, `notes`, `rejections`
- `id` format: `US-001`, `US-002`, etc.
- `passes` is always `false` initially
- `notes` is always `""` initially
- `rejections` is always `0` initially
- `priority` is a number (1 = highest). No two stories share a priority.
- `branchName` must be set — the loop uses it for git checkout

**Story sizing:**
- Each story must be completable in ONE agent context window
- Target: 1-3 files changed per story
- Too big → split. Too small → combine.

**Acceptance criteria rules:**
- Every criterion must be independently verifiable by the evaluator
- NOT "works well" — instead "function returns X when given Y"
- Include quality gates: "No lint errors", "Tests pass", etc.

### Step 5: Generate Sprint Contracts

For each story, create `.loop/contracts/{story-id}.contract.md`:

```markdown
# Sprint Contract: {Story ID} — {Story Title}

## What Will Be Built
Concrete description of the deliverable.

## Done Conditions
- [ ] Condition 1 (specific, testable)
- [ ] Condition 2
- [ ] All acceptance criteria from prd.json met

## Evaluation Criteria
What the evaluator will specifically check:
- [ ] Check 1
- [ ] Check 2
- [ ] No regressions in existing functionality

## Out of Scope
- Thing 1
- Thing 2

## Key Files
- path/to/file.ext — what changes

## Dependencies
- Depends on: [story IDs or "none"]
- Blocks: [story IDs or "none"]
```

### Step 6: Initialize Progress File

Create `.loop/progress.md`:

```markdown
# Progress

## Codebase Patterns

- [Patterns discovered during analysis]

---

## Session Log

### Planning Session
Date: YYYY-MM-DD HH:MM

**PRD created:** {N} stories for "{description}"
**Estimated iterations:** {N + 30%}

---
```

### Step 7: Present Summary

Show the user:

> **Plan Ready — Review Before Running**
>
> | Stories | Est. Iterations | Mode | Branch |
> |---------|----------------|------|--------|
> | {N}     | {N+30%}        | {mode} | {branchName} |
>
> **Stories:**
> 1. US-001: {title}
> 2. US-002: {title}
> ...
>
> **Review these files before running:**
> - `.loop/prd.json` — stories and acceptance criteria
> - `.loop/contracts/` — done conditions and scope per story
>
> Adjust anything you'd like, then run:
> ```
> /agent-loop:run
> ```

### Step 8: Wait for Review

Wait for the user to review. If they request changes, make them and re-present.

**Do NOT automatically start the loop.** The user must explicitly invoke `/agent-loop:run` when ready.