@hivehub/rulebook 5.4.1 → 5.5.0

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

@@ -1,47 +1,47 @@
----
-name: /rulebook-memory-search
-id: rulebook-memory-search
-category: Rulebook
-description: Search persistent memories using hybrid BM25+vector search for context across sessions.
----
-<!-- RULEBOOK:START -->
-**Guardrails**
-- Use the MCP memory tools when available (preferred over CLI commands).
-- The memory system uses 3-layer search: Layer 1 (compact search), Layer 2 (timeline), Layer 3 (full details).
-- Always start with a broad search, then narrow down with timeline and full details.
-
-**Steps**
-1. **Search memories** using the MCP tool or CLI:
-   ```
-   # Via MCP (preferred)
-   rulebook_memory_search({ query: "search terms", mode: "hybrid", limit: 20 })
-
-   # Via CLI
-   rulebook memory search "search terms" --mode hybrid --limit 20
-   ```
-   Modes: `hybrid` (default, best results), `bm25` (keyword only), `vector` (semantic only).
-
-2. **Get timeline context** around a relevant result:
-   ```
-   rulebook_memory_timeline({ memoryId: "<id>", window: 5 })
-   ```
-
-3. **Get full details** for specific memories:
-   ```
-   rulebook_memory_get({ ids: ["<id1>", "<id2>"] })
-   ```
-
-**Memory Types**
-- `bugfix` - Bug fixes and error resolutions
-- `feature` - New features and capabilities
-- `refactor` - Code restructuring
-- `decision` - Architecture/design decisions (protected from eviction)
-- `discovery` - Findings about codebase or tools
-- `change` - General code changes
-- `observation` - General observations
-
-**Reference**
-- Use `rulebook memory stats` to check database health
-- Decisions are never evicted during cleanup
-- Privacy: content within `<private>...</private>` tags is automatically redacted
-<!-- RULEBOOK:END -->
+---
+name: /rulebook-memory-search
+id: rulebook-memory-search
+category: Rulebook
+description: Search persistent memories using hybrid BM25+vector search for context across sessions.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Use the MCP memory tools when available (preferred over CLI commands).
+- The memory system uses 3-layer search: Layer 1 (compact search), Layer 2 (timeline), Layer 3 (full details).
+- Always start with a broad search, then narrow down with timeline and full details.
+
+**Steps**
+1. **Search memories** using the MCP tool or CLI:
+   ```
+   # Via MCP (preferred)
+   rulebook_memory_search({ query: "search terms", mode: "hybrid", limit: 20 })
+
+   # Via CLI
+   rulebook memory search "search terms" --mode hybrid --limit 20
+   ```
+   Modes: `hybrid` (default, best results), `bm25` (keyword only), `vector` (semantic only).
+
+2. **Get timeline context** around a relevant result:
+   ```
+   rulebook_memory_timeline({ memoryId: "<id>", window: 5 })
+   ```
+
+3. **Get full details** for specific memories:
+   ```
+   rulebook_memory_get({ ids: ["<id1>", "<id2>"] })
+   ```
+
+**Memory Types**
+- `bugfix` - Bug fixes and error resolutions
+- `feature` - New features and capabilities
+- `refactor` - Code restructuring
+- `decision` - Architecture/design decisions (protected from eviction)
+- `discovery` - Findings about codebase or tools
+- `change` - General code changes
+- `observation` - General observations
+
+**Reference**
+- Use `rulebook memory stats` to check database health
+- Decisions are never evicted during cleanup
+- Privacy: content within `<private>...</private>` tags is automatically redacted
+<!-- RULEBOOK:END -->

package/.claude/commands/rulebook-task-apply.md

