@graypark/loophaus 2.0.0

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

package/skills/ralph-orchestrator/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: ralph-orchestrator
+description: "Orchestration patterns for loop: subagent spawning, parallel exploration, and task decomposition strategies"
+---
+
+# Loop Orchestrator — Multi-Agent Loop Patterns
+
+You are an expert at designing optimal execution strategies for Loop tasks.
+When asked to orchestrate a task, analyze its structure and recommend the best combination of sequential loops, parallel subagents, and phased execution.
+
+## Core Concept
+
+Not every task should run in a single linear loop. Complex tasks benefit from:
+
+- **Parallel exploration** — spawn subagents to search/analyze independently, then merge results
+- **Divide and conquer** — split work by service/directory/concern with isolated agents
+- **Pipeline stages** — sequential phases where each feeds into the next
+- **Hybrid patterns** — combine parallel research with sequential implementation
+
+## When to Use Subagents
+
+### Use Subagents (Parallel) When:
+
+| Signal                      | Example                                                    |
+| --------------------------- | ---------------------------------------------------------- |
+| **Broad codebase search**   | "Find all API endpoints that lack auth checks"             |
+| **Independent file groups** | Frontend components + backend routes + database migrations |
+| **Multi-service changes**   | auth-service + api-gateway + frontend simultaneously       |
+| **Audit/review tasks**      | Security audit + performance audit + accessibility audit   |
+| **Pattern extraction**      | Scan 50+ files for inconsistent patterns                   |
+
+### Do NOT Use Subagents When:
+
+| Signal                      | Reason                                               |
+| --------------------------- | ---------------------------------------------------- |
+| **Sequential dependencies** | Step 2 needs Step 1's output                         |
+| **Shared mutable state**    | Multiple agents editing the same file = conflicts    |
+| **Small scope (< 5 files)** | Overhead outweighs benefit                           |
+| **Context-heavy tasks**     | Agent needs deep understanding of full codebase flow |
+
+## Orchestration Patterns
+
+### Pattern 1: Parallel Explore → Sequential Implement
+
+Best for: Large codebases where you need to understand before you change.
+
+```
+Phase 1 (Parallel Subagents):
+├── Agent A: Scan src/frontend/** for pattern X → report-frontend.md
+├── Agent B: Scan src/backend/** for pattern X → report-backend.md
+└── Agent C: Scan src/shared/** for pattern X → report-shared.md
+
+Phase 2 (Sequential Loop):
+└── Loop: Read all reports → implement fixes in priority order
+```
+
+**Prompt pattern for Phase 1:**
+
+```
+## Subagent Tasks (run in parallel)
+Use the Agent tool to spawn these subagents simultaneously:
+
+1. Agent "frontend-scan": Search src/frontend/** for [pattern].
+   Write findings to .loophaus/reports/frontend-scan.md
+2. Agent "backend-scan": Search src/backend/** for [pattern].
+   Write findings to .loophaus/reports/backend-scan.md
+3. Agent "shared-scan": Search src/shared/** for [pattern].
+   Write findings to .loophaus/reports/shared-scan.md
+
+After ALL agents complete, merge reports into .loophaus/reports/merged.md
+with a unified priority list.
+```
+
+### Pattern 2: Divide by Ownership
+
+Best for: Multi-service changes where files don't overlap.
+
+```
+Phase 1 (Parallel Implementation):
+├── Agent "fe-dev": Modify src/frontend/** only → commit per item
+├── Agent "be-dev": Modify src/backend/** only → commit per item
+└── Agent "auth-dev": Modify src/auth/** only → commit per item
+
+Phase 2 (Integration Verification):
+└── Loop: Run full test suite, fix any integration issues
+```
+
+**Prompt pattern:**
+
+```
+## Parallel Work Streams
+Spawn these agents with strict file ownership:
+
+1. Agent "fe-dev" (isolation: worktree):
+   - ONLY touch files in src/frontend/**
+   - Tasks: [frontend items]
+   - Commit each fix individually
+
+2. Agent "be-dev" (isolation: worktree):
+   - ONLY touch files in src/backend/**
+   - Tasks: [backend items]
+   - Commit each fix individually
+
+After all agents complete, merge their branches and run integration tests.
+```
+
+### Pattern 3: Fan-Out / Fan-In Research
+
+Best for: Tasks that need comprehensive analysis before any action.
+
+```
+Fan-Out (Parallel):
+├── Agent 1: Analyze problem from angle A → findings-a.md
+├── Agent 2: Analyze problem from angle B → findings-b.md
+└── Agent 3: Analyze problem from angle C → findings-c.md
+
+Fan-In (Sequential):
+└── Loop: Synthesize all findings → create action plan → implement
+```
+
+### Pattern 4: Pipeline with Checkpoints
+
+Best for: Complex multi-stage transformations.
+
+```
+Stage 1 (Loop): Parse + validate input → intermediate.json
+  ↓ checkpoint: verify intermediate.json schema
+Stage 2 (Loop): Transform data → output draft
+  ↓ checkpoint: run regression tests
+Stage 3 (Parallel Agents): Apply fixes to multiple output files
+  ↓ checkpoint: final integration test
+```
+
+### Pattern 5: Scout-Then-Execute
+
+Best for: Unfamiliar codebases or risky changes.
+
+```
+Scout Phase (Single Agent, read-only):
+└── Agent "scout": Explore codebase, map dependencies, identify risks
+    → .loophaus/reports/scout-report.md
+
+Execute Phase (Loop):
+└── Loop: Use scout report as reference, implement changes
+```
+
+## Subagent Configuration Reference
+
+### Codex CLI (experimental)
+
+Codex spawns subagents via natural language prompts with keywords: "spawn", "parallel", "delegate", "one agent per".
+
+```
+# Enable in ~/.codex/config.toml
+[agents]
+max_threads = 6          # Max concurrent agent threads (default: 6)
+max_depth = 1            # No grandchild agents (default: 1)
+```
+
+**Custom agent definitions** in `.codex/agents/` (TOML):
+
+```toml
+# .codex/agents/scanner.toml
+name = "scanner"
+description = "Read-only codebase explorer for pattern extraction"
+model = "gpt-5.4-mini"          # Faster model for exploration
+model_reasoning_effort = "low"
+sandbox_mode = "read-only"
+developer_instructions = """
+Scan files for the requested pattern. Report findings with file paths and line numbers.
+Do NOT modify any files.
+"""
+```
+
+**Spawning in prompts:**
+
+```
+"Spawn one agent per service directory to scan for auth issues:
+ 1. scanner on src/frontend/** → .loophaus/reports/frontend.md
+ 2. scanner on src/backend/** → .loophaus/reports/backend.md
+ 3. scanner on src/auth/** → .loophaus/reports/auth.md
+ Wait for all, then summarize findings by severity."
+```
+
+**Batch processing** with `spawn_agents_on_csv`:
+
+```
+# For 100+ similar items, use CSV-driven batch spawning:
+spawn_agents_on_csv:
+  csv_path: .loophaus/items.csv
+  instruction: "Review {file_path} for {issue_type}. Return JSON via report_agent_job_result"
+  output_schema: { file: string, severity: string, fix: string }
+  output_csv_path: .loophaus/reports/batch-results.csv
+  max_concurrency: 6
+```
+
+### Model Selection Guide (Codex)
+
+| Role                    | Recommended Model   | Reasoning Effort |
+| ----------------------- | ------------------- | ---------------- |
+| Coordinator / main loop | gpt-5.4             | medium           |
+| Explorer / scanner      | gpt-5.4-mini        | low              |
+| Reviewer / security     | gpt-5.4             | high             |
+| Quick iteration / TDD   | gpt-5.3-codex-spark | medium           |
+
+### Key Constraints
+
+| Setting              | Default | Note                                                                    |
+| -------------------- | ------- | ----------------------------------------------------------------------- |
+| `agents.max_threads` | 6       | Hard cap on concurrent agents                                           |
+| `agents.max_depth`   | 1       | No recursive agent spawning                                             |
+| File conflicts       | N/A     | Multiple agents writing same file = conflicts. Use ownership isolation. |
+| Token usage          | Higher  | Each subagent does own inference. Use faster models for workers.        |
+
+## Report Directory Convention
+
+All subagent outputs should follow this structure:
+
+```
+.loophaus/
+└── reports/
+    ├── {agent-name}.md       # Individual agent output
+    ├── merged.md             # Combined findings (created by orchestrator)
+    └── plan.md               # Action plan derived from findings
+```
+
+This directory should be in `.gitignore` — reports are ephemeral working artifacts.
+
+## Decision Matrix
+
+When analyzing a task, use this scoring to decide the orchestration pattern:
+
+| Factor                         | Score | Pattern             |
+| ------------------------------ | ----- | ------------------- |
+| Files span 3+ directories      | +2    | Parallel            |
+| Items are independent          | +2    | Parallel            |
+| Need full context to decide    | -2    | Sequential          |
+| Order matters                  | -2    | Sequential          |
+| 10+ similar items              | +1    | Parallel            |
+| Needs cross-file understanding | -1    | Sequential          |
+| Multiple services/repos        | +3    | Divide by Ownership |
+
+- **Score >= 3**: Recommend parallel subagents
+- **Score 0–2**: Recommend sequential with optional scout phase
+- **Score < 0**: Recommend single sequential Loop
+
+## Integration with Loop Interview
+
+When `/loop-plan` invokes this skill, provide:
+
+1. **Recommended pattern** — which orchestration pattern fits best
+2. **Agent breakdown** — list of subagents with their roles and file boundaries
+3. **Phase structure** — how phases connect and what checkpoints exist
+4. **Prompt snippets** — ready-to-embed subagent instructions for the loop prompt

