@hivehub/rulebook 5.5.2 → 5.8.0

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

@@ -1,75 +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`.
+<!-- 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/no-deferred.md

@@ -1,31 +1,31 @@
----
-name: no-deferred
-tier: 2
-description: "Never defer tasks — implement or explain why impossible"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# No Deferred Tasks
-
-If a task is in the checklist, **implement it**. No exceptions.
-
-## Forbidden
-
-- Marking tasks as "Deferred"
-- Writing "Deferred — requires X"
-- Skipping tasks with excuses
-- Partial implementations with "will do later"
-
-## Required Behavior
-
-If a task has a genuine dependency:
-1. Implement the dependency FIRST
-2. Then implement the task
-3. Mark BOTH as done
-
-If you truly cannot implement something:
-1. Explain WHY in concrete terms
-2. Propose an alternative solution
-3. Do NOT just write "Deferred"
+---
+name: no-deferred
+tier: 2
+description: "Never defer tasks — implement or explain why impossible"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# No Deferred Tasks
+
+If a task is in the checklist, **implement it**. No exceptions.
+
+## Forbidden
+
+- Marking tasks as "Deferred"
+- Writing "Deferred — requires X"
+- Skipping tasks with excuses
+- Partial implementations with "will do later"
+
+## Required Behavior
+
+If a task has a genuine dependency:
+1. Implement the dependency FIRST
+2. Then implement the task
+3. Mark BOTH as done
+
+If you truly cannot implement something:
+1. Explain WHY in concrete terms
+2. Propose an alternative solution
+3. Do NOT just write "Deferred"

package/templates/rules/no-shortcuts.md

@@ -1,30 +1,30 @@
----
-name: no-shortcuts
-tier: 1
-description: "Never use stubs, TODOs, placeholders, or approximations"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# No Shortcuts — Quality Over Speed
-
-Response time is IRRELEVANT. The ONLY thing that matters is quality.
-
-## Absolutely Forbidden
-
-1. **NEVER simplify logic** to deliver faster — implement the correct algorithm
-2. **NEVER add TODOs** — if it needs to be done, do it NOW
-3. **NEVER use stubs** — every function must have its real implementation
-4. **NEVER use placeholders** — no `// placeholder`, no `return 0; // fixme`
-5. **NEVER cut corners** to reduce output size
-6. **NEVER skip edge cases** — handle all of them
-7. **NEVER deliver partial implementations** — complete or explain why not
-8. **NEVER alter existing logic** to make your task easier
-
-## Required Behavior
-
-- **Research** the correct approach before writing code
-- **Implement completely** — every function, every edge case, every error path
-- **Take as long as needed** — correct > fast
-- **Ask if unsure** — propose a plan, never silently simplify
+---
+name: no-shortcuts
+tier: 1
+description: "Never use stubs, TODOs, placeholders, or approximations"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# No Shortcuts — Quality Over Speed
+
+Response time is IRRELEVANT. The ONLY thing that matters is quality.
+
+## Absolutely Forbidden
+
+1. **NEVER simplify logic** to deliver faster — implement the correct algorithm
+2. **NEVER add TODOs** — if it needs to be done, do it NOW
+3. **NEVER use stubs** — every function must have its real implementation
+4. **NEVER use placeholders** — no `// placeholder`, no `return 0; // fixme`
+5. **NEVER cut corners** to reduce output size
+6. **NEVER skip edge cases** — handle all of them
+7. **NEVER deliver partial implementations** — complete or explain why not
+8. **NEVER alter existing logic** to make your task easier
+
+## Required Behavior
+
+- **Research** the correct approach before writing code
+- **Implement completely** — every function, every edge case, every error path
+- **Take as long as needed** — correct > fast
+- **Ask if unsure** — propose a plan, never silently simplify

package/templates/rules/python.md

@@ -1,43 +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.
+---
+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/research-first.md

@@ -1,30 +1,30 @@
----
-name: research-first
-tier: 1
-description: "Always research before implementing — never guess"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Research Before Implementing
-
-NEVER guess at bug causes, API behavior, or algorithm correctness.
-
-## Required Process
-
-1. **State what you KNOW** (from logs, debug output, code reading)
-2. **State what you DON'T KNOW**
-3. **Research** the unknown (read source, check docs, use diagnostic tools)
-4. **Only then** implement the fix
-
-## Forbidden
-
-- Guessing at the cause of a bug
-- "Trying things" to see if they work
-- Hypothesizing without reading code
-- Assuming how an API works without checking docs
-- Iterating blindly — each attempt must be informed by new data
-
-**"I think this might be the problem" is NOT acceptable.**
-**"Source X does Y at file:line, we do Z, the difference causes W" IS acceptable.**
+---
+name: research-first
+tier: 1
+description: "Always research before implementing — never guess"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Research Before Implementing
+
+NEVER guess at bug causes, API behavior, or algorithm correctness.
+
+## Required Process
+
+1. **State what you KNOW** (from logs, debug output, code reading)
+2. **State what you DON'T KNOW**
+3. **Research** the unknown (read source, check docs, use diagnostic tools)
+4. **Only then** implement the fix
+
+## Forbidden
+
+- Guessing at the cause of a bug
+- "Trying things" to see if they work
+- Hypothesizing without reading code
+- Assuming how an API works without checking docs
+- Iterating blindly — each attempt must be informed by new data
+
+**"I think this might be the problem" is NOT acceptable.**
+**"Source X does Y at file:line, we do Z, the difference causes W" IS acceptable.**

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

@@ -1,41 +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`.
+<!-- 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

@@ -1,40 +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.
+---
+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/sequential-editing.md

@@ -1,21 +1,21 @@
----
-name: sequential-editing
-tier: 1
-description: "Edit files one at a time, never batch-edit"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Sequential File Editing
-
-ALWAYS edit files one at a time: Read file1 → Edit file1 → Read file2 → Edit file2.
-
-NEVER batch-read multiple files then batch-edit them. By the time you edit file 3, context from file 1 may be stale.
-
-When a task touches 3+ files across subsystems:
-1. **STOP** — do not start implementing
-2. **Plan** the changes (list files, dependency order)
-3. **Decompose** into sub-tasks of 1-2 files each
-4. **Execute** sub-tasks in dependency order (upstream first)
-5. **Build/test** after each sub-task
+---
+name: sequential-editing
+tier: 1
+description: "Edit files one at a time, never batch-edit"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Sequential File Editing
+
+ALWAYS edit files one at a time: Read file1 → Edit file1 → Read file2 → Edit file2.
+
+NEVER batch-read multiple files then batch-edit them. By the time you edit file 3, context from file 1 may be stale.
+
+When a task touches 3+ files across subsystems:
+1. **STOP** — do not start implementing
+2. **Plan** the changes (list files, dependency order)
+3. **Decompose** into sub-tasks of 1-2 files each
+4. **Execute** sub-tasks in dependency order (upstream first)
+5. **Build/test** after each sub-task