@hivehub/rulebook 5.4.0 → 5.4.1

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

@@ -1,76 +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 -->
+---
+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-decision-create.md

@@ -1,55 +1,55 @@
----
-name: /rulebook-decision-create
-id: rulebook-decision-create
-category: Rulebook
-description: Create a new Architecture Decision Record (ADR) with auto-numbering and memory integration.
----
-<!-- RULEBOOK:START -->
-**Guardrails**
-- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
-- Keep changes tightly scoped to the requested outcome.
-- Decisions are stored in `.rulebook/decisions/` as numbered Markdown files with metadata sidecars.
-
-**Steps**
-1. **Understand the Decision**: Ask the user what architectural/technical decision needs to be recorded. Gather:
-   - **Title**: Short, descriptive name (e.g., "Use PostgreSQL for Primary Database")
-   - **Context**: Why this decision is needed — constraints, requirements, trade-offs
-   - **Decision**: What was decided
-   - **Alternatives**: What other options were considered and why they were rejected
-   - **Consequences**: What follows from this decision (positive and negative)
-   - **Related Tasks**: Any task IDs this decision relates to
-
-2. **Check Existing Decisions**:
-   ```bash
-   rulebook decision list
-   ```
-   Verify no duplicate or conflicting decision exists.
-
-3. **Create the Decision**:
-   ```bash
-   rulebook decision create "<title>" --context "<context>" --related-task <task-id>
-   ```
-   The system auto-numbers the decision (e.g., ADR-001, ADR-002).
-
-4. **Enrich the Decision File**: Open the generated `.rulebook/decisions/NNN-<slug>.md` and fill in:
-   - Context section with full background
-   - Decision section with the chosen approach
-   - Alternatives Considered with reasoning for each rejected option
-   - Consequences with both positive and negative outcomes
-
-5. **Update Status** (if immediately accepted):
-   ```bash
-   # Via MCP tool or direct metadata edit
-   ```
-
-6. **Verify**:
-   ```bash
-   rulebook decision show <id>
-   ```
-
-**Reference**
-- Decisions use 4 statuses: `proposed` → `accepted` → `superseded` | `deprecated`
-- Use `rulebook decision supersede <oldId> <newId>` to replace a decision
-- Decisions are auto-injected into AGENTS.md on `rulebook update`
-- See `/.rulebook/specs/DECISIONS.md` for format documentation
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-decision-create
+id: rulebook-decision-create
+category: Rulebook
+description: Create a new Architecture Decision Record (ADR) with auto-numbering and memory integration.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Decisions are stored in `.rulebook/decisions/` as numbered Markdown files with metadata sidecars.
+
+**Steps**
+1. **Understand the Decision**: Ask the user what architectural/technical decision needs to be recorded. Gather:
+   - **Title**: Short, descriptive name (e.g., "Use PostgreSQL for Primary Database")
+   - **Context**: Why this decision is needed — constraints, requirements, trade-offs
+   - **Decision**: What was decided
+   - **Alternatives**: What other options were considered and why they were rejected
+   - **Consequences**: What follows from this decision (positive and negative)
+   - **Related Tasks**: Any task IDs this decision relates to
+
+2. **Check Existing Decisions**:
+   ```bash
+   rulebook decision list
+   ```
+   Verify no duplicate or conflicting decision exists.
+
+3. **Create the Decision**:
+   ```bash
+   rulebook decision create "<title>" --context "<context>" --related-task <task-id>
+   ```
+   The system auto-numbers the decision (e.g., ADR-001, ADR-002).
+
+4. **Enrich the Decision File**: Open the generated `.rulebook/decisions/NNN-<slug>.md` and fill in:
+   - Context section with full background
+   - Decision section with the chosen approach
+   - Alternatives Considered with reasoning for each rejected option
+   - Consequences with both positive and negative outcomes
+
+5. **Update Status** (if immediately accepted):
+   ```bash
+   # Via MCP tool or direct metadata edit
+   ```
+
+6. **Verify**:
+   ```bash
+   rulebook decision show <id>
+   ```
+
+**Reference**
+- Decisions use 4 statuses: `proposed` → `accepted` → `superseded` | `deprecated`
+- Use `rulebook decision supersede <oldId> <newId>` to replace a decision
+- Decisions are auto-injected into AGENTS.md on `rulebook update`
+- See `/.rulebook/specs/DECISIONS.md` for format documentation
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-decision-list.md

