@hivehub/rulebook 4.0.0 → 4.2.0

package/.claude/commands/continue.md

@@ -1,33 +1,33 @@
----
-name: /continue
-id: continue
-category: Rulebook
-description: Update tasks.md, archive completed tasks, and continue implementation.
----
-<!-- RULEBOOK:START -->
-**Steps**
-
-1. **Update tasks.md for all active tasks**:
-   - Mark completed items as `[x]` in every active `tasks.md`
-   - Remove or update items that are no longer relevant
-
-2. **Archive fully completed tasks**:
-   For each task where ALL items are `[x]`:
-   ```bash
-   rulebook task archive <task-id>
-   ```
-
-3. **Get current session context**:
-   ```bash
-   rulebook continue
-   ```
-   Use this output to understand what's pending and what was done.
-
-4. **Continue implementation**:
-   - Pick the next pending task from the context above
-   - Work through its `tasks.md` checklist item by item
-   - Follow priority order: tests → coverage → update tasks.md → commit
-
-**Reference**
-- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
-<!-- RULEBOOK:END -->
+---
+name: /continue
+id: continue
+category: Rulebook
+description: Update tasks.md, archive completed tasks, and continue implementation.
+---
+<!-- RULEBOOK:START -->
+**Steps**
+
+1. **Update tasks.md for all active tasks**:
+   - Mark completed items as `[x]` in every active `tasks.md`
+   - Remove or update items that are no longer relevant
+
+2. **Archive fully completed tasks**:
+   For each task where ALL items are `[x]`:
+   ```bash
+   rulebook task archive <task-id>
+   ```
+
+3. **Get current session context**:
+   ```bash
+   rulebook continue
+   ```
+   Use this output to understand what's pending and what was done.
+
+4. **Continue implementation**:
+   - Pick the next pending task from the context above
+   - Work through its `tasks.md` checklist item by item
+   - Follow priority order: tests → coverage → update tasks.md → commit
+
+**Reference**
+- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
+<!-- RULEBOOK:END -->

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

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