@hivehub/rulebook 5.2.1 → 5.3.1

package/templates/rules/full-task-no-questions.md

@@ -0,0 +1,37 @@
+<!-- Generated by @hivehub/rulebook v5.3.0 — delete this comment to prevent regeneration on `rulebook update` -->
+
+# Execute the full task — never stop to ask permission mid-way
+
+**HIGHEST PRECEDENCE.** When the user gives you a task, execute it COMPLETELY in one turn. No "step 1, await confirmation, step 2". No mid-task check-ins.
+
+## Required
+
+- Read the full request, plan internally, execute end-to-end (read → edit → test → commit if asked) in **one turn**
+- Make decisions autonomously for anything within the scope of what was requested
+- When 3+ files need editing, edit them all in sequence in the same turn
+- Run the full quality pipeline (lint + type-check + test + commit if part of the request) without stopping
+- Report ONCE at the end with what was done
+
+## Forbidden
+
+- ❌ "I've done step 1. Should I proceed with step 2?"
+- ❌ "Want me to also update X?"
+- ❌ "Should I commit this now?" (unless commit was not part of the original request)
+- ❌ "Let me know if you'd like me to continue"
+- ❌ Doing one file edit then stopping to confirm before the next related file
+- ❌ Breaking a multi-file refactor into one-file-per-turn
+- ❌ Mid-task summaries asking for approval
+
+## When asking IS appropriate
+
+Only these three cases:
+
+1. **Genuine ambiguity that changes the result** — not "should I proceed?" but "you said 'fix the bug', there are 2 bugs in this file, which one?"
+2. **Destructive operations not explicitly authorized** — deletes, force pushes, dropping tables, etc.
+3. **Task as stated is impossible** — and you need a different approach to even attempt it
+
+Anything else: just keep going until done.
+
+## Why
+
+The user is busy. They asked once. Stop interrupting them with confirmations for work they already requested. A confirmation prompt mid-task wastes a full round-trip and breaks their flow. Trust the request, execute it, report at the end.

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/incremental-implementation.md

@@ -1,56 +1,56 @@
----
-name: incremental-implementation
-tier: 1
-description: "Implement step by step, test each step, restart from scratch if stuck"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Incremental Implementation — Step by Step, Test Each Step
-
-NEVER implement everything at once. Build incrementally, verify at every step, and restart from scratch when stuck.
-
-## Required Process
-
-1. **Understand** the full scope before writing any code
-2. **Decompose** into the smallest possible steps
-3. **Implement ONE step** at a time
-4. **Test/verify** that step immediately (compile, run, test)
-5. **Fix any errors** before moving to the next step
-6. **Record learnings** in the knowledge base after each significant discovery
-7. **Repeat** until complete
-
-## The Restart Rule
-
-If you have spent more than 3 failed attempts fixing the same error:
-
-1. **STOP** — do not try a 4th variation of the same approach
-2. **Analyze** what went wrong — write down root causes, not symptoms
-3. **Record** the failed approach as an anti-pattern in the knowledge base
-4. **Remove** the broken code completely — do not patch on top of patches
-5. **Reimplementation from scratch** using a different approach informed by what you learned
-6. **Test each step** of the new approach before proceeding
-
-## Knowledge Base Integration
-
-After every significant implementation:
-
-1. **Check existing knowledge** before starting: `rulebook knowledge list` or search `.rulebook/knowledge/`
-2. **Record patterns** that worked: `rulebook knowledge add pattern "<title>" --category <cat>`
-3. **Record anti-patterns** that failed: `rulebook knowledge add anti-pattern "<title>" --category <cat>`
-4. **Capture learnings** from debugging: `rulebook learn capture --title "<title>" --content "<content>"`
-
-## Forbidden
-
-- Implementing an entire feature in one pass without intermediate verification
-- Spending more than 3 attempts fixing the same error with the same approach
-- Patching broken code on top of broken code instead of restarting clean
-- Ignoring the knowledge base — check it BEFORE implementing, update it AFTER
-- Batching all tests to the end instead of testing each step
-
-## Why
-
-AI agents that implement everything at once produce cascading errors. One early mistake propagates through the entire implementation, and debugging becomes exponentially harder. Step-by-step with immediate verification catches errors at the source. When stuck, restarting from scratch with new knowledge is always faster than patching endlessly. The line between persistence and stubbornness is thin.
-
-**"Slow is smooth, smooth is fast."**
+---
+name: incremental-implementation
+tier: 1
+description: "Implement step by step, test each step, restart from scratch if stuck"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Incremental Implementation — Step by Step, Test Each Step
+
+NEVER implement everything at once. Build incrementally, verify at every step, and restart from scratch when stuck.
+
+## Required Process
+
+1. **Understand** the full scope before writing any code
+2. **Decompose** into the smallest possible steps
+3. **Implement ONE step** at a time
+4. **Test/verify** that step immediately (compile, run, test)
+5. **Fix any errors** before moving to the next step
+6. **Record learnings** in the knowledge base after each significant discovery
+7. **Repeat** until complete
+
+## The Restart Rule
+
+If you have spent more than 3 failed attempts fixing the same error:
+
+1. **STOP** — do not try a 4th variation of the same approach
+2. **Analyze** what went wrong — write down root causes, not symptoms
+3. **Record** the failed approach as an anti-pattern in the knowledge base
+4. **Remove** the broken code completely — do not patch on top of patches
+5. **Reimplementation from scratch** using a different approach informed by what you learned
+6. **Test each step** of the new approach before proceeding
+
+## Knowledge Base Integration
+
+After every significant implementation:
+
+1. **Check existing knowledge** before starting: `rulebook knowledge list` or search `.rulebook/knowledge/`
+2. **Record patterns** that worked: `rulebook knowledge add pattern "<title>" --category <cat>`
+3. **Record anti-patterns** that failed: `rulebook knowledge add anti-pattern "<title>" --category <cat>`
+4. **Capture learnings** from debugging: `rulebook learn capture --title "<title>" --content "<content>"`
+
+## Forbidden
+
+- Implementing an entire feature in one pass without intermediate verification
+- Spending more than 3 attempts fixing the same error with the same approach
+- Patching broken code on top of broken code instead of restarting clean
+- Ignoring the knowledge base — check it BEFORE implementing, update it AFTER
+- Batching all tests to the end instead of testing each step
+
+## Why
+
+AI agents that implement everything at once produce cascading errors. One early mistake propagates through the entire implementation, and debugging becomes exponentially harder. Step-by-step with immediate verification catches errors at the source. When stuck, restarting from scratch with new knowledge is always faster than patching endlessly. The line between persistence and stubbornness is thin.
+
+**"Slow is smooth, smooth is fast."**

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.