@hivehub/rulebook 2.0.0 → 3.0.0

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

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

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

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

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

@@ -8,7 +8,7 @@ description: Implement an approved Rulebook task and keep tasks checklist in syn
 **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/RULEBOOK.md` for complete task management guidelines.
+- Refer to `/rulebook/specs/RULEBOOK.md` for complete task management guidelines.
 - **CRITICAL**: Update `tasks.md` IMMEDIATELY after completing and testing each implementation step.
 
 **Steps**
@@ -62,6 +62,6 @@ Track these steps as TODOs and complete them one by one.
 **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/RULEBOOK.md` for complete task management guidelines and priority order
+- See `/rulebook/specs/RULEBOOK.md` for complete task management guidelines and priority order
 <!-- RULEBOOK:END -->
 

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

@@ -8,7 +8,7 @@ description: Archive a completed Rulebook task and apply spec deltas to main spe
 **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/RULEBOOK.md` for complete task management guidelines.
+- Refer to `/rulebook/specs/RULEBOOK.md` for complete task management guidelines.
 
 **Steps**
 1. **Verify Task Completion**:
@@ -65,6 +65,6 @@ description: Archive a completed Rulebook task and apply spec deltas to main spe
 **Reference**
 - Use `rulebook task list --archived` to see archived tasks
 - Use `rulebook task show <task-id>` to view task details
-- See `/rulebook/RULEBOOK.md` for complete task management guidelines
+- See `/rulebook/specs/RULEBOOK.md` for complete task management guidelines
 <!-- RULEBOOK:END -->
 

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

@@ -8,7 +8,7 @@ description: Create a new Rulebook task following OpenSpec-compatible format wit
 **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/RULEBOOK.md` for complete task management guidelines and format requirements.
+- 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.
 
@@ -77,7 +77,7 @@ description: Create a new Rulebook task following OpenSpec-compatible format wit
    - Delta headers: Use ADDED/MODIFIED/REMOVED/RENAMED ✅
 
 **Reference**
-- See `/rulebook/RULEBOOK.md` for complete task management guidelines
+- 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

package/templates/commands/rulebook-task-list.md

@@ -8,7 +8,7 @@ description: List all Rulebook tasks (active and optionally archived).
 **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/RULEBOOK.md` for complete task management guidelines.
+- Refer to `/rulebook/specs/RULEBOOK.md` for complete task management guidelines.
 
 **Steps**
 1. **List Active Tasks**:
@@ -37,6 +37,6 @@ description: List all Rulebook tasks (active and optionally archived).
 **Reference**
 - Use `rulebook task show <task-id>` to view task details
 - Use `rulebook task validate <task-id>` to check task format
-- See `/rulebook/RULEBOOK.md` for complete task management guidelines
+- See `/rulebook/specs/RULEBOOK.md` for complete task management guidelines
 <!-- RULEBOOK:END -->
 

package/templates/commands/rulebook-task-show.md

@@ -8,7 +8,7 @@ description: Show detailed information about a specific Rulebook task.
 **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/RULEBOOK.md` for complete task management guidelines.
+- Refer to `/rulebook/specs/RULEBOOK.md` for complete task management guidelines.
 
 **Steps**
 1. **Show Task Details**:
@@ -47,6 +47,6 @@ description: Show detailed information about a specific Rulebook task.
 **Reference**
 - Use `rulebook task list` to see all tasks
 - Use `rulebook task validate <task-id>` to check task format
-- See `/rulebook/RULEBOOK.md` for complete task management guidelines
+- See `/rulebook/specs/RULEBOOK.md` for complete task management guidelines
 <!-- RULEBOOK:END -->
 

package/templates/commands/rulebook-task-validate.md

@@ -8,7 +8,7 @@ description: Validate Rulebook task format against OpenSpec-compatible requireme
 **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/RULEBOOK.md` for complete task management guidelines and format requirements.
+- Refer to `/rulebook/specs/RULEBOOK.md` for complete task management guidelines and format requirements.
 
 **Steps**
 1. **Validate Task Format**:
@@ -46,7 +46,7 @@ description: Validate Rulebook task format against OpenSpec-compatible requireme
    - ❌ `## New Requirements` → ✅ `## ADDED Requirements`
 
 **Reference**
-- See `/rulebook/RULEBOOK.md` for complete format requirements
+- See `/rulebook/specs/RULEBOOK.md` for complete format requirements
 - Use Context7 MCP to get official OpenSpec format documentation
 - Use `rulebook task show <task-id>` to view task details
 <!-- RULEBOOK:END -->

package/templates/git/CI_CD_PATTERNS.md

@@ -655,7 +655,7 @@ npx @hivehub/rulebook workflows
 
 ## Related Templates
 
