loop-loop/skills/loop-init/SKILL.md

name, description

name	description
init	Initialize the agent loop harness in the current project. Scaffolds .loop/ directory, detects tech stack, picks mode, generates config, and flows into planning.

/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.

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

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: 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]. The main source is in [dir/]."

Step 2: Mode Selection

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.

Step 3: Clarifying Questions

Based on the mode, ask 3-5 questions:

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

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

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

Step 4: Generate Configuration

Create .loop/config.json based on the project and user's answers:

{
  "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 startup (if applicable)
• Test runner command
• Type checker command
• Linter command
• Any environment setup needed

Make init.sh executable.

Step 5: Flow into Planning

Tell the user:

"Project configured. Now let's plan the work."

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.