@hivehub/rulebook 5.8.1 → 6.0.0

package/templates/rules/session-workflow.md

@@ -1,24 +1,24 @@
----
-name: session-workflow
-tier: 2
-description: "Read PLANS.md at session start, save summary at session end"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Session Workflow — Preserve Context Across Sessions
-
-## At Session Start
-1. Read `.rulebook/PLANS.md` for current context and active task
-2. Search memory for relevant past work: `rulebook_memory_search` or `rulebook_session_start`
-3. Check `.rulebook/tasks/` for pending work
-
-## During Session
-- Update PLANS.md when making key decisions or discoveries
-- Save important context to memory as you go
-
-## At Session End
-1. Save session summary to PLANS.md: `rulebook_session_end`
-2. Summary should include: what was accomplished, key decisions, next steps
-3. Update tasks.md with completed items
+---
+name: session-workflow
+tier: 2
+description: "Read PLANS.md at session start, save summary at session end"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Session Workflow — Preserve Context Across Sessions
+
+## At Session Start
+1. Read `.rulebook/PLANS.md` for current context and active task
+2. `rulebook_session_start` loads relevant prior context
+3. Check `.rulebook/tasks/` for pending work
+
+## During Session
+- Update PLANS.md when making key decisions or discoveries
+- Capture knowledge/learnings as you go (`rulebook_knowledge_add` / `rulebook_learn_capture`)
+
+## At Session End
+1. Save session summary to PLANS.md: `rulebook_session_end`
+2. Summary should include: what was accomplished, key decisions, next steps
+3. Update tasks.md with completed items

package/templates/rules/task-decomposition.md

@@ -1,32 +1,32 @@
----
-name: task-decomposition
-tier: 2
-description: "Decompose multi-file tasks into 1-2 file sub-tasks"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Task Decomposition
-
-When a task touches multiple subsystems, decompose into sub-tasks where each modifies **at most 1-2 files**.
-
-## Why
-
-AI agents lose accuracy when editing 3+ files in one pass. Context from earlier files gets compressed away.
-
-## Rules
-
-1. **Each sub-task modifies 1-2 files** — never more
-2. **Each sub-task is independently verifiable** — it compiles, it doesn't break existing behavior
-3. **Sub-tasks follow data flow order** — upstream first (component → buffer → renderer → shader)
-4. **Each sub-task has a clear "done when"** — not "implement X", but "field Y exists with default Z"
-5. **Build after each sub-task** — verify compilation before proceeding
-
-## When an Agent Receives a Multi-File Task
-
-1. **STOP** — do not start implementing
-2. **Create a change plan** listing all files and dependency order
-3. **Decompose** into sub-tasks following this rule
-4. **Report back** with the decomposition
-5. **Implement** one sub-task at a time
+---
+name: task-decomposition
+tier: 2
+description: "Decompose multi-file tasks into 1-2 file sub-tasks"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Task Decomposition
+
+When a task touches multiple subsystems, decompose into sub-tasks where each modifies **at most 1-2 files**.
+
+## Why
+
+AI agents lose accuracy when editing 3+ files in one pass. Context from earlier files gets compressed away.
+
+## Rules
+
+1. **Each sub-task modifies 1-2 files** — never more
+2. **Each sub-task is independently verifiable** — it compiles, it doesn't break existing behavior
+3. **Sub-tasks follow data flow order** — upstream first (component → buffer → renderer → shader)
+4. **Each sub-task has a clear "done when"** — not "implement X", but "field Y exists with default Z"
+5. **Build after each sub-task** — verify compilation before proceeding
+
+## When an Agent Receives a Multi-File Task
+
+1. **STOP** — do not start implementing
+2. **Create a change plan** listing all files and dependency order
+3. **Decompose** into sub-tasks following this rule
+4. **Report back** with the decomposition
+5. **Implement** one sub-task at a time

package/templates/rules/typescript.md

