loop-loop/skills/plan/SKILL.md

---
name: plan
description: Interactive planning session that generates PRD (prd.json) and sprint contracts for the agent loop. Run /agent-loop:init first.
---

# /plan — Generate PRD and Sprint Contracts

Interactive planning session that produces all artifacts needed for the autonomous agent loop.

## Prerequisites

- `.loop/` directory must exist with `config.json` (run `/agent-loop:init` first if not)
- User should have a clear idea of what they want to build/explore/fix

## Usage

```
/loop-plan <optional feature description>
```

Examples:
- `/loop-plan Add OAuth authentication with Google and GitHub`
- `/loop-plan Explore the payment processing system`
- `/loop-plan Fix all critical security issues from the audit`

## Instructions

### Step 1: Understand the Request

If the user provided a feature description, use it. Otherwise 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 for the feature
- Existing tests to understand testing patterns
- Configuration files for conventions
- Recent git history (`git log --oneline -20`) for active work

### Step 3: Clarifying Questions

Ask 3-5 targeted questions based on what you found in the code. These should be questions where the answer isn't obvious from the codebase. Examples:

- "I see you have both REST endpoints and GraphQL. Should this feature use REST or GraphQL?"
- "The existing auth uses JWT. Should I add OAuth alongside it or replace it?"
- "I found two competing patterns for data validation. Which should I follow?"

**Do NOT ask questions you can answer from the code.** Only ask when human judgment is needed.

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

Create `.loop/prd.json` with properly-sized, dependency-ordered stories.

**Story Sizing Rules (CRITICAL):**
- Each story must be completable in ONE context window (~100K tokens of work)
- Target: 1-3 files changed per story
- Too big: "Build the authentication system" → split into migration, endpoint, middleware, UI, tests
- Too small: "Add import statement" → combine with the story that needs it

**Dependency Ordering:**
1. Schema/database changes first (they block everything)
2. Backend logic (depends on schema)
3. Frontend components (depend on backend)
4. Integration/wiring (depends on components)
5. Polish/edge cases (depends on core being done)

**Required Fields Per Story:**
```json
{
  "id": "US-001",
  "title": "Short descriptive title",
  "description": "As a [role], I want [feature] so that [benefit].",
  "acceptanceCriteria": [
    "Specific, verifiable criterion",
    "Another criterion",
    "Typecheck passes"
  ],
  "priority": 1,
  "passes": false,
  "notes": "",
  "rejections": 0
}
```

**Acceptance Criteria Rules:**
- Every criterion must be independently verifiable (not "works well" — "returns 200 with valid token")
- Always include "Typecheck passes" (or equivalent for the language)
- UI stories must include "Verify UI renders and responds to interaction"
- API stories must include status code expectations
- Database stories must include migration success check

### 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. Not the user story — the actual thing being built.

## 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 [specific area]

## Out of Scope
Things explicitly NOT part of this story:
- Thing 1
- Thing 2

## Key Files
Files likely to be created or modified:
- path/to/file.ext — what changes
- path/to/other.ext — what changes

## Dependencies
- Depends on: [story IDs that must be done first, or "none"]
- Blocks: [story IDs that depend on this one, or "none"]
```

### Step 6: Initialize Progress File

Create `.loop/progress.md` from the template with an initial Codebase Patterns section populated from what you learned during analysis:

```markdown
# Progress

## Codebase Patterns

- [Pattern you discovered during analysis]
- [Convention you noticed]
- [Testing approach used in the project]

---

## Session Log

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

**PRD created:** {N} stories for "{feature description}"
**Estimated iterations:** {N stories + ~30% for evaluator rejections}
**Key decisions:**
- [Decision 1 and why]
- [Decision 2 and why]

---
```

### Step 7: Present Summary

Show the user a summary:

> **Plan Ready**
>
> | Stories | Est. Iterations | Mode | Branch |
> |---------|----------------|------|--------|
> | {N}     | {N+30%}        | {mode} | {branchName} |
>
> **Story Overview:**
> 1. US-001: {title} (priority 1)
> 2. US-002: {title} (priority 2)
> ...
>
> Review the stories in `.loop/prd.json` and contracts in `.loop/contracts/`.
> Adjust anything you'd like, then run:
> ```
> /agent-loop:run            # Interactive (recommended)
> .loop/loop.sh              # Headless
> ```

### Step 8: Review Before Execution

Tell the user:
> **Review the plan before running.** The stories and contracts are designed to be human-reviewed and adjusted before handing off to the autonomous loop.
>
> **Files to review:**
> - `.loop/prd.json` — stories, acceptance criteria, priorities
> - `.loop/contracts/` — sprint contracts with done conditions and scope
>
> **Common adjustments:**
> - Split a story that's too large
> - Reorder priorities
> - Tighten or loosen acceptance criteria
> - Add/remove stories
> - Adjust scope in contracts
>
> Let me know what changes you'd like, or when you're happy with the plan, run:
> ```
> /agent-loop:run
> ```

Wait for the user to review. If they request changes, make them and re-present the summary. Do NOT automatically start the loop — the user must explicitly invoke `/agent-loop:run` when they're ready.