@hivehub/rulebook 5.1.3 → 5.2.1

package/templates/modules/VECTORIZER.md

@@ -1,63 +1,63 @@
-<!-- VECTORIZER:START -->
-# Vectorizer Instructions
-
-**CRITICAL**: Use MCP Vectorizer as primary data source for project information instead of file reading.
-
-## Core Functions
-
-### Search
-```
-mcp_vectorizer_search - Multiple strategies:
-  - intelligent: AI-powered with query expansion
-  - semantic: Advanced with reranking  
-  - contextual: Context-aware with filtering
-  - multi_collection: Cross-project search
-  - batch: Parallel queries
-  - by_file_type: Filter by extension (.rs, .ts, .py)
-```
-
-### File Operations
-```
-get_content - Retrieve file without disk I/O
-list_files - List indexed files with metadata
-get_summary - File summaries (extractive/structural)
-get_chunks - Progressive reading of large files
-get_outline - Project structure overview
-get_related - Find semantically related files
-```
-
-### Discovery
-```
-full_pipeline - Complete discovery with scoring
-broad_discovery - Multi-query with deduplication
-semantic_focus - Deep semantic search
-expand_queries - Generate query variations
-```
-
-## When to Use
-
-| Task | Tool |
-|------|------|
-| Explore unfamiliar code | intelligent search |
-| Read file | get_content |
-| Understand structure | get_outline |
-| Find related files | get_related |
-| Read large file | get_chunks |
-| Complex question | full_pipeline |
-
-## Best Practices
-
-✅ **DO:**
-- Start with intelligent search for exploration
-- Use file_operations to avoid disk I/O
-- Batch queries for related items
-- Set similarity thresholds (0.6-0.8)
-- Use specific collections when known
-
-❌ **DON'T:**
-- Read files from disk when available in vectorizer
-- Use sequential searches (batch instead)
-- Skip similarity thresholds
-- Search entire codebase when collection is known
-
-<!-- VECTORIZER:END -->
+<!-- VECTORIZER:START -->
+# Vectorizer Instructions
+
+**CRITICAL**: Use MCP Vectorizer as primary data source for project information instead of file reading.
+
+## Core Functions
+
+### Search
+```
+mcp_vectorizer_search - Multiple strategies:
+  - intelligent: AI-powered with query expansion
+  - semantic: Advanced with reranking  
+  - contextual: Context-aware with filtering
+  - multi_collection: Cross-project search
+  - batch: Parallel queries
+  - by_file_type: Filter by extension (.rs, .ts, .py)
+```
+
+### File Operations
+```
+get_content - Retrieve file without disk I/O
+list_files - List indexed files with metadata
+get_summary - File summaries (extractive/structural)
+get_chunks - Progressive reading of large files
+get_outline - Project structure overview
+get_related - Find semantically related files
+```
+
+### Discovery
+```
+full_pipeline - Complete discovery with scoring
+broad_discovery - Multi-query with deduplication
+semantic_focus - Deep semantic search
+expand_queries - Generate query variations
+```
+
+## When to Use
+
+| Task | Tool |
+|------|------|
+| Explore unfamiliar code | intelligent search |
+| Read file | get_content |
+| Understand structure | get_outline |
+| Find related files | get_related |
+| Read large file | get_chunks |
+| Complex question | full_pipeline |
+
+## Best Practices
+
+✅ **DO:**
+- Start with intelligent search for exploration
+- Use file_operations to avoid disk I/O
+- Batch queries for related items
+- Set similarity thresholds (0.6-0.8)
+- Use specific collections when known
+
+❌ **DON'T:**
+- Read files from disk when available in vectorizer
+- Use sequential searches (batch instead)
+- Skip similarity thresholds
+- Search entire codebase when collection is known
+
+<!-- VECTORIZER:END -->

package/templates/modules/sequential-thinking.md

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

