@hivehub/rulebook 5.5.1 → 5.7.0

package/.claude/commands/ralph-config.md

@@ -1,112 +0,0 @@
----
-name: /ralph-config
-id: ralph-config
-category: Ralph
-description: Configure Ralph autonomous loop settings and parameters.
----
-<!-- RALPH:START -->
-**Overview**
-Manage Ralph's configuration including max iterations, AI tool selection, and other loop parameters. Configuration is stored in `.rulebook/ralph/config.json`.
-
-**Guardrails**
-- Configuration applies to future iterations only
-- Changing config mid-loop may not affect current iteration
-- Save configuration changes before resuming loop
-- Common settings: max_iterations, ai_tool, branch_name
-
-**Configuration Options**
-
-### Max Iterations
-Maximum number of iterations Ralph will run before stopping.
-```bash
-rulebook ralph config set max_iterations 20
-```
-- Recommended: 5-20 for most projects
-- Higher values allow more complex tasks to complete
-- Lower values quick validation runs
-
-### AI Tool
-Which AI tool to use for solving tasks (claude, cursor, gemini).
-```bash
-rulebook ralph config set ai_tool claude
-```
-- `claude` (recommended): Best for complex reasoning
-- `cursor`: Fast iteration if you have Cursor CLI
-- `gemini`: Alternative option for diversity
-- Note: Tool must be installed and available on CLI
-
-### Branch Name
-Git branch Ralph works on for this loop.
-```bash
-rulebook ralph config set branch_name ralph/my-feature
-```
-- Automatically set during init
-- Change if working on different feature
-- Ralph commits to this branch
-
-### Project Name
-Project name for documentation and tracking.
-```bash
-rulebook ralph config set project_name my-project
-```
-
-**Steps**
-
-1. **View Current Configuration**:
-   ```bash
-   rulebook ralph config show
-   ```
-   Displays all current settings
-
-2. **Update a Setting**:
-   ```bash
-   rulebook ralph config set <key> <value>
-   ```
-   Example:
-   ```bash
-   rulebook ralph config set max_iterations 15
-   rulebook ralph config set ai_tool cursor
-   ```
-
-3. **Reset to Defaults**:
-   ```bash
-   rulebook ralph config reset
-   ```
-   Resets to default values from init
-
-4. **Verify Changes**:
-   ```bash
-   rulebook ralph status
-   ```
-   Shows updated config in status output
-
-**Configuration File**
-Location: `.rulebook/ralph/config.json`
-
-Example structure:
-```json
-{
-  "enabled": true,
-  "max_iterations": 10,
-  "current_iteration": 0,
-  "ai_tool": "claude",
-  "project_name": "my-project",
-  "branch_name": "ralph/my-project",
-  "paused": false
-}
-```
-
-**Workflow**
-1. Initialize Ralph: `rulebook ralph init` (sets initial config)
-2. Review config: `rulebook ralph config show`
-3. Adjust as needed: `rulebook ralph config set <key> <value>`
-4. Start loop: `rulebook ralph run`
-5. Monitor with: `rulebook ralph status`
-
-**Troubleshooting**
-- **Config file missing**: Run `rulebook ralph init` again
-- **Settings not updating**: Ensure you're using correct key name
-- **Changes not taking effect**: Pause loop, update config, then resume
-- **Invalid ai_tool**: Check tool is installed (e.g., `claude --version`)
-
-<!-- RALPH:END -->

package/.claude/commands/ralph-history.md

