feat(ralph): add Ralph Loop plugin

[baleen37]

Summary

Ralph Loop 플러그인을 추가합니다. PRD 기반 영속 루프 — Claude의 Stop 이벤트를 가로채서 모든 유저 스토리가 통과할 때까지 Claude가 계속 작업하도록 합니다.

Changes

• plugins/ralph/.claude-plugin/plugin.json — 플러그인 메타데이터
• plugins/ralph/hooks/hooks.json — Stop 이벤트에 ralph-persist.ts 등록
• plugins/ralph/hooks/ralph-persist.ts — Stop 훅 엔진 (Bun TypeScript): state 읽기 → block 또는 allow 결정
• plugins/ralph/skills/ralph/SKILL.md — Claude 프로토콜: PRD 작성 → 스토리 실행 → 검증 → cancel signal
• .claude-plugin/marketplace.json — ralph 플러그인 등록
• tests/ralph_hooks_json.bats — hooks.json 검증 테스트 (3개)
• tests/ralph_persist.bats — ralph-persist.ts 유닛 + 플로우 테스트 (10개)
• docs/superpowers/specs/2026-03-23-ralph-plugin-design.md — 설계 스펙
• docs/superpowers/plans/2026-03-23-ralph-plugin.md — 구현 플랜

Tests

• bats tests/ — 63/63 통과
• E2E 검증: no-state → allow, activation sentinel → block, active loop → block + iterate, cancel signal → allow
• ralph 플러그인 파일에 대한 pre-commit hooks 통과

Breaking

없음.

Summary by CodeRabbit

• New Features
  • Added Ralph plugin for automated task execution with persistent state management across sessions
  • Enables iterative product requirement document generation and story-based workflow automation
  • Includes built-in progress tracking, verification steps, and cancellation support

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 941a6d34-a865-4966-b848-9fefa44d43ab

📥 Commits

Reviewing files that changed from the base of the PR and between 750aa51 and b93844f.

📒 Files selected for processing (9)

• .claude-plugin/marketplace.json
• docs/superpowers/plans/2026-03-23-ralph-plugin.md
• docs/superpowers/specs/2026-03-23-ralph-plugin-design.md
• plugins/ralph/.claude-plugin/plugin.json
• plugins/ralph/hooks/hooks.json
• plugins/ralph/hooks/ralph-persist.ts
• plugins/ralph/skills/ralph/SKILL.md
• tests/ralph_hooks_json.bats
• tests/ralph_persist.bats

---

📝 Walkthrough

Walkthrough

Adds a new standalone "ralph" Claude plugin that registers in the marketplace, provides a Bun-based Stop-hook executable to persist and control an iterative loop via .ralph/state/, includes skill and design docs, and supplies Bats tests validating hook configuration and runtime behavior.

Changes

Cohort / File(s)	Summary
Marketplace & Manifest .claude-plugin/marketplace.json, plugins/ralph/.claude-plugin/plugin.json	New marketplace entry and plugin manifest for ralph (version 1.0.0, category: development, tags/keywords).
Hook config & runtime plugins/ralph/hooks/hooks.json, plugins/ralph/hooks/ralph-persist.ts	Registers a Stop hook that runs bun run "${CLAUDE_PLUGIN_ROOT}/hooks/ralph-persist.ts" (timeout 10s). The script reads stdin JSON, manages .ralph/state/ files and sentinels, decides block vs allow, increments iterations, extends max_iterations, handles activation and cancel-signal, and treats stale state (>2h) as inactive.
Skill, spec & plan docs plugins/ralph/skills/ralph/SKILL.md, docs/superpowers/specs/2026-03-23-ralph-plugin-design.md, docs/superpowers/plans/2026-03-23-ralph-plugin.md	Adds the Ralph skill doc, design spec, and implementation plan describing state layout, Stop-hook contract, activation/loop/completion protocol, required files (prd.json, progress.txt, state files), and test scenarios.
Tests tests/ralph_hooks_json.bats, tests/ralph_persist.bats	Bats tests validating hooks.json structure and placeholder, and comprehensive runtime tests for ralph-persist.ts: pass-through cases, activation sentinel, cancel-signal behavior, stale handling, iteration increments, and max_iterations extension.

Sequence Diagram

sequenceDiagram
    participant Claude as Claude IDE
    participant HookEngine as Hook Engine
    participant Script as ralph-persist.ts
    participant FS as File System

    Claude->>HookEngine: Trigger Stop event
    HookEngine->>Script: Execute with JSON (session_id, cwd)
    Script->>FS: Inspect .ralph/state/ (state file, sentinels)
    alt activating sentinel present (no state)
        Script->>FS: Read sentinel, init ralph-state.json, delete sentinel
        Script-->>HookEngine: Write {"decision":"block", "reason": ...}
    else state missing/inactive or session mismatch
        Script-->>HookEngine: No output (allow stop)
    else state active & session matches
        Script->>FS: Check last_checked_at (stale >2h?)
        alt stale
            Script->>FS: Mark inactive, persist
            Script-->>HookEngine: No output (allow stop)
        else fresh
            Script->>FS: Check cancel-signal-state.json
            alt cancel signal exists
                Script->>FS: Delete cancel-signal, mark inactive, persist
                Script-->>HookEngine: No output (allow stop)
            else
                Script->>FS: Increment iteration, maybe extend max_iterations, persist
                Script-->>HookEngine: Write {"decision":"block", "reason": ...}
            end
        end
    end
    HookEngine-->>Claude: Decision (block or allow)

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 In burrows of code I quietly dwell,
A loop named Ralph keeps stories well,
Sentinels blink, iterations hum,
Cancel-signal knocks and freedom comes,
I nibble state and cheer, "Persist, then quell!"

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/ralph-plugin

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}