From fe14d81073be3c31944c8bacf31a7e07faf283b4 Mon Sep 17 00:00:00 2001 From: Sheldon Finlay Date: Fri, 27 Mar 2026 08:46:18 -0400 Subject: [PATCH] fix: init skill avoids brainstorming interception, detects existing specs --- skills/init/SKILL.md | 88 +++++++++++++++++++------------------------- 1 file changed, 38 insertions(+), 50 deletions(-) diff --git a/skills/init/SKILL.md b/skills/init/SKILL.md index 12f1e1d..14c13bc 100644 --- a/skills/init/SKILL.md +++ b/skills/init/SKILL.md @@ -1,19 +1,21 @@ --- name: init -description: Initialize the agent loop harness in the current project. Scaffolds .loop/ directory, detects tech stack, picks mode, generates config, and flows into planning. +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." --- # /init — Initialize Agent Loop for a Project -Set up the agent loop harness in the current project. This is the entry point for first-time use. +Set up the agent loop harness in the current project. This is infrastructure setup, not creative work. + +**IMPORTANT:** Do NOT invoke brainstorming, planning, or idea-generation skills. This skill handles its own flow. If the user wants to brainstorm first, they should do that separately before running this skill. ## What This Skill Does -1. Scaffolds the `.loop/` directory with prompts, templates, and lib scripts from the plugin -2. Analyzes the project to understand its tech stack, structure, and conventions -3. Asks the user what they want to accomplish (explore, implement, or fix) -4. Creates project-specific configuration (`config.json`, `init.sh`) -5. Flows into planning to generate the PRD and sprint contracts +1. Checks for existing specs/plans in the project (uses them if found) +2. Scaffolds the `.loop/` directory +3. Detects tech stack +4. Picks mode and generates config +5. Flows into `/agent-loop:plan` to decompose the spec into stories ## Instructions @@ -56,17 +58,23 @@ archive/ **If `.loop/` already exists**, ask the user if they want to re-initialize (which resets config but preserves prd.json/progress.md if they exist). -### Step 1: Project Discovery +### Step 1: Check for Existing Specs -Read the project to understand what we're working with: -- Check for `CLAUDE.md`, `AGENTS.md`, `README.md` at the project root -- Check for `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Package.swift`, `composer.json` to identify the tech stack -- Run `ls` on the project root to see the top-level structure +Search for existing design documents or specs in the project: +- `docs/superpowers/specs/*.md` +- `docs/specs/*.md` +- `docs/*.md` (that look like feature specs) +- `SPEC.md`, `PRD.md`, `DESIGN.md` at root +- Any markdown file that contains design/architecture/requirements content -Present a brief summary: -> "I see this is a [language/framework] project with [key characteristics]. The main source is in [dir/]." +**If a spec is found:** +> "I found an existing spec at `{path}`. I'll use this as the basis for generating stories." -### Step 2: Mode Selection +Read the spec and use it as input for planning. Do NOT ask the user to re-describe what they want — the spec already has it. Skip to Step 3 (mode is almost certainly **implement**). + +**If no spec is found**, proceed to Step 2. + +### Step 2: Mode Selection and Description Ask the user: @@ -76,28 +84,25 @@ Ask the user: > b) **Implement** — Build a new feature from a PRD. Code changes, commits, and tests. > c) **Fix** — Work through a list of bugs or tech debt items. Targeted code changes. -### Step 3: Clarifying Questions +Based on the mode, ask 2-3 brief clarifying questions. Do NOT over-interview — keep it focused: -Based on the mode, ask 3-5 questions: +**For Implement:** "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?" -**For Explore:** -- "What areas are you most interested in? (e.g., auth, database, API, frontend, everything)" -- "Are there known problem areas you want me to focus on?" -- "How many exploration sessions should I budget? (default: 20)" +### Step 3: Project Discovery -**For Implement:** -- "Describe the feature you want to build (1-3 sentences is fine)" -- "Are there any architectural constraints I should know about?" -- "Should I follow any specific patterns from the existing codebase?" +Read the project to understand what we're working with: +- Check for `CLAUDE.md`, `AGENTS.md`, `README.md` at the project root +- Check for `package.json`, `Cargo.toml`, `pyproject.toml`, `go.mod`, `Package.swift`, `composer.json` to identify the tech stack +- Run `ls` on the project root to see the top-level structure -**For Fix:** -- "Do you have a list of issues, or should I find them?" -- "Any areas that are off-limits for changes?" -- "What's the priority: security, stability, or code quality?" +Present a brief summary: +> "I see this is a [language/framework] project with [key characteristics]." ### Step 4: Generate Configuration -Create `.loop/config.json` based on the project and user's answers: +Create `.loop/config.json` based on the project: ```json { @@ -114,28 +119,11 @@ Create `.loop/config.json` based on the project and user's answers: } ``` -Create `.loop/init.sh` with project-specific setup commands: -- Dev server startup (if applicable) -- Test runner command -- Type checker command -- Linter command -- Any environment setup needed - -Make `init.sh` executable. +Create `.loop/init.sh` with project-specific setup commands (dev server, test runner, linter, etc.). Make it executable. ### Step 5: Flow into Planning Tell the user: -> "Project configured. Now let's plan the work." +> "Project configured. Generating stories from {spec name / user description}..." -Then invoke the `/agent-loop:plan` skill to generate the PRD and sprint contracts. - -### Step 6: Ready to Run - -Once planning is complete, tell the user: -> "Everything is set up. To start the loop:" -> ``` -> /agent-loop:run # Interactive (recommended) — visible, can intervene -> .loop/loop.sh # Headless — fully autonomous -> ``` -> You can monitor progress in `.loop/progress.md` and check story status in `.loop/prd.json`. +Then invoke `/agent-loop:plan` to generate the PRD and sprint contracts. If a spec was found in Step 1, pass it as context so the plan skill uses it directly.