@hivehub/rulebook 3.4.2 → 4.1.0

package/templates/core/MULTI_AGENT.md

@@ -0,0 +1,74 @@
+<!-- MULTI_AGENT:START -->
+# Multi-Agent Development Directives
+
+## Overview
+
+When `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is enabled, Claude Code can spawn specialized sub-agents that work in parallel on complex tasks. This template defines coordination rules and team patterns for effective multi-agent development.
+
+## When to Use Teams
+
+Use agent teams when:
+- Tasks have clear parallel work streams (e.g., frontend + backend simultaneously)
+- Research, implementation, and testing can run concurrently
+- Multiple independent modules need changes at the same time
+- Complex refactoring spans many files across different subsystems
+
+Do NOT use teams when:
+- The task is simple and sequential
+- Changes are tightly coupled and require serial execution
+- The task can be completed in under 5 minutes by a single agent
+
+## Team Structure Patterns
+
+### Standard Team (Recommended)
+
+| Agent | Role | Responsibilities |
+|-------|------|-----------------|
+| **team-lead** | Orchestrator | Breaks down tasks, assigns work, integrates results |
+| **researcher** | Information Gatherer | Reads code, searches docs, analyzes patterns |
+| **implementer** | Code Writer | Writes production code following established patterns |
+| **tester** | Quality Assurance | Writes tests, validates coverage, runs quality checks |
+
+### Minimal Team (Simple Tasks)
+
+| Agent | Role |
+|-------|------|
+| **team-lead** | Orchestrator + integrator |
+| **implementer** | Code writer + researcher |
+
+## Coordination Rules
+
+1. **Team lead assigns tasks explicitly** -- agents do not self-assign work
+2. **Agents report completion via SendMessage** -- not by writing to shared files
+3. **No two agents modify the same file simultaneously** -- team lead coordinates file ownership
+4. **Use git-friendly workflows** -- each agent works on distinct files to avoid merge conflicts
+5. **Quality gates are mandatory** -- tester agent validates all changes before completion
+
+## Communication Protocol
+
+- **Task Assignment**: Team lead sends specific, scoped instructions to each agent
+- **Progress Updates**: Agents report status via messages, not file-based communication
+- **Blocking Issues**: Agents immediately notify team lead of blockers
+- **Completion**: Agents send explicit "done" messages with summary of changes
+
+## File Ownership
+
+To prevent conflicts, the team lead must:
+1. Identify all files that need modification
+2. Assign exclusive ownership of each file to one agent
+3. If multiple agents need the same file, serialize their access
+
+## Agent Definitions
+
+Pre-configured agent definitions are available in `.claude/agents/`. These provide specialized instructions for each agent role, ensuring consistent behavior and expertise.
+
+## Quality Enforcement
+
+All agent teams must adhere to the project's quality gates:
+- Type checking must pass
+- Linter must pass with zero warnings
+- All tests must pass
+- Coverage thresholds must be met
+
+The tester agent is responsible for running these checks before the team lead marks a task as complete.
+<!-- MULTI_AGENT:END -->

package/templates/core/PLANS.md

@@ -0,0 +1,28 @@
+<!-- PLANS:START -->
+# Project Plans & Session Context
+
+This file is a **persistent session scratchpad** maintained by AI agents.
+It provides continuity across sessions without relying on conversation history.
+
+## How to Use
+
+At the **start of each session**: Read this file to understand current context.
+During the **session**: Update with decisions, discoveries, and progress.
+At **session end**: Write a summary to the Session History section.
+
+## Active Context
+
+<!-- PLANS:CONTEXT:START -->
+_No active context. Start a session to populate this section._
+<!-- PLANS:CONTEXT:END -->
+
+## Current Task
+
+<!-- PLANS:TASK:START -->
+_No task in progress._
+<!-- PLANS:TASK:END -->
+
+## Session History
+
+<!-- PLANS:HISTORY:START -->
+<!-- PLANS:HISTORY:END -->

package/templates/core/RALPH.md

@@ -94,10 +94,35 @@ Ralph automatically checks these gates after each iteration:
 | **lint** | ESLint code quality | No errors |
 | **tests** | Unit tests | All passing |
 | **coverage** | Code coverage | ≥95% |
+| **security** | Vulnerability scan | No findings above `failOn` severity |
+
+**Security Gate** scans for vulnerabilities using the first available tool:
+1. **trivy** — container and filesystem scanning (`trivy fs --format json`)
+2. **semgrep** — static analysis (`semgrep --config auto --json`)
+3. **npm audit** — Node.js dependency audit (always available in Node projects)
+
+Configure via `.rulebook` file:
+```json
+{
+  "ralph": {
+    "securityGate": {
+      "enabled": true,
+      "failOn": "high",
+      "tool": "auto"
+    }
+  }
+}
+```
+
+| Setting | Default | Options | Description |
+|---------|---------|---------|-------------|
+| `enabled` | `true` | `true`/`false` | Enable/disable security gate |
+| `failOn` | `"high"` | `critical`/`high`/`moderate`/`low` | Minimum severity to fail |
+| `tool` | `"auto"` | `auto`/`npm-audit`/`trivy`/`semgrep` | Scanner to use |
 
 **Iteration Status:**
-- ✅ **success** - All 4 gates pass
-- ⚠️ **partial** - 2-3 gates pass
+- ✅ **success** - All 5 gates pass
+- ⚠️ **partial** - 2-4 gates pass
 - ❌ **failed** - 0-1 gates pass
 
 ### Fresh Context Strategy
@@ -177,7 +202,17 @@ Acceptance Criteria:
     "enabled": true,
     "maxIterations": 10,
     "tool": "claude",
-    "maxContextLoss": 3
+    "maxContextLoss": 3,
+    "securityGate": {
+      "enabled": true,
+      "failOn": "high",
+      "tool": "auto"
+    },
+    "contextCompression": {
+      "enabled": true,
+      "recentCount": 3,
+      "threshold": 5
+    }
   }
 }
 ```
