---
name: plan
description: "Generate prd.json and sprint contracts from a spec or feature description. Requires .loop/ directory. Does NOT write source code or start the loop."
---

# /plan — Generate PRD and Sprint Contracts

Read a spec or feature description, decompose it into stories, and write `.loop/prd.json` and `.loop/contracts/`. This skill does NOT write any project source code or start the loop.

## STOP: What This Skill Does NOT Do

- Does NOT write any project source code (no .js, .py, .ts, .html, .css, etc.)
- Does NOT start the loop or invoke /agent-loop:run
- Does NOT make git commits to project code

## Prerequisites

`.loop/config.json` must exist. If not, tell the user to run `/agent-loop:init` first and stop.

## Steps

### 1. Find the feature spec or description

Check these locations for an existing spec:
- `docs/superpowers/specs/*.md`
- `docs/specs/*.md`
- `SPEC.md`, `PRD.md`, `DESIGN.md` at project root

If found: "I found a spec at `{path}`. Using it."

If not found, check if the user passed a description as an argument. If nothing: ask "What do you want to build? 1-3 sentences."

### 2. Analyze the project

- Read relevant source directories
- Check for existing tests and conventions
- Run `git log --oneline -20` if git history exists

### 3. Ask 2-3 clarifying questions

Only questions where human judgment is needed. Do NOT ask what you can answer from the code or spec.

### 4. Generate prd.json

**CRITICAL: Use this EXACT schema. The loop orchestrator will break if you deviate.**

Write `.loop/prd.json`:

```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",
        "Another criterion"
      ],
      "priority": 1,
      "passes": false,
      "notes": "",
      "rejections": 0
    }
  ]
}
```

**Rules:**
- Top-level array key MUST be `userStories`. Not `sprints`, `stories`, or `tasks`.
- IDs: `US-001`, `US-002`, etc.
- `passes`: always `false`. `notes`: always `""`. `rejections`: always `0`.
- Each priority is unique (1 = highest).
- Each story fits in one agent context window (1-3 files changed).
- Acceptance criteria must be independently verifiable — not "works well" but "returns X when given Y".

### 5. Generate sprint contracts

Create `.loop/contracts/` directory. For each story, write `.loop/contracts/{id}.contract.md`:

```markdown
# Sprint Contract: {id} — {title}

## What Will Be Built
Concrete deliverable description.

## Done Conditions
- [ ] Specific testable condition
- [ ] All acceptance criteria from prd.json met

## Evaluation Criteria
- [ ] What the evaluator checks
- [ ] No regressions

## Out of Scope
- Things NOT in this story

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

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

### 6. Initialize progress.md

Write `.loop/progress.md`:

```markdown
# Progress

## Codebase Patterns

- [Patterns from analysis]

---

## Session Log

### Planning Session
Date: {today}

**PRD created:** {N} stories for "{description}"

---
```

### 7. Present for review

> **Plan Ready — Review Before Running**
>
> | Stories | Mode | Branch |
> |---------|------|--------|
> | {N}     | {mode} | {branchName} |
>
> **Stories:**
> 1. US-001: {title}
> 2. US-002: {title}
> ...
>
> **Review before running:**
> - `.loop/prd.json` — stories and acceptance criteria
> - `.loop/contracts/` — done conditions per story
>
> When ready:
> ```
> /agent-loop:run
> ```

**STOP HERE. Do NOT start the loop. Wait for the user to run /agent-loop:run explicitly.**