@hivehub/rulebook 5.2.1 → 5.3.0

package/templates/rules/go.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.go"
+  - "go.mod"
+  - "go.sum"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Go rules
+
+Loaded by Claude Code when touching Go sources.
+
+## Non-negotiables
+
+1. **`go vet ./...` before `go test ./...`.** Vet is near-instant and catches common issues before the slower test runner.
+2. **`gofmt -s -w .` and `goimports -w .`** on every file you touch. There is no formatting debate in Go.
+3. **Error handling is explicit.** Every `err` is either handled, wrapped with `fmt.Errorf("context: %w", err)`, or propagated up. Never `_ = err`.
+4. **No naked returns in functions longer than 5 lines.** They obscure control flow.
+5. **`context.Context` is the first parameter** for any function that does I/O or may block. Never store contexts in structs.
+
+## Conventions
+
+- Package names are short, lowercase, and singular (`user`, not `users` or `userManager`).
+- Interfaces defined by the consumer, not the producer. Keep them small (1–3 methods).
+- Struct fields ordered: exported before unexported, grouped by logical purpose.
+- Use `any` instead of `interface{}` (Go 1.18+).
+- Prefer table-driven tests with `t.Run` subtests.
+
+## Testing
+
+- Test files live in the same package, suffix `_test.go`.
+- `testify/require` or stdlib `testing` — pick one and stick with it.
+- Race detector on CI: `go test -race ./...`.
+- No test skipping without `t.Skip("reason: ...")`.
+
+## Build & tooling
+
+- `go mod tidy` after adding imports; commit both `go.mod` and `go.sum`.
+- Never commit `vendor/` unless the project explicitly vendors.
+- Use `go build ./...` to catch packages you forgot to test.

package/templates/rules/java.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "**/*.java"
+  - "pom.xml"
+  - "**/build.gradle"
+  - "**/build.gradle.kts"
+  - "**/settings.gradle"
+  - "**/settings.gradle.kts"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Java rules
+
+Loaded by Claude Code when touching Java sources or build files.
+
+## Non-negotiables
+
+1. **Compile before test.** `mvn compile` / `gradle classes` before running the test suite. Compilation errors are cheaper to fix than a broken test run.
+2. **Static analysis enabled.** SpotBugs, ErrorProne, or Checkstyle per project config. Warnings count as failures.
+3. **Null safety.** Use `Optional<T>` for values that may be absent at API boundaries. Annotate fields with `@Nullable` / `@NonNull` where the project uses JSR-305 / JSpecify.
+4. **Immutability first.** `final` by default on fields, parameters, and local variables. Prefer records (Java 16+) for data carriers.
+5. **Never swallow exceptions.** Every `catch` either handles, wraps (`throw new X("context", e)`), or logs with context.
+
+## Conventions
+
+- Follow the project's Google Java Style or similar — formatter handles it.
+- Package names all lowercase, reverse-DNS (`com.hivehub.rulebook.foo`).
+- One public class per file; file name matches the class.
+- Prefer composition over inheritance; avoid deep hierarchies.
+- Use `java.time` (not `java.util.Date`) for dates and times.
+
+## Testing
+
+- JUnit 5 is default; use the project's configured framework.
+- AssertJ or Hamcrest for readable assertions.
+- Mockito for mocks; avoid PowerMock unless strictly necessary.
+- One logical assertion per test; multiple mechanical ones allowed.
+
+## Build & tooling
+
+- Commit `pom.xml` / `build.gradle`, never `target/` / `build/`.
+- Pin plugin versions; do not use ranges.
+- Java version declared in the build file, not assumed from the environment.

package/templates/rules/javascript.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.js"
+  - "**/*.jsx"
+  - "**/*.mjs"
+  - "**/*.cjs"
+  - "package.json"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# JavaScript rules
+
+Loaded by Claude Code when touching JavaScript files.
+
+## Non-negotiables
+
+1. **Lint before test.** Run the project's linter (ESLint / Biome) before the test suite. Lint errors are cheaper to surface than test failures.
+2. **No `var`.** Use `const` by default, `let` only when reassignment is necessary.
+3. **Strict equality.** Always `===` and `!==`, never `==` / `!=`.
+4. **No implicit globals.** Every file that modifies state at the top level should explicitly export it.
+5. **Module type matches the project.** If the project is ESM (`"type": "module"` in package.json), use `import`/`export`; if CommonJS, use `require`/`module.exports`. Do not mix without a clear boundary.
+
+## Conventions
+
+- Prefer arrow functions for callbacks; named `function` declarations for top-level or hoisted functions.
+- `async`/`await` over raw Promise chains.
+- Destructure function arguments when there are 3+ parameters.
+- Never rely on falsy checks for "value exists" — use explicit `=== undefined` / `!= null` where the distinction matters.
+
+## Testing
+
+- Use the project's configured test runner. Do not add a new one.
+- Mock external boundaries (network, filesystem, time).
+- No `describe.skip` / `it.skip` left behind in committed code.
+
+## Dependencies
+
+- Check `package.json` before adding imports. Do not install new dependencies without explicit authorization.
+- Pin `peerDependencies` carefully; they affect consumers of the package.