@@ -186,8 +221,14 @@ Acceptance Criteria:
 |---------|---------|-------------|
 | `enabled` | `true` | Enable Ralph features |
 | `maxIterations` | `10` | Max iterations per run |
-| `tool` | `claude` | Default AI tool |
+| `tool` | `claude` | Default AI tool: `claude`, `amp`, `gemini` |
 | `maxContextLoss` | `3` | Allow 3 context loss events before stopping |
+| `securityGate.enabled` | `true` | Enable 5th quality gate (vulnerability scan) |
+| `securityGate.failOn` | `"high"` | Fail on: `critical`, `high`, `moderate`, `low` |
+| `securityGate.tool` | `"auto"` | Scanner: `auto`, `npm-audit`, `trivy`, `semgrep` |
+| `contextCompression.enabled` | `true` | Compress old iteration history in prompts |
+| `contextCompression.recentCount` | `3` | Iterations shown in full detail |
+| `contextCompression.threshold` | `5` | Min iterations before compression activates |
 
 ## MCP Integration
 

package/templates/core/RULEBOOK.md

@@ -304,6 +304,48 @@ rulebook task archive <task-id> --yes
 4. Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
 5. Updates related specifications
 
+## 🚨 MANDATORY: Deferred Items → Tasks Rule
+
+**ABSOLUTE RULE — NO EXCEPTIONS**: Whenever a task is archived with items marked as "Deferred" or "Phase X+", you MUST immediately create Rulebook tasks for those deferred items **before archiving**.
+
+### The Deferred Items Protocol
+
+```
+❌ WRONG — defer without creating task:
+1. Archive task with "- [ ] D1. feature X — deferred Phase 4"
+   → Feature X is now forgotten forever
+
+✅ CORRECT — defer with tracking:
+1. Add "- [ ] D1. feature X — deferred Phase 4" to tasks.md
+2. Call rulebook_task_create("phase4-feature-x")
+3. Write tasks.md for the new task with full context
+4. THEN call rulebook_task_archive
+```
+
+### tasks.md Format for Archived Tasks
+
+```markdown
+## 1. Implemented Feature
+
+- [x] 1.1 Thing that was done
+- [x] 1.2 Another thing done
+
+## Deferred to Phase N (reason: dependency not ready)
+
+- [ ] D1. Feature X — deferred (reason)   ← task phase4-feature-x MUST exist
+- [ ] D2. Feature Y — deferred (reason)   ← task phaseN-feature-y MUST exist
+```
+
+### Archive Checklist (ALL must be done before `rulebook_task_archive`)
+
+```
+□ 1. tasks.md uses - [x] for implemented, - [ ] for deferred
+□ 2. Each deferred item has a "Phase N" target
+□ 3. A rulebook task exists for EVERY deferred item or group
+□ 4. The new deferred tasks have tasks.md with full context
+□ 5. THEN call rulebook_task_archive
+```
+
 ## Task Format Examples
 
 ### Correct Format ✅

