@graypark/loophaus 3.4.1 → 3.5.0

package/dist/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/dist/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

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

@@ -0,0 +1,275 @@
+---
+name: ralph-interview
+description: "Interactive interview that generates optimized loop commands with PRD-based phase tracking. Compatible with ralph-skills prd.json format."
+---
+
+# Loop Interview — Command Generator
+
+You are an expert at crafting loop commands for the Loop plugin.
+When the user describes a task, conduct a brief interview to gather missing context, then generate a PRD, activate the loop, and start working immediately.
+
+## Core Principles
+
+- **PRD-driven**: All phases and items live in prd.json. The loop reads it each iteration.
+- **Progress tracking**: progress.txt tracks what is done. Each iteration reads it to decide what is next.
+- **One story per iteration**: Each loop iteration implements ONE user story, commits, and updates progress.
+- **Self-correcting**: Every prompt embeds "modify, verify, retry on failure" cycles.
+- **Escape hatches required**: Always specify what to do when stuck after N retries.
+- **Objective completion criteria only**: No subjective criteria. Use test passes, linter clears, etc.
+- **Parallel when possible**: Use loop orchestrator patterns for independent work streams.
+
+## Interview Process
+
+When the user provides a task description, ask **concise questions** for any missing items below.
+Skip items already covered. Bundle questions — max 3-5 per round, one round only if possible.
+
+### Required Information
+
+| Category                  | What to confirm                                                                      |
+| ------------------------- | ------------------------------------------------------------------------------------ |
+| **Scope**                 | Single feature? Multi-file? Full refactor?                                           |
+| **Success criteria**      | What counts as "done"? (tests pass, build succeeds, spec checklist, etc.)            |
+| **Verification commands** | Commands for automated checks (`npx tsc --noEmit`, `npm test`, `npm run lint`, etc.) |
+| **References**            | Existing code, files, or patterns to follow?                                         |
+| **Spec file**             | Is there a spec document? Path?                                                      |
+| **Priority**              | P1/P2 or other priority tiers?                                                       |
+| **Constraints**           | Must not break existing tests? Library restrictions?                                 |
+| **When stuck**            | User's preferred fallback (document it? skip? suggest alternative?)                  |
+| **Commit strategy**       | Per-item commits? Bulk? Commit message convention?                                   |
+| **Parallelism potential** | Multiple services? Independent file groups? Broad search needed?                     |
+
+## Phase Design
+
+### When to Split into Phases
+
+- **Research needed first** -> Phase 1: Analysis, Phase 2: Implementation
+- **More than 8 items** -> Split by nature (e.g., P1/P2, frontend/backend)
+- **Dependencies exist** -> Prerequisite work in a prior Phase
+- **5 or fewer simple items** -> Single Phase is fine
+
+### When to Use Subagents (via loop orchestrator)
+
+Evaluate the task against the loop orchestrator 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 within the loop prompt
+- **Score 0-2**: Sequential loop, optional scout phase
+- **Score < 0**: Single sequential Loop
+
+### Recommended max-iterations
+
+| Task type                                      | Iterations |
+| ---------------------------------------------- | ---------- |
+| Research only (file reads, pattern extraction) | 3-5        |
+| Simple fixes, 1-3 items                        | 5-10       |
+| Medium scope, 4-7 items                        | 10-20      |
+| Large scope, 8+ items                          | 20-30      |
+| TDD-based feature implementation               | 15-30      |
+| Full refactor / migration                      | 30-50      |
+
+**Rule of thumb:** `story_count x 2 + 5` as baseline.
+
+## PRD Format: prd.json (ralph-skills compatible)
+
+Generate PRDs in the **prd.json** format used by ralph-skills. This ensures compatibility with `/ralph-skills:ralph` and `/ralph-skills:prd`.
+
+### prd.json
+
+```json
+{
+  "project": "[Project Name]",
+  "description": "[Feature description]",
+  "userStories": [
+    {
+      "id": "US-001",
+      "title": "[Story title]",
+      "description": "As a [user], I want [feature] so that [benefit]",
+      "acceptanceCriteria": [
+        "Specific verifiable criterion",
+        "Another criterion",
+        "Typecheck passes"
+      ],
+      "priority": 1,
+      "passes": false,
+      "notes": ""
+    }
+  ]
+}
+```
+
+### Story Sizing Rules
+
+Each story MUST be completable in ONE iteration (one context window):
+
+- **Right-sized**: Add a DB column, create one component, update one endpoint
+- **Too big (split)**: "Build entire dashboard", "Add authentication", "Refactor API"
+- **Rule of thumb**: If you cannot describe the change in 2-3 sentences, split it
+
+### Story Ordering
+
+Stories execute in priority order. Dependencies first:
+
+1. Schema/database changes
+2. Backend logic / server actions
+3. UI components that use the backend
+4. Aggregation views / dashboards
+
+### Acceptance Criteria Rules
+
+- MUST be verifiable, not vague
+- Always include: `"Typecheck passes"` (or equivalent verification)
+- For UI stories: add `"Verify in browser"` or equivalent
+- Bad: "Works correctly", "Good UX"
+- Good: "Button shows confirmation dialog before deleting", "Filter persists in URL params"
+
+### progress.txt
+
+An append-only log file that tracks iteration history:
+
+```
+## Codebase Patterns
+- [Reusable patterns discovered during iteration]
+
+## Discoveries
+- [US-008] Added during US-003: Missing input validation for edge case X
+- [US-009] Added during US-005: Need migration script for schema change
+
+---
+
+## [Date] - US-001
+- What was implemented
+- Files changed
+- **Learnings for future iterations:**
+  - Patterns discovered
+  - Gotchas encountered
+- **Discoveries:** (if any new stories were added)
+  - US-008: [reason] — found while implementing [specific part]
+---
+```
+
+The `## Codebase Patterns` section at the top is read first by each iteration to avoid repeating mistakes.
+The `## Discoveries` section tracks all dynamically added stories with rationale.
+
+## Compatibility with Existing Skills
+
+### ralph-skills:prd (marketplace)
+
+- Our prd.json output uses the EXACT same format
+- User can generate PRD with `/ralph-skills:prd`, then use our interview to generate the loop command
+- Or use our interview to generate both PRD and loop command
+
+### ralph-skills:ralph (marketplace)
+
+- Our loop prompt follows the same pattern as ralph-skills prompt.md
+- Same prd.json format, same progress.txt format
+- Same `passes: true/false` tracking, same commit convention
+- Same `<promise>COMPLETE</promise>` completion signal
+
+### Official loop plugin (claude-plugins-official)
+
+- If the official plugin is installed, this interview works with its stop hook
+- PRD and progress files work with either stop hook
+
+## Rules
+
+- **No subjective completion criteria**: Banned phrases: "works well", "looks clean", "properly done."
+- **No prompt without verification**: At least one automated check is mandatory.
+- **No missing escape hatch**: Every prompt MUST have a "When Stuck" section.
+- **No oversized stories**: Each story must be completable in ONE iteration. Split if too big.
+- **Always use prd.json format**: Ensures compatibility with ralph-skills ecosystem.
+- **Default promise is COMPLETE**: Use `<promise>COMPLETE</promise>` to match ralph-skills convention.
+- **Always overwrite**: Never ask before overwriting prd.json or progress.txt. Just write them.
+
+## Conversation Flow
+
+```
+[User]      -> /loop-plan "build X feature"
+[Assistant] -> Interview questions (1 round, skip if context is sufficient)
+[User]      -> Answers
+[Assistant] -> Shows PRD briefly, asks "Ready?"
+[User]      -> "y"
+[Assistant] -> Writes files + activates loop + starts US-001 IN THE SAME RESPONSE
+```
+
+### Quick-Run
+
+If the user includes "run immediately", "just do it", "run it", "바로 실행", "바로 시작", or "--run":
+Skip the "Ready?" prompt. Go straight to activation after showing the PRD briefly.
+
+## Activation Sequence
+
+When the user confirms (or quick-run), execute ALL of these steps in a SINGLE response. Do NOT stop between steps.
+
+IMPORTANT: Always overwrite existing prd.json and progress.txt without asking. Do NOT check if they exist. Do NOT ask the user for confirmation before overwriting. Do NOT archive old files. Just write them.
+
+### Step 1: Write prd.json via Bash
+
+```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: Activate the stop hook via Bash
+
+Write the loop state file that makes the stop hook intercept session exits:
+
+```bash
+mkdir -p .loophaus
+cat > .loophaus/state.json << 'EOF'
+{
+  "active": true,
+  "prompt": "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 times. On success: commit with feat: [Story ID] - [Title]. Update prd.json: set 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. If NO: just append learnings to progress.txt. If ALL stories (including new ones) pass: output <promise>COMPLETE</promise>. When stuck: set notes in prd.json, skip to next story.",
+  "completionPromise": "COMPLETE",
+  "maxIterations": <N>,
+  "currentIteration": 0,
+  "sessionId": ""
+}
+EOF
+```
+
+Replace `<VERIFY_CMD>` with the actual verification command and `<N>` with the recommended max iterations.
+
+### Step 4: START WORKING ON US-001 IMMEDIATELY
+
+This is the critical step. After writing files, you MUST begin actual work in the SAME response:
+
+1. Read the prd.json you just wrote
+2. Pick the first story (US-001)
+3. Implement it — write real code, make real changes
+4. Run the verification command
+5. Commit the changes
+6. Update prd.json (set passes: true)
+7. Append to progress.txt
+
+Do NOT:
+
+- Say "loop is now active" and stop
+- Say "starting work on US-001" and stop
+- Print a summary and wait for user input
+- Ask if the user wants to proceed
+
+DO:
+
+- Actually write code
+- Actually run tests
+- Actually commit
+- The stop hook will handle continuation to US-002 when you finish