@hivehub/rulebook 5.5.2 → 5.8.0

package/templates/skills/workflows/ralph/SETUP.md

@@ -1,228 +0,0 @@
-# Ralph Autonomous Loop Setup Guide
-
-## Installation
-
-Ralph is installed as part of `@hivehub/rulebook`. To enable it as a Claude Code skill:
-
-### Option 1: Automatic Installation (Recommended)
-
-```bash
-# During project initialization
-rulebook init
-# → Select "Ralph Autonomous Loop" when prompted for skills
-
-# Or enable existing project
-rulebook skill enable ralph-autonomous-loop
-```
-
-### Option 2: Manual Installation
-
-```bash
-# 1. Install rulebook (if not already installed)
-npm install -g @hivehub/rulebook
-
-# 2. Run the Ralph skill setup
-bash templates/skills/workflows/ralph/install.sh
-
-# 3. Verify installation
-cat .rulebook | grep -A 5 '"ralph"'
-```
-
-## Claude Code Integration
-
-### Configuration in .cursorrules
-
-Ralph skill automatically adds to `.cursorrules`:
-
-```
-## Ralph Autonomous Loop
-
-When working with Ralph autonomous loop:
-
-1. **Before each iteration**:
-   - Read .rulebook-ralph/prd.json for task specifications
-   - Read .rulebook-ralph/progress.txt for past learnings
-   - Reference recent git commits for architectural context
-
-2. **During implementation**:
-   - Focus on ONE task from PRD
-   - Apply patterns from progress.txt
-   - Write tests first (95%+ coverage required)
-
-3. **After implementation**:
-   - Run quality gates: type-check, lint, tests, coverage
-   - Commit with clear message including iteration number
-   - Ralph will update progress.txt with learnings
-
-4. **Commands**:
-   - Check status: rulebook ralph status
-   - View history: rulebook ralph history
-   - Pause loop: rulebook ralph pause (Ctrl+C)
-   - Resume: rulebook ralph resume
-```
-
-### Enabling in Claude Code
-
-When you run `npx init` or `rulebook init`, Claude Code will:
-
-1. ✅ Detect Ralph skill in `.rulebook` configuration
-2. ✅ Register Ralph commands and MCP tools
-3. ✅ Load Ralph documentation into context
-4. ✅ Enable Ralph-specific prompting
-
-### Using Ralph in Claude Code
-
-```bash
-# After initialization, Ralph is available via:
-rulebook ralph <command>
-
-# Example workflow:
-1. Create tasks
-2. Initialize Ralph
-3. Run autonomous loop
-4. Monitor progress
-5. Review and deploy
-```
-
-## Configuration
-
-### .rulebook Configuration
-
-```json
-{
-  "ralph": {
-    "enabled": true,
-    "maxIterations": 10,
-    "tool": "claude",
-    "maxContextLoss": 3
-  }
-}
-```
-
-**Options**:
-- `enabled` (boolean): Enable Ralph autonomous loop
-- `maxIterations` (number): Max iterations before stopping
-- `tool` (string): AI CLI tool ("claude", "amp", "gemini")
-- `maxContextLoss` (number): Tolerance for incomplete outputs
-
-### Directory Structure
-
-Ralph creates and uses:
-
-```
-.rulebook-ralph/
-├── prd.json                    # Task specifications (auto-generated)
-├── progress.txt                # Append-only learning log
-└── history/                    # Per-iteration metadata
-    ├── iteration-1.json
-    ├── iteration-2.json
-    └── ...
-```
-
-## Quick Start
-
-```bash
-# 1. Create tasks (can be multiple)
-rulebook task create implement-auth
-rulebook task create add-api-endpoints
-rulebook task create write-tests
-
-# 2. Initialize Ralph
-rulebook ralph init
-# → Creates .rulebook-ralph/prd.json from tasks
-# → Initializes progress.txt
-
-# 3. Start autonomous loop
-rulebook ralph run --max-iterations 10
-# → Ralph picks first task
-# → Runs Claude Code to implement
-# → Runs quality checks
-# → Updates task status and progress.txt
-# → Repeats for next task
-
-# 4. Monitor progress
-rulebook ralph status           # Current status
-rulebook ralph history          # Iteration history
-rulebook ralph history --learnings  # What was learned
-
-# 5. Pause/resume if needed
-rulebook ralph pause            # Gracefully pause
-rulebook ralph resume           # Continue later
-```
-
-## MCP Server Integration
-
-Ralph commands are available via MCP for programmatic use:
-
-```bash
-# Start MCP server
-rulebook-mcp
-
-# Available tools:
-# - rulebook_ralph_init: Initialize Ralph
-# - rulebook_ralph_run: Start autonomous loop
-# - rulebook_ralph_status: Query loop status
-# - rulebook_ralph_get_iteration_history: Fetch history
-```
-
-## Troubleshooting
-
-### Ralph not found after installation
-
-```bash
-# Ensure @hivehub/rulebook is installed
-npm list -g @hivehub/rulebook
-
-# If not installed
-npm install -g @hivehub/rulebook
-
-# Verify Ralph skill is registered
-rulebook skill list | grep ralph
-```
-
-### .rulebook configuration not created
-
-```bash
-# Run init if not already done
-rulebook init
-
-# Manually enable Ralph
-rulebook skill enable ralph-autonomous-loop
-```
-
-### Claude Code not recognizing Ralph commands
-
-```bash
-# Ensure .cursorrules is updated
-cat .cursorrules | grep -i ralph
-
-# Manually add Ralph section if missing
-echo "
-## Ralph Autonomous Loop
-[See SKILL.md for full content]
-" >> .cursorrules
-```
-
-## Next Steps
-
-1. **Read SKILL.md** — Full documentation
-2. **Review manifest.json** — Complete skill specification
-3. **Run examples** — Try the quick start commands
-4. **Monitor iterations** — Use `rulebook ralph history`
-5. **Customize** — Adjust maxIterations, tool, etc. in .rulebook
-
-## Documentation
-
-- **SKILL.md** — Complete Ralph skill documentation
-- **manifest.json** — Skill specification and metadata
-- **install.sh** — Installation/setup script
-- **SETUP.md** — This file
-
-## Support
-
-For issues or questions:
-
-- Check `rulebook ralph --help`
-- Review `rulebook ralph history` for error messages
-- See [Ralph GitHub](https://github.com/snarktank/ralph) for pattern details
-- Check [Rulebook docs](https://github.com/hivellm/rulebook) for CLI reference

package/templates/skills/workflows/ralph/SKILL.md

@@ -1,309 +0,0 @@
----
-name: "Ralph Autonomous Loop"
-description: "Autonomous AI agent loop for iterative task implementation (@hivehub/rulebook ralph)"
-version: "1.0.0"
-category: "workflow"
-author: "Rulebook"
-tags: ["autonomous", "ralph", "iterative", "workflow"]
-dependencies: ["rulebook"]
-conflicts: []
----
-<!-- RALPH:START -->
-# Ralph Autonomous Loop Skill
-
-**Purpose**: Automate iterative feature implementation using Ralph's autonomous agent loop pattern.
-
-## Installation
-
-Ralph is installed as part of @hivehub/rulebook:
-
-```bash
-npm install -g @hivehub/rulebook
-# or
-npx @hivehub/rulebook init
-```
-
-## Quick Start
-
-### Step 1: Initialize Ralph for Your Project
-
-```bash
-# Create task specifications in .rulebook/tasks/
-rulebook task create my-feature
-
-# Initialize Ralph
-rulebook ralph init
-
-# This creates:
-# - .rulebook-ralph/prd.json (task specifications in PRD format)
-# - .rulebook-ralph/progress.txt (learning log across iterations)
-# - .rulebook-ralph/history/ (per-iteration metadata)
-```
-
-### Step 2: Run Autonomous Loop
-
-```bash
-# Run with default settings
-rulebook ralph run
-
-# Or with custom iterations and tool
-rulebook ralph run --max-iterations 10 --tool claude
-```
-
-### Step 3: Monitor Progress
-
-```bash
-# Check current status
-rulebook ralph status
-
-# View iteration history
-rulebook ralph history
-
-# See learnings discovered
-rulebook ralph history --learnings
-```
-
-## Understanding the Ralph Loop
-
-### Loop Workflow
-
-```
-1. Pick highest-priority incomplete task from PRD
-2. Execute AI agent (Claude Code, Cursor, or Gemini)
-   - Provide full PRD context
-   - Include progress.txt (learnings from past iterations)
-   - Include git history (recent commits)
-3. Run quality gates (type-check, lint, tests)
-4. If success:
-   - Commit changes with iteration metadata
-   - Update task status to completed
-   - Record learnings to progress.txt
-5. If failure:
-   - Mark task as blocked
-   - Record error and blockers to progress.txt
-6. Repeat until all tasks completed or max iterations reached
-```
-
-### Fresh Context Per Iteration
-
-Each iteration starts fresh:
-- New AI agent instance (clean context)
-- Memory persists through: git commits, PRD.json, progress.txt
-- AI agent reads past learnings to avoid repeating mistakes
-
-This pattern prevents "context degradation" where AI agent loses track of architectural decisions across many iterations.
-
-## Configuration
-
-### .rulebook Configuration
-
-```json
-{
-  "ralph": {
-    "enabled": false,
-    "maxIterations": 10,
-    "tool": "claude",
-    "maxContextLoss": 3
-  }
-}
-```
-
-**Options**:
-- `enabled`: Enable Ralph autonomous loop (default: false)
-- `maxIterations`: Max iterations before stopping (default: 10)
-- `tool`: AI CLI tool to use (default: "claude")
-  - `"claude"` — Claude Code CLI
-  - `"amp"` — Amp CLI (for Cursor)
-  - `"gemini"` — Gemini CLI
-- `maxContextLoss`: Tolerance for incomplete agent outputs (default: 3)
-
-### PRD Format (.rulebook-ralph/prd.json)
-
-```json
-{
-  "tasks": [
-    {
-      "id": "task-id",
-      "title": "Task Title",
-      "description": "What needs to be done",
-      "priority": 1,
-      "status": "pending",
-      "acceptanceCriteria": [
-        "Criterion 1",
-        "Criterion 2"
-      ],
-      "estimatedComplexity": "medium"
-    }
-  ]
-}
-```
-
-### Progress Log (.rulebook-ralph/progress.txt)
-
-Append-only learning log:
-
-```
-=== Iteration 1 ===
-Task: implement-auth
-Tool: Claude Code
-Result: SUCCESS
-Learnings:
-- Discovered OAuth token refresh pattern (30-min expiry)
-- Gotcha: Tokens expire silently, need header check before retry
-- Pattern: Use interceptor middleware for transparent refresh
-
-=== Iteration 2 ===
-Task: add-caching
-Tool: Claude Code
-Result: FAILED - Tests failed
-Error: Cache invalidation not handling concurrent updates
-Blockers: Need to implement distributed cache locking
-```
-
-## Usage Patterns
-
-### Pattern 1: Progressive Feature Implementation
-
-Break large features into tasks:
-
-```bash
-# Create tasks for phases
-rulebook task create setup-database
-rulebook task create create-api-endpoints
-rulebook task create add-authentication
-rulebook task create write-tests
-
-# Initialize Ralph
-rulebook ralph init
-
-# Run autonomous loop — implements all tasks iteratively
-rulebook ralph run --max-iterations 20
-```
-
-### Pattern 2: Learning Across Iterations
-
-Ralph learns from past iterations:
-
-1. **Iteration 1**: Implements feature A, discovers pattern X
-2. **Progress.txt updated**: Records pattern X
-3. **Iteration 2**: Reads progress.txt, applies pattern X to feature B
-4. **Iteration 3+**: Builds on discovered patterns
-
-### Pattern 3: Pause and Resume
-
-Stop loop gracefully and resume later:
-
-```bash
-# Start autonomous loop
-rulebook ralph run --max-iterations 100
-
-# (User presses Ctrl+C)
-# Loop pauses, state saved
-
-# Resume later
-rulebook ralph resume
-
-# Continues from last incomplete task with full history
-```
-
-## Quality Gates
-
-Ralph enforces quality checks after each iteration:
-
-```bash
-# After each implementation, Ralph runs:
-npm run type-check    # TypeScript compilation
-npm run lint          # ESLint (0 warnings)
-npm run test          # All tests (100% pass)
-npm run test:coverage # Coverage threshold met (95%)
-```
-
-**If ANY gate fails**:
-- Task marked as `blocked` with error details
-- Error recorded to progress.txt
-- Loop continues to next task (unless `--strict` mode)
-
-## MCP Integration
-
-Use Ralph via Model Context Protocol:
-
-```javascript
-// Initialize Ralph
-rulebook_ralph_init({ force: false })
-  → Returns: { success: true, taskCount: 5, prdPath: "..." }
-
-// Start autonomous loop
-rulebook_ralph_run({ maxIterations: 10, tool: "claude" })
-  → Returns: { success: true, loopId: "loop-123", status: "running" }
-
-// Query loop status
-rulebook_ralph_status()
-  → Returns: { loopStatus: "running", iteration: 5, currentTask: "task-id", ... }
-
-// Get iteration history
-rulebook_ralph_get_iteration_history({ limit: 10 })
-  → Returns: { iterations: [...], total: 12 }
-```
-
-## Best Practices
-
-### DO ✅
-
-- **Break features into right-sized tasks**: 1-2 context windows each
-- **Write clear acceptance criteria**: AI uses these to validate completion
-- **Monitor iteration history**: Review learnings and errors
-- **Run manual testing**: Ralph is automated but human review is important
-- **Commit frequently**: Each iteration commits, creating audit trail
-- **Use meaningful task IDs**: Descriptive names help AI understand context
-
-### DON'T ❌
-
-- **Don't create huge tasks**: "Build entire backend" won't fit in one iteration
-- **Don't skip acceptance criteria**: AI needs clear completion signals
-- **Don't ignore blocked tasks**: Review errors and adjust task sizing
-- **Don't run without version control**: You need git history for learning
-- **Don't disable quality gates**: Tests catch failures early
-
-## Troubleshooting
-
-### Loop Stops Early
-
-**Problem**: Ralph stops before reaching max iterations
-**Cause**: All tasks completed (success!) or multiple blockers
-**Solution**: Check `rulebook ralph history` for blockers
-
-### Same Task Keeps Failing
-
-**Problem**: Task marked blocked multiple times
-**Cause**: Task too large, acceptance criteria unclear, or AI context insufficient
-**Solution**:
-1. Break task into smaller subtasks
-2. Clarify acceptance criteria
-3. Add examples to task spec
-
-### Quality Gates Failing
-
-**Problem**: Type-check, lint, or tests fail after implementation
-**Cause**: AI-generated code doesn't meet project standards
-**Solution**:
-1. Review error details in progress.txt
-2. Update AGENTS.md with clearer standards
-3. Provide more examples in task specs
-
-## Next Steps
-
-1. **Create tasks**: `rulebook task create <task-id>` (multiple times)
-2. **Initialize Ralph**: `rulebook ralph init`
-3. **Run loop**: `rulebook ralph run --max-iterations N`
-4. **Monitor**: `rulebook ralph status` and `rulebook ralph history`
-5. **Review**: Check generated code and learnings
-6. **Deploy**: Code is committed and ready
-
-## References
-
-- **Ralph Pattern**: https://github.com/snarktank/ralph
-- **Task Management**: See `RULEBOOK.md` in AGENTS.md
-- **Rulebook CLI**: `rulebook --help`
-- **MCP Server**: `rulebook-mcp` (stdio transport)
-
-<!-- RALPH:END -->

package/templates/skills/workflows/ralph/install.sh

@@ -1,87 +0,0 @@
-#!/bin/bash
-# Ralph Autonomous Loop Skill Installation
-# This script is executed when users run: rulebook init or rulebook skill enable ralph
-
-set -e
-
-echo "🔧 Installing Ralph Autonomous Loop Skill..."
-
-# Check if rulebook is installed
-if ! command -v rulebook &> /dev/null; then
-  echo "❌ Error: @hivehub/rulebook not found"
-  echo "   Install with: npm install -g @hivehub/rulebook"
-  exit 1
-fi
-
-# Check if .rulebook config exists
-if [ ! -f ".rulebook" ]; then
-  echo "❌ Error: .rulebook config not found"
-  echo "   Run: rulebook init"
-  exit 1
-fi
-
-# Enable Ralph in .rulebook config
-echo "📝 Enabling Ralph in .rulebook..."
-if grep -q '"ralph"' .rulebook; then
-  # Ralph section exists, update enabled flag
-  sed -i.bak 's/"enabled": false/"enabled": true/g' .rulebook && rm -f .rulebook.bak
-else
-  # Add Ralph section to config
-  # Insert before closing }
-  sed -i.bak '$ s/}/,\n  "ralph": {\n    "enabled": true,\n    "maxIterations": 10,\n    "tool": "claude",\n    "maxContextLoss": 3\n  }\n}/' .rulebook && rm -f .rulebook.bak
-fi
-
-# Create Ralph directories
-echo "📁 Creating Ralph directories..."
-mkdir -p .rulebook-ralph/history
-
-# Create initial PRD if tasks exist
-if [ -d ".rulebook/tasks" ] && [ "$(ls -A .rulebook/tasks)" ]; then
-  echo "📋 Generating PRD from existing tasks..."
-  rulebook ralph init || echo "⚠️  Could not auto-generate PRD. Run: rulebook ralph init"
-else
-  echo "💡 No tasks found. Create tasks first: rulebook task create <task-id>"
-fi
-
-# Create .cursorrules entry for Ralph if working with Claude Code
-if [ -f ".cursorrules" ]; then
-  echo "🔗 Updating .cursorrules for Ralph..."
-  cat >> .cursorrules << 'EOF'
-
-## Ralph Autonomous Loop
-
-When working with Ralph autonomous loop:
-
-1. **Before each iteration**:
-   - Read .rulebook-ralph/prd.json for task specifications
-   - Read .rulebook-ralph/progress.txt for past learnings
-   - Reference recent git commits for architectural context
-
-2. **During implementation**:
-   - Focus on ONE task from PRD
-   - Apply patterns from progress.txt
-   - Write tests first (95%+ coverage required)
-
-3. **After implementation**:
-   - Run quality gates: type-check, lint, tests, coverage
-   - Commit with clear message including iteration number
-   - Ralph will update progress.txt with learnings
-
-4. **Commands**:
-   - Check status: rulebook ralph status
-   - View history: rulebook ralph history
-   - Pause loop: rulebook ralph pause (Ctrl+C)
-   - Resume: rulebook ralph resume
-EOF
-fi
-
-echo ""
-echo "✅ Ralph Autonomous Loop Skill Installed!"
-echo ""
-echo "📖 Next steps:"
-echo "   1. Create tasks: rulebook task create <task-id>"
-echo "   2. Initialize Ralph: rulebook ralph init"
-echo "   3. Start loop: rulebook ralph run [--max-iterations N] [--tool claude]"
-echo "   4. Monitor: rulebook ralph status"
-echo ""
-echo "📚 For more info: rulebook ralph --help"