package/templates/ides/CONTINUE_RULES.md

@@ -0,0 +1,16 @@
+<!-- RULEBOOK:START -->
+# Continue.dev — Code Assistant Rules
+
+## Context Loading
+- Always read AGENTS.md before making changes
+- Check `.rulebook/specs/` for relevant spec files
+
+## Code Standards
+- Match existing code style and conventions
+- Prefer editing existing files over creating new ones
+- Add types for all new parameters and return values
+
+## Testing
+- Write tests for every new function
+- Run existing tests after changes to verify no regressions
+<!-- RULEBOOK:END -->

package/templates/ides/COPILOT_INSTRUCTIONS.md

@@ -0,0 +1,23 @@
+<!-- RULEBOOK:START -->
+# GitHub Copilot — Project Instructions
+
+## Code Style
+- Use TypeScript with strict mode
+- Follow existing naming conventions (camelCase functions, PascalCase classes)
+- Prefer `async/await` over callbacks or raw Promises
+
+## Architecture
+- Follow the module structure described in AGENTS.md
+- Keep functions small and focused (single responsibility)
+- Use dependency injection over direct imports where possible
+
+## Testing
+- Write Vitest tests for all new functions
+- Place tests in `tests/` directory, not alongside source files
+- Mock external dependencies in unit tests
+
+## Security
+- Never commit credentials or API keys
+- Validate all external input at system boundaries
+- Follow OWASP top 10 guidelines
+<!-- RULEBOOK:END -->

package/templates/ides/GEMINI_RULES.md

@@ -0,0 +1,17 @@
+<!-- RULEBOOK:START -->
+# Gemini CLI — Project Directives
+
+## Code Generation Rules
+- Generate TypeScript with strict mode enabled
+- Follow existing file and function naming conventions
+- Always add error handling for async operations
+- Generate tests alongside implementation code
+
+## Quality Standards
+- All code must pass TypeScript type-check
+- All code must pass ESLint without warnings
+- Test coverage must meet project thresholds
+
+## Project Context
+See AGENTS.md for full project architecture and team conventions.
+<!-- RULEBOOK:END -->

package/templates/ides/WINDSURF_RULES.md

@@ -0,0 +1,14 @@
+<!-- RULEBOOK:START -->
+# Windsurf — Project Rules
+
+You are an AI assistant for this project. Follow these rules:
+
+1. Read AGENTS.md for full project context before starting any task
+2. Never create files in the root unless explicitly asked
+3. All TypeScript must be strict-mode compatible
+4. Write tests for new functionality
+5. Run quality checks before marking work complete
+
+## Project Structure
+Follow the existing directory structure. See AGENTS.md for details.
+<!-- RULEBOOK:END -->