@@ -1,110 +0,0 @@
----
-name: /ralph-history
-id: ralph-history
-category: Ralph
-description: View past Ralph iterations, quality check results, and learnings.
----
-<!-- RALPH:START -->
-**Overview**
-Review detailed records of all Ralph iterations, including:
-- Task completion status
-- Quality gate results (type-check, lint, tests, coverage)
-- Execution time and performance metrics
-- Errors encountered and learnings discovered
-- Git commits associated with each iteration
-
-**Guardrails**
-- History is automatically recorded by Ralph during execution
-- Read-only view - use to analyze and debug past iterations
-- Useful for identifying patterns in failures or learning opportunities
-- Each iteration is stored separately for audit trail
-
-**Steps**
-1. **View All Iterations**:
-   ```bash
-   rulebook ralph history
-   ```
-   Shows summary of all iterations with status and task info
-
-2. **View Latest Iterations**:
-   ```bash
-   rulebook ralph history --limit 5
-   ```
-   Shows most recent N iterations (useful for large iteration counts)
-
-3. **View Specific Iteration**:
-   ```bash
-   rulebook ralph history --iteration 3
-   ```
-   Shows detailed information for iteration 3
-
-4. **Export History**:
-   ```bash
-   rulebook ralph history --export history.json
-   ```
-   Exports full iteration history for analysis
-
-**Iteration Record Fields**
-Each iteration record contains:
-- **Metadata**:
-  - Iteration number
-  - Timestamp
-  - Task ID and title
-  - AI tool used
-  - Execution time (ms)
-  - Status: success / partial / failed
-
-- **Quality Checks**:
-  - type-check: TypeScript compilation result
-  - lint: ESLint check result
-  - tests: Test suite result
-  - coverage_met: Coverage threshold result
-
-- **Output**:
-  - output_summary: Summary of what was done
-  - learnings: Insights discovered during iteration
-  - errors: Any errors encountered
-
-- **Git**:
-  - git_commit: Commit hash if changes were committed
-  - branch: Branch used for this iteration
-
-**Analyzing History**
-1. **Success Rate**:
-   ```bash
-   # Successful iterations / total iterations
-   # Shows loop health and AI tool effectiveness
-   ```
-
-2. **Quality Gate Patterns**:
-   - Check which gates fail most often
-   - Identify systematic issues (e.g., always failing lint)
-   - Plan improvements based on failure patterns
-
-3. **Learnings Extraction**:
-   - Ralph records lessons learned from each iteration
-   - Use these to improve task definitions or AI prompts
-   - Share with team for knowledge base
-
-4. **Performance Metrics**:
-   - Track execution time per iteration
-   - Identify slow tasks or AI tools
-   - Optimize based on trends
-
-**Location**
-- Iteration records stored in: `.rulebook/ralph/history/`
-- Each file named: `iteration-<N>.json`
-- Full history also available in: `.rulebook/ralph/history-all.json`
-
-**Using History for Debugging**
-1. **Failed iteration**: Check error field for root cause
-2. **Partial success**: Review which quality gates failed
-3. **Slow iteration**: Check execution_time_ms
-4. **Pattern analysis**: Compare multiple iterations for trends
-
-**Next Steps**
-- After reviewing history, fix issues and retry: `rulebook ralph run`
-- Save learnings to persistent memory: `rulebook memory save "learning from iteration" ...`
-- Update PRD based on discoveries from history analysis
-
-<!-- RALPH:END -->

package/.claude/commands/ralph-init.md

