fix: tighten skill specs — exact prd.json schema, explicit scaffold, validation
This commit is contained in:
@@ -7,40 +7,53 @@ description: "Setup task: scaffold .loop/ directory and generate config for the
|
||||
|
||||
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
|
||||
**IMPORTANT:** Do NOT invoke brainstorming, planning, or idea-generation skills. This skill handles its own flow.
|
||||
|
||||
## Instructions
|
||||
|
||||
When the user invokes this skill, follow this sequence:
|
||||
Follow these steps exactly. Do not skip or reorder them.
|
||||
|
||||
### Step 0: Scaffold .loop/ Directory
|
||||
### Step 1: Scaffold .loop/ Directory
|
||||
|
||||
Check if `.loop/` already exists in the project root.
|
||||
|
||||
**If it does NOT exist**, create it by copying from the plugin:
|
||||
**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.
|
||||
|
||||
1. The plugin's root directory is available at `${CLAUDE_PLUGIN_ROOT}`. Copy the harness files:
|
||||
**Create `.loop/` and copy ALL required harness files.** Run these commands exactly:
|
||||
|
||||
```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.
|
||||
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)
|
||||
|
||||
2. Create `.loop/.gitignore` with runtime artifacts:
|
||||
Copy ALL of these directories and files — every one is required:
|
||||
|
||||
```bash
|
||||
# Find the harness source (plugin cache)
|
||||
HARNESS_SRC=$(ls -d ~/.claude/plugins/cache/agent-loop/agent-loop/*/prompts/.. 2>/dev/null | head -1)
|
||||
|
||||
if [ -n "$HARNESS_SRC" ]; then
|
||||
cp -r "$HARNESS_SRC/prompts" .loop/
|
||||
cp -r "$HARNESS_SRC/templates" .loop/
|
||||
cp -r "$HARNESS_SRC/lib" .loop/
|
||||
cp "$HARNESS_SRC/loop.sh" .loop/
|
||||
chmod +x .loop/loop.sh
|
||||
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`
|
||||
|
||||
If any are missing, tell the user the scaffold failed and show which files are missing.
|
||||
|
||||
Create `.loop/.gitignore`:
|
||||
|
||||
```
|
||||
prd.json
|
||||
@@ -56,74 +69,78 @@ archive/
|
||||
.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 2: Check for Existing Specs
|
||||
|
||||
### Step 1: Check for Existing Specs
|
||||
|
||||
Search for existing design documents or specs in the project:
|
||||
Search for existing design documents or specs:
|
||||
- `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**).
|
||||
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 2.
|
||||
**If no spec is found**, proceed to Step 3.
|
||||
|
||||
### Step 2: Mode Selection and Description
|
||||
### Step 3: 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.
|
||||
> 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.
|
||||
|
||||
Based on the mode, ask 2-3 brief clarifying questions. Do NOT over-interview — keep it focused:
|
||||
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?"
|
||||
|
||||
**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]."
|
||||
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` based on the project:
|
||||
Create `.loop/config.json` with this EXACT structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"tool": "claude",
|
||||
"mode": "<selected mode>",
|
||||
"maxIterations": <appropriate default>,
|
||||
"mode": "<implement|explore|fix>",
|
||||
"maxIterations": 20,
|
||||
"skipEval": false,
|
||||
"evalRetries": 2,
|
||||
"autoHooks": true,
|
||||
"branchPrefix": "loop/",
|
||||
"scopeBudgets": {
|
||||
// Set based on project size and mode
|
||||
"explore": {
|
||||
"maxFilesToRead": 15,
|
||||
"maxLinesToWrite": 0,
|
||||
"maxFilesToModify": 0
|
||||
},
|
||||
"implement": {
|
||||
"maxFilesToRead": 50,
|
||||
"maxLinesToWrite": 500,
|
||||
"maxFilesToModify": 10
|
||||
},
|
||||
"fix": {
|
||||
"maxFilesToRead": 30,
|
||||
"maxLinesToWrite": 200,
|
||||
"maxFilesToModify": 5
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Create `.loop/init.sh` with project-specific setup commands (dev server, test runner, linter, etc.). Make it executable.
|
||||
Adjust `maxIterations` based on estimated story count (stories + 30% for rejections).
|
||||
|
||||
Create `.loop/init.sh` with project-specific setup commands. Make it executable.
|
||||
|
||||
### Step 5: Flow into Planning
|
||||
|
||||
Tell the user:
|
||||
> "Project configured. Generating stories from {spec name / user description}..."
|
||||
Say:
|
||||
> "Project configured. Generating stories..."
|
||||
|
||||
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.
|
||||
Then invoke `/agent-loop:plan`. If a spec was found in Step 2, tell the plan skill to use it.
|
||||
|
||||
Reference in New Issue
Block a user