@hivehub/rulebook 5.8.2 → 6.0.0

package/templates/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/templates/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/templates/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/templates/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/templates/commands/rulebook-learn-capture.md

@@ -6,7 +6,7 @@ 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 are saved as markdown under `.rulebook/learnings/`, committed with the repo.
 - Learnings can be promoted to patterns/decisions later via `rulebook learn promote`.
 
 **Steps**
@@ -35,7 +35,6 @@ rulebook learn promote <id> decision     # → creates an ADR
 ```
 
 **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/templates/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/templates/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 -->
+