@@ -1,67 +1,67 @@
----
-name: /rulebook-task-apply
-id: rulebook-task-apply
-category: Rulebook
-description: Implement an approved Rulebook task and keep tasks checklist in sync.
----
-<!-- 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.
-- Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines.
-- **CRITICAL**: Update `tasks.md` IMMEDIATELY after completing and testing each implementation step.
-
-**Steps**
-Track these steps as TODOs and complete them one by one.
-
-1. **Read Task Details**:
-   ```bash
-   rulebook task show <task-id>
-   ```
-   Read `proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
-
-2. **Follow Priority Order (MANDATORY)**:
-   - **Tests** (HIGHEST PRIORITY) - Write tests first
-   - **Coverage Verification** (CRITICAL) - Verify coverage ≥95%
-   - **Update Task Status** (MANDATORY) - Mark completed items as `[x]` in `tasks.md`
-   - **Next Task** (Only after above steps)
-
-3. **Work Through Tasks Sequentially**:
-   - Work through `tasks.md` checklist item by item
-   - Keep edits minimal and focused on the requested change
-   - Follow priority order (most critical first)
-
-4. **After Each Implementation Step**:
-   - ✅ Implement the feature
-   - ✅ Test the implementation
-   - ✅ Verify test coverage (run `npm test -- --coverage`)
-   - ✅ Update `tasks.md` IMMEDIATELY (mark as `[x]`)
-   - ✅ Commit locally (backup)
-   - ✅ Only then proceed to next task
-
-5. **Update Tasks Checklist**:
-   After completing and testing each item:
-   ```markdown
-   ## 1. Implementation Phase
-   - [x] 1.1 Create task manager module <!-- tested, coverage: 95% -->
-   - [x] 1.2 Add validation logic <!-- tested, coverage: 92%, status: complete -->
-   - [ ] 1.3 Add archive functionality <!-- next: will start after status update -->
-   ```
-
-6. **Confirm Completion**:
-   - Make sure every item in `tasks.md` is finished
-   - All tests pass
-   - Coverage meets thresholds
-   - Documentation updated
-
-7. **Update Checklist After All Work**:
-   - Mark each completed task as `[x]`
-   - Add comments with test status and coverage
-   - Reflect reality in the checklist
-
-**Reference**
-- Use `rulebook task show <task-id>` when additional context is required
-- Use `rulebook task validate <task-id>` to check format before archiving
-- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines and priority order
-<!-- RULEBOOK:END -->
-
+---
+name: /rulebook-task-apply
+id: rulebook-task-apply
+category: Rulebook
+description: Implement an approved Rulebook task and keep tasks checklist in sync.
+---
+<!-- 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.
+- Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines.
+- **CRITICAL**: Update `tasks.md` IMMEDIATELY after completing and testing each implementation step.
+
+**Steps**
+Track these steps as TODOs and complete them one by one.
+
+1. **Read Task Details**:
+   ```bash
+   rulebook task show <task-id>
+   ```
+   Read `proposal.md`, `design.md` (if present), and `tasks.md` to confirm scope and acceptance criteria.
+
+2. **Follow Priority Order (MANDATORY)**:
+   - **Tests** (HIGHEST PRIORITY) - Write tests first
+   - **Coverage Verification** (CRITICAL) - Verify coverage ≥95%
+   - **Update Task Status** (MANDATORY) - Mark completed items as `[x]` in `tasks.md`
+   - **Next Task** (Only after above steps)
+
+3. **Work Through Tasks Sequentially**:
+   - Work through `tasks.md` checklist item by item
+   - Keep edits minimal and focused on the requested change
+   - Follow priority order (most critical first)
+
+4. **After Each Implementation Step**:
+   - ✅ Implement the feature
+   - ✅ Test the implementation
+   - ✅ Verify test coverage (run `npm test -- --coverage`)
+   - ✅ Update `tasks.md` IMMEDIATELY (mark as `[x]`)
+   - ✅ Commit locally (backup)
+   - ✅ Only then proceed to next task
+
+5. **Update Tasks Checklist**:
+   After completing and testing each item:
+   ```markdown
+   ## 1. Implementation Phase
+   - [x] 1.1 Create task manager module <!-- tested, coverage: 95% -->
+   - [x] 1.2 Add validation logic <!-- tested, coverage: 92%, status: complete -->
+   - [ ] 1.3 Add archive functionality <!-- next: will start after status update -->
+   ```
+
+6. **Confirm Completion**:
+   - Make sure every item in `tasks.md` is finished
+   - All tests pass
+   - Coverage meets thresholds
+   - Documentation updated
+
+7. **Update Checklist After All Work**:
+   - Mark each completed task as `[x]`
+   - Add comments with test status and coverage
+   - Reflect reality in the checklist
+
+**Reference**
+- Use `rulebook task show <task-id>` when additional context is required
+- Use `rulebook task validate <task-id>` to check format before archiving
+- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines and priority order
+<!-- RULEBOOK:END -->
+

package/.claude/commands/rulebook-task-archive.md

@@ -1,94 +1,94 @@
----
-name: /rulebook-task-archive
-id: rulebook-task-archive
-category: Rulebook
-description: Archive a completed Rulebook task and apply spec deltas to main specifications.
----
-<!-- 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.
-- Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines.
-
-**Steps**
-1. **Verify Task Completion**:
-   - All items in `tasks.md` must be marked as `[x]`
-   - All tests must pass
-   - Code review complete (if applicable)
-   - Documentation updated (README, CHANGELOG, specs)
-
-2. **Run Quality Checks**:
-   ```bash
-   npm test
-   npm run lint
-   npm run type-check
-   npm run build
-   ```
-   Ensure all checks pass before archiving.
-
-3. **Validate Task Format**:
-   ```bash
-   rulebook task validate <task-id>
-   ```
-   Must pass all format checks.
-
-4. **Archive Task**:
-   ```bash
-   rulebook task archive <task-id>
-   ```
-   Or without prompts:
-   ```bash
-   rulebook task archive <task-id> --skip-validation
-   ```
-   (Only use `--skip-validation` if you're certain the task is valid)
-
-5. **Archive Process**:
-   - Validates task format (unless skipped)
-   - Checks task completion status
-   - Applies spec deltas to main specifications
-   - Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
-   - Updates related specifications
-
-6. **Verify Archive**:
-   ```bash
-   rulebook task list --archived
-   ```
-   Task should appear in archived list.
-
-7. **Post-Archive Actions**:
-   - Ensure spec deltas are applied to main specifications
-   - Update CHANGELOG.md with the change
-   - Document any breaking changes
-   - Create migration guides (if needed)
-   - Unblock related tasks (if any)
-
-8. **🚨 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**.
-
-   ```
-   ❌ 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
-   ```
-
-   **Archive Checklist (ALL must be done before archiving):**
-   ```
-   □ 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
-   ```
-
-**Reference**
-- Use `rulebook task list --archived` to see archived tasks
-- Use `rulebook task show <task-id>` to view task details
-- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
-<!-- RULEBOOK:END -->
-
+---
+name: /rulebook-task-archive
+id: rulebook-task-archive
+category: Rulebook
+description: Archive a completed Rulebook task and apply spec deltas to main specifications.
+---
+<!-- 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.
+- Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines.
+
+**Steps**
+1. **Verify Task Completion**:
+   - All items in `tasks.md` must be marked as `[x]`
+   - All tests must pass
+   - Code review complete (if applicable)
+   - Documentation updated (README, CHANGELOG, specs)
+
+2. **Run Quality Checks**:
+   ```bash
+   npm test
+   npm run lint
+   npm run type-check
+   npm run build
+   ```
+   Ensure all checks pass before archiving.
+
+3. **Validate Task Format**:
+   ```bash
+   rulebook task validate <task-id>
+   ```
+   Must pass all format checks.
+
+4. **Archive Task**:
+   ```bash
+   rulebook task archive <task-id>
+   ```
+   Or without prompts:
+   ```bash
+   rulebook task archive <task-id> --skip-validation
+   ```
+   (Only use `--skip-validation` if you're certain the task is valid)
+
+5. **Archive Process**:
+   - Validates task format (unless skipped)
+   - Checks task completion status
+   - Applies spec deltas to main specifications
+   - Moves task to `/.rulebook/tasks/archive/YYYY-MM-DD-<task-id>/`
+   - Updates related specifications
+
+6. **Verify Archive**:
+   ```bash
+   rulebook task list --archived
+   ```
+   Task should appear in archived list.
+
+7. **Post-Archive Actions**:
+   - Ensure spec deltas are applied to main specifications
+   - Update CHANGELOG.md with the change
+   - Document any breaking changes
+   - Create migration guides (if needed)
+   - Unblock related tasks (if any)
+
+8. **🚨 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**.
+
+   ```
+   ❌ 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
+   ```
+
+   **Archive Checklist (ALL must be done before archiving):**
+   ```
+   □ 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
+   ```
+
+**Reference**
+- Use `rulebook task list --archived` to see archived tasks
+- Use `rulebook task show <task-id>` to view task details
+- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
+<!-- RULEBOOK:END -->
+

package/.claude/commands/rulebook-task-create.md

@@ -1,93 +1,93 @@
----
-name: /rulebook-task-create
-id: rulebook-task-create
-category: Rulebook
-description: Create a new Rulebook task following OpenSpec-compatible format with Context7 MCP validation.
----
-<!-- 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.
-- Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines and format requirements.
-- **CRITICAL**: Context7 MCP is REQUIRED for task creation to ensure correct OpenSpec-compatible format.
-- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
-
-**Steps**
-1. **Check Context7 MCP (MANDATORY)**: Query Context7 for OpenSpec documentation to get the official format:
-   ```
-   @Context7 /fission-ai/openspec task creation format spec structure
-   ```
-   Review official format requirements: spec delta format, requirement structure, scenario formatting, delta headers (ADDED/MODIFIED/REMOVED/RENAMED).
-
-2. **Explore Current State**: 
-   - Run `rulebook task list` to see existing tasks
-   - Review related code or docs (e.g., via `rg`/`ls`) to understand current behavior
-   - Note any gaps that require clarification
-
-3. **Choose Task ID**: Use verb-led kebab-case (e.g., `add-feature`, `update-api`, `refactor-module`). Must be unique.
-
-4. **Create Task Structure**:
-   ```bash
-   rulebook task create <task-id>
-   ```
-   This creates `/.rulebook/tasks/<task-id>/` with:
-   - `proposal.md` - Why and what changes
-   - `tasks.md` - Implementation checklist
-   - `specs/` - Directory for spec deltas
-
-5. **Write Proposal** (`proposal.md`):
-   - **Why**: Minimum 20 characters explaining why this change is needed
-   - **What Changes**: Detailed description of what will change
-   - **Impact**: Affected specs, code, breaking changes, user benefits
-
-6. **Write Tasks Checklist** (`tasks.md`):
-   - Organize by phases (Implementation, Testing, Documentation)
-   - Use checkbox format: `- [ ] Task description`
-   - Include validation steps (tests, coverage checks)
-
-7. **Write Spec Delta** (`specs/<module>/spec.md`):
-   - Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers
-   - Requirements MUST use `### Requirement: [Name]` with SHALL/MUST keywords
-   - Scenarios MUST use `#### Scenario:` (4 hashtags, NOT 3)
-   - Scenarios MUST use Given/When/Then structure
-   - Example:
-     ```markdown
-     ## ADDED Requirements
-     
-     ### Requirement: Feature Name
-     The system SHALL do something specific and testable.
-     
-     #### Scenario: Scenario Name
-     Given some precondition
-     When an action occurs
-     Then an expected outcome happens
-     ```
-
-8. **Validate Task**:
-   ```bash
-   rulebook task validate <task-id>
-   ```
-   Fix any validation errors before proceeding.
-
-9. **Verify Format**:
-   - Purpose section: ≥20 characters ✅
-   - Requirements: Contain SHALL or MUST ✅
-   - Scenarios: Use `#### Scenario:` (4 hashtags) ✅
-   - Scenarios: Use Given/When/Then structure ✅
-   - Delta headers: Use ADDED/MODIFIED/REMOVED/RENAMED ✅
-
-**Reference**
-- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
-- Use `rulebook task show <task-id>` to view task details
-- Use `rulebook task list` to see all tasks
-- Search existing requirements with `rg -n "Requirement:|Scenario:" .rulebook/tasks` before writing new ones
-- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities
-
-**Common Pitfalls to Avoid**
-- ❌ Using 3 hashtags for scenarios (`### Scenario:`) - MUST use 4 (`#### Scenario:`)
-- ❌ Missing SHALL/MUST keywords in requirements
-- ❌ Using bullet points for scenarios instead of Given/When/Then
-- ❌ Purpose section too short (<20 characters)
-- ❌ Wrong delta headers (use ADDED/MODIFIED/REMOVED/RENAMED, not "New Requirements" or "Changes")
-<!-- RULEBOOK:END -->
-
+---
+name: /rulebook-task-create
+id: rulebook-task-create
+category: Rulebook
+description: Create a new Rulebook task following OpenSpec-compatible format with Context7 MCP validation.
+---
+<!-- 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.
+- Refer to `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines and format requirements.
+- **CRITICAL**: Context7 MCP is REQUIRED for task creation to ensure correct OpenSpec-compatible format.
+- Identify any vague or ambiguous details and ask the necessary follow-up questions before editing files.
+
+**Steps**
+1. **Check Context7 MCP (MANDATORY)**: Query Context7 for OpenSpec documentation to get the official format:
+   ```
+   @Context7 /fission-ai/openspec task creation format spec structure
+   ```
+   Review official format requirements: spec delta format, requirement structure, scenario formatting, delta headers (ADDED/MODIFIED/REMOVED/RENAMED).
+
+2. **Explore Current State**: 
+   - Run `rulebook task list` to see existing tasks
+   - Review related code or docs (e.g., via `rg`/`ls`) to understand current behavior
+   - Note any gaps that require clarification
+
+3. **Choose Task ID**: Use verb-led kebab-case (e.g., `add-feature`, `update-api`, `refactor-module`). Must be unique.
+
+4. **Create Task Structure**:
+   ```bash
+   rulebook task create <task-id>
+   ```
+   This creates `/.rulebook/tasks/<task-id>/` with:
+   - `proposal.md` - Why and what changes
+   - `tasks.md` - Implementation checklist
+   - `specs/` - Directory for spec deltas
+
+5. **Write Proposal** (`proposal.md`):
+   - **Why**: Minimum 20 characters explaining why this change is needed
+   - **What Changes**: Detailed description of what will change
+   - **Impact**: Affected specs, code, breaking changes, user benefits
+
+6. **Write Tasks Checklist** (`tasks.md`):
+   - Organize by phases (Implementation, Testing, Documentation)
+   - Use checkbox format: `- [ ] Task description`
+   - Include validation steps (tests, coverage checks)
+
+7. **Write Spec Delta** (`specs/<module>/spec.md`):
+   - Use `## ADDED|MODIFIED|REMOVED|RENAMED Requirements` headers
+   - Requirements MUST use `### Requirement: [Name]` with SHALL/MUST keywords
+   - Scenarios MUST use `#### Scenario:` (4 hashtags, NOT 3)
+   - Scenarios MUST use Given/When/Then structure
+   - Example:
+     ```markdown
+     ## ADDED Requirements
+     
+     ### Requirement: Feature Name
+     The system SHALL do something specific and testable.
+     
+     #### Scenario: Scenario Name
+     Given some precondition
+     When an action occurs
+     Then an expected outcome happens
+     ```
+
+8. **Validate Task**:
+   ```bash
+   rulebook task validate <task-id>
+   ```
+   Fix any validation errors before proceeding.
+
+9. **Verify Format**:
+   - Purpose section: ≥20 characters ✅
+   - Requirements: Contain SHALL or MUST ✅
+   - Scenarios: Use `#### Scenario:` (4 hashtags) ✅
+   - Scenarios: Use Given/When/Then structure ✅
+   - Delta headers: Use ADDED/MODIFIED/REMOVED/RENAMED ✅
+
+**Reference**
+- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
+- Use `rulebook task show <task-id>` to view task details
+- Use `rulebook task list` to see all tasks
+- Search existing requirements with `rg -n "Requirement:|Scenario:" .rulebook/tasks` before writing new ones
+- Explore the codebase with `rg <keyword>`, `ls`, or direct file reads so proposals align with current implementation realities
+
+**Common Pitfalls to Avoid**
+- ❌ Using 3 hashtags for scenarios (`### Scenario:`) - MUST use 4 (`#### Scenario:`)
+- ❌ Missing SHALL/MUST keywords in requirements
+- ❌ Using bullet points for scenarios instead of Given/When/Then
+- ❌ Purpose section too short (<20 characters)
+- ❌ Wrong delta headers (use ADDED/MODIFIED/REMOVED/RENAMED, not "New Requirements" or "Changes")
+<!-- RULEBOOK:END -->
+