loop-loop/skills/plan/SKILL.md

name, description

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

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

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

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