diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md index 53cc27e..12683fb 100644 --- a/skills/init/SKILL.md +++ b/skills/init/SKILL.md @@ -1,38 +1,36 @@ --- 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 mkdir -p .loop -``` -Then check if the plugin root has the harness files. Try these paths in order: -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) +# Find plugin harness source HARNESS_SRC=$(ls -d ~/.claude/plugins/cache/agent-loop/agent-loop/*/prompts/.. 2>/dev/null | head -1) if [ -n "$HARNESS_SRC" ]; then @@ -41,19 +39,14 @@ if [ -n "$HARNESS_SRC" ]; then cp -r "$HARNESS_SRC/lib" .loop/ cp "$HARNESS_SRC/loop.sh" .loop/ chmod +x .loop/loop.sh +else + echo "ERROR: Could not find agent-loop plugin files" fi ``` -**Verify the copy worked.** Check that these paths exist: -- `.loop/prompts/generator/_base.md` -- `.loop/prompts/evaluator/_base.md` -- `.loop/templates/progress.md.template` -- `.loop/lib/state.sh` -- `.loop/loop.sh` +Verify `.loop/prompts/generator/_base.md` exists. If not, report the error and stop. -If any are missing, tell the user the scaffold failed and show which files are missing. - -Create `.loop/.gitignore`: +### 3. Create .loop/.gitignore ``` prd.json @@ -69,41 +62,14 @@ archive/ .loop.lock ``` -### Step 2: Check for Existing Specs +### 4. Detect project and generate config -Search for existing design documents or specs: -- `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 +Read the project root to detect tech stack (package.json, go.mod, Cargo.toml, etc.). Ask the user: +> **Mode?** (a) Explore (b) Implement (c) Fix -> **What would you like to do?** -> -> 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: +Write `.loop/config.json`: ```json { @@ -115,32 +81,22 @@ Create `.loop/config.json` with this EXACT structure: "autoHooks": true, "branchPrefix": "loop/", "scopeBudgets": { - "explore": { - "maxFilesToRead": 15, - "maxLinesToWrite": 0, - "maxFilesToModify": 0 - }, - "implement": { - "maxFilesToRead": 50, - "maxLinesToWrite": 500, - "maxFilesToModify": 10 - }, - "fix": { - "maxFilesToRead": 30, - "maxLinesToWrite": 200, - "maxFilesToModify": 5 - } + "explore": { "maxFilesToRead": 15, "maxLinesToWrite": 0, "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: -> "Project configured. Generating stories..." +Tell the user: -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 +> ``` diff --git a/skills/plan/SKILL.md b/skills/plan/SKILL.md index 9e2c32c..055adef 100644 --- a/skills/plan/SKILL.md +++ b/skills/plan/SKILL.md @@ -1,48 +1,50 @@ --- 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 -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 -- `.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 if a spec or feature description was passed from `/agent-loop:init`. If so, use it directly. - -Otherwise, check for specs in the project: +Check these locations for an existing spec: - `docs/superpowers/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: -- Relevant source directories -- Existing tests -- Configuration files -- Recent git history (`git log --oneline -20`) +### 2. Analyze the project -### 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 { @@ -55,8 +57,8 @@ Write `.loop/prd.json` with this structure: "title": "Short descriptive title", "description": "What this story delivers", "acceptanceCriteria": [ - "Specific, verifiable criterion 1", - "Specific, verifiable criterion 2" + "Specific, verifiable criterion", + "Another criterion" ], "priority": 1, "passes": false, @@ -67,109 +69,86 @@ Write `.loop/prd.json` with this structure: } ``` -**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 +**Rules:** +- Top-level array key MUST be `userStories`. Not `sprints`, `stories`, or `tasks`. +- IDs: `US-001`, `US-002`, etc. +- `passes`: always `false`. `notes`: always `""`. `rejections`: always `0`. +- Each priority is unique (1 = highest). +- Each story fits in one agent context window (1-3 files changed). +- Acceptance criteria must be independently verifiable — not "works well" but "returns X when given Y". -**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. +### 5. Generate sprint contracts -**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`: +Create `.loop/contracts/` directory. For each story, write `.loop/contracts/{id}.contract.md`: ```markdown -# Sprint Contract: {Story ID} — {Story Title} +# Sprint Contract: {id} — {title} ## What Will Be Built -Concrete description of the deliverable. +Concrete deliverable description. ## Done Conditions -- [ ] Condition 1 (specific, testable) -- [ ] Condition 2 +- [ ] Specific testable condition - [ ] All acceptance criteria from prd.json met ## Evaluation Criteria -What the evaluator will specifically check: -- [ ] Check 1 -- [ ] Check 2 -- [ ] No regressions in existing functionality +- [ ] What the evaluator checks +- [ ] No regressions ## Out of Scope -- Thing 1 -- Thing 2 +- Things NOT in this story ## Key Files -- path/to/file.ext — what changes +- path/to/file — what changes ## Dependencies -- Depends on: [story IDs or "none"] -- Blocks: [story IDs or "none"] +- Depends on: [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 # Progress ## Codebase Patterns -- [Patterns discovered during analysis] +- [Patterns from analysis] --- ## Session Log ### Planning Session -Date: YYYY-MM-DD HH:MM +Date: {today} **PRD created:** {N} stories for "{description}" -**Estimated iterations:** {N + 30%} --- ``` -### Step 7: Present Summary - -Show the user: +### 7. Present for review > **Plan Ready — Review Before Running** > -> | Stories | Est. Iterations | Mode | Branch | -> |---------|----------------|------|--------| -> | {N} | {N+30%} | {mode} | {branchName} | +> | Stories | Mode | Branch | +> |---------|------|--------| +> | {N} | {mode} | {branchName} | > > **Stories:** > 1. US-001: {title} > 2. US-002: {title} > ... > -> **Review these files before running:** +> **Review before running:** > - `.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 > ``` -### 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. +**STOP HERE. Do NOT start the loop. Wait for the user to run /agent-loop:run explicitly.**