@hivehub/rulebook 5.7.0 → 5.8.0

package/templates/rules/follow-task-sequence.md

@@ -1,36 +1,36 @@
----
-name: follow-task-sequence
-tier: 1
-description: "Execute tasks in the exact order defined — no reordering, no cherry-picking"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Follow Task Sequence — No Reordering, No Cherry-Picking
-
-When a `tasks.md` checklist defines a sequence, execute items in EXACTLY that order.
-
-## Forbidden
-
-- Skipping ahead to "easier" or "more interesting" tasks
-- Reordering tasks because you think a different order is better
-- Cherry-picking tasks from the middle of a list
-- Deciding which tasks are "important enough" to do
-- Grouping or batching tasks in a different sequence
-- Starting Phase N+1 before Phase N is 100% complete
-
-## Required Behavior
-
-1. Read `tasks.md` from top to bottom
-2. Find the FIRST unchecked item (`- [ ]`)
-3. Implement THAT item — not the one you prefer
-4. Mark it `[x]` with what was done
-5. Move to the NEXT unchecked item
-6. Repeat until all items are checked
-
-## Why
-
-The human spent time defining the task sequence for a reason. The order reflects dependencies, priorities, and a deliberate implementation strategy. When AI agents skip around, dependencies break, progress tracking becomes unreliable, and work has to be redone.
-
-**The task list is an ORDER, not a MENU.**
+---
+name: follow-task-sequence
+tier: 1
+description: "Execute tasks in the exact order defined — no reordering, no cherry-picking"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Follow Task Sequence — No Reordering, No Cherry-Picking
+
+When a `tasks.md` checklist defines a sequence, execute items in EXACTLY that order.
+
+## Forbidden
+
+- Skipping ahead to "easier" or "more interesting" tasks
+- Reordering tasks because you think a different order is better
+- Cherry-picking tasks from the middle of a list
+- Deciding which tasks are "important enough" to do
+- Grouping or batching tasks in a different sequence
+- Starting Phase N+1 before Phase N is 100% complete
+
+## Required Behavior
+
+1. Read `tasks.md` from top to bottom
+2. Find the FIRST unchecked item (`- [ ]`)
+3. Implement THAT item — not the one you prefer
+4. Mark it `[x]` with what was done
+5. Move to the NEXT unchecked item
+6. Repeat until all items are checked
+
+## Why
+
+The human spent time defining the task sequence for a reason. The order reflects dependencies, priorities, and a deliberate implementation strategy. When AI agents skip around, dependencies break, progress tracking becomes unreliable, and work has to be redone.
+
+**The task list is an ORDER, not a MENU.**

package/templates/rules/git-safety.md

@@ -1,29 +1,29 @@
----
-name: git-safety
-tier: 1
-description: "Git safety — explicit allow-list, forbidden destructive operations"
-alwaysApply: true
-filePatterns: ["*"]
-tools: ["all"]
----
-
-# Git Safety Rules
-
-## Allowed (always safe)
-- `git status`, `git diff`, `git log`, `git blame`
-- `git add <files>`, `git commit` (after quality checks)
-
-## Forbidden (require explicit user authorization)
-- `git stash` — hidden state gets forgotten
-- `git rebase` — rewrites history
-- `git reset --hard` — destroys uncommitted changes
-- `git checkout -- .` / `git restore .` — discards all changes
-- `git revert` — creates unexpected commits
-- `git cherry-pick` — can cause conflicts
-- `git merge` — requires human judgment
-- `git branch -D` — permanent branch deletion
-- `git push --force` — NEVER on main/master
-- `git clean -f` — permanently deletes untracked files
-- `git checkout <branch>` / `git switch` — breaks concurrent AI sessions
-
-Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.
+---
+name: git-safety
+tier: 1
+description: "Git safety — explicit allow-list, forbidden destructive operations"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Git Safety Rules
+
+## Allowed (always safe)
+- `git status`, `git diff`, `git log`, `git blame`
+- `git add <files>`, `git commit` (after quality checks)
+
+## Forbidden (require explicit user authorization)
+- `git stash` — hidden state gets forgotten
+- `git rebase` — rewrites history
+- `git reset --hard` — destroys uncommitted changes
+- `git checkout -- .` / `git restore .` — discards all changes
+- `git revert` — creates unexpected commits
+- `git cherry-pick` — can cause conflicts
+- `git merge` — requires human judgment
+- `git branch -D` — permanent branch deletion
+- `git push --force` — NEVER on main/master
+- `git clean -f` — permanently deletes untracked files
+- `git checkout <branch>` / `git switch` — breaks concurrent AI sessions
+
+Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.

package/templates/rules/go.md

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

@@ -1,29 +1,29 @@
----
-name: incremental-tests
-tier: 2
-description: "Write tests in small batches, verify immediately"
-alwaysApply: true
-filePatterns: ["*.test.*", "*.spec.*", "*_test.*"]
-tools: ["all"]
----
-
-# Incremental Test Development
-
-Write tests 1-3 at a time. Test immediately after writing. Fix errors before proceeding.
-
-## Rules
-
-1. **Write 1-3 tests** at a time, NOT entire test files at once
-2. **Run immediately** after writing — use single-file test execution
-3. **Fix errors** before writing more tests
-4. **Never run full suite** while developing tests — use individual file execution
-5. **Coverage updates** only after completing a block of tests
-
-## Why
-
-Writing full test files at once leads to cascading failures. One early error invalidates all subsequent tests, creating debug fatigue and wasted time.
-
-## Development Testing vs Validation Testing
-
-- **Development**: Run single test file (`vitest run tests/my.test.ts`)
-- **Validation**: Run full suite only when a batch of tests is complete
+---
+name: incremental-tests
+tier: 2
+description: "Write tests in small batches, verify immediately"
+alwaysApply: true
+filePatterns: ["*.test.*", "*.spec.*", "*_test.*"]
+tools: ["all"]
+---
+
+# Incremental Test Development
+
+Write tests 1-3 at a time. Test immediately after writing. Fix errors before proceeding.
+
+## Rules
+
+1. **Write 1-3 tests** at a time, NOT entire test files at once
+2. **Run immediately** after writing — use single-file test execution
+3. **Fix errors** before writing more tests
+4. **Never run full suite** while developing tests — use individual file execution
+5. **Coverage updates** only after completing a block of tests
+
+## Why
+
+Writing full test files at once leads to cascading failures. One early error invalidates all subsequent tests, creating debug fatigue and wasted time.
+
+## Development Testing vs Validation Testing
+
+- **Development**: Run single test file (`vitest run tests/my.test.ts`)
+- **Validation**: Run full suite only when a batch of tests is complete

package/templates/rules/java.md

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

@@ -1,39 +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.
+---
+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/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."**