-- See `/rulebook/GITHUB_ACTIONS.md` for GitHub Actions specifics
-- See `/rulebook/GITLAB_CI.md` for GitLab CI specifics
-- See `/rulebook/SECRETS_MANAGEMENT.md` for secrets handling
-- See `/rulebook/QUALITY_ENFORCEMENT.md` for quality standards
+- See `/rulebook/specs/GITHUB_ACTIONS.md` for GitHub Actions specifics
+- See `/rulebook/specs/GITLAB_CI.md` for GitLab CI specifics
+- See `/rulebook/specs/SECRETS_MANAGEMENT.md` for secrets handling
+- See `/rulebook/specs/QUALITY_ENFORCEMENT.md` for quality standards

package/templates/git/GITHUB_ACTIONS.md

@@ -722,7 +722,7 @@ npx @hivehub/rulebook workflows
 
 ## Related Templates
 
-- See `/rulebook/CI_CD_PATTERNS.md` for common CI/CD patterns
-- See `/rulebook/SECRETS_MANAGEMENT.md` for secrets handling
-- See `/rulebook/QUALITY_ENFORCEMENT.md` for quality gates
+- See `/rulebook/specs/CI_CD_PATTERNS.md` for common CI/CD patterns
+- See `/rulebook/specs/SECRETS_MANAGEMENT.md` for secrets handling
+- See `/rulebook/specs/QUALITY_ENFORCEMENT.md` for quality gates
 - See language-specific templates for test/build commands

package/templates/git/GITLAB_CI.md

@@ -724,7 +724,7 @@ npx @hivehub/rulebook workflows
 
 ## Related Templates
 
-- See `/rulebook/GITHUB_ACTIONS.md` for GitHub Actions comparison
-- See `/rulebook/CI_CD_PATTERNS.md` for general CI/CD patterns
-- See `/rulebook/SECRETS_MANAGEMENT.md` for secrets handling
-- See `/rulebook/QUALITY_ENFORCEMENT.md` for quality gates
+- See `/rulebook/specs/GITHUB_ACTIONS.md` for GitHub Actions comparison
+- See `/rulebook/specs/CI_CD_PATTERNS.md` for general CI/CD patterns
+- See `/rulebook/specs/SECRETS_MANAGEMENT.md` for secrets handling
+- See `/rulebook/specs/QUALITY_ENFORCEMENT.md` for quality gates

package/templates/git/SECRETS_MANAGEMENT.md

@@ -579,7 +579,7 @@ AWS_SECRET_ACCESS_KEY=your-secret-key
 
 ## Related Templates
 
-- See `/rulebook/GITHUB_ACTIONS.md` for GitHub Actions secrets
-- See `/rulebook/GITLAB_CI.md` for GitLab CI secrets
-- See `/rulebook/CI_CD_PATTERNS.md` for deployment patterns
-- See `/rulebook/GIT.md` for .gitignore patterns
+- See `/rulebook/specs/GITHUB_ACTIONS.md` for GitHub Actions secrets
+- See `/rulebook/specs/GITLAB_CI.md` for GitLab CI secrets
+- See `/rulebook/specs/CI_CD_PATTERNS.md` for deployment patterns
+- See `/rulebook/specs/GIT.md` for .gitignore patterns

package/templates/hooks/COMMIT_MSG.md

@@ -524,7 +524,7 @@ npx @hivehub/rulebook init
 
 ## Related Templates
 
-- See `/rulebook/PRE_COMMIT.md` for quality checks before commit
-- See `/rulebook/PREPARE_COMMIT_MSG.md` for auto-generating commit messages
-- See `/rulebook/GIT.md` for git workflow and commit conventions
-- See `/rulebook/DOCUMENTATION_RULES.md` for changelog generation from commits
+- See `/rulebook/specs/PRE_COMMIT.md` for quality checks before commit
+- See `/rulebook/specs/PREPARE_COMMIT_MSG.md` for auto-generating commit messages
+- See `/rulebook/specs/GIT.md` for git workflow and commit conventions
+- See `/rulebook/specs/DOCUMENTATION_RULES.md` for changelog generation from commits

package/templates/hooks/POST_CHECKOUT.md

@@ -540,7 +540,7 @@ npx @hivehub/rulebook init
 
 ## Related Templates
 
-- See `/rulebook/PRE_COMMIT.md` for pre-commit quality checks
-- See `/rulebook/PRE_PUSH.md` for pre-push validation
-- See `/rulebook/GIT.md` for git workflow
+- See `/rulebook/specs/PRE_COMMIT.md` for pre-commit quality checks
+- See `/rulebook/specs/PRE_PUSH.md` for pre-push validation
+- See `/rulebook/specs/GIT.md` for git workflow
 - See language-specific templates for dependency management commands

