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

fix: radically simplify skills — each does exactly one thing, no chaining, explicit boundaries

Browse Source
This commit is contained in:
Sheldon Finlay
2026-03-27 09:03:47 -04:00
parent fee323a2d6
commit 53086c9dbc
2 changed files with 93 additions and 158 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
skills/init/SKILL.md
View File

@@ -1,38 +1,36 @@
--- ---
name: init name: init
description: "Setup task: scaffold .loop/ directory and generate config for the agent loop harness. Not a creative task — do not brainstorm or generate ideas. Reads existing specs if present." description: "Infrastructure setup: scaffold .loop/ directory with harness files and generate config.json. Does NOT plan or write code."
--- ---
# /init — Initialize Agent Loop for a Project # /init — Scaffold the Agent Loop
Set up the agent loop harness in the current project. This is infrastructure setup, not creative work. Create the `.loop/` directory and generate `config.json`. That's it. This skill does NOT plan features, generate stories, or write any project source code.
**IMPORTANT:** Do NOT invoke brainstorming, planning, or idea-generation skills. This skill handles its own flow. ## STOP: What This Skill Does NOT Do
## Instructions - Does NOT read or use any spec files
- Does NOT generate prd.json or stories
- Does NOT write any source code
- Does NOT invoke /agent-loop:plan
- Does NOT start the loop
Follow these steps exactly. Do not skip or reorder them. ## Steps
### Step 1: Scaffold .loop/ Directory ### 1. Check if .loop/ already exists
Check if `.loop/` already exists in the project root. If yes, ask: "`.loop/` already exists. Re-initialize? (This resets config but keeps prd.json and progress.md)"
**If `.loop/` already exists** and contains `prd.json`, ask the user if they want to re-initialize. If yes, delete `.loop/` and continue. If no, skip to Step 3. If they say no, stop.
**Create `.loop/` and copy ALL required harness files.** Run these commands exactly: ### 2. Copy harness files
Run these commands:
```bash ```bash
mkdir -p .loop mkdir -p .loop
```
Then check if the plugin root has the harness files. Try these paths in order: # Find plugin harness source
1. `${CLAUDE_PLUGIN_ROOT}/prompts/` (if CLAUDE_PLUGIN_ROOT env var is set)
2. `~/.claude/plugins/cache/agent-loop/agent-loop/*/prompts/` (glob for any version)
Copy ALL of these directories and files — every one is required:
```bash
# Find the harness source (plugin cache)
HARNESS_SRC=$(ls -d ~/.claude/plugins/cache/agent-loop/agent-loop/*/prompts/.. 2>/dev/null | head -1) HARNESS_SRC=$(ls -d ~/.claude/plugins/cache/agent-loop/agent-loop/*/prompts/.. 2>/dev/null | head -1)
if [ -n "$HARNESS_SRC" ]; then if [ -n "$HARNESS_SRC" ]; then
@@ -41,19 +39,14 @@ if [ -n "$HARNESS_SRC" ]; then
cp -r "$HARNESS_SRC/lib" .loop/ cp -r "$HARNESS_SRC/lib" .loop/
cp "$HARNESS_SRC/loop.sh" .loop/ cp "$HARNESS_SRC/loop.sh" .loop/
chmod +x .loop/loop.sh chmod +x .loop/loop.sh
else
echo "ERROR: Could not find agent-loop plugin files"
fi fi
``` ```
**Verify the copy worked.** Check that these paths exist: Verify `.loop/prompts/generator/_base.md` exists. If not, report the error and stop.
- `.loop/prompts/generator/_base.md`
- `.loop/prompts/evaluator/_base.md`
- `.loop/templates/progress.md.template`
- `.loop/lib/state.sh`
- `.loop/loop.sh`
If any are missing, tell the user the scaffold failed and show which files are missing. ### 3. Create .loop/.gitignore
Create `.loop/.gitignore`:
``` ```
prd.json prd.json
@@ -69,41 +62,14 @@ archive/
.loop.lock .loop.lock
``` ```
### Step 2: Check for Existing Specs ### 4. Detect project and generate config
Search for existing design documents or specs: Read the project root to detect tech stack (package.json, go.mod, Cargo.toml, etc.).
- `docs/superpowers/specs/*.md`
- `docs/specs/*.md`
- `SPEC.md`, `PRD.md`, `DESIGN.md` at root
**If a spec is found:**
> "I found an existing spec at `{path}`. I'll use this as the basis for generating stories."
Read it. The user does NOT need to re-describe what they want. Set mode to `implement` and skip to Step 4.
**If no spec is found**, proceed to Step 3.
### Step 3: Mode Selection
Ask the user: Ask the user:
> **Mode?** (a) Explore (b) Implement (c) Fix
> **What would you like to do?** Write `.loop/config.json`:
>
> a) **Explore** — Read-only codebase analysis. No code changes.
> b) **Implement** — Build a feature. Code changes, commits, and tests.
> c) **Fix** — Targeted bug fixes or tech debt.
For **implement** without a spec: "Describe the feature in 1-3 sentences."
For **explore**: "What areas should I focus on?"
For **fix**: "Do you have a list of issues, or should I find them?"
Also read the project to detect the tech stack:
- Check for `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, etc.
- Run `ls` on the project root
### Step 4: Generate Configuration
Create `.loop/config.json` with this EXACT structure:
```json ```json
{ {
@@ -115,32 +81,22 @@ Create `.loop/config.json` with this EXACT structure:
"autoHooks": true, "autoHooks": true,
"branchPrefix": "loop/", "branchPrefix": "loop/",
"scopeBudgets": { "scopeBudgets": {
"explore": { "explore": { "maxFilesToRead": 15, "maxLinesToWrite": 0, "maxFilesToModify": 0 },
"maxFilesToRead": 15, "implement": { "maxFilesToRead": 50, "maxLinesToWrite": 500, "maxFilesToModify": 10 },
"maxLinesToWrite": 0, "fix": { "maxFilesToRead": 30, "maxLinesToWrite": 200, "maxFilesToModify": 5 }
"maxFilesToModify": 0
},
"implement": {
"maxFilesToRead": 50,
"maxLinesToWrite": 500,
"maxFilesToModify": 10
},
"fix": {
"maxFilesToRead": 30,
"maxLinesToWrite": 200,
"maxFilesToModify": 5
}
} }
} }
``` ```
Adjust `maxIterations` based on estimated story count (stories + 30% for rejections). ### 5. Generate init.sh
Create `.loop/init.sh` with project-specific setup commands. Make it executable. Write `.loop/init.sh` with project-specific setup (dependency install, dev server, test runner). Make it executable.
### Step 5: Flow into Planning ### 6. Done
Say: Tell the user:
> "Project configured. Generating stories..."
Then invoke `/agent-loop:plan`. If a spec was found in Step 2, tell the plan skill to use it. > `.loop/` is ready. Next steps:
> ```
> /agent-loop:plan # Generate stories from your spec or feature description
> ```

135
skills/plan/SKILL.md
View File

@@ -1,48 +1,50 @@
--- ---
name: plan name: plan
description: Generate PRD (prd.json) with user stories and sprint contracts for the agent loop. Requires .loop/ directory (run /agent-loop:init first). description: "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 # /plan — Generate PRD and Sprint Contracts
Produces all artifacts needed for the autonomous agent loop. 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 ## Prerequisites
- `.loop/` directory must exist with `config.json` (run `/agent-loop:init` first) `.loop/config.json` must exist. If not, tell the user to run `/agent-loop:init` first and stop.
## Instructions ## Steps
Follow these steps exactly. ### 1. Find the feature spec or description
### Step 1: Understand the Request Check these locations for an existing spec:
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/superpowers/specs/*.md`
- `docs/specs/*.md` - `docs/specs/*.md`
- `SPEC.md`, `PRD.md`, `DESIGN.md` - `SPEC.md`, `PRD.md`, `DESIGN.md` at project root
If still nothing, ask: "What would you like to work on? Describe it in 1-3 sentences." If found: "I found a spec at `{path}`. Using it."
### Step 2: Codebase Analysis 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."
Read key project files to understand existing patterns: ### 2. Analyze the project
- Relevant source directories
- Existing tests
- Configuration files
- Recent git history (`git log --oneline -20`)
### Step 3: Clarifying Questions - Read relevant source directories
- Check for existing tests and conventions
- Run `git log --oneline -20` if git history exists
Ask 2-3 targeted questions where human judgment is needed. Do NOT ask questions you can answer from the code or spec. ### 3. Ask 2-3 clarifying questions
### Step 4: Generate PRD (`prd.json`) Only questions where human judgment is needed. Do NOT ask what you can answer from the code or spec.
**CRITICAL: The prd.json MUST use this EXACT schema.** The loop orchestrator parses this structure. Any deviation will break execution. ### 4. Generate prd.json
Write `.loop/prd.json` with this structure: **CRITICAL: Use this EXACT schema. The loop orchestrator will break if you deviate.**
Write `.loop/prd.json`:
```json ```json
{ {
@@ -55,8 +57,8 @@ Write `.loop/prd.json` with this structure:
"title": "Short descriptive title", "title": "Short descriptive title",
"description": "What this story delivers", "description": "What this story delivers",
"acceptanceCriteria": [ "acceptanceCriteria": [
"Specific, verifiable criterion 1", "Specific, verifiable criterion",
"Specific, verifiable criterion 2" "Another criterion"
], ],
"priority": 1, "priority": 1,
"passes": false, "passes": false,
@@ -67,109 +69,86 @@ Write `.loop/prd.json` with this structure:
} }
``` ```
**Schema rules — do NOT deviate:** **Rules:**
- Top-level key is `userStories` (array). NOT `sprints`, NOT `stories`, NOT `tasks`. - Top-level array key MUST be `userStories`. Not `sprints`, `stories`, or `tasks`.
- Each story has: `id`, `title`, `description`, `acceptanceCriteria`, `priority`, `passes`, `notes`, `rejections` - IDs: `US-001`, `US-002`, etc.
- `id` format: `US-001`, `US-002`, etc. - `passes`: always `false`. `notes`: always `""`. `rejections`: always `0`.
- `passes` is always `false` initially - Each priority is unique (1 = highest).
- `notes` is always `""` initially - Each story fits in one agent context window (1-3 files changed).
- `rejections` is always `0` initially - Acceptance criteria must be independently verifiable — not "works well" but "returns X when given Y".
- `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:** ### 5. Generate sprint contracts
- 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:** Create `.loop/contracts/` directory. For each story, write `.loop/contracts/{id}.contract.md`:
- 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`:
```markdown ```markdown
# Sprint Contract: {Story ID} — {Story Title} # Sprint Contract: {id} — {title}
## What Will Be Built ## What Will Be Built
Concrete description of the deliverable. Concrete deliverable description.
## Done Conditions ## Done Conditions
- [ ] Condition 1 (specific, testable) - [ ] Specific testable condition
- [ ] Condition 2
- [ ] All acceptance criteria from prd.json met - [ ] All acceptance criteria from prd.json met
## Evaluation Criteria ## Evaluation Criteria
What the evaluator will specifically check: - [ ] What the evaluator checks
- [ ] Check 1 - [ ] No regressions
- [ ] Check 2
- [ ] No regressions in existing functionality
## Out of Scope ## Out of Scope
- Thing 1 - Things NOT in this story
- Thing 2
## Key Files ## Key Files
- path/to/file.ext — what changes - path/to/file — what changes
## Dependencies ## Dependencies
- Depends on: [story IDs or "none"] - Depends on: [IDs or "none"]
- Blocks: [story IDs or "none"] - Blocks: [IDs or "none"]
``` ```
### Step 6: Initialize Progress File ### 6. Initialize progress.md
Create `.loop/progress.md`: Write `.loop/progress.md`:
```markdown ```markdown
# Progress # Progress
## Codebase Patterns ## Codebase Patterns
- [Patterns discovered during analysis] - [Patterns from analysis]
--- ---
## Session Log ## Session Log
### Planning Session ### Planning Session
Date: YYYY-MM-DD HH:MM Date: {today}
**PRD created:** {N} stories for "{description}" **PRD created:** {N} stories for "{description}"
**Estimated iterations:** {N + 30%}
--- ---
``` ```
### Step 7: Present Summary ### 7. Present for review
Show the user:
> **Plan Ready — Review Before Running** > **Plan Ready — Review Before Running**
> >
> | Stories | Est. Iterations | Mode | Branch | > | Stories | Mode | Branch |
> |---------|----------------|------|--------| > |---------|------|--------|
> | {N} | {N+30%} | {mode} | {branchName} | > | {N} | {mode} | {branchName} |
> >
> **Stories:** > **Stories:**
> 1. US-001: {title} > 1. US-001: {title}
> 2. US-002: {title} > 2. US-002: {title}
> ... > ...
> >
> **Review these files before running:** > **Review before running:**
> - `.loop/prd.json` — stories and acceptance criteria > - `.loop/prd.json` — stories and acceptance criteria
> - `.loop/contracts/` — done conditions and scope per story > - `.loop/contracts/` — done conditions per story
> >
> Adjust anything you'd like, then run: > When ready:
> ``` > ```
> /agent-loop:run > /agent-loop:run
> ``` > ```
### Step 8: Wait for Review **STOP HERE. Do NOT start the loop. Wait for the user to run /agent-loop:run explicitly.**
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.