package/templates/rules/multi-agent-teams.md

@@ -0,0 +1,75 @@
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Multi-agent work MUST use Teams
+
+This project has **more than one specialized agent** and relies on Claude Code's
+experimental Teams feature (`CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`). When
+you need parallel execution across agents, use **Teams** — not standalone
+background `Agent` calls.
+
+## Why
+
+Standalone background agents **cannot communicate with each other**. Only
+agents inside a Team have access to the `SendMessage` tool. When two or
+more independent background agents run without a Team:
+
+- They cannot coordinate, share intermediate results, or reach consensus.
+- They silently produce conflicting edits or duplicate work.
+- You lose the ability to orchestrate hand-offs between specialists.
+
+Rulebook enforces this with a `PreToolUse` hook that **denies** any
+`Agent` invocation with `run_in_background: true` unless it is either:
+
+1. `subagent_type: team-lead` (the coordinator that will create the Team), or
+2. Passes `team_name` (already joined to an existing Team).
+
+Foreground single-agent calls are unaffected.
+
+## How to do parallel multi-agent work correctly
+
+**Option A — Spawn a team-lead that creates the Team:**
+
+```
+Agent(
+  subagent_type: "team-lead",
+  run_in_background: true,
+  description: "Coordinate the refactor",
+  prompt: "Create a team with roles [...]"
+)
+```
+
+The team-lead then uses `TeamCreate` and dispatches members with `team_name`.
+
+**Option B — Create the Team first, then spawn members:**
+
+```
+TeamCreate(name: "refactor-team", members: [...])
+Agent(
+  subagent_type: "rust-expert",
+  team_name: "refactor-team",
+  run_in_background: true,
+  description: "Port the auth module",
+  prompt: "..."
+)
+Agent(
+  subagent_type: "test-writer",
+  team_name: "refactor-team",
+  run_in_background: true,
+  description: "Write tests",
+  prompt: "..."
+)
+```
+
+Both members can now exchange messages via `SendMessage`.
+
+## What is NOT blocked
+
+- **Foreground `Agent`** (any `subagent_type`, no `run_in_background`): always allowed. Use this for simple delegation where you just need the result.
+- **Background `Agent` with `team_name` set**: allowed because the agent has a coordination channel.
+- **Background `Agent` with `subagent_type: "team-lead"`**: allowed because a team-lead is expected to bootstrap its Team before dispatching members.
+
+## Environment requirement
+
+This feature requires `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in your
+`.claude/settings.json`. Rulebook sets this automatically when
+`multi_agent: true` is enabled in `.rulebook/rulebook.json`.

package/templates/rules/python.md

@@ -0,0 +1,43 @@
+---
+paths:
+  - "**/*.py"
+  - "**/*.pyi"
+  - "pyproject.toml"
+  - "setup.py"
+  - "setup.cfg"
+  - "requirements*.txt"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Python rules
+
+Loaded by Claude Code when touching Python files.
+
+## Non-negotiables
+
+1. **Type-check before test.** Run `mypy` / `pyright` / `pyre` (whichever the project configures) before `pytest`. Type errors are 10x cheaper to discover than test failures.
+2. **Lint with `ruff` or the project's linter** before committing. `ruff check` is fast enough to run on every save.
+3. **Format with `black` / `ruff format`** — never hand-format.
+4. **Type hints on all public functions.** `def foo(x: int) -> str` minimum. Use `from __future__ import annotations` for forward refs.
+5. **No bare `except:`** — catch specific exceptions or `except Exception as e:` at the very least.
+
+## Conventions
+
+- Follow PEP 8 (handled by the formatter).
+- `pathlib.Path` over `os.path` for filesystem operations.
+- f-strings over `.format()` and `%` formatting.
+- Dataclasses or `pydantic` for data containers, not raw dicts at API boundaries.
+- `logging` module, never `print()`, for anything that ships.
+
+## Testing
+
+- `pytest` is the default; use the project's configured runner.
+- Fixtures in `conftest.py`, one per module where relevant.
+- `pytest-cov` for coverage; meet the project's threshold.
+- No skipped tests without an explicit comment linking to an issue.
+
+## Dependencies & environments
+
+- Respect the project's virtualenv / pyenv / poetry / uv setup. Do not install globally.
+- `pyproject.toml` over `setup.py` for new projects.
+- Pin versions in production; unpin only in libraries.

package/templates/rules/respect-handoff-trigger.md

@@ -0,0 +1,41 @@
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Respect handoff triggers
+
+When you receive `additionalContext` mentioning a **handoff trigger**
+(containing phrases like "CONTEXT AT", "invoke /handoff", or
+"session state"), you MUST:
+
+1. **Stop** your current task immediately — do not finish the current
+   step, do not start a new one.
+2. **Invoke the `/handoff` skill** to write `.rulebook/handoff/_pending.md`
+   with: active task, decisions made this session, files touched, next
+   steps, and the exact resume command.
+3. **Display the message** `>>> TYPE /clear NOW — your context will be auto-restored <<<`
+   prominently so the user sees it.
+4. **Do not continue working** past the handoff message. The user must
+   type `/clear` before any further implementation.
+
+## Why
+
+Sessions degrade as context fills. Research shows that model quality
+at 80%+ context is measurably lower than at 0–50%. The handoff
+mechanism ensures work is preserved and the next session starts fresh
+with full context loaded via the `SessionStart` resume hook.
+
+This rule has the **highest precedence** after `git-safety.md`. If a
+handoff trigger fires while you are mid-edit, finish the current
+atomic write (do not leave a file in a broken state), then stop.
+
+## What triggers a handoff
+
+The `Stop` hook (`check-context-and-handoff.sh`) estimates context
+usage from the JSONL transcript. Two thresholds:
+
+- **warn (default 75%)**: advisory — the model should invoke `/handoff`
+  and suggest `/clear`.
+- **force (default 90%)**: mandatory — the model MUST invoke `/handoff`
+  and MUST NOT continue working.
+
+Both thresholds are configurable in `.rulebook/rulebook.json` under
+`handoff.warnThresholdPct` and `handoff.forceThresholdPct`.

package/templates/rules/rust.md

@@ -0,0 +1,40 @@
+---
+paths:
+  - "**/*.rs"
+  - "Cargo.toml"
+  - "Cargo.lock"
+  - "rust-toolchain.toml"
+---
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Rust rules
+
+Loaded by Claude Code when touching Rust sources or Cargo manifests.
+
+## Non-negotiables
+
+1. **`cargo check` before `cargo test`.** Check is 5–10x faster and surfaces type/borrow errors immediately. `cargo test` runs the checker anyway, but you lose the fast feedback loop.
+2. **`cargo clippy -- -D warnings`** must pass before committing. Warnings are errors in this project.
+3. **`cargo fmt`** before committing. Formatting is not a stylistic choice — `rustfmt` is the only authority.
+4. **No `unwrap()` / `expect()` in non-test code** unless the invariant is obvious from the surrounding 5 lines. Prefer `?` and proper error types.
+5. **No `unsafe` without a `// SAFETY:` comment** explaining why the invariants hold.
+
+## Conventions
+
+- Error types: use `thiserror` for libraries, `anyhow` for applications. Do not mix.
+- `Result<T, E>` returns on public APIs; never panic for recoverable errors.
+- `#[must_use]` on functions returning a value the caller must handle.
+- Lifetimes explicit only when the compiler asks for them. Do not add elided lifetimes "for clarity".
+- Trait bounds on the impl block, not on every method, unless they genuinely differ.
+
+## Testing
+
+- Unit tests in `#[cfg(test)] mod tests { ... }` at the bottom of the same file.
+- Integration tests in `tests/`, one file per public behavior.
+- `cargo test --all-features` is the baseline; default features may hide bugs.
+
+## Build & tooling
+
+- Never commit `target/` or `Cargo.lock` for libraries (commit for binaries).
+- Prefer `cargo add <crate>` over editing `Cargo.toml` by hand.
+- Use `cargo-watch` locally; never add watchers to CI.

package/templates/rules/typescript.md

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

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

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

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

@@ -0,0 +1,27 @@
+---
+name: handoff
+description: Save session state to .rulebook/handoff/_pending.md for cross-session continuity
+model: sonnet
+context: fork
+agent: researcher
+---
+Save a session handoff to `.rulebook/handoff/_pending.md`.
+
+The handoff file MUST contain:
+
+1. **Active task**: current task ID + phase + which checklist items are done
+2. **Decisions made this session**: architectural choices, trade-offs, rejected alternatives
+3. **Files touched**: list of files modified with one-line reason each
+4. **Next steps**: concrete, actionable items (not vague "continue working")
+5. **Exact resume command**: what to tell the next session to do first
+6. **Open questions / blockers**: anything unresolved that needs the user's input
+
+Write the file to `.rulebook/handoff/_pending.md` using the Write tool.
+
+After writing successfully, display this message prominently:
+
+>>> TYPE /clear NOW — your context will be auto-restored in the next session <<<
+
+If the file `.rulebook/handoff/.urgent` exists, skip any confirmations and write immediately.
+
+The SessionStart hook (`resume-from-handoff.sh`) will automatically inject the handoff content into the next session and archive the file.