package/store/state-store.mjs

@@ -0,0 +1,80 @@
+import { readFile, writeFile, mkdir, rename } from "node:fs/promises";
+import { join, dirname } from "node:path";
+
+const DEFAULT_STATE = {
+  active: false,
+  prompt: "",
+  completionPromise: "TADA",
+  maxIterations: 20,
+  currentIteration: 0,
+  sessionId: "",
+};
+
+export function getStatePath(cwd) {
+  if (process.env.LOOPHAUS_STATE_FILE) return process.env.LOOPHAUS_STATE_FILE;
+  if (process.env.RALPH_STATE_FILE) return process.env.RALPH_STATE_FILE;
+  return join(cwd || process.cwd(), ".loophaus", "state.json");
+}
+
+const LEGACY_PATHS = [
+  (cwd) => join(cwd, ".codex", "ralph-loop.state.json"),
+  (cwd) => join(cwd, ".claude", "ralph-loop.local.md"),
+];
+
+export async function read(cwd) {
+  const primary = getStatePath(cwd);
+
+  try {
+    const raw = await readFile(primary, "utf-8");
+    return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+  } catch {
+    // Primary not found, try legacy paths
+  }
+
+  const dir = cwd || process.cwd();
+  for (const pathFn of LEGACY_PATHS) {
+    const legacyPath = pathFn(dir);
+    try {
+      const raw = await readFile(legacyPath, "utf-8");
+      if (legacyPath.endsWith(".md")) {
+        return migrateMdFormat(raw);
+      }
+      return { ...DEFAULT_STATE, ...JSON.parse(raw) };
+    } catch {
+      continue;
+    }
+  }
+
+  return { ...DEFAULT_STATE };
+}
+
+export async function write(state, cwd) {
+  const statePath = getStatePath(cwd);
+  await mkdir(dirname(statePath), { recursive: true });
+  const tmp = statePath + ".tmp";
+  await writeFile(tmp, JSON.stringify(state, null, 2), "utf-8");
+  await rename(tmp, statePath);
+}
+
+export async function reset(cwd) {
+  await write({ ...DEFAULT_STATE }, cwd);
+}
+
+function migrateMdFormat(raw) {
+  const state = { ...DEFAULT_STATE };
+  const lines = raw.split("\n");
+  for (const line of lines) {
+    const match = line.match(/^(\w+):\s*(.+)$/);
+    if (!match) continue;
+    const [, key, value] = match;
+    if (key === "active") state.active = value.trim() === "true";
+    else if (key === "iteration") state.currentIteration = parseInt(value.trim(), 10) || 0;
+    else if (key === "max_iterations") state.maxIterations = parseInt(value.trim(), 10) || 20;
+    else if (key === "completion_promise") state.completionPromise = value.trim();
+    else if (key === "prompt") state.prompt = value.trim();
+    else if (key === "session_id") state.sessionId = value.trim();
+  }
+  return state;
+}
+
+export { DEFAULT_STATE };