loop-loop/skills/init/SKILL.md

name, description

name	description
init	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 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. 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

When the user invokes this skill, follow this sequence:

Step 0: Scaffold .loop/ Directory

Check if .loop/ already exists in the project root.

If it does NOT exist, create it by copying from the plugin:

1. The plugin's root directory is available at ${CLAUDE_PLUGIN_ROOT}. Copy the harness files:

mkdir -p .loop
cp -r "${CLAUDE_PLUGIN_ROOT}/prompts" .loop/
cp -r "${CLAUDE_PLUGIN_ROOT}/templates" .loop/
cp -r "${CLAUDE_PLUGIN_ROOT}/lib" .loop/
cp "${CLAUDE_PLUGIN_ROOT}/loop.sh" .loop/
chmod +x .loop/loop.sh

IMPORTANT: If ${CLAUDE_PLUGIN_ROOT} is not set or the path doesn't exist, look for the files in the plugin's own directory structure. The prompts, templates, and lib directories are bundled with this plugin.

2. Create .loop/.gitignore with runtime artifacts:

prd.json
progress.md
progress-archive.md
config.json
init.sh
contracts/
triage/
archive/
.archive-staging/
.last-branch
.loop.lock

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: Check for Existing Specs

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

If a spec is found:

"I found an existing spec at {path}. I'll use this as the basis for generating stories."

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:

What would you like to do?

a) Explore — Analyze the codebase to understand what exists, find issues, and document the system. No code changes. 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.

Based on the mode, ask 2-3 brief clarifying questions. Do NOT over-interview — keep it focused:

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?"

Step 3: Project Discovery

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

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:

{
  "tool": "claude",
  "mode": "<selected mode>",
  "maxIterations": <appropriate default>,
  "skipEval": false,
  "evalRetries": 2,
  "autoHooks": true,
  "branchPrefix": "loop/",
  "scopeBudgets": {
    // Set based on project size and mode
  }
}

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. Generating stories from {spec name / user description}..."

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.