@hivehub/rulebook 5.3.3 → 5.4.1

package/templates/skills/core/rulebook-terse/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: "Rulebook Terse"
+description: "Output-verbosity compression. Cuts response tokens ~40-70% without losing technical accuracy. Four intensity levels (off/brief/terse/ultra) aligned with Rulebook's agent-tier system. Use when user says 'terse mode', 'be terse', 'less tokens please', or invokes /rulebook-terse. Auto-activates via SessionStart hook with tier-aware default."
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["core", "output", "tokens", "compression"]
+dependencies: []
+conflicts: []
+---
+<!-- RULEBOOK_TERSE:START -->
+# Rulebook Terse — Output Compression
+
+Respond tersely. All technical substance stays. Only fluff dies.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once set. No revert after many turns. No filler drift. Still active if unsure.
+
+Off only via: `/rulebook-terse off` · "normal mode" · "stop terse" · session end.
+
+Default intensity resolves from: `RULEBOOK_TERSE_MODE` env → `.rulebook/rulebook.json` `terse.defaultMode` → active agent tier → `terse`.
+
+## Rules
+
+**Drop**:
+- Articles (`a`, `an`, `the`) — level-dependent, see intensity table
+- Filler (`just`, `really`, `basically`, `actually`, `simply`, `essentially`)
+- Pleasantries (`sure`, `certainly`, `of course`, `happy to`, `great question`, `I'd recommend`)
+- Hedging (`it might be worth`, `you could consider`, `perhaps`, `I think`)
+- Preamble + restating the question
+
+**Keep exact**:
+- Technical terms (library names, API names, protocols, algorithms)
+- Code blocks (fenced and inline) — byte-for-byte pass-through
+- File paths (`/src/foo.ts`, `./config.yaml`, `E:\project\file`)
+- URLs + links
+- Commands (`npm test`, `git commit`)
+- Error messages (quoted)
+- Version numbers + dates
+- Proper nouns
+
+**Pattern**:
+
+```
+[thing] [action] [reason]. [next step].
+```
+
+**Example**:
+
+❌ "Sure! I'd be happy to help. The issue you're experiencing is most likely caused by the authentication middleware not properly validating token expiry. Let me take a look."
+
+✅ "Bug in auth middleware. Token expiry check uses `<` not `<=`. Fix:"
+
+## Intensity
+
+| Level | What changes |
+|-------|-------------|
+| **off** | No compression. Full prose. Full reasoning welcome. Default for Core tier (opus). |
+| **brief** | Drop filler + hedging + pleasantries. Keep articles + full sentences. Default for Standard tier (sonnet). |
+| **terse** | Drop articles. Fragments OK. Short synonyms (`fix` not "implement a solution for", `big` not "extensive"). Default for Research tier (haiku). |
+| **ultra** | Abbreviate (DB/auth/config/req/res/fn/impl). Strip conjunctions. Arrows for causality (`X → Y`). One word when one word suffices. |
+
+### Example — "Why does my React component re-render?"
+
+- **off**: "Your component re-renders because you're creating a new object reference on every render. When you pass an inline object as a prop, React's shallow comparison sees it as a different object each time. Wrap it in `useMemo` to stabilize the reference."
+- **brief**: "Component re-renders because you create a new object reference each render. Inline object prop fails shallow comparison. Wrap it in `useMemo`."
+- **terse**: "New object ref each render. Inline object prop = new ref = re-render. Wrap in `useMemo`."
+- **ultra**: "Inline obj prop → new ref → re-render. `useMemo`."
+
+### Example — "Explain database connection pooling."
+
+- **off**: "Connection pooling reuses a set of pre-opened database connections instead of creating a new connection for each request. This avoids the overhead of establishing a new TCP handshake and authenticating every time."
+- **brief**: "Connection pooling reuses open connections instead of creating new ones per request. Avoids repeated handshake + auth overhead."
+- **terse**: "Pool reuses open DB connections. No new connection per request. Skip handshake overhead."
+- **ultra**: "Pool = reuse DB conn. Skip handshake → fast under load."
+
+## Auto-Clarity (mandatory escape hatch)
+
+Compression is suspended — for the affected turn only — when ANY of the following applies. Full prose is restored. Compression resumes on the next turn.
+
+1. **Security warnings** — CVE-class findings, credential exposure, permission-elevation warnings.
+2. **Destructive-op confirmations** — `rm -rf`, `git reset --hard`, `DROP TABLE`, `rulebook_task_delete`, irreversible file deletion.
+3. **Quality-gate failures** — type-check errors, lint failures, failing tests, coverage below threshold, hook-emitted deny messages from `enforce-no-deferred` / `enforce-no-shortcuts` / `enforce-mcp-for-tasks`.
+4. **Multi-step sequences** where fragment ambiguity risks misread (migration steps, ordered deploys, multi-service restarts).
+5. **User confusion** — explicit "I don't understand", "explain again", or repeat of the same question.
+
+### Example — destructive op
+
+> **Warning**: This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Verify a backup exists before proceeding. After confirmation, terse resumes.
+
+## Boundaries
+
+- **Code blocks**: byte-for-byte unchanged. Never compressed, never abbreviated, never reordered.
+- **Commit messages**: handled by the separate `rulebook-terse-commit` skill. Base skill does nothing to commits.
+- **PR reviews**: handled by `rulebook-terse-review`. Base skill does nothing to reviews.
+- **Specs** (`.rulebook/specs/**`, `proposal.md`, `spec.md`): unchanged.
+- **Test assertions + error strings**: verbatim.
+
+## Activation surface
+
+| Surface | Example |
+|---------|---------|
+| Slash command | `/rulebook-terse`, `/rulebook-terse brief\|terse\|ultra\|off` |
+| Natural language (on) | "be terse", "less tokens please", "terse mode", "activate rulebook-terse" |
+| Natural language (off) | "normal mode", "stop terse", "disable terse" |
+| Model inference | Any trigger phrase in this skill's `description` frontmatter |
+| Automatic | SessionStart hook, tier-aware default |
+
+<!-- RULEBOOK_TERSE:END -->