@@ -1,15 +1,15 @@
----
-name: /rulebook-decision-list
-id: rulebook-decision-list
-category: Rulebook
-description: List all Architecture Decision Records with optional status filter.
----
-<!-- RULEBOOK:START -->
-**Steps**
-1. Run `rulebook decision list` to see all decisions.
-2. Optionally filter: `rulebook decision list --status accepted`
-3. Present results to the user with ID, title, and status.
-4. If the user wants details on a specific decision, run `rulebook decision show <id>`.
-
-**Status Values**: proposed, accepted, superseded, deprecated
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-decision-list
+id: rulebook-decision-list
+category: Rulebook
+description: List all Architecture Decision Records with optional status filter.
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook decision list` to see all decisions.
+2. Optionally filter: `rulebook decision list --status accepted`
+3. Present results to the user with ID, title, and status.
+4. If the user wants details on a specific decision, run `rulebook decision show <id>`.
+
+**Status Values**: proposed, accepted, superseded, deprecated
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-knowledge-add.md

@@ -1,41 +1,41 @@
----
-name: /rulebook-knowledge-add
-id: rulebook-knowledge-add
-category: Rulebook
-description: Add a pattern or anti-pattern to the project knowledge base.
----
-<!-- RULEBOOK:START -->
-**Guardrails**
-- Knowledge entries are auto-injected into AGENTS.md on `rulebook update`, making them visible to all AI assistants.
-- Patterns go to `.rulebook/knowledge/patterns/`, anti-patterns to `.rulebook/knowledge/anti-patterns/`.
-
-**Steps**
-1. **Determine Type**: Ask if this is a `pattern` (good practice to follow) or `anti-pattern` (bad practice to avoid).
-
-2. **Gather Details**:
-   - **Title**: Short, descriptive name (e.g., "Repository Pattern", "God Object")
-   - **Category**: `architecture` | `code` | `testing` | `security` | `performance` | `devops`
-   - **Description**: What the pattern/anti-pattern is
-   - **Example**: Code showing correct (or incorrect) usage
-   - **When to Use**: Situations where this applies
-   - **When NOT to Use**: Exceptions and edge cases
-   - **Tags**: For searchability
-
-3. **Create Entry**:
-   ```bash
-   rulebook knowledge add <type> "<title>" --category <category> --description "<desc>"
-   ```
-
-4. **Enrich the Entry**: Open `.rulebook/knowledge/<type>s/<slug>.md` and fill in Example, When to Use, and When NOT to Use sections with concrete code examples.
-
-5. **Verify**:
-   ```bash
-   rulebook knowledge show <slug>
-   ```
-
-**Reference**
-- Use `rulebook knowledge list` to see all entries
-- Use `rulebook knowledge list --type pattern --category architecture` to filter
-- Use `rulebook knowledge remove <slug>` to delete an entry
-- Entries appear in AGENTS.md "Project Knowledge" section after `rulebook update`
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-knowledge-add
+id: rulebook-knowledge-add
+category: Rulebook
+description: Add a pattern or anti-pattern to the project knowledge base.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Knowledge entries are auto-injected into AGENTS.md on `rulebook update`, making them visible to all AI assistants.
+- Patterns go to `.rulebook/knowledge/patterns/`, anti-patterns to `.rulebook/knowledge/anti-patterns/`.
+
+**Steps**
+1. **Determine Type**: Ask if this is a `pattern` (good practice to follow) or `anti-pattern` (bad practice to avoid).
+
+2. **Gather Details**:
+   - **Title**: Short, descriptive name (e.g., "Repository Pattern", "God Object")
+   - **Category**: `architecture` | `code` | `testing` | `security` | `performance` | `devops`
+   - **Description**: What the pattern/anti-pattern is
+   - **Example**: Code showing correct (or incorrect) usage
+   - **When to Use**: Situations where this applies
+   - **When NOT to Use**: Exceptions and edge cases
+   - **Tags**: For searchability
+
+3. **Create Entry**:
+   ```bash
+   rulebook knowledge add <type> "<title>" --category <category> --description "<desc>"
+   ```
+
+4. **Enrich the Entry**: Open `.rulebook/knowledge/<type>s/<slug>.md` and fill in Example, When to Use, and When NOT to Use sections with concrete code examples.
+
+5. **Verify**:
+   ```bash
+   rulebook knowledge show <slug>
+   ```
+
+**Reference**
+- Use `rulebook knowledge list` to see all entries
+- Use `rulebook knowledge list --type pattern --category architecture` to filter
+- Use `rulebook knowledge remove <slug>` to delete an entry
+- Entries appear in AGENTS.md "Project Knowledge" section after `rulebook update`
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-knowledge-list.md

@@ -1,15 +1,15 @@
----
-name: /rulebook-knowledge-list
-id: rulebook-knowledge-list
-category: Rulebook
-description: List project knowledge entries (patterns and anti-patterns).
----
-<!-- RULEBOOK:START -->
-**Steps**
-1. Run `rulebook knowledge list` to see all entries.
-2. Optionally filter:
-   - By type: `rulebook knowledge list --type pattern`
-   - By category: `rulebook knowledge list --category architecture`
-3. Present results with type badge, title, and category.
-4. If the user wants details, run `rulebook knowledge show <slug>`.
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-knowledge-list
+id: rulebook-knowledge-list
+category: Rulebook
+description: List project knowledge entries (patterns and anti-patterns).
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook knowledge list` to see all entries.
+2. Optionally filter:
+   - By type: `rulebook knowledge list --type pattern`
+   - By category: `rulebook knowledge list --category architecture`
+3. Present results with type badge, title, and category.
+4. If the user wants details, run `rulebook knowledge show <slug>`.
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-learn-capture.md