@@ -1,40 +1,40 @@
----
-paths:
-  - "**/*.ts"
-  - "**/*.tsx"
-  - "tsconfig.json"
-  - "tsconfig.*.json"
----
-<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
-
-# TypeScript rules
-
-Loaded by Claude Code when touching TypeScript files. Keeps guidance focused so the main `CLAUDE.md` stays small.
-
-## Non-negotiables
-
-1. **Type-check before test.** Run the project's `type-check` (usually `tsc --noEmit` or `npm run type-check`) before running the test suite. A type error is a faster, cheaper signal than a test failure.
-2. **No `any`** unless the value is genuinely untyped (e.g. `JSON.parse` output before validation). Prefer `unknown` with a narrowing step.
-3. **No `// @ts-ignore` / `// @ts-expect-error`** without a one-line comment explaining why. If you can fix the type, fix it.
-4. **Strict null checks.** Treat `undefined` and `null` as distinct. Use optional chaining (`?.`) and nullish coalescing (`??`), not `||`, for "value might be absent" logic.
-5. **ESM everywhere.** Use `import`/`export`, not `require`. Relative imports include the `.js` extension (Node ESM rule) even when the source file is `.ts`.
-
-## Conventions
-
-- Public API types live next to their implementation. Large shared types go in `src/types.ts` or `src/types/`.
-- Interfaces for object shapes, `type` aliases for unions and mapped types.
-- `readonly` wherever mutation is not required.
-- Exhaustive `switch` on union types uses a `const _exhaustive: never = x;` tail.
-- Async functions return `Promise<T>` explicitly on public APIs.
-
-## Testing
-
-- Use the project's configured test runner (Vitest, Jest, Node test) — do not add a new one.
-- Mock at the module boundary, not inside the unit under test.
-- Every `describe` has at least one `it`; no empty test blocks.
-
-## Build & tooling
-
-- Never commit `dist/`, `build/`, `.tsbuildinfo`, or `node_modules/`.
-- `tsconfig.json` is the source of truth for compiler options. Do not override via inline comments unless explicitly required.
-- Prefer `tsx` / `ts-node` for scripts; never shell-execute a raw `.ts` file in production.
+---
+paths:
+  - "**/*.ts"
+  - "**/*.tsx"
+  - "tsconfig.json"
+  - "tsconfig.*.json"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# TypeScript rules
+
+Loaded by Claude Code when touching TypeScript files. Keeps guidance focused so the main `CLAUDE.md` stays small.
+
+## Non-negotiables
+
+1. **Type-check before test.** Run the project's `type-check` (usually `tsc --noEmit` or `npm run type-check`) before running the test suite. A type error is a faster, cheaper signal than a test failure.
+2. **No `any`** unless the value is genuinely untyped (e.g. `JSON.parse` output before validation). Prefer `unknown` with a narrowing step.
+3. **No `// @ts-ignore` / `// @ts-expect-error`** without a one-line comment explaining why. If you can fix the type, fix it.
+4. **Strict null checks.** Treat `undefined` and `null` as distinct. Use optional chaining (`?.`) and nullish coalescing (`??`), not `||`, for "value might be absent" logic.
+5. **ESM everywhere.** Use `import`/`export`, not `require`. Relative imports include the `.js` extension (Node ESM rule) even when the source file is `.ts`.
+
+## Conventions
+
+- Public API types live next to their implementation. Large shared types go in `src/types.ts` or `src/types/`.
+- Interfaces for object shapes, `type` aliases for unions and mapped types.
+- `readonly` wherever mutation is not required.
+- Exhaustive `switch` on union types uses a `const _exhaustive: never = x;` tail.
+- Async functions return `Promise<T>` explicitly on public APIs.
+
+## Testing
+
+- Use the project's configured test runner (Vitest, Jest, Node test) — do not add a new one.
+- Mock at the module boundary, not inside the unit under test.
+- Every `describe` has at least one `it`; no empty test blocks.
+
+## Build & tooling
+
+- Never commit `dist/`, `build/`, `.tsbuildinfo`, or `node_modules/`.
+- `tsconfig.json` is the source of truth for compiler options. Do not override via inline comments unless explicitly required.
+- Prefer `tsx` / `ts-node` for scripts; never shell-execute a raw `.ts` file in production.

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

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

package/templates/skills/core/agent-automation/SKILL.md

