@hivehub/rulebook 5.8.2 → 6.0.0

package/templates/skills/modules/vectorizer/SKILL.md

@@ -1,73 +1,73 @@
----
-name: "Vectorizer"
-description: "Use MCP Vectorizer as primary data source for project information instead of file reading."
-version: "1.0.0"
-category: "modules"
-author: "Rulebook"
-tags: ["modules", "mcp"]
-dependencies: []
-conflicts: []
----
-<!-- 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 -->
+---
+name: "Vectorizer"
+description: "Use MCP Vectorizer as primary data source for project information instead of file reading."
+version: "1.0.0"
+category: "modules"
+author: "Rulebook"
+tags: ["modules", "mcp"]
+dependencies: []
+conflicts: []
+---
+<!-- 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/.claude/commands/analysis.md

@@ -1,35 +0,0 @@
-# /analysis — Structured analysis workflow
-
-Create a structured analysis for a topic. Scaffolds `docs/analysis/<slug>/` with skeleton files (README.md, findings.md, execution-plan.md, manifest.json).
-
-## Usage
-
-```
-/analysis <topic>
-```
-
-## What it does
-
-1. Slugifies the topic (e.g. "Auth Refactor v2" → `auth-refactor-v2`)
-2. Creates `docs/analysis/<slug>/` with:
-   - **README.md** — executive summary, methodology, conclusion
-   - **findings.md** — numbered findings F-001..F-NNN (title, evidence, impact, confidence)
-   - **execution-plan.md** — phased implementation plan
-   - **manifest.json** — metadata (agents, timestamps, version)
-3. Idempotent: re-running updates manifest but preserves user-edited content files
-
-## After scaffolding
-
-1. Fill `findings.md` with investigation results
-2. Design the phases in `execution-plan.md`
-3. Create implementation tasks from the plan: `rulebook task create phase1_<slug>-<name>`
-4. Each task should reference the analysis: `Source: docs/analysis/<slug>/README.md#F-NNN`
-5. Before implementing, consult the knowledge base: `rulebook_knowledge_list` filtered by `analysis:<slug>`
-
-## MCP equivalent
-
-```
-rulebook_analysis_create({ topic: "<topic>" })
-rulebook_analysis_list()
-rulebook_analysis_show({ slug: "<slug>" })
-```

package/.claude/commands/continue.md

@@ -1,33 +0,0 @@
----
-name: /continue
-id: continue
-category: Rulebook
-description: Update tasks.md, archive completed tasks, and continue implementation.
----
-<!-- RULEBOOK:START -->
-**Steps**
-
-1. **Update tasks.md for all active tasks**:
-   - Mark completed items as `[x]` in every active `tasks.md`
-   - Remove or update items that are no longer relevant
-
-2. **Archive fully completed tasks**:
-   For each task where ALL items are `[x]`:
-   ```bash
-   rulebook task archive <task-id>
-   ```
-
-3. **Get current session context**:
-   ```bash
-   rulebook continue
-   ```
-   Use this output to understand what's pending and what was done.
-
-4. **Continue implementation**:
-   - Pick the next pending task from the context above
-   - Work through its `tasks.md` checklist item by item
-   - Follow priority order: tests → coverage → update tasks.md → commit
-
-**Reference**
-- See `/.rulebook/specs/RULEBOOK.md` for complete task management guidelines
-<!-- RULEBOOK:END -->

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

@@ -1,55 +0,0 @@
----
-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 +0,0 @@
----
-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 +0,0 @@
----
-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 +0,0 @@
----
-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,41 +0,0 @@
----
-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) 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
-```
-
-**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 +0,0 @@
----
-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/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 +0,0 @@
----
-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 -->

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

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