@@ -1,48 +1,48 @@
----
-name: /rulebook-learn-capture
-id: rulebook-learn-capture
-category: Rulebook
-description: Capture a learning from implementation work for future reference.
----
-<!-- RULEBOOK:START -->
-**Guardrails**
-- Learnings are saved to both the memory system and `.rulebook/learnings/` for offline backup.
-- Learnings can be promoted to patterns/decisions later via `rulebook learn promote`.
-
-**Steps**
-1. **Gather the Learning**:
-   - **Title**: Short description of what was learned
-   - **Content**: Full explanation — what happened, what was discovered, why it matters
-   - **Tags**: Keywords for searchability
-   - **Related Task**: Task ID if this learning came from a specific task
-   - **Source**: `manual` (default), `ralph`, or `task-archive`
-
-2. **Capture**:
-   ```bash
-   rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2" --related-task <task-id>
-   ```
-
-3. **Verify**:
-   ```bash
-   rulebook learn list --limit 5
-   ```
-
-**Promotion Flow**
-If a learning is significant enough to become a team pattern or decision:
-```bash
-rulebook learn promote <id> knowledge    # → creates a pattern
-rulebook learn promote <id> decision     # → creates an ADR
-```
-
-**Ralph Integration**
-Extract learnings from Ralph autonomous loop history:
-```bash
-rulebook learn from-ralph
-```
-This reads `.rulebook/ralph/history/iteration-*.json` and captures entries with non-empty learnings.
-
-**Reference**
-- Learnings are searchable via `rulebook memory search`
-- Use `rulebook learn list` to see all learnings
-- Learnings captured during `rulebook task archive` have source `task-archive`
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-learn-capture
+id: rulebook-learn-capture
+category: Rulebook
+description: Capture a learning from implementation work for future reference.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Learnings are saved to both the memory system and `.rulebook/learnings/` for offline backup.
+- Learnings can be promoted to patterns/decisions later via `rulebook learn promote`.
+
+**Steps**
+1. **Gather the Learning**:
+   - **Title**: Short description of what was learned
+   - **Content**: Full explanation — what happened, what was discovered, why it matters
+   - **Tags**: Keywords for searchability
+   - **Related Task**: Task ID if this learning came from a specific task
+   - **Source**: `manual` (default), `ralph`, or `task-archive`
+
+2. **Capture**:
+   ```bash
+   rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2" --related-task <task-id>
+   ```
+
+3. **Verify**:
+   ```bash
+   rulebook learn list --limit 5
+   ```
+
+**Promotion Flow**
+If a learning is significant enough to become a team pattern or decision:
+```bash
+rulebook learn promote <id> knowledge    # → creates a pattern
+rulebook learn promote <id> decision     # → creates an ADR
+```
+
+**Ralph Integration**
+Extract learnings from Ralph autonomous loop history:
+```bash
+rulebook learn from-ralph
+```
+This reads `.rulebook/ralph/history/iteration-*.json` and captures entries with non-empty learnings.
+
+**Reference**
+- Learnings are searchable via `rulebook memory search`
+- Use `rulebook learn list` to see all learnings
+- Learnings captured during `rulebook task archive` have source `task-archive`
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-learn-list.md

@@ -1,13 +1,13 @@
----
-name: /rulebook-learn-list
-id: rulebook-learn-list
-category: Rulebook
-description: List captured learnings with source and promotion status.
----
-<!-- RULEBOOK:START -->
-**Steps**
-1. Run `rulebook learn list` to see all learnings (newest first).
-2. Optionally limit: `rulebook learn list --limit 10`
-3. Present results with source badge (manual/ralph/archive) and promotion status.
-4. Suggest promotion for significant learnings: `rulebook learn promote <id> knowledge|decision`
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-learn-list
+id: rulebook-learn-list
+category: Rulebook
+description: List captured learnings with source and promotion status.
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook learn list` to see all learnings (newest first).
+2. Optionally limit: `rulebook learn list --limit 10`
+3. Present results with source badge (manual/ralph/archive) and promotion status.
+4. Suggest promotion for significant learnings: `rulebook learn promote <id> knowledge|decision`
+<!-- RULEBOOK:END -->

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

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