feat: agent loop harness with Claude Code plugin support
Generator-evaluator architecture with iterative context-reset for long-running coding tasks. Ships as a Claude Code plugin — install with /plugin and use /agent-loop:init, /agent-loop:plan, /agent-loop:run.
This commit is contained in:
141
skills/loop-init/SKILL.md
Normal file
141
skills/loop-init/SKILL.md
Normal file
@@ -0,0 +1,141 @@
|
||||
---
|
||||
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.
|
||||
---
|
||||
|
||||
# /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:
|
||||
|
||||
```bash
|
||||
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:
|
||||
|
||||
```json
|
||||
{
|
||||
"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`.
|
||||
Reference in New Issue
Block a user