loop-loop/skills/plan/SKILL.md

name, description

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

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

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

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