package/templates/ides/cursor-mdc/go.mdc

@@ -0,0 +1,24 @@
+---
+description: Go coding standards and best practices
+globs: ["**/*.go"]
+alwaysApply: false
+---
+
+# Go Rules
+
+See `/.rulebook/specs/GO.md` for full requirements.
+
+## Key Rules
+
+- Always check and handle errors (never `_` for error returns)
+- Use `errors.Is()` / `errors.As()` for error comparison
+- Prefer `context.Context` for cancellation and deadlines
+- Use `fmt.Errorf("...: %w", err)` for error wrapping
+- Follow standard Go project layout (`cmd/`, `internal/`, `pkg/`)
+- Run `gofmt` and `golangci-lint` before committing
+
+## Error Handling
+
+- Return errors as last return value
+- Wrap errors with context using `%w`
+- Use sentinel errors for well-known conditions

package/templates/ides/cursor-mdc/python.mdc

@@ -0,0 +1,24 @@
+---
+description: Python coding standards and best practices
+globs: ["**/*.py"]
+alwaysApply: false
+---
+
+# Python Rules
+
+See `/.rulebook/specs/PYTHON.md` for full requirements.
+
+## Key Rules
+
+- Type hints required for all function signatures
+- Use `dataclasses` or `pydantic` for structured data
+- Prefer `pathlib.Path` over `os.path`
+- Use `async/await` for I/O-bound operations
+- Black formatting, ruff linting
+- `__all__` in modules to control public API
+
+## Error Handling
+
+- Use specific exception types (not bare `except`)
+- Validate inputs at module boundaries
+- Log errors with context before re-raising

package/templates/ides/cursor-mdc/quality.mdc

@@ -0,0 +1,25 @@
+---
+description: Quality enforcement rules — type safety, linting, testing, coverage
+alwaysApply: true
+---
+
+# Quality Enforcement
+
+See `/.rulebook/specs/QUALITY_ENFORCEMENT.md` for full requirements.
+
+## Mandatory Quality Gates
+
+Every change MUST pass all quality gates before merge:
+
+1. **Type Check** — `npm run type-check` (zero TypeScript errors)
+2. **Lint** — `npm run lint` (zero ESLint errors)
+3. **Tests** — `npm test` (all tests pass)
+4. **Coverage** — Meet configured threshold (default 75%)
+
+## Code Standards
+
+- No `any` types without explicit justification
+- No unused variables or imports
+- Error handling at system boundaries only
+- No over-engineering: minimum complexity for the task
+- No backwards-compatibility hacks for unused code

package/templates/ides/cursor-mdc/ralph.mdc

@@ -0,0 +1,39 @@
+---
+description: Ralph autonomous loop directives for AI-driven task completion
+alwaysApply: false
+---
+
+# Ralph Autonomous Loop
+
+See `/.rulebook/specs/AGENT_AUTOMATION.md` for full directives.
+
+## Ralph Commands
+
+```bash
+rulebook ralph init     # Initialize autonomous loop
+rulebook ralph run      # Start iterating on tasks
+rulebook ralph status   # Check progress
+rulebook ralph pause    # Pause for manual intervention
+rulebook ralph history  # View past iterations
+```
+
+## PRD Format
+
+Ralph uses `.rulebook/ralph/prd.json` with `userStories[]`:
+
+```json
+{
+  "id": "US-001",
+  "title": "Story Title",
+  "description": "What needs to be done",
+  "acceptanceCriteria": ["Must compile", "Tests pass"],
+  "passes": false
+}
+```
+
+## Quality Gates
+
+All 4 gates MUST pass per iteration:
+- type-check ✓, lint ✓, tests ✓, coverage ✓
+
+Failed gates mark the story `passes: false` for retry.

package/templates/ides/cursor-mdc/rulebook.mdc

