loop-loop/skills/plan/SKILL.md

name, description

name	description
plan	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:

{
  "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:

# 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:

# 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.