@hivehub/rulebook 5.4.1 → 5.5.1

package/templates/rules/knowledge-base-usage.md

@@ -1,41 +1,41 @@
-# Always use the knowledge base — read before implementing, write after learning
-
-# Knowledge Base Usage — Mandatory for All Implementation Work
-
-The knowledge base (`rulebook knowledge` + `rulebook learn`) is the project's institutional memory. It prevents repeating mistakes and ensures proven patterns are reused.
-
-## BEFORE Starting Any Implementation
-
-1. **Check existing knowledge**: `rulebook knowledge list`
-2. **Search for relevant learnings**: `rulebook learn list`
-3. **Apply patterns** that match your task — do NOT reinvent approaches that are already documented
-4. **Avoid anti-patterns** — if a documented anti-pattern matches your planned approach, STOP and choose a different path
-
-## DURING Implementation
-
-When you discover something non-obvious:
-- A workaround for a framework limitation → `rulebook learn capture`
-- A debugging technique that saved time → `rulebook learn capture`
-- A pattern that emerged and worked well → `rulebook knowledge add pattern`
-- An approach that failed → `rulebook knowledge add anti-pattern`
-
-## AFTER Completing a Task (before archive)
-
-**Minimum 1 entry per task**. Record at least one of:
-- `rulebook knowledge add pattern "<what worked>"` — reusable approach
-- `rulebook knowledge add anti-pattern "<what failed>"` — approach to avoid
-- `rulebook learn capture --title "<title>" --content "<insight>"` — implementation insight
-- `rulebook decision create` — if a significant architectural choice was made
-
-## Forbidden
-
-- Starting implementation without checking `rulebook knowledge list`
-- Archiving a task without capturing at least one learning
-- Ignoring documented anti-patterns and repeating known mistakes
-- Discovering a useful pattern and not recording it
-
-## Why
-
-Without the knowledge base, every session starts from zero. AI agents repeat the same mistakes, rediscover the same patterns, and waste cycles on approaches that were already tried and failed. The knowledge base is what makes the project smarter over time.
-
-**"Those who cannot remember the past are condemned to repeat it."**
+# Always use the knowledge base — read before implementing, write after learning
+
+# Knowledge Base Usage — Mandatory for All Implementation Work
+
+The knowledge base (`rulebook knowledge` + `rulebook learn`) is the project's institutional memory. It prevents repeating mistakes and ensures proven patterns are reused.
+
+## BEFORE Starting Any Implementation
+
+1. **Check existing knowledge**: `rulebook knowledge list`
+2. **Search for relevant learnings**: `rulebook learn list`
+3. **Apply patterns** that match your task — do NOT reinvent approaches that are already documented
+4. **Avoid anti-patterns** — if a documented anti-pattern matches your planned approach, STOP and choose a different path
+
+## DURING Implementation
+
+When you discover something non-obvious:
+- A workaround for a framework limitation → `rulebook learn capture`
+- A debugging technique that saved time → `rulebook learn capture`
+- A pattern that emerged and worked well → `rulebook knowledge add pattern`
+- An approach that failed → `rulebook knowledge add anti-pattern`
+
+## AFTER Completing a Task (before archive)
+
+**Minimum 1 entry per task**. Record at least one of:
+- `rulebook knowledge add pattern "<what worked>"` — reusable approach
+- `rulebook knowledge add anti-pattern "<what failed>"` — approach to avoid
+- `rulebook learn capture --title "<title>" --content "<insight>"` — implementation insight
+- `rulebook decision create` — if a significant architectural choice was made
+
+## Forbidden
+
+- Starting implementation without checking `rulebook knowledge list`
+- Archiving a task without capturing at least one learning
+- Ignoring documented anti-patterns and repeating known mistakes
+- Discovering a useful pattern and not recording it
+
+## Why
+
+Without the knowledge base, every session starts from zero. AI agents repeat the same mistakes, rediscover the same patterns, and waste cycles on approaches that were already tried and failed. The knowledge base is what makes the project smarter over time.
+
+**"Those who cannot remember the past are condemned to repeat it."**

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