@@ -0,0 +1,38 @@
+---
+description: Core Rulebook project directives and task management rules
+alwaysApply: true
+---
+
+# Project Agent Directives
+
+Generated by @hivehub/rulebook. See `.rulebook/specs/` for detailed specifications.
+
+## Task Management
+
+All tasks MUST follow the Rulebook task structure:
+
+```
+.rulebook/tasks/<task-id>/
+├── proposal.md         # Why and what changes
+├── tasks.md            # Simple checklist only
+└── specs/<module>/spec.md  # Technical specs
+```
+
+- Use `rulebook task create` to create tasks
+- `tasks.md` contains ONLY simple checklist items
+- Technical details go in `specs/<module>/spec.md`
+- NEVER create README.md or PROCESS.md in task directories
+
+## Quality Gates
+
+Before every commit:
+- `npm run type-check` — TypeScript must compile
+- `npm run lint` — Zero lint errors
+- `npm test` — All tests must pass
+- Coverage threshold must be met
+
+## Spec References
+
+- Core rules: `/.rulebook/specs/RULEBOOK.md`
+- Quality enforcement: `/.rulebook/specs/QUALITY_ENFORCEMENT.md`
+- Git workflow: `/.rulebook/specs/GIT.md`

package/templates/ides/cursor-mdc/rust.mdc

@@ -0,0 +1,24 @@
+---
+description: Rust coding standards and best practices
+globs: ["**/*.rs"]
+alwaysApply: false
+---
+
+# Rust Rules
+
+See `/.rulebook/specs/RUST.md` for full requirements.
+
+## Key Rules
+
+- Prefer `Result<T, E>` over `unwrap()` / `expect()`
+- Use `thiserror` for library errors, `anyhow` for application errors
+- Minimize `clone()` — prefer borrows and lifetimes
+- Use `clippy` with `#![deny(clippy::all)]`
+- Document public API with `///` doc comments
+- Prefer iterator adapters over manual loops
+
+## Error Handling
+
+- Propagate errors with `?` operator
+- Define domain error enums with `thiserror`
+- Never `panic!` in library code

package/templates/ides/cursor-mdc/typescript.mdc

@@ -0,0 +1,25 @@
+---
+description: TypeScript coding standards and best practices
+globs: ["**/*.ts", "**/*.tsx"]
+alwaysApply: false
+---
+
+# TypeScript Rules
+
+See `/.rulebook/specs/TYPESCRIPT.md` for full requirements.
+
+## Key Rules
+
+- Strict mode enabled — all types must be explicit
+- No `any` without justification comment
+- Use `interface` for public API shapes, `type` for unions/aliases
+- Prefer `async/await` over raw Promises
+- Use `readonly` for immutable data
+- `path.join()` for file paths (never string concatenation)
+- Export only what is needed (avoid barrel re-exports)
+
+## Error Handling
+
+- Validate at system boundaries (user input, external APIs)
+- Use typed error classes for domain errors
+- Never swallow errors silently

package/templates/modules/sequential-thinking.md

@@ -0,0 +1,42 @@
+<!-- SEQUENTIAL_THINKING:START -->
+# Sequential Thinking MCP
+
+Sequential thinking MCP enables structured, step-by-step problem solving for complex tasks.
+
+## When to Use
+
+Use sequential thinking for:
+- Complex architectural decisions requiring multiple trade-off analyses
+- Debugging hard-to-reproduce issues
+- Planning multi-step implementations before writing code
+- Tasks where mistakes are costly (data migrations, API changes)
+
+## Usage Pattern
+
+```
+mcp__sequential-thinking__sequentialthinking
+```
+
+Call with a thought/problem to explore it step by step before committing to an implementation.
+
+## Integration
+
+When sequential thinking MCP is available:
+1. Start complex tasks with a thinking step to plan the approach
+2. Use it to validate assumptions before writing code
+3. Record key decisions from the thinking process in task spec files
+
+## Install (if not configured)
+
+```bash
+# Add to .mcp.json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"]
+    }
+  }
+}
+```
+<!-- SEQUENTIAL_THINKING:END -->