@@ -1,72 +0,0 @@
----
-name: /ralph-init
-id: ralph-init
-category: Ralph
-description: Initialize Ralph autonomous loop for AI-driven task completion in a project.
----
-<!-- RALPH:START -->
-**Overview**
-Ralph is an autonomous AI loop that iteratively solves tasks from a PRD (Product Requirements Document). It runs your AI tool (Claude, Cursor, Gemini) in a continuous loop, tracks iterations, and learns from execution results.
-
-**Guardrails**
-- Always initialize Ralph before running iterations
-- Use `rulebook ralph status` to check initialization and loop state
-- Set appropriate max iterations (5-20 recommended for most projects)
-- Keep the AI tool consistent across iterations for learning continuity
-
-**Prerequisites**
-- Project must be initialized with `rulebook init`
-- Git repository must be set up with a remote origin
-- Current branch will be used as the base for Ralph work
-
-**Steps**
-1. **Initialize Ralph**:
-   ```bash
-   rulebook ralph init
-   ```
-
-2. **Interactive Setup**:
-   - Select max iterations (number of attempts to complete tasks)
-   - Choose AI tool: `claude` (recommended), `cursor`, or `gemini`
-   - Creates `.rulebook/ralph/` directory with configuration and PRD
-
-3. **Verify Initialization**:
-   ```bash
-   rulebook ralph status
-   ```
-   Should show:
-   - `enabled: true`
-   - `current_iteration: 0`
-   - `max_iterations: <your choice>`
-   - `ai_tool: <your choice>`
-
-4. **Review Generated PRD**:
-   - View `.rulebook/ralph/prd.json` for generated user stories
-   - Each story has: `id`, `title`, `description`, `acceptanceCriteria`, `priority`, `passes`, `notes`
-   - `passes: false` indicates pending stories
-
-5. **Optional: Customize PRD**:
-   - Edit user stories directly in `prd.json`
-   - Adjust priorities, add acceptance criteria, refine descriptions
-   - Ralph will track which stories are completed (`passes: true`)
-
-**Output**
-Ralph creates:
-- `.rulebook/ralph/prd.json` - The product requirements document
-- `.rulebook/ralph/config.json` - Loop configuration (max_iterations, ai_tool)
-- `.rulebook/ralph/history/` - Directory for iteration records
-
-**Next Steps**
-After initialization, use:
-- `rulebook ralph run` - Start the autonomous loop
-- `rulebook ralph pause` - Pause ongoing iterations
-- `rulebook ralph resume` - Resume paused loop
-- `rulebook ralph status` - Check current state
-- `rulebook ralph history` - View past iterations
-
-**Troubleshooting**
-- **Init hangs**: Check git remote is properly configured (`git remote -v`)
-- **PRD not generated**: Ensure project has valid task/context for Ralph to work with
-- **Configuration lost**: Check `.rulebook/ralph/config.json` exists
-
-<!-- RALPH:END -->

package/.claude/commands/ralph-pause-resume.md

@@ -1,105 +0,0 @@
----
-name: /ralph-pause-resume
-id: ralph-pause-resume
-category: Ralph
-description: Pause and resume Ralph autonomous loop for manual intervention or debugging.
----
-<!-- RALPH:START -->
-**Overview**
-Control Ralph's iteration loop by pausing and resuming execution:
-- **Pause**: Stop after current iteration completes, allows manual inspection or fixes
-- **Resume**: Continue from where paused, picking up with next incomplete story
-
-**Guardrails**
-- Pause completes current iteration before stopping (safe operation)
-- Loop can only be resumed from paused state
-- Use pause when: debugging failures, making manual fixes, investigating quality issues
-- Keep pause duration short - long pauses may lose AI context
-
-**Steps**
-
-### Pausing the Loop
-
-1. **Pause Ralph**:
-   ```bash
-   rulebook ralph pause
-   ```
-   - Completes current iteration
-   - Stops before next iteration starts
-   - Preserves all progress and iteration records
-
-2. **Verify Paused State**:
-   ```bash
-   rulebook ralph status
-   ```
-   Should show: `Paused: true`
-
-3. **Investigate Issues** (while paused):
-   - Review latest iteration: `rulebook ralph history --iteration <N>`
-   - Check quality gate failures: `rulebook ralph show <story-id>`
-   - Review error logs and learnings
-   - Make manual fixes to code if needed
-
-### Resuming the Loop
-
-1. **Resume Ralph**:
-   ```bash
-   rulebook ralph resume
-   ```
-   - Continues from where paused
-   - Picks up with next incomplete story
-   - Maintains iteration count and progress
-
-2. **Verify Running State**:
-   ```bash
-   rulebook ralph status
-   ```
-   Should show: `Paused: false`
-
-3. **Monitor Resumed Iterations**:
-   ```bash
-   rulebook ralph history --limit 3
-   ```
-   Check latest iterations to ensure resumption succeeded
-
-**Common Workflows**
-
-### Debugging Quality Gate Failures
-1. Loop running, tests fail in iteration 5
-2. `rulebook ralph pause` - stops after iteration 5
-3. Analyze: `rulebook ralph history --iteration 5`
-4. Identify test failure root cause
-5. Make manual code fixes
-6. `rulebook ralph resume` - continues from iteration 6
-
-### Making Manual Adjustments
-1. Pause loop: `rulebook ralph pause`
-2. Manually edit code based on iteration learnings
-3. Update PRD: `vi .rulebook/ralph/prd.json`
-4. Resume: `rulebook ralph resume` - continues with updated PRD
-
-### Inspecting AI Tool Output
-1. Pause: `rulebook ralph pause`
-2. Check `rulebook ralph history --iteration <N>` for AI output
-3. Review learnings and errors from iteration
-4. Resume: `rulebook ralph resume`
-
-**Pause vs Stopping**
-- **Pause** (`ralph pause`): Loop continues later with resume
-- **Stop** (Ctrl+C during run): Stops immediately, may interrupt current iteration
-- Use pause for graceful, resumable stops
-- Use Ctrl+C only for emergency stops
-
-**State Preservation**
-When paused:
-- Current iteration status saved
-- User story states preserved
-- Learnings and errors recorded
-- Loop progress not lost
-
-**Edge Cases**
-- **Can't pause if not running**: Check with `ralph status`
-- **Can't resume if not paused**: Call `ralph run` instead
-- **Resuming after long pause**: Ralph retains context up to max iterations allowed
-
-<!-- RALPH:END -->

