sheldon/loop-loop
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

fix: tighten skill specs — exact prd.json schema, explicit scaffold, validation

Browse Source
This commit is contained in:
Sheldon Finlay
2026-03-27 08:57:40 -04:00
parent fe14d81073
commit fee323a2d6
3 changed files with 220 additions and 248 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
skills/plan/SKILL.md
View File

@@ -1,94 +1,91 @@
---
name: plan
description: Interactive planning session that generates PRD (prd.json) and sprint contracts for the agent loop. Run /agent-loop:init first.
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
Interactive planning session that produces all artifacts needed for the autonomous agent loop.
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`
- `.loop/` directory must exist with `config.json` (run `/agent-loop:init` first)
## Instructions
Follow these steps exactly.
### 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."
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 for the feature
- Existing tests to understand testing patterns
- Configuration files for conventions
- Recent git history (`git log --oneline -20`) for active work
- Relevant source directories
- Existing tests
- Configuration files
- Recent git history (`git log --oneline -20`)
### 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.
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`)
Create `.loop/prd.json` with properly-sized, dependency-ordered stories.
**CRITICAL: The prd.json MUST use this EXACT schema.** The loop orchestrator parses this structure. Any deviation will break execution.
**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
Write `.loop/prd.json` with this structure:
**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
"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
}
]
}
```
**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
**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
@@ -98,7 +95,7 @@ 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.
Concrete description of the deliverable.
## Done Conditions
- [ ] Condition 1 (specific, testable)
@@ -109,35 +106,30 @@ Concrete description of the deliverable. Not the user story — the actual thing
What the evaluator will specifically check:
- [ ] Check 1
- [ ] Check 2
- [ ] No regressions in [specific area]
- [ ] No regressions in existing functionality
## 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"]
- Depends on: [story IDs or "none"]
- Blocks: [story IDs 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:
Create `.loop/progress.md`:
```markdown
# Progress
## Codebase Patterns
- [Pattern you discovered during analysis]
- [Convention you noticed]
- [Testing approach used in the project]
- [Patterns discovered during analysis]
---
@@ -146,56 +138,38 @@ Create `.loop/progress.md` from the template with an initial Codebase Patterns s
### 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]
**PRD created:** {N} stories for "{description}"
**Estimated iterations:** {N + 30%}
---
```
### Step 7: Present Summary
Show the user a summary:
Show the user:
> **Plan Ready**
> **Plan Ready — Review Before Running**
>
> | Stories | Est. Iterations | Mode | Branch |
> |---------|----------------|------|--------|
> | {N} | {N+30%} | {mode} | {branchName} |
>
> **Story Overview:**
> 1. US-001: {title} (priority 1)
> 2. US-002: {title} (priority 2)
> **Stories:**
> 1. US-001: {title}
> 2. US-002: {title}
> ...
>
> Review the stories in `.loop/prd.json` and contracts in `.loop/contracts/`.
> **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 # 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.
### 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.