@graypark/loophaus 2.0.0

package/skills/ralph-claude-cancel/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: ralph-claude-cancel
+description: "Cancel the active Loop in Claude Code"
+---
+
+# Cancel Loop (Claude Code)
+
+To cancel the loop:
+
+1. Check if `.loophaus/state.json` exists using Bash: `test -f .loophaus/state.json && echo "EXISTS" || echo "NOT_FOUND"`
+   - If not found, also check legacy path: `test -f .claude/ralph-loop.local.md && echo "LEGACY" || echo "NOT_FOUND"`
+
+2. **If NOT_FOUND** on both: Say "No active loop found."
+
+3. **If EXISTS** (.loophaus/state.json):
+   - Read `.loophaus/state.json` to get the current iteration number from `currentIteration`
+   - Remove the file using Bash: `rm .loophaus/state.json`
+   - Report: "Stopped loop at iteration N."
+
+4. **If LEGACY** (.claude/ralph-loop.local.md):
+   - Read `.claude/ralph-loop.local.md` to get the iteration number from the `iteration:` field
+   - Remove the file using Bash: `rm .claude/ralph-loop.local.md`
+   - Report: "Stopped loop at iteration N. (migrated from legacy path)"

package/skills/ralph-claude-interview/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: ralph-claude-interview
+description: "Claude Code interview that generates PRD, activates the official loop stop hook, and starts working immediately. Uses Skill tool for loop invocation."
+---
+
+# Loop Interview (Claude Code)
+
+You are an expert at generating PRD-driven Loop tasks for Claude Code.
+Interview the user, generate prd.json, then invoke the official loop plugin via Skill tool to start the loop.
+
+## Core Principles
+
+- **PRD-driven**: prd.json (ralph-skills compatible) tracks all stories
+- **progress.txt**: Append-only log with Codebase Patterns section
+- **One story per iteration**: Each loop cycle implements ONE story
+- **Self-contained stop hook**: Uses loophaus's own bash stop hook
+- **Skill tool invocation**: Start the loop via the Skill tool (`loophaus:ralph-loop`)
+
+## Interview Process
+
+Ask **concise questions** for missing items. Max 3-5 per round, one round only.
+
+| Category                  | What to confirm                                      |
+| ------------------------- | ---------------------------------------------------- |
+| **Scope**                 | Single feature? Multi-file? Full refactor?           |
+| **Success criteria**      | What counts as "done"?                               |
+| **Verification commands** | `npx tsc --noEmit`, `npm test`, `npm run lint`, etc. |
+| **References**            | Existing code, files, or patterns to follow?         |
+| **Priority**              | P1/P2 or other tiers?                                |
+| **Constraints**           | Must not break existing tests? Library restrictions? |
+| **When stuck**            | Document? Skip? Suggest alternative?                 |
+| **Parallelism potential** | Multiple services? Independent file groups?          |
+
+## Phase Design
+
+- **Research needed** → Phase 1: Analysis, Phase 2: Implementation
+- **8+ items** → Split by nature (P1/P2, frontend/backend)
+- **Dependencies** → Prerequisite work first
+- **5 or fewer** → Single phase fine
+
+### Parallelism (ralph-claude-orchestrator)
+
+| Factor                          | Score |
+| ------------------------------- | ----- |
+| Files span 3+ dirs              | +2    |
+| Items independent               | +2    |
+| Need full context               | -2    |
+| Order matters                   | -2    |
+| 10+ similar items               | +1    |
+| Cross-file understanding needed | -1    |
+| Multiple services               | +3    |
+
+Score >= 3: Use parallel Agent tool subagents in the prompt.
+
+### max-iterations
+
+| Task             | Iterations |
+| ---------------- | ---------- |
+| Research only    | 3-5        |
+| 1-3 simple fixes | 5-10       |
+| 4-7 medium items | 10-20      |
+| 8+ large items   | 20-30      |
+| TDD feature      | 15-30      |
+
+Formula: `story_count x 2 + 5`
+
+## PRD Format: prd.json
+
+ralph-skills compatible format:
+
+```json
+{
+  "project": "[Name]",
+  "description": "[Description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": ["Criterion 1", "Typecheck passes"],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+### Story Rules
+
+- Each story completable in ONE iteration
+- Dependencies ordered by priority (schema → backend → UI)
+- Acceptance criteria must be verifiable, not vague
+- Always include "Typecheck passes" or equivalent
+
+## Rules
+
+- No subjective criteria ("works well", "looks clean")
+- At least one automated verification check per prompt
+- Every prompt has a "When Stuck" section
+- Max 8 items per phase
+- Always use prd.json format
+- Default promise: COMPLETE
+- Always overwrite existing prd.json/progress.txt without asking
+
+## Conversation Flow
+
+```
+[User]      → /loop-plan "build X"
+[Assistant] → Interview questions (skip if enough context)
+[User]      → Answers
+[Assistant] → Shows PRD briefly, asks "Ready?"
+[User]      → "y"
+[Assistant] → Writes files + invokes loop via Skill tool
+```
+
+### Quick-Run
+
+If user includes "run immediately", "just do it", "바로 실행", "바로 시작", "--run":
+Skip "Ready?" prompt. Write files and invoke immediately.
+
+## Activation Sequence
+
+When user confirms, execute ALL steps in ONE response:
+
+### Step 1: Write prd.json via Bash
+
+Always overwrite. Do NOT ask about existing files.
+
+```bash
+cat > prd.json << 'EOF'
+{ ... generated PRD ... }
+EOF
+```
+
+### Step 2: Write progress.txt via Bash
+
+```bash
+cat > progress.txt << 'EOF'
+## Codebase Patterns
+(none yet)
+EOF
+```
+
+### Step 3: Invoke loop via Skill tool
+
+This is the critical step. You MUST use the Skill tool to start the loop:
+
+```
+Skill tool call:
+  skill: "loophaus:ralph-loop"
+  args: "Read prd.json for task plan. Read progress.txt for status (Codebase Patterns first). Pick highest priority story where passes is false. Implement that ONE story. Run verification: <VERIFY_CMD>. On failure: fix and retry, max 3. On success: commit 'feat: [Story ID] - [Title]'. Update prd.json passes to true. DISCOVERY PHASE: Review what you just built — did you find hidden complexity, missing edge cases, new dependencies, or broken assumptions? If YES: add new stories to prd.json (next sequential ID, passes: false), log discovery in progress.txt under Discoveries section, and increase maxIterations in .loophaus/state.json if needed (formula: current_iteration + remaining*2 + 3). If NO: just append learnings to progress.txt. If ALL stories (including new ones) pass: <promise>COMPLETE</promise>. When stuck: set notes in prd.json, skip to next." --max-iterations <N> --completion-promise "COMPLETE"
+```
+
+Replace `<VERIFY_CMD>` and `<N>` with actual values.
+
+### IMPORTANT: Actually invoke the Skill tool
+
+After writing prd.json and progress.txt, you MUST make a real Skill tool call.
+
+WRONG:
+
+- Printing the /loop command as text
+- Writing files and saying "ready"
+- Describing what would happen
+
+RIGHT:
+
+- Use the Skill tool with skill="loophaus:ralph-loop" and the generated args
+- This starts the loop — loophaus's stop hook takes over from there
+
+loophaus will:
+
+1. Run the setup script (creates `.loophaus/state.json`)
+2. Inject the prompt into the session
+3. You start working on US-001
+4. When you finish and try to exit, the stop hook re-injects the prompt
+5. You pick US-002, and so on until `<promise>COMPLETE</promise>`

package/skills/ralph-claude-loop/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: ralph-claude-loop
+description: "Start a PRD-driven Loop in Claude Code. Reads prd.json + progress.txt each iteration. Uses the official loop stop hook."
+---
+
+# Loop (Claude Code)
+
+Start a Loop optimized for Claude Code. This skill sets up the loop state, activates the official stop hook, and begins working on the first pending story from prd.json.
+
+## Prerequisites
+
+- The `loophaus` plugin must be installed
+- A `prd.json` file must exist in the project root (generate one with `/loop-plan`)
+
+## How It Works
+
+1. This skill writes `.loophaus/state.json` (the state file)
+2. loophaus's stop hook reads this file and intercepts session exits
+3. Each iteration follows the **Implement → Discover → Plan → Continue** cycle
+4. When all stories pass: output `<promise>COMPLETE</promise>`
+
+### Iteration Cycle (per story)
+
+```
+┌─ IMPLEMENT ─────────────────────────────┐
+│ Pick next story → implement → verify    │
+└─────────────────────┬───────────────────┘
+                      ▼
+┌─ DISCOVER ──────────────────────────────┐
+│ Review what you just built.             │
+│ Did you find:                           │
+│  - Hidden complexity?                   │
+│  - Missing edge cases?                  │
+│  - New dependencies?                    │
+│  - Broken assumptions from the PRD?     │
+└─────────────────────┬───────────────────┘
+                      ▼
+┌─ UPDATE PRD ────────────────────────────┐
+│ If discoveries found:                   │
+│  1. Add new stories to prd.json         │
+│  2. Log discoveries in progress.txt     │
+│  3. Adjust max_iterations if needed     │
+│ If nothing new: skip                    │
+└─────────────────────┬───────────────────┘
+                      ▼
+┌─ CONTINUE ──────────────────────────────┐
+│ Mark current story done → next story    │
+└─────────────────────────────────────────┘
+```
+
+## Activation
+
+Run the setup script to create the state file:
+
+```!
+mkdir -p .loophaus && cat > .loophaus/state.json << 'LOOP_STATE'
+{
+  "active": true,
+  "prompt": "Read prd.json for the task plan. Read progress.txt for current status (check Codebase Patterns section first). Pick the highest priority user story where passes is false. Implement that ONE story. Run verification: $VERIFY_CMD. On failure: read error, fix, retry up to 3 times. On success: commit with message feat: [Story ID] - [Story Title]. Update prd.json: set passes to true for the completed story. DISCOVERY PHASE — After completing the story, review what you just built: did implementation reveal hidden complexity not covered by existing stories? Are there missing edge cases, error handling, or integration points? Did you discover new dependencies or broken assumptions? Are there follow-up tasks needed for what you just built? If YES to any: add new user stories to prd.json with the next available ID (e.g. US-010), set passes: false, and set priority appropriately. Log the discovery in progress.txt under Discoveries section with rationale. If NO: skip, just append progress to progress.txt with learnings. If ALL stories (including newly added ones) have passes true, output <promise>COMPLETE</promise>. When stuck after 3 retries: set notes field in prd.json with error details, move to next story.",
+  "completionPromise": "COMPLETE",
+  "maxIterations": $MAX_ITERATIONS,
+  "currentIteration": 0,
+  "sessionId": ""
+}
+LOOP_STATE
+```
+
+Replace `$MAX_ITERATIONS` with the desired limit and `$VERIFY_CMD` with the project's verification command.
+
+After setup, immediately begin working:
+
+1. Read prd.json
+2. Pick the first story with `passes: false`
+3. Implement it — write real code, make real changes
+4. Run verification
+5. Commit
+6. **Discovery Phase** — review what you just built for hidden complexity, missing cases, new dependencies
+7. If discoveries found: add new stories to prd.json, log in progress.txt
+8. Update prd.json (mark current story done) and progress.txt
+9. The stop hook will re-inject this prompt for the next story
+
+### Discovery Phase Rules
+
+- New stories MUST follow the same format (id, title, description, acceptanceCriteria, priority, passes: false)
+- Use next sequential ID (if last is US-007, new ones start at US-008)
+- Set priority relative to remaining work (urgent discoveries get lower priority number)
+- Do NOT add trivial or cosmetic items — only genuinely missing functionality
+- Log each discovery in progress.txt: what was found, why it matters, which story revealed it
+- If adding stories increases scope significantly, update `maxIterations` in `.loophaus/state.json`
+
+### max_iterations Auto-Adjustment
+
+When adding N new stories, update maxIterations:
+
+```
+new_max = current_iteration + (remaining_stories + new_stories) * 2 + 3
+```
+
+Only increase, never decrease. Update the value in `.loophaus/state.json`.
+
+CRITICAL RULE: Only output `<promise>COMPLETE</promise>` when ALL stories in prd.json (including dynamically added ones) have `passes: true`. Do not output it prematurely.

package/skills/ralph-claude-orchestrator/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ralph-claude-orchestrator
+description: "Multi-agent orchestration patterns for Loop in Claude Code. Uses the Agent tool for parallel subagent spawning."
+---
+
+# Loop Orchestrator — Multi-Agent Patterns (Claude Code)
+
+Orchestration patterns optimized for Claude Code's Agent tool. Analyzes tasks and recommends the best combination of sequential loops and parallel subagents.
+
+## Subagent Configuration (Claude Code Agent Tool)
+
+```
+Agent tool parameters:
+- description: "short task description"
+- prompt: "detailed instructions"
+- subagent_type: "general-purpose" | "Explore" | "Plan" | "coder-fe" | "coder-be"
+- isolation: "worktree"  (gives agent an isolated repo copy)
+- run_in_background: true  (for parallel execution)
+```
+
+**Best practices:**
+
+- Use `subagent_type: "Explore"` for read-only scanning — faster and safer
+- Use `isolation: "worktree"` when agents write to files — prevents merge conflicts
+- Launch parallel agents in a single message with multiple Agent tool calls
+- Use `run_in_background: true` for truly independent work streams
+
+## Orchestration Patterns
+
+### Pattern 1: Parallel Explore then Sequential Implement
+
+Best for: Large codebases where you need to understand before you change.
+
+```
+Phase 1 (Parallel Subagents via Agent tool):
+├── Agent "fe-scan" (Explore, background): Scan src/frontend/** → .loophaus/reports/frontend.md
+├── Agent "be-scan" (Explore, background): Scan src/backend/** → .loophaus/reports/backend.md
+└── Agent "db-scan" (Explore, background): Scan src/db/** → .loophaus/reports/db.md
+
+Phase 2 (Loop):
+└── Read merged reports → implement fixes story by story via prd.json
+```
+
+### Pattern 2: Divide by Ownership
+
+Best for: Multi-service changes where files do not overlap.
+
+```
+Spawn agents with isolation: "worktree":
+├── Agent "fe-dev" (worktree): ONLY touch src/frontend/** → commit per item
+├── Agent "be-dev" (worktree): ONLY touch src/backend/** → commit per item
+└── Agent "auth-dev" (worktree): ONLY touch src/auth/** → commit per item
+
+After all complete: merge branches, run integration tests
+```
+
+### Pattern 3: Fan-Out / Fan-In Research
+
+Best for: Comprehensive analysis before any action.
+
+```
+Fan-Out (parallel Agent calls in single message):
+├── Agent "security" (Explore): Audit for OWASP top 10 → findings.md
+├── Agent "perf" (Explore): Profile and benchmark → findings.md
+└── Agent "a11y" (Explore): Check accessibility → findings.md
+
+Fan-In (Loop):
+└── Synthesize all findings → create action plan → implement
+```
+
+### Pattern 4: Scout-Then-Execute
+
+Best for: Unfamiliar codebases or risky changes.
+
+```
+Scout (single Agent, Explore type):
+└── Map codebase, trace dependencies, identify risks → scout-report.md
+
+Execute (Loop):
+└── Use scout report as reference, implement changes
+```
+
+### Pattern 5: Pipeline with Checkpoints
+
+Best for: Complex multi-stage transformations.
+
+```
+Stage 1 (Loop): Parse + validate → intermediate output
+  checkpoint: verify schema
+Stage 2 (Loop): Transform → draft output
+  checkpoint: run regression tests
+Stage 3 (Parallel Agents): Apply to multiple files
+  checkpoint: final integration test
+```
+
+## Decision Matrix
+
+| Factor                         | Score |
+| ------------------------------ | ----- |
+| Files span 3+ directories      | +2    |
+| Items are independent          | +2    |
+| Need full context to decide    | -2    |
+| Order matters                  | -2    |
+| 10+ similar items              | +1    |
+| Needs cross-file understanding | -1    |
+| Multiple services/repos        | +3    |
+
+- **Score >= 3**: Recommend parallel subagents
+- **Score 0-2**: Sequential loop, optional scout phase
+- **Score < 0**: Single sequential Loop
+
+## Report Convention
+
+```
+.loophaus/
+└── reports/
+    ├── {agent-name}.md       # Individual agent output
+    ├── merged.md             # Combined findings
+    └── plan.md               # Action plan
+```
+
+## Integration with Loop Interview
+
+When `/loop-plan` invokes this skill, provide:
+
+1. Recommended pattern
+2. Agent breakdown with roles and file boundaries
+3. Phase structure and checkpoints
+4. Ready-to-embed Agent tool call instructions for the loop prompt