@hivehub/rulebook 3.1.0 → 3.2.1

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

@@ -0,0 +1,112 @@
+---
+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

@@ -0,0 +1,110 @@
+---
+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

@@ -0,0 +1,72 @@
+---
+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

@@ -0,0 +1,105 @@
+---
+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

@@ -0,0 +1,101 @@
+---
+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

@@ -0,0 +1,76 @@
+---
+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 -->

package/.claude/commands/rulebook-memory-save.md

@@ -0,0 +1,48 @@
+---
+name: /rulebook-memory-save
+id: rulebook-memory-save
+category: Rulebook
+description: Save a new persistent memory for context across AI sessions.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Use the MCP memory tools when available (preferred over CLI commands).
+- Choose the correct memory type for accurate classification and search.
+- Keep titles concise and content descriptive.
+- Use tags for better discoverability.
+
+**Steps**
+1. **Save a memory** using the MCP tool or CLI:
+   ```
+   # Via MCP (preferred)
+   rulebook_memory_save({
+     type: "feature",
+     title: "Short descriptive title",
+     content: "Detailed description of what happened, why, and context",
+     tags: ["relevant", "tags"]
+   })
+
+   # Via CLI
+   rulebook memory save "content text" --type feature --title "Title" --tags tag1,tag2
+   ```
+
+2. **Choose the right type**:
+   - `bugfix` - Fixed a bug or resolved an error
+   - `feature` - Added new functionality
+   - `refactor` - Restructured code without changing behavior
+   - `decision` - Made an architecture or design choice (protected from eviction)
+   - `discovery` - Found something important about the codebase
+   - `change` - General code modification
+   - `observation` - Noted something worth remembering
+
+3. **Verify** the memory was saved:
+   ```
+   rulebook_memory_search({ query: "your title keywords" })
+   ```
+
+**Best Practices**
+- Save decisions early - they are protected from cache eviction
+- Include "why" in content, not just "what"
+- Use consistent tags across related memories
+- Content within `<private>...</private>` tags will be automatically redacted
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-memory-search.md

@@ -0,0 +1,47 @@
+---
+name: /rulebook-memory-search
+id: rulebook-memory-search
+category: Rulebook
+description: Search persistent memories using hybrid BM25+vector search for context across sessions.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Use the MCP memory tools when available (preferred over CLI commands).
+- The memory system uses 3-layer search: Layer 1 (compact search), Layer 2 (timeline), Layer 3 (full details).
+- Always start with a broad search, then narrow down with timeline and full details.
+
+**Steps**
+1. **Search memories** using the MCP tool or CLI:
+   ```
+   # Via MCP (preferred)
+   rulebook_memory_search({ query: "search terms", mode: "hybrid", limit: 20 })
+
+   # Via CLI
+   rulebook memory search "search terms" --mode hybrid --limit 20
+   ```
+   Modes: `hybrid` (default, best results), `bm25` (keyword only), `vector` (semantic only).
+
+2. **Get timeline context** around a relevant result:
+   ```
+   rulebook_memory_timeline({ memoryId: "<id>", window: 5 })
+   ```
+
+3. **Get full details** for specific memories:
+   ```
+   rulebook_memory_get({ ids: ["<id1>", "<id2>"] })
+   ```
+
+**Memory Types**
+- `bugfix` - Bug fixes and error resolutions
+- `feature` - New features and capabilities
+- `refactor` - Code restructuring
+- `decision` - Architecture/design decisions (protected from eviction)
+- `discovery` - Findings about codebase or tools
+- `change` - General code changes
+- `observation` - General observations
+
+**Reference**
+- Use `rulebook memory stats` to check database health
+- Decisions are never evicted during cleanup
+- Privacy: content within `<private>...</private>` tags is automatically redacted
+<!-- RULEBOOK:END -->