package/templates/hooks/PREPARE_COMMIT_MSG.md

@@ -614,6 +614,6 @@ npx @hivehub/rulebook init
 
 ## Related Templates
 
-- See `/rulebook/COMMIT_MSG.md` for commit message validation
-- See `/rulebook/GIT.md` for git workflow and branch naming
-- See `/rulebook/PRE_COMMIT.md` for pre-commit checks
+- See `/rulebook/specs/COMMIT_MSG.md` for commit message validation
+- See `/rulebook/specs/GIT.md` for git workflow and branch naming
+- See `/rulebook/specs/PRE_COMMIT.md` for pre-commit checks

package/templates/hooks/PRE_COMMIT.md

@@ -407,8 +407,8 @@ Hook configuration in `.rulebook`:
 
 ## Related Templates
 
-- See `/rulebook/PRE_PUSH.md` for build and test checks before push
-- See `/rulebook/COMMIT_MSG.md` for commit message validation
-- See `/rulebook/QUALITY_ENFORCEMENT.md` for quality standards
-- See `/rulebook/GIT.md` for git workflow and commit conventions
+- See `/rulebook/specs/PRE_PUSH.md` for build and test checks before push
+- See `/rulebook/specs/COMMIT_MSG.md` for commit message validation
+- See `/rulebook/specs/QUALITY_ENFORCEMENT.md` for quality standards
+- See `/rulebook/specs/GIT.md` for git workflow and commit conventions
 - See language-specific templates for language-specific quality commands

package/templates/hooks/PRE_PUSH.md

@@ -594,8 +594,8 @@ Hook configuration in `.rulebook`:
 
 ## Related Templates
 
-- See `/rulebook/PRE_COMMIT.md` for fast quality checks before commit
-- See `/rulebook/QUALITY_ENFORCEMENT.md` for quality standards
-- See `/rulebook/GIT.md` for git workflow and conventions
-- See `/rulebook/GITHUB_ACTIONS.md` for CI/CD integration
+- See `/rulebook/specs/PRE_COMMIT.md` for fast quality checks before commit
+- See `/rulebook/specs/QUALITY_ENFORCEMENT.md` for quality standards
+- See `/rulebook/specs/GIT.md` for git workflow and conventions
+- See `/rulebook/specs/GITHUB_ACTIONS.md` for CI/CD integration
 - See language-specific templates for test commands and coverage tools

package/templates/modules/MEMORY.md

@@ -0,0 +1,63 @@
+<!-- MEMORY:START -->
+## Persistent Memory System
+
+The rulebook memory system provides persistent context across AI sessions using hybrid search (BM25 keyword + HNSW vector) with zero native dependencies.
+
+### 3-Layer Search Pattern (Token-Efficient)
+
+**Layer 1 — Compact Search**: Get brief results to scan relevance.
+```
+rulebook_memory_search({ query: "authentication bug", mode: "hybrid", limit: 10 })
+→ Returns: { id, title, type, score, matchType, createdAt } per result (~50 tokens each)
+```
+
+**Layer 2 — Timeline**: Get chronological context around a memory.
+```
+rulebook_memory_timeline({ memoryId: "abc-123", window: 5 })
+→ Returns: 5 memories before + anchor + 5 memories after (~200 tokens each)
+```
+
+**Layer 3 — Full Details**: Get complete content only for selected memories.
+```
+rulebook_memory_get({ ids: ["abc-123", "def-456"] })
+→ Returns: Full memory objects with content (~500-1000 tokens each)
+```
+
+### Memory Types
+
+- **bugfix**: Bug fixes, error resolutions
+- **feature**: New features, additions
+- **refactor**: Code restructuring
+- **decision**: Architectural decisions (protected from eviction)
+- **discovery**: Insights and learnings
+- **change**: Updates and modifications
+- **observation**: General observations
+
+### CLI Commands
+
+```bash
+rulebook memory search "authentication bug"     # Hybrid search
+rulebook memory save "Decided to use sql.js" --type decision --title "DB Choice"
+rulebook memory list --limit 10                  # Recent memories
+rulebook memory stats                            # Database statistics
+rulebook memory cleanup --force                  # Force eviction
+rulebook memory export --format json             # Export all memories
+```
+
+### Configuration (.rulebook)
+
+```json
+{
+  "memory": {
+    "enabled": true,
+    "dbPath": ".rulebook-memory/memory.db",
+    "maxSizeBytes": 524288000,
+    "vectorDimensions": 256
+  }
+}
+```
+
+### Privacy
+
+Content between `<private>` and `</private>` tags is automatically stripped before storage.
+<!-- MEMORY:END -->