package/.claude/commands/ralph-run.md

@@ -1,101 +0,0 @@
----
-name: /ralph-run
-id: ralph-run
-category: Ralph
-description: Start Ralph autonomous loop to iteratively complete tasks from the PRD.
----
-<!-- RALPH:START -->
-**Overview**
-Ralph runs your configured AI tool in a continuous loop, solving user stories from the PRD one at a time. Each iteration:
-1. Picks the next incomplete user story
-2. Invokes your AI tool (Claude, Cursor, or Gemini) to solve it
-3. Parses the output for quality checks and completion status
-4. Records the iteration results
-5. Marks the story as complete if all quality gates pass
-6. Moves to the next story or stops if max iterations reached
-
-**Guardrails**
-- Ralph must be initialized first with `rulebook ralph init`
-- Quality gates MUST pass: type-check, lint, tests, coverage
-- Failed iterations are recorded but don't auto-mark stories complete
-- Monitor logs and iteration history for quality issues
-
-**Prerequisites**
-- Ralph initialized with `rulebook ralph init`
-- All quality gate tools installed: TypeScript, ESLint, test framework, coverage reporter
-- `.rulebook/ralph/prd.json` exists with user stories
-
-**Steps**
-1. **Start the Loop**:
-   ```bash
-   rulebook ralph run
-   ```
-   Ralph will:
-   - Load configuration and PRD
-   - Find first incomplete story (`passes: false`)
-   - Invoke your AI tool
-   - Parse output for task completion and quality checks
-
-2. **Monitor Execution**:
-   - Watch the console for iteration progress
-   - Each iteration shows: story ID, title, execution time, quality gate results
-   - Ralph will pause on quality gate failures for review
-
-3. **Review Iteration Results**:
-   ```bash
-   rulebook ralph history
-   ```
-   Shows:
-   - Iteration number
-   - Task ID and title
-   - Success/partial/failed status
-   - Quality check results (type-check, lint, tests, coverage)
-   - Execution time
-   - Errors and learnings
-
-4. **Check Status**:
-   ```bash
-   rulebook ralph status
-   ```
-   Shows:
-   - Current iteration count
-   - Pending user stories count
-   - Completion percentage
-   - Paused state (if paused)
-
-**Iteration Lifecycle**
-1. **Iteration Start**: Ralph picks next incomplete story
-2. **AI Tool Execution**: Runs your configured tool (Claude/Cursor/Gemini)
-3. **Output Parsing**: Extracts quality checks, errors, completion indicators
-4. **Quality Gates**:
-   - type-check ✓ - TypeScript compilation succeeds
-   - lint ✓ - ESLint passes without errors
-   - tests ✓ - All test suites pass
-   - coverage ✓ - Coverage meets thresholds
-5. **Story Completion**: If all gates pass, marks `passes: true`
-6. **Next Iteration**: Moves to next story or completes loop
-
-**Quality Gate Failures**
-If gates fail:
-- Status recorded as `partial` or `failed`
-- Story remains `passes: false` for retry
-- Error details saved in iteration history
-- Manual review and fixes may be needed before retry
-
-**Pausing and Resuming**
-- `rulebook ralph pause` - Pause after current iteration
-- `rulebook ralph resume` - Continue from where paused
-- Useful for investigating failures or making manual adjustments
-
-**Iteration Records**
-Each iteration is recorded in:
-- `.rulebook/ralph/history/iteration-<N>.json` with full details
-- Includes: task details, quality checks, errors, learnings, git commit
-
-**Troubleshooting**
-- **Loop stops early**: Check quality gate failures in latest iteration
-- **AI tool not found**: Ensure `rulebook ralph config set ai-tool <tool>` is set correctly
-- **Infinite loops**: Use `rulebook ralph pause` and check loop configuration
-- **Context loss**: Ralph tracks context loss and reports it in iteration metadata
-
-<!-- RALPH:END -->