@@ -1,194 +1,194 @@
----
-name: "Agent Automation"
-description: "Mandatory workflow that AI agents MUST execute after EVERY implementation."
-version: "1.0.0"
-category: "core"
-author: "Rulebook"
-tags: ["core"]
-dependencies: []
-conflicts: []
----
-<!-- AGENT_AUTOMATION:START -->
-# Agent Automation Rules
-
-**CRITICAL**: Mandatory workflow that AI agents MUST execute after EVERY implementation.
-
-## Workflow Overview
-
-After completing ANY feature, bug fix, or code change, execute this workflow in order:
-
-### Step 1: Quality Checks (MANDATORY)
-
-Run these checks in order - ALL must pass:
-
-```bash
-1. Type check (if applicable)
-2. Lint (MUST pass with ZERO warnings)
-3. Format code
-4. Run ALL tests (MUST pass 100%)
-5. Verify coverage meets threshold (default 95%)
-```
-
-**Language-specific commands**: See your language template (TYPESCRIPT, RUST, PYTHON, etc.) for exact commands.
-
-**IF ANY CHECK FAILS:**
-- ❌ STOP immediately
-- ❌ DO NOT proceed
-- ❌ DO NOT commit
-- ✅ Fix the issue first
-- ✅ Re-run ALL checks
-
-### Step 2: Security & Dependency Audits
-
-```bash
-# Check for vulnerabilities (language-specific)
-# Check for outdated dependencies (informational)
-# Find unused dependencies (optional)
-```
-
-**Language-specific commands**: See your language template for audit commands.
-
-**IF VULNERABILITIES FOUND:**
-- ✅ Attempt automatic fix
-- ✅ Document if auto-fix fails
-- ✅ Include in Step 5 report
-- ❌ Never ignore critical/high vulnerabilities without user approval
-
-### Step 3: Update OpenSpec Tasks
-
-If `openspec/` directory exists:
-
-```bash
-# Mark completed tasks as [DONE]
-# Update in-progress tasks
-# Add new tasks if discovered
-# Update progress percentages
-# Document deviations or blockers
-```
-
-### Step 4: Update Documentation
-
-```bash
-# Update ROADMAP.md (if feature is milestone)
-# Update CHANGELOG.md (conventional commits format)
-# Update feature specs (if implementation differs)
-# Update README.md (if public API changed)
-```
-
-### Step 5: Git Commit
-
-**ONLY after ALL above steps pass:**
-
-**⚠️ CRITICAL: All commit messages MUST be in English**
-
-```bash
-git add .
-git commit -m "<type>(<scope>): <description>
-
-- Detailed change 1
-- Detailed change 2
-- Tests: [describe coverage]
-- Coverage: X% (threshold: 95%)
-
-Closes #<issue> (if applicable)"
-```
-
-**Commit Types**: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
-
-**Language Requirement**: Commit messages must be written in English. Never use Portuguese, Spanish, or any other language.
-
-### Step 6: Report to User
-
-```
-✅ Implementation Complete
-
-📝 Changes:
-- [List main changes]
-
-🧪 Quality Checks:
-- ✅ Type check: Passed
-- ✅ Linting: Passed (0 warnings)
-- ✅ Formatting: Applied
-- ✅ Tests: X/X passed (100%)
-- ✅ Coverage: X% (threshold: 95%)
-
-🔒 Security:
-- ✅ No vulnerabilities
-
-📊 OpenSpec:
-- ✅ Tasks updated
-- ✅ Progress: X% → Y%
-
-📚 Documentation:
-- ✅ CHANGELOG.md updated
-- ✅ [other docs updated]
-
-💾 Git:
-- ✅ Committed: <commit message>
-- ✅ Hash: <commit hash>
-
-📋 Next Steps:
-- [ ] Review changes
-- [ ] Push to remote (if ready)
-```
-
-## Automation Exceptions
-
-Skip steps ONLY when:
-
-1. **Exploratory Code**: User says "experimental", "draft", "try"
-   - Still run quality checks
-   - Don't commit
-
-2. **User Explicitly Requests**: User says "skip tests", "no commit"
-   - Only skip requested step
-   - Warn about skipped steps
-
-3. **Emergency Hotfix**: Critical production bug
-   - Run minimal checks
-   - Document technical debt
-
-**In ALL other cases: Execute complete workflow**
-
-## Error Recovery
-
-If workflow fails 3+ times:
-
-```bash
-1. Create backup branch
-2. Reset to last stable commit
-3. Report to user with error details
-4. Request guidance or try alternative approach
-```
-
-## Best Practices
-
-### DO's ✅
-- ALWAYS run complete workflow
-- ALWAYS update OpenSpec and documentation
-- ALWAYS use conventional commits
-- ALWAYS report summary to user
-- ASK before skipping steps
-
-### DON'Ts ❌
-- NEVER skip quality checks without permission
-- NEVER commit failing tests
-- NEVER commit linting errors
-- NEVER skip documentation updates
-- NEVER assume user wants to skip automation
-- NEVER commit debug code or secrets
-
-## Summary
-
-**Complete workflow after EVERY implementation:**
-
-1. ✅ Quality checks (type, lint, format, test, coverage)
-2. ✅ Security audit
-3. ✅ Update OpenSpec tasks
-4. ✅ Update documentation
-5. ✅ Git commit (conventional format)
-6. ✅ Report summary to user
-
-**Only skip with explicit user permission and document why.**
-
-<!-- AGENT_AUTOMATION:END -->
+---
+name: "Agent Automation"
+description: "Mandatory workflow that AI agents MUST execute after EVERY implementation."
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["core"]
+dependencies: []
+conflicts: []
+---
+<!-- AGENT_AUTOMATION:START -->
+# Agent Automation Rules
+
+**CRITICAL**: Mandatory workflow that AI agents MUST execute after EVERY implementation.
+
+## Workflow Overview
+
+After completing ANY feature, bug fix, or code change, execute this workflow in order:
+
+### Step 1: Quality Checks (MANDATORY)
+
+Run these checks in order - ALL must pass:
+
+```bash
+1. Type check (if applicable)
+2. Lint (MUST pass with ZERO warnings)
+3. Format code
+4. Run ALL tests (MUST pass 100%)
+5. Verify coverage meets threshold (default 95%)
+```
+
+**Language-specific commands**: See your language template (TYPESCRIPT, RUST, PYTHON, etc.) for exact commands.
+
+**IF ANY CHECK FAILS:**
+- ❌ STOP immediately
+- ❌ DO NOT proceed
+- ❌ DO NOT commit
+- ✅ Fix the issue first
+- ✅ Re-run ALL checks
+
+### Step 2: Security & Dependency Audits
+
+```bash
+# Check for vulnerabilities (language-specific)
+# Check for outdated dependencies (informational)
+# Find unused dependencies (optional)
+```
+
+**Language-specific commands**: See your language template for audit commands.
+
+**IF VULNERABILITIES FOUND:**
+- ✅ Attempt automatic fix
+- ✅ Document if auto-fix fails
+- ✅ Include in Step 5 report
+- ❌ Never ignore critical/high vulnerabilities without user approval
+
+### Step 3: Update OpenSpec Tasks
+
+If `openspec/` directory exists:
+
+```bash
+# Mark completed tasks as [DONE]
+# Update in-progress tasks
+# Add new tasks if discovered
+# Update progress percentages
+# Document deviations or blockers
+```
+
+### Step 4: Update Documentation
+
+```bash
+# Update ROADMAP.md (if feature is milestone)
+# Update CHANGELOG.md (conventional commits format)
+# Update feature specs (if implementation differs)
+# Update README.md (if public API changed)
+```
+
+### Step 5: Git Commit
+
+**ONLY after ALL above steps pass:**
+
+**⚠️ CRITICAL: All commit messages MUST be in English**
+
+```bash
+git add .
+git commit -m "<type>(<scope>): <description>
+
+- Detailed change 1
+- Detailed change 2
+- Tests: [describe coverage]
+- Coverage: X% (threshold: 95%)
+
+Closes #<issue> (if applicable)"
+```
+
+**Commit Types**: `feat`, `fix`, `docs`, `refactor`, `perf`, `test`, `build`, `ci`, `chore`
+
+**Language Requirement**: Commit messages must be written in English. Never use Portuguese, Spanish, or any other language.
+
+### Step 6: Report to User
+
+```
+✅ Implementation Complete
+
+📝 Changes:
+- [List main changes]
+
+🧪 Quality Checks:
+- ✅ Type check: Passed
+- ✅ Linting: Passed (0 warnings)
+- ✅ Formatting: Applied
+- ✅ Tests: X/X passed (100%)
+- ✅ Coverage: X% (threshold: 95%)
+
+🔒 Security:
+- ✅ No vulnerabilities
+
+📊 OpenSpec:
+- ✅ Tasks updated
+- ✅ Progress: X% → Y%
+
+📚 Documentation:
+- ✅ CHANGELOG.md updated
+- ✅ [other docs updated]
+
+💾 Git:
+- ✅ Committed: <commit message>
+- ✅ Hash: <commit hash>
+
+📋 Next Steps:
+- [ ] Review changes
+- [ ] Push to remote (if ready)
+```
+
+## Automation Exceptions
+
+Skip steps ONLY when:
+
+1. **Exploratory Code**: User says "experimental", "draft", "try"
+   - Still run quality checks
+   - Don't commit
+
+2. **User Explicitly Requests**: User says "skip tests", "no commit"
+   - Only skip requested step
+   - Warn about skipped steps
+
+3. **Emergency Hotfix**: Critical production bug
+   - Run minimal checks
+   - Document technical debt
+
+**In ALL other cases: Execute complete workflow**
+
+## Error Recovery
+
+If workflow fails 3+ times:
+
+```bash
+1. Create backup branch
+2. Reset to last stable commit
+3. Report to user with error details
+4. Request guidance or try alternative approach
+```
+
+## Best Practices
+
+### DO's ✅
+- ALWAYS run complete workflow
+- ALWAYS update OpenSpec and documentation
+- ALWAYS use conventional commits
+- ALWAYS report summary to user
+- ASK before skipping steps
+
+### DON'Ts ❌
+- NEVER skip quality checks without permission
+- NEVER commit failing tests
+- NEVER commit linting errors
+- NEVER skip documentation updates
+- NEVER assume user wants to skip automation
+- NEVER commit debug code or secrets
+
+## Summary
+
+**Complete workflow after EVERY implementation:**
+
+1. ✅ Quality checks (type, lint, format, test, coverage)
+2. ✅ Security audit
+3. ✅ Update OpenSpec tasks
+4. ✅ Update documentation
+5. ✅ Git commit (conventional format)
+6. ✅ Report summary to user
+
+**Only skip with explicit user permission and document why.**
+
+<!-- AGENT_AUTOMATION:END -->