package/templates/ralph/ralph-history.bat

@@ -0,0 +1,4 @@
+@echo off
+REM Ralph History — View iteration history
+REM Generated by @hivehub/rulebook
+npx @hivehub/rulebook@latest ralph history %*

package/templates/ralph/ralph-history.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Ralph History — View iteration history
+# Generated by @hivehub/rulebook
+echo "Loading Ralph history..."
+npx @hivehub/rulebook@latest ralph history "$@"

package/templates/ralph/ralph-init.bat

@@ -0,0 +1,5 @@
+@echo off
+REM Ralph Init — Initialize autonomous loop
+REM Generated by @hivehub/rulebook
+echo Initializing Ralph autonomous loop...
+npx @hivehub/rulebook@latest ralph init %*

package/templates/ralph/ralph-init.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Ralph Init — Initialize autonomous loop
+# Generated by @hivehub/rulebook
+echo "Initializing Ralph autonomous loop..."
+npx @hivehub/rulebook@latest ralph init "$@"

package/templates/ralph/ralph-pause.bat

@@ -0,0 +1,5 @@
+@echo off
+REM Ralph Pause — Pause autonomous loop
+REM Generated by @hivehub/rulebook
+echo Pausing Ralph autonomous loop...
+npx @hivehub/rulebook@latest ralph pause %*

package/templates/ralph/ralph-pause.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Ralph Pause — Pause autonomous loop
+# Generated by @hivehub/rulebook
+echo "Pausing Ralph autonomous loop..."
+npx @hivehub/rulebook@latest ralph pause "$@"

package/templates/ralph/ralph-run.bat

@@ -0,0 +1,5 @@
+@echo off
+REM Ralph Run — Start autonomous loop
+REM Generated by @hivehub/rulebook
+echo Starting Ralph autonomous loop...
+npx @hivehub/rulebook@latest ralph run %*

package/templates/ralph/ralph-run.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Ralph Run — Start autonomous loop
+# Generated by @hivehub/rulebook
+echo "Starting Ralph autonomous loop..."
+npx @hivehub/rulebook@latest ralph run "$@"

package/templates/ralph/ralph-status.bat

@@ -0,0 +1,4 @@
+@echo off
+REM Ralph Status — Check loop status
+REM Generated by @hivehub/rulebook
+npx @hivehub/rulebook@latest ralph status %*

package/templates/ralph/ralph-status.sh

@@ -0,0 +1,5 @@
+#!/bin/sh
+# Ralph Status — Check loop status
+# Generated by @hivehub/rulebook
+echo "Checking Ralph status..."
+npx @hivehub/rulebook@latest ralph status "$@"

package/templates/services/DATADOG.md

@@ -0,0 +1,26 @@
+<!-- DATADOG:START -->
+# Datadog — APM and Monitoring
+
+## Initialization
+- Import `dd-trace` as the FIRST import in application entry point
+- Configure via environment variables: `DD_AGENT_HOST`, `DD_TRACE_AGENT_PORT`, `DD_ENV`, `DD_SERVICE`, `DD_VERSION`
+
+## Tracing
+- Use automatic instrumentation for Express, pg, Redis, etc.
+- Add manual traces for business-critical operations:
+  ```typescript
+  const tracer = require('dd-trace');
+  const span = tracer.startSpan('operation.name');
+  ```
+
+## Logs
+- Inject trace IDs into log records for correlation:
+  ```typescript
+  const span = tracer.scope().active();
+  if (span) log.info({ dd: { trace_id: span.context().toTraceId(), span_id: span.context().toSpanId() }, message });
+  ```
+
+## Custom Metrics
+- Use `dogstatsd-client` for custom metrics: counters, gauges, histograms
+- Tag metrics with `env`, `service`, `version` for consistent filtering
+<!-- DATADOG:END -->