@@ -1,4 +1,4 @@
-@echo off
-REM Ralph History — View iteration history
-REM Generated by @hivehub/rulebook
-npx @hivehub/rulebook@latest ralph history %*
+@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

@@ -1,5 +1,5 @@
-#!/bin/sh
-# Ralph History — View iteration history
-# Generated by @hivehub/rulebook
-echo "Loading Ralph history..."
-npx @hivehub/rulebook@latest ralph history "$@"
+#!/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

@@ -1,5 +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 %*
+@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

@@ -1,5 +1,5 @@
-#!/bin/sh
-# Ralph Init — Initialize autonomous loop
-# Generated by @hivehub/rulebook
-echo "Initializing Ralph autonomous loop..."
-npx @hivehub/rulebook@latest ralph init "$@"
+#!/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

@@ -1,5 +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 %*
+@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

@@ -1,5 +1,5 @@
-#!/bin/sh
-# Ralph Pause — Pause autonomous loop
-# Generated by @hivehub/rulebook
-echo "Pausing Ralph autonomous loop..."
-npx @hivehub/rulebook@latest ralph pause "$@"
+#!/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

@@ -1,5 +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 %*
+@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

@@ -1,5 +1,5 @@
-#!/bin/sh
-# Ralph Run — Start autonomous loop
-# Generated by @hivehub/rulebook
-echo "Starting Ralph autonomous loop..."
-npx @hivehub/rulebook@latest ralph run "$@"
+#!/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

@@ -1,4 +1,4 @@
-@echo off
-REM Ralph Status — Check loop status
-REM Generated by @hivehub/rulebook
-npx @hivehub/rulebook@latest ralph status %*
+@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

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

package/templates/rules/follow-task-sequence.md

@@ -1,36 +1,36 @@
----
-name: follow-task-sequence
-tier: 1
-description: "Execute tasks in the exact order defined — no reordering, no cherry-picking"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Follow Task Sequence — No Reordering, No Cherry-Picking
-
-When a `tasks.md` checklist defines a sequence, execute items in EXACTLY that order.
-
-## Forbidden
-
-- Skipping ahead to "easier" or "more interesting" tasks
-- Reordering tasks because you think a different order is better
-- Cherry-picking tasks from the middle of a list
-- Deciding which tasks are "important enough" to do
-- Grouping or batching tasks in a different sequence
-- Starting Phase N+1 before Phase N is 100% complete
-
-## Required Behavior
-
-1. Read `tasks.md` from top to bottom
-2. Find the FIRST unchecked item (`- [ ]`)
-3. Implement THAT item — not the one you prefer
-4. Mark it `[x]` with what was done
-5. Move to the NEXT unchecked item
-6. Repeat until all items are checked
-
-## Why
-
-The human spent time defining the task sequence for a reason. The order reflects dependencies, priorities, and a deliberate implementation strategy. When AI agents skip around, dependencies break, progress tracking becomes unreliable, and work has to be redone.
-
-**The task list is an ORDER, not a MENU.**
+---
+name: follow-task-sequence
+tier: 1
+description: "Execute tasks in the exact order defined — no reordering, no cherry-picking"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Follow Task Sequence — No Reordering, No Cherry-Picking
+
+When a `tasks.md` checklist defines a sequence, execute items in EXACTLY that order.
+
+## Forbidden
+
+- Skipping ahead to "easier" or "more interesting" tasks
+- Reordering tasks because you think a different order is better
+- Cherry-picking tasks from the middle of a list
+- Deciding which tasks are "important enough" to do
+- Grouping or batching tasks in a different sequence
+- Starting Phase N+1 before Phase N is 100% complete
+
+## Required Behavior
+
+1. Read `tasks.md` from top to bottom
+2. Find the FIRST unchecked item (`- [ ]`)
+3. Implement THAT item — not the one you prefer
+4. Mark it `[x]` with what was done
+5. Move to the NEXT unchecked item
+6. Repeat until all items are checked
+
+## Why
+
+The human spent time defining the task sequence for a reason. The order reflects dependencies, priorities, and a deliberate implementation strategy. When AI agents skip around, dependencies break, progress tracking becomes unreliable, and work has to be redone.
+
+**The task list is an ORDER, not a MENU.**