package/.claude/commands/ralph-status.md

@@ -1,76 +0,0 @@
----
-name: /ralph-status
-id: ralph-status
-category: Ralph
-description: Check the status of Ralph autonomous loop and view task completion statistics.
----
-<!-- RALPH:START -->
-**Overview**
-View the current state of Ralph's autonomous loop, including:
-- Loop enabled/disabled status
-- Current iteration count and max iterations
-- Paused/running state
-- User story completion statistics
-- Overall project progress
-
-**Guardrails**
-- Status shows real-time state from `.rulebook/ralph/config.json` and `prd.json`
-- Use status regularly to monitor loop health
-- Paused state prevents iterations from continuing (must resume to continue)
-
-**Steps**
-1. **Check Ralph Status**:
-   ```bash
-   rulebook ralph status
-   ```
-
-2. **Interpret Output**:
-   ```
-   Ralph Status:
-   ├─ Enabled: true
-   ├─ Current Iteration: 3
-   ├─ Max Iterations: 10
-   ├─ AI Tool: claude
-   ├─ Paused: false
-   ├─ Task Statistics:
-   │  ├─ Total Stories: 5
-   │  ├─ Completed: 2
-   │  ├─ Pending: 3
-   │  └─ Completion: 40%
-   └─ Branch: ralph/my-project
-   ```
-
-3. **Status Fields**:
-   - **Enabled**: Whether Ralph loop is active
-   - **Current Iteration**: Which iteration loop is on (0 = not started)
-   - **Max Iterations**: Total iterations allowed before stopping
-   - **AI Tool**: Which AI tool is being used (claude, cursor, gemini)
-   - **Paused**: Whether loop is paused (must resume to continue)
-   - **Task Statistics**: User story completion breakdown
-   - **Branch**: Git branch Ralph is working on
-
-4. **Check Completion**:
-   ```bash
-   # View detailed task statistics
-   rulebook ralph status --detailed
-   ```
-   Shows individual user story status and completion breakdown
-
-**Common Patterns**
-- **Just initialized**: `Current Iteration: 0`, `Pending: <all stories>`
-- **In progress**: `Current Iteration: N` increasing, `Pending` decreasing
-- **Complete**: `Current Iteration` matches total completed stories, `Pending: 0`
-- **Paused**: `Paused: true`, resume with `rulebook ralph resume`
-
-**Next Steps**
-- If loop not started: `rulebook ralph run`
-- If paused: `rulebook ralph resume`
-- To view iterations: `rulebook ralph history`
-- To view story details: `rulebook ralph show <story-id>` (if available)
-
-**Troubleshooting**
-- **Status shows disabled**: Run `rulebook ralph init` to enable
-- **Iteration count stuck**: Check if loop is paused or if max iterations reached
-- **Statistics don't match**: Check `.rulebook/ralph/prd.json` for consistency
-
-<!-- RALPH:END -->