@hivehub/rulebook 5.8.1 → 6.0.0

package/templates/cli/CLAUDE.md

@@ -1,117 +1,102 @@
-<!-- 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
-5. Save learnings to persistent memory
-
-**Critical**: Claude has 200K context - paste full AGENTS.md for best results.
-
-## ⚠️ Token Optimization (CRITICAL)
-
-**MINIMIZE unnecessary output to reduce token consumption:**
-
-### DO ✅
-- Output code directly without explanations
-- Use code comments for complex logic instead of markdown
-- Return results concisely: "✅ Done" or "❌ Error: reason"
-- Use tables only when absolutely necessary
-- Combine multiple small outputs into single response
-
-### DON'T ❌
-- **NEVER generate markdown reports or summaries** unless explicitly requested
-- **NEVER use excessive heading levels** (#, ##, ###, etc.)
-- **NEVER create "Quality Checks" sections** with status boxes
-- **NEVER output commit messages verbatim** - just say "committed"
-- **NEVER explain what you did** - assume user knows project structure
-- **NEVER use emoji status lines** (✅ Type check: Passed) - too verbose
-- **NEVER generate "Next Steps" sections** - just do the work
-- **NEVER output implementation details in plain text** - put in code comments
-
-### Example: BAD (Wastes Tokens)
-```
-✅ Implementation Complete
-
-📝 Changes:
-- Added UserService class
-- Added authentication middleware
-- Updated routes configuration
-
-🧪 Quality Checks:
-- ✅ Type check: Passed
-- ✅ Linting: Passed (0 warnings)
-- ✅ Tests: 45/45 passed (100%)
-- ✅ Coverage: 96% (threshold: 95%)
-
-📊 Summary:
-This implementation adds...
-
-Next Steps:
-1. Review the code
-2. Deploy to production
-```
-
-### Example: GOOD (Efficient)
-```
-✅ Done. UserService added with auth middleware.
-```
-
-Put details in code comments, not markdown.
-
-## Persistent Memory Integration
-
-### Search for Past Context
-Before implementing a feature, search memory for similar past work:
-
-```bash
-# Search for past implementations
-rulebook memory search "feature name" --mode hybrid --type feature
-
-# View timeline of related work
-rulebook memory timeline --memoryId <id>
-```
-
-### Save Implementation Insights
-After completing implementation, capture key learnings:
-
-```bash
-# Save feature implementation
-rulebook memory save "Implemented [feature] with [approach]. Key decision: [why]. Gotcha: [edge case]. Pattern: [reusable solution]" --type feature --title "[Feature name]" --tags tag1,tag2
-
-# Save bugfix insights
-rulebook memory save "Fixed [bug] by [solution]. Root cause: [why it happened]. Test case: [added validation]" --type bugfix --title "[Bug description]" --tags bugfix,area
-
-# Save architectural decisions
-rulebook memory save "Chose [approach] over [alternative] because [reasoning]. Tradeoffs: [what was sacrificed]. Future implications: [impact on architecture]" --type decision --title "[Decision name]" --tags architecture,decision
-```
-
-### Use Context from Memory
-When Claude Code returns, your memory system auto-captures learnings. Review and augment:
-1. Search relevant memories: `rulebook memory search "your topic"`
-2. Review 3-layer search results: compact → timeline → full details
-3. Reference past patterns in new implementations
-
-<!-- CLAUDE:END -->
+<!-- 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
+5. Capture knowledge/learnings/decisions
+
+**Critical**: Claude has 200K context - paste full AGENTS.md for best results.
+
+## ⚠️ Token Optimization (CRITICAL)
+
+**MINIMIZE unnecessary output to reduce token consumption:**
+
+### DO ✅
+- Output code directly without explanations
+- Use code comments for complex logic instead of markdown
+- Return results concisely: "✅ Done" or "❌ Error: reason"
+- Use tables only when absolutely necessary
+- Combine multiple small outputs into single response
+
+### DON'T ❌
+- **NEVER generate markdown reports or summaries** unless explicitly requested
+- **NEVER use excessive heading levels** (#, ##, ###, etc.)
+- **NEVER create "Quality Checks" sections** with status boxes
+- **NEVER output commit messages verbatim** - just say "committed"
+- **NEVER explain what you did** - assume user knows project structure
+- **NEVER use emoji status lines** (✅ Type check: Passed) - too verbose
+- **NEVER generate "Next Steps" sections** - just do the work
+- **NEVER output implementation details in plain text** - put in code comments
+
+### Example: BAD (Wastes Tokens)
+```
+✅ Implementation Complete
+
+📝 Changes:
+- Added UserService class
+- Added authentication middleware
+- Updated routes configuration
+
+🧪 Quality Checks:
+- ✅ Type check: Passed
+- ✅ Linting: Passed (0 warnings)
+- ✅ Tests: 45/45 passed (100%)
+- ✅ Coverage: 96% (threshold: 95%)
+
+📊 Summary:
+This implementation adds...
+
+Next Steps:
+1. Review the code
+2. Deploy to production
+```
+
+### Example: GOOD (Efficient)
+```
+✅ Done. UserService added with auth middleware.
+```
+
+Put details in code comments, not markdown.
+
+## Knowledge Capture
+
+### Review Past Context
+Before implementing a feature, review the file-based knowledge base for similar past work:
+
+```bash
+rulebook knowledge list
+rulebook learn list
+rulebook decision list
+```
+
+### Capture Implementation Insights
+After completing implementation, record key learnings (committed with the repo):
+
+- `rulebook_knowledge_add` — reusable patterns and anti-patterns.
+- `rulebook_learn_capture` — gotchas, edge cases, and performance insights.
+- `rulebook_decision_create` — architectural decisions and their tradeoffs.
+
+<!-- CLAUDE:END -->

package/templates/cli/_GENERIC_TEMPLATE.md

@@ -1,29 +1,29 @@
-<!-- {TOOL}:START -->
-# {Tool Name} CLI Rules
-
-**Tool**: {Brief description}
-
-## Quick Start
-
-```bash
-{installation command}
-```
-
-## Usage
-
-Always reference AGENTS.md in prompts:
-```
-"Follow @AGENTS.md standards. Implement [feature] with tests first (95%+ coverage)."
-```
-
-## Workflow
-
-1. Include AGENTS.md in context (tool-specific method)
-2. Request features with "@AGENTS.md" reference
-3. Review generated code
-4. Run quality checks: `npm run lint && npm test`
-
-**Critical**: Reference AGENTS.md for consistent standards.
-
-<!-- {TOOL}:END -->
-
+<!-- {TOOL}:START -->
+# {Tool Name} CLI Rules
+
+**Tool**: {Brief description}
+
+## Quick Start
+
+```bash
+{installation command}
+```
+
+## Usage
+
+Always reference AGENTS.md in prompts:
+```
+"Follow @AGENTS.md standards. Implement [feature] with tests first (95%+ coverage)."
+```
+
+## Workflow
+
+1. Include AGENTS.md in context (tool-specific method)
+2. Request features with "@AGENTS.md" reference
+3. Review generated code
+4. Run quality checks: `npm run lint && npm test`
+
+**Critical**: Reference AGENTS.md for consistent standards.
+
+<!-- {TOOL}:END -->
+

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 -->