176 lines
4.4 KiB
Markdown
176 lines
4.4 KiB
Markdown
---
|
|
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.
|