package/templates/skills/cli/aider/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: "Aider"
+description: "Tool: AI pair programming in terminal (`pip install aider-chat`)"
+version: "1.0.0"
+category: "cli"
+author: "Rulebook"
+tags: ["cli", "cli-tool"]
+dependencies: []
+conflicts: []
+---
+<!-- AIDER:START -->
+# Aider CLI Rules
+
+**Tool**: AI pair programming in terminal (`pip install aider-chat`)
+
+## Quick Start
+
+```bash
+# Always include AGENTS.md
+aider AGENTS.md src/feature.ts tests/feature.test.ts
+
+# In chat:
+"Follow AGENTS.md standards. Implement [feature] with tests first."
+```
+
+## Essential Commands
+
+```bash
+/add file.ts          # Add files to context
+/drop file.ts         # Remove from context
+/run npm test         # Run command
+/commit "message"     # Commit changes
+/undo                 # Undo last change
+/diff                 # Review changes
+```
+
+## Configuration (.aider.conf.yml)
+
+```yaml
+model: gpt-4
+read: [AGENTS.md]
+lint: true
+lint-cmd: "npm run lint"
+test-cmd: "npm test"
+auto-commits: true
+commit-prompt: true
+```
+
+## Workflow
+
+1. Start session with `aider AGENTS.md [files]`
+2. Request: "Follow AGENTS.md. Implement [feature] with tests first (95%+ coverage)"
+3. Review diffs with `/diff`
+4. Test with `/run npm test`
+5. Commit with `/commit "feat: description"`
+
+**Critical**: Always reference AGENTS.md in your requests for consistent standards.
+
+<!-- AIDER:END -->

package/templates/skills/cli/amazon-q/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: "Amazon Q"
+description: "Tool: AWS-focused AI assistant with security scanning"
+version: "1.0.0"
+category: "cli"
+author: "Rulebook"
+tags: ["cli", "cli-tool"]
+dependencies: []
+conflicts: []
+---
+<!-- AMAZON_Q:START -->
+# Amazon Q Developer Rules
+
+**Tool**: AWS-focused AI assistant with security scanning
+
+## Quick Start
+
+Available in AWS IDE Toolkit or via AWS Console.
+
+## Usage
+
+```
+"Follow @AGENTS.md standards. Implement [feature] with tests (95%+ coverage)."
+```
+
+## Workflow
+
+1. Reference AGENTS.md in prompts
+2. Leverage Q's security scanning for vulnerabilities
+3. Review generated code
+4. Run quality checks
+
+**Critical**: Q excels at AWS/security - combine with AGENTS.md standards.
+
+<!-- AMAZON_Q:END -->

package/templates/skills/cli/auggie/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: "Auggie"
+description: "Tool: TDD mode and intelligent refactoring"
+version: "1.0.0"
+category: "cli"
+author: "Rulebook"
+tags: ["cli", "cli-tool"]
+dependencies: []
+conflicts: []
+---
+<!-- AUGGIE:START -->
+# Auggie (Augment CLI) Rules
+
+**Tool**: TDD mode and intelligent refactoring
+
+## Quick Start
+
+```bash
+npm install -g augment-cli
+augment --tdd
+```
+
+## Usage
+
+```bash
+# TDD mode with AGENTS.md:
+augment --tdd --context AGENTS.md
+
+# In prompts:
+"Follow @AGENTS.md. Write tests for [feature], then implement."
+```
+
+## Workflow
+
+1. Use `--tdd` flag for test-first development
+2. Include `--context AGENTS.md`
+3. Auggie writes tests, then implementation
+4. Review and verify coverage
+
+**Critical**: TDD mode aligns perfectly with AGENTS.md test-first approach.
+
+<!-- AUGGIE:END -->

package/templates/skills/cli/claude/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: "Claude"
+description: "Tool: Anthropic Claude API with 200K context window"
+version: "1.0.0"
+category: "cli"
+author: "Rulebook"
+tags: ["cli", "cli-tool"]
+dependencies: []
+conflicts: []
+---
+<!-- CLAUDE:START -->
+# Claude API/CLI Rules
+
+**Tool**: Anthropic Claude API with 200K context window
+
+## Quick Start
+
+```bash
+export ANTHROPIC_API_KEY=your_key
+# Use via API or compatible CLIs
+```
+
+## Usage
+
+In API requests or CLI prompts, include:
+```
+"Follow these project standards from AGENTS.md:
+[paste relevant AGENTS.md sections]
+
+Implement [feature] with tests first (95%+ coverage)."
+```
+
+## Workflow
+
+1. Include AGENTS.md content in system prompt or context
+2. Request features with standards reference
+3. Review generated code
+4. Run quality checks
+
+**Critical**: Claude has 200K context - paste full AGENTS.md for best results.
+
+<!-- CLAUDE:END -->