package/templates/skills/core/rulebook-terse-commit/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: "Rulebook Terse Commit"
+description: "Terse Conventional Commits generator. Subject ≤50 chars (hard cap 72), body only when 'why' isn't obvious, no filler. Use when user says 'write a commit', 'generate commit', 'commit message', or invokes /rulebook-terse-commit. Independent of the base rulebook-terse mode."
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["core", "git", "commits", "tokens"]
+dependencies: []
+conflicts: []
+---
+<!-- RULEBOOK_TERSE_COMMIT:START -->
+# Rulebook Terse Commit
+
+Write commit messages terse and exact. Conventional Commits format. Why over what.
+
+## Subject line
+
+- Format: `<type>(<scope>): <imperative summary>` — `<scope>` optional.
+- Types: `feat`, `fix`, `refactor`, `perf`, `docs`, `test`, `chore`, `build`, `ci`, `style`, `revert`.
+- Imperative mood: "add", "fix", "remove" — not "added", "adds", "adding".
+- Target ≤50 chars. Hard cap 72.
+- No trailing period.
+- Match project capitalization convention after the colon (match the repo's existing history).
+
+## Body
+
+- **Skip the body entirely** when the subject is self-explanatory.
+- Add a body ONLY for: non-obvious `why`, breaking changes, migration notes, linked issues.
+- Wrap at 72 chars.
+- Bullets use `-`, not `*`.
+- Reference issues/PRs at the end: `Closes #42`, `Refs #17`.
+
+## Never include
+
+- "This commit does X", "I", "we", "now", "currently" — the diff says what.
+- "As requested by ..." — use the `Co-authored-by` trailer instead.
+- "Generated with Claude Code" or any AI attribution.
+- Emoji (unless project convention requires them).
+- Restating the file name when `<scope>` already identifies it.
+
+## Auto-Clarity
+
+Always include a body for:
+
+- **Breaking changes** (`!` suffix on type, plus `BREAKING CHANGE:` footer).
+- **Security fixes** (CVE ID when applicable).
+- **Data migrations** that touch user data.
+- **Reverts** of a prior commit (reference the reverted SHA).
+- **Performance regressions fixed** (include before/after numbers when possible).
+
+Terseness is NEVER permitted to obscure these cases — future debuggers need the context.
+
+## Examples
+
+### New endpoint with non-obvious why
+
+```
+feat(api): add GET /users/:id/profile
+
+Mobile client needs profile data without the full user payload to
+reduce LTE bandwidth on cold-launch screens.
+
+Closes #128
+```
+
+### Breaking API change
+
+```
+feat(api)!: rename /v1/orders to /v1/checkout
+
+BREAKING CHANGE: clients on /v1/orders must migrate to /v1/checkout
+before 2026-06-01. Old route returns 410 after that date.
+```
+
+### Simple bug fix — subject only
+
+```
+fix(auth): reject expired tokens on boundary second
+```
+
+### Revert
+
+```
+revert: "feat(api): add GET /users/:id/profile"
+
+This reverts commit a1b2c3d. Endpoint caused 5% latency regression
+on the hot path; see incident INC-4219.
+```
+
+## Boundaries
+
+Only generates the commit message. Does NOT run `git commit`, does NOT stage files, does NOT amend. Output is a code block ready to paste.
+
+Override: `/rulebook-terse-commit off` or "stop terse commit" reverts to the model's default commit style.
+
+<!-- RULEBOOK_TERSE_COMMIT:END -->

package/templates/skills/core/rulebook-terse-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: "Rulebook Terse Review"
+description: "Ultra-compressed code review comments. One line per finding: location, problem, fix. Use when user says 'review this PR', 'code review', 'review the diff', or invokes /rulebook-terse-review. Independent of the base rulebook-terse mode."
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["core", "review", "tokens"]
+dependencies: []
+conflicts: []
+---
+<!-- RULEBOOK_TERSE_REVIEW:START -->
+# Rulebook Terse Review
+
+Write code-review comments terse and actionable. One line per finding. Location, problem, fix. No throat-clearing.
+
+## Format
+
+```
+L<line>: <severity> <problem>. <fix>.
+```
+
+For multi-file diffs:
+
+```
+<file>:L<line>: <severity> <problem>. <fix>.
+```
+
+## Severity prefixes
+
+Use when mixing severities in the same review. Optional when all findings are the same severity.
+
+| Prefix | Meaning |
+|--------|---------|
+| 🔴 `bug:` | Broken behavior; will cause an incident. |
+| 🟡 `risk:` | Works but fragile (race, missing null check, swallowed error, unvalidated input). |
+| 🔵 `nit:` | Style, naming, micro-optim. Author can ignore without consequence. |
+| ❓ `q:` | Genuine question, not a suggestion. |
+
+## Drop
+
+- Throat-clearing: "I noticed that...", "It seems like...", "You might want to consider...".
+- Per-comment pleasantries: "Great work!", "Looks good overall but...". Say it once at the top of the review, not per comment.
+- Restating what the line does — the reviewer can read the diff.
+- Hedging: "perhaps", "maybe", "I think". If unsure, use `❓ q:`.
+- "This is just a suggestion but..." — use `🔵 nit:` instead.
+
+## Keep
+
+- Exact line numbers.
+- Exact symbol, function, and variable names in backticks.
+- A concrete fix, not "consider refactoring this".
+- The `why` if the fix isn't obvious from the problem statement.
+
+## Examples
+
+### ❌ Verbose
+
+> "I noticed that on line 42 you're not checking if the user object is null before accessing the email property. This could potentially cause a crash if the user is not found in the database. You might want to add a null check here."
+
+### ✅ Terse
+
+```
+L42: 🔴 bug: user can be null after .find(). Add guard before .email.
+```
+
+---
+
+### ❌ Verbose
+
+> "It looks like this function is doing a lot of things and might benefit from being broken up into smaller functions for readability."
+
+### ✅ Terse
+
+```
+L88-140: 🔵 nit: 50-line fn does 4 things. Extract validate/normalize/persist.
+```
+
+---
+
+### ❌ Verbose
+
+> "Have you considered what happens if the API returns a 429? I think we should probably handle that case."
+
+### ✅ Terse
+
+```
+L23: 🟡 risk: no retry on 429. Wrap in withBackoff(3).
+```
+
+## Auto-Clarity
+
+Drop terse mode and write full prose for:
+
+- **Security findings** (CVE-class bugs, auth bypass, credential exposure) — need full explanation + CWE or CVE reference.
+- **Architectural disagreements** — need rationale, not a one-liner.
+- **Onboarding contexts** where the author is new to the codebase — they need the `why`, not just the `what`.
+
+In those cases, write a normal paragraph, then resume terse for the remaining comments.
+
+## Boundaries
+
+Review-only. Does NOT:
+
+- Write the code fix.
+- Approve or request changes on the PR.
+- Run linters or tests.
+
+Output is the comment(s), ready to paste into the PR review UI.
+
+Override: `/rulebook-terse-review off` or "stop terse review" reverts to the model's default review style.
+
+<!-- RULEBOOK_TERSE_REVIEW:END -->

package/templates/skills/dev/accessibility/SKILL.md

@@ -1,17 +1,17 @@
----
-name: accessibility
-description: Accessibility audit for WCAG compliance and usability
-model: haiku
-context: fork
-agent: accessibility-reviewer
----
-Audit accessibility for: $ARGUMENTS
-
-If no arguments, audit the entire frontend codebase.
-
-Steps:
-1. Check semantic HTML usage (headings, landmarks, labels)
-2. Verify ARIA attributes are correct and complete
-3. Test keyboard navigation flow
-4. Check color contrast ratios meet WCAG 2.1 AA
-5. Report violations with severity and remediation steps
+---
+name: accessibility
+description: Accessibility audit for WCAG compliance and usability
+model: haiku
+context: fork
+agent: accessibility-reviewer
+---
+Audit accessibility for: $ARGUMENTS
+
+If no arguments, audit the entire frontend codebase.
+
+Steps:
+1. Check semantic HTML usage (headings, landmarks, labels)
+2. Verify ARIA attributes are correct and complete
+3. Test keyboard navigation flow
+4. Check color contrast ratios meet WCAG 2.1 AA
+5. Report violations with severity and remediation steps

package/templates/skills/dev/analysis/SKILL.md

@@ -1,19 +1,19 @@
----
-name: analysis
-description: Create structured analyses with numbered findings, execution plans, and task materialization
-model: opus
-context: fork
-agent: researcher
----
-Create a structured analysis for: $ARGUMENTS
-
-Steps:
-1. Call `rulebook_analysis_create` with the topic to scaffold `docs/analysis/<slug>/`
-2. Check existing knowledge: `rulebook_knowledge_list` and `rulebook_memory_search` for prior context
-3. Investigate the topic — read relevant files, search codebase, fetch docs as needed
-4. Fill `findings.md` with numbered findings (F-001..F-NNN), each with: title, evidence (file:line), impact, confidence
-5. Design phased execution plan in `execution-plan.md`
-6. Consolidate the executive summary in `README.md`
-7. Capture each key finding to the knowledge base: `rulebook_knowledge_add` for patterns/anti-patterns
-8. Save analysis summary to memory: `rulebook_memory_save` with type `observation` and tags `["analysis", "<slug>"]`
-9. Offer to materialize implementation tasks from the execution plan via `rulebook_task_create`
+---
+name: analysis
+description: Create structured analyses with numbered findings, execution plans, and task materialization
+model: opus
+context: fork
+agent: researcher
+---
+Create a structured analysis for: $ARGUMENTS
+
+Steps:
+1. Call `rulebook_analysis_create` with the topic to scaffold `docs/analysis/<slug>/`
+2. Check existing knowledge: `rulebook_knowledge_list` and `rulebook_memory_search` for prior context
+3. Investigate the topic — read relevant files, search codebase, fetch docs as needed
+4. Fill `findings.md` with numbered findings (F-001..F-NNN), each with: title, evidence (file:line), impact, confidence
+5. Design phased execution plan in `execution-plan.md`
+6. Consolidate the executive summary in `README.md`
+7. Capture each key finding to the knowledge base: `rulebook_knowledge_add` for patterns/anti-patterns
+8. Save analysis summary to memory: `rulebook_memory_save` with type `observation` and tags `["analysis", "<slug>"]`
+9. Offer to materialize implementation tasks from the execution plan via `rulebook_task_create`

package/templates/skills/dev/api-design/SKILL.md

@@ -1,15 +1,15 @@
----
-name: api-design
-description: Design or review API endpoints (REST/GraphQL)
-model: sonnet
-context: fork
-agent: api-designer
----
-Design or review the API for: $ARGUMENTS
-
-Steps:
-1. Gather requirements from the codebase and any existing API patterns
-2. Design endpoints following REST conventions (or GraphQL schema)
-3. Define request/response schemas with types
-4. Document error responses and status codes
-5. Write or update OpenAPI spec if applicable
+---
+name: api-design
+description: Design or review API endpoints (REST/GraphQL)
+model: sonnet
+context: fork
+agent: api-designer
+---
+Design or review the API for: $ARGUMENTS
+
+Steps:
+1. Gather requirements from the codebase and any existing API patterns
+2. Design endpoints following REST conventions (or GraphQL schema)
+3. Define request/response schemas with types
+4. Document error responses and status codes
+5. Write or update OpenAPI spec if applicable

package/templates/skills/dev/architect/SKILL.md

@@ -1,17 +1,17 @@
----
-name: architect
-description: Architecture review, design decisions, and ADR writing
-model: opus
-context: fork
-agent: architect
----
-Analyze architecture for: $ARGUMENTS
-
-If no arguments, do a general architecture review of the project.
-
-Steps:
-1. Map the current system architecture (modules, dependencies, data flow)
-2. Identify architectural concerns (coupling, scalability, complexity)
-3. Evaluate alternative approaches with trade-offs
-4. Write an Architecture Decision Record (ADR) if a decision is needed
-5. Present recommendations with clear rationale
+---
+name: architect
+description: Architecture review, design decisions, and ADR writing
+model: opus
+context: fork
+agent: architect
+---
+Analyze architecture for: $ARGUMENTS
+
+If no arguments, do a general architecture review of the project.
+
+Steps:
+1. Map the current system architecture (modules, dependencies, data flow)
+2. Identify architectural concerns (coupling, scalability, complexity)
+3. Evaluate alternative approaches with trade-offs
+4. Write an Architecture Decision Record (ADR) if a decision is needed
+5. Present recommendations with clear rationale

package/templates/skills/dev/build-fix/SKILL.md

@@ -1,17 +1,17 @@
----
-name: build-fix
-description: Diagnose and fix build failures or CI issues
-model: sonnet
-context: fork
-agent: build-engineer
----
-Diagnose and fix the current build failure.
-
-If $ARGUMENTS is provided, focus on that specific build error or CI job.
-
-Steps:
-1. Run the build command and capture the error output
-2. Read the error message and trace to the source file
-3. Identify the root cause (missing dep, type error, config issue)
-4. Apply the minimal fix
-5. Re-run the build to verify the fix works
+---
+name: build-fix
+description: Diagnose and fix build failures or CI issues
+model: sonnet
+context: fork
+agent: build-engineer
+---
+Diagnose and fix the current build failure.
+
+If $ARGUMENTS is provided, focus on that specific build error or CI job.
+
+Steps:
+1. Run the build command and capture the error output
+2. Read the error message and trace to the source file
+3. Identify the root cause (missing dep, type error, config issue)
+4. Apply the minimal fix
+5. Re-run the build to verify the fix works

package/templates/skills/dev/db-design/SKILL.md

@@ -1,15 +1,15 @@
----
-name: db-design
-description: Database schema design, migrations, and query optimization
-model: sonnet
-context: fork
-agent: database-architect
----
-Design or review the database for: $ARGUMENTS
-
-Steps:
-1. Understand the data model requirements
-2. Design or review the schema (tables, relationships, indexes)
-3. Plan migration strategy if schema changes are needed
-4. Review existing queries for optimization opportunities
-5. Document the schema decisions and trade-offs
+---
+name: db-design
+description: Database schema design, migrations, and query optimization
+model: sonnet
+context: fork
+agent: database-architect
+---
+Design or review the database for: $ARGUMENTS
+
+Steps:
+1. Understand the data model requirements
+2. Design or review the schema (tables, relationships, indexes)
+3. Plan migration strategy if schema changes are needed
+4. Review existing queries for optimization opportunities
+5. Document the schema decisions and trade-offs

package/templates/skills/dev/debug/SKILL.md

@@ -1,16 +1,16 @@
----
-name: debug
-description: Systematic debugging workflow for bugs and test failures
-model: sonnet
-context: fork
-agent: researcher
----
-Debug the following issue: $ARGUMENTS
-
-Steps:
-1. Reproduce the issue by reading the error message or running the failing test
-2. Read the relevant source code and trace the execution path
-3. Form a hypothesis about the root cause
-4. Search for similar patterns in the codebase that work correctly
-5. Identify the exact root cause with file and line reference
-6. Propose a minimal fix with explanation
+---
+name: debug
+description: Systematic debugging workflow for bugs and test failures
+model: sonnet
+context: fork
+agent: researcher
+---
+Debug the following issue: $ARGUMENTS
+
+Steps:
+1. Reproduce the issue by reading the error message or running the failing test
+2. Read the relevant source code and trace the execution path
+3. Form a hypothesis about the root cause
+4. Search for similar patterns in the codebase that work correctly
+5. Identify the exact root cause with file and line reference
+6. Propose a minimal fix with explanation

package/templates/skills/dev/deploy/SKILL.md

@@ -1,17 +1,17 @@
----
-name: deploy
-description: Prepare deployment artifacts and verify CI/CD readiness
-model: sonnet
-context: fork
-agent: devops-engineer
----
-Prepare the project for deployment.
-
-If $ARGUMENTS is provided, focus on that specific deployment target or environment.
-
-Steps:
-1. Verify the build succeeds with no errors
-2. Check CI/CD pipeline configuration is valid
-3. Validate environment variables and secrets are documented
-4. Review Dockerfile or deployment configs if present
-5. Generate a deployment checklist with any missing items
+---
+name: deploy
+description: Prepare deployment artifacts and verify CI/CD readiness
+model: sonnet
+context: fork
+agent: devops-engineer
+---
+Prepare the project for deployment.
+
+If $ARGUMENTS is provided, focus on that specific deployment target or environment.
+
+Steps:
+1. Verify the build succeeds with no errors
+2. Check CI/CD pipeline configuration is valid
+3. Validate environment variables and secrets are documented
+4. Review Dockerfile or deployment configs if present
+5. Generate a deployment checklist with any missing items

package/templates/skills/dev/docs/SKILL.md

@@ -1,17 +1,17 @@
----
-name: docs
-description: Generate or update project documentation based on recent changes
-model: haiku
-context: fork
-agent: docs-writer
----
-Analyze recent code changes and update project documentation accordingly.
-
-If $ARGUMENTS is provided, focus documentation on that specific topic or file.
-
-Steps:
-1. Run `git diff HEAD~5 --name-only` to find recently changed files
-2. Read the changed files to understand what was modified
-3. Check existing docs for sections that need updating
-4. Update or create documentation to reflect the changes
-5. Ensure code examples are accurate and up-to-date
+---
+name: docs
+description: Generate or update project documentation based on recent changes
+model: haiku
+context: fork
+agent: docs-writer
+---
+Analyze recent code changes and update project documentation accordingly.
+
+If $ARGUMENTS is provided, focus documentation on that specific topic or file.
+
+Steps:
+1. Run `git diff HEAD~5 --name-only` to find recently changed files
+2. Read the changed files to understand what was modified
+3. Check existing docs for sections that need updating
+4. Update or create documentation to reflect the changes
+5. Ensure code examples are accurate and up-to-date