package/templates/rules/git-safety.md

@@ -1,29 +1,29 @@
----
-name: git-safety
-tier: 1
-description: "Git safety — explicit allow-list, forbidden destructive operations"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Git Safety Rules
-
-## Allowed (always safe)
-- `git status`, `git diff`, `git log`, `git blame`
-- `git add <files>`, `git commit` (after quality checks)
-
-## Forbidden (require explicit user authorization)
-- `git stash` — hidden state gets forgotten
-- `git rebase` — rewrites history
-- `git reset --hard` — destroys uncommitted changes
-- `git checkout -- .` / `git restore .` — discards all changes
-- `git revert` — creates unexpected commits
-- `git cherry-pick` — can cause conflicts
-- `git merge` — requires human judgment
-- `git branch -D` — permanent branch deletion
-- `git push --force` — NEVER on main/master
-- `git clean -f` — permanently deletes untracked files
-- `git checkout <branch>` / `git switch` — breaks concurrent AI sessions
-
-Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.
+---
+name: git-safety
+tier: 1
+description: "Git safety — explicit allow-list, forbidden destructive operations"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Git Safety Rules
+
+## Allowed (always safe)
+- `git status`, `git diff`, `git log`, `git blame`
+- `git add <files>`, `git commit` (after quality checks)
+
+## Forbidden (require explicit user authorization)
+- `git stash` — hidden state gets forgotten
+- `git rebase` — rewrites history
+- `git reset --hard` — destroys uncommitted changes
+- `git checkout -- .` / `git restore .` — discards all changes
+- `git revert` — creates unexpected commits
+- `git cherry-pick` — can cause conflicts
+- `git merge` — requires human judgment
+- `git branch -D` — permanent branch deletion
+- `git push --force` — NEVER on main/master
+- `git clean -f` — permanently deletes untracked files
+- `git checkout <branch>` / `git switch` — breaks concurrent AI sessions
+
+Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.

package/templates/rules/incremental-tests.md

@@ -1,29 +1,29 @@
----
-name: incremental-tests
-tier: 2
-description: "Write tests in small batches, verify immediately"
-alwaysApply: true
-filePatterns: ["*.test.*", "*.spec.*", "*_test.*"]
-tools: ["all"]
----
-
-# Incremental Test Development
-
-Write tests 1-3 at a time. Test immediately after writing. Fix errors before proceeding.
-
-## Rules
-
-1. **Write 1-3 tests** at a time, NOT entire test files at once
-2. **Run immediately** after writing — use single-file test execution
-3. **Fix errors** before writing more tests
-4. **Never run full suite** while developing tests — use individual file execution
-5. **Coverage updates** only after completing a block of tests
-
-## Why
-
-Writing full test files at once leads to cascading failures. One early error invalidates all subsequent tests, creating debug fatigue and wasted time.
-
-## Development Testing vs Validation Testing
-
-- **Development**: Run single test file (`vitest run tests/my.test.ts`)
-- **Validation**: Run full suite only when a batch of tests is complete
+---
+name: incremental-tests
+tier: 2
+description: "Write tests in small batches, verify immediately"
+alwaysApply: true
+filePatterns: ["*.test.*", "*.spec.*", "*_test.*"]
+tools: ["all"]
+---
+
+# Incremental Test Development
+
+Write tests 1-3 at a time. Test immediately after writing. Fix errors before proceeding.
+
+## Rules
+
+1. **Write 1-3 tests** at a time, NOT entire test files at once
+2. **Run immediately** after writing — use single-file test execution
+3. **Fix errors** before writing more tests
+4. **Never run full suite** while developing tests — use individual file execution
+5. **Coverage updates** only after completing a block of tests
+
+## Why
+
+Writing full test files at once leads to cascading failures. One early error invalidates all subsequent tests, creating debug fatigue and wasted time.
+
+## Development Testing vs Validation Testing
+
+- **Development**: Run single test file (`vitest run tests/my.test.ts`)
+- **Validation**: Run full suite only when a batch of tests is complete

package/templates/rules/knowledge-base-usage.md

@@ -0,0 +1,41 @@
+# Always use the knowledge base — read before implementing, write after learning
+
+# Knowledge Base Usage — Mandatory for All Implementation Work
+
+The knowledge base (`rulebook knowledge` + `rulebook learn`) is the project's institutional memory. It prevents repeating mistakes and ensures proven patterns are reused.
+
+## BEFORE Starting Any Implementation
+
+1. **Check existing knowledge**: `rulebook knowledge list`
+2. **Search for relevant learnings**: `rulebook learn list`
+3. **Apply patterns** that match your task — do NOT reinvent approaches that are already documented
+4. **Avoid anti-patterns** — if a documented anti-pattern matches your planned approach, STOP and choose a different path
+
+## DURING Implementation
+
+When you discover something non-obvious:
+- A workaround for a framework limitation → `rulebook learn capture`
+- A debugging technique that saved time → `rulebook learn capture`
+- A pattern that emerged and worked well → `rulebook knowledge add pattern`
+- An approach that failed → `rulebook knowledge add anti-pattern`
+
+## AFTER Completing a Task (before archive)
+
+**Minimum 1 entry per task**. Record at least one of:
+- `rulebook knowledge add pattern "<what worked>"` — reusable approach
+- `rulebook knowledge add anti-pattern "<what failed>"` — approach to avoid
+- `rulebook learn capture --title "<title>" --content "<insight>"` — implementation insight
+- `rulebook decision create` — if a significant architectural choice was made
+
+## Forbidden
+
+- Starting implementation without checking `rulebook knowledge list`
+- Archiving a task without capturing at least one learning
+- Ignoring documented anti-patterns and repeating known mistakes
+- Discovering a useful pattern and not recording it
+
+## Why
+
+Without the knowledge base, every session starts from zero. AI agents repeat the same mistakes, rediscover the same patterns, and waste cycles on approaches that were already tried and failed. The knowledge base is what makes the project smarter over time.
+
+**"Those who cannot remember the past are condemned to repeat it."**

package/templates/rules/no-deferred.md

@@ -1,31 +1,31 @@
----
-name: no-deferred
-tier: 2
-description: "Never defer tasks — implement or explain why impossible"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# No Deferred Tasks
-
-If a task is in the checklist, **implement it**. No exceptions.
-
-## Forbidden
-
-- Marking tasks as "Deferred"
-- Writing "Deferred — requires X"
-- Skipping tasks with excuses
-- Partial implementations with "will do later"
-
-## Required Behavior
-
-If a task has a genuine dependency:
-1. Implement the dependency FIRST
-2. Then implement the task
-3. Mark BOTH as done
-
-If you truly cannot implement something:
-1. Explain WHY in concrete terms
-2. Propose an alternative solution
-3. Do NOT just write "Deferred"
+---
+name: no-deferred
+tier: 2
+description: "Never defer tasks — implement or explain why impossible"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# No Deferred Tasks
+
+If a task is in the checklist, **implement it**. No exceptions.
+
+## Forbidden
+
+- Marking tasks as "Deferred"
+- Writing "Deferred — requires X"
+- Skipping tasks with excuses
+- Partial implementations with "will do later"
+
+## Required Behavior
+
+If a task has a genuine dependency:
+1. Implement the dependency FIRST
+2. Then implement the task
+3. Mark BOTH as done
+
+If you truly cannot implement something:
+1. Explain WHY in concrete terms
+2. Propose an alternative solution
+3. Do NOT just write "Deferred"