@hivehub/rulebook 4.3.1 → 5.0.0

package/templates/core/TIER1_PROHIBITIONS.md

@@ -0,0 +1,154 @@
+<!-- TIER1_PROHIBITIONS:START -->
+# Absolute Prohibitions (Tier 1 — Highest Precedence)
+
+**These rules override ALL other rules. Violation = output rejected.**
+
+---
+
+## PROHIBITION 1: No Shortcuts, Stubs, or Simplified Logic
+
+**NEVER** simplify logic, add TODO/FIXME/HACK, create stubs, use placeholders, alter existing logic to avoid complexity, reduce scope, skip edge cases, or deliver partial implementations.
+
+**Response time is IRRELEVANT. Quality is everything.**
+
+### Forbidden Patterns
+- `// TODO` — unfinished work disguised as progress
+- `// FIXME` — a known bug left for "later"
+- `// HACK` — a shortcut that will haunt you
+- `return 0; // placeholder` — a lie that compiles
+- `/* stub */` — an empty promise
+- Simplified algorithms where the correct one is known
+- Partial implementations ("I'll add the rest later")
+- Reduced scope without explicit approval
+
+### 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 implementation > fast delivery
+- **Ask if unsure** — propose a plan, never silently simplify
+
+---
+
+## PROHIBITION 2: No Destructive Git Operations Without Authorization
+
+### Allowed (always safe)
+- `git status`, `git diff`, `git log`, `git blame`
+- `git add`, `git commit` (after quality checks)
+
+### Forbidden (require explicit user authorization)
+- `git stash` — can lose uncommitted work
+- `git rebase` — rewrites history
+- `git reset --hard` — destroys uncommitted changes
+- `git checkout -- .` / `git restore .` — discards all changes
+- `git revert` — creates new commits
+- `git cherry-pick` — can cause conflicts
+- `git merge` — can create conflicts
+- `git branch -D` — deletes branch permanently
+- `git push --force` — overwrites remote history
+- `git clean -f` — deletes untracked files permanently
+- `git checkout <branch>` / `git switch` — breaks concurrent sessions sharing the worktree
+
+**Why**: Multiple AI sessions may share the same working tree. Destructive operations affect ALL concurrent sessions.
+
+---
+
+## PROHIBITION 3: No Deletion Without Authorization
+
+**NEVER** run `rm`, `rm -rf`, `del`, or delete any file without explicit user authorization ("yes, delete it").
+
+This includes:
+- Cache files (they auto-invalidate — DO NOT manually delete)
+- Backup files
+- Temporary files (clean up YOUR temp files, never others')
+- Build artifacts (use the build system's clean command)
+- Lock files (investigate what holds the lock first)
+
+**Why**: AI agents repeatedly delete important files during "cleanup." The cost of an unauthorized deletion (hours rebuilding caches, lost data) always exceeds the cost of asking first.
+
+---
+
+## PROHIBITION 4: Research Before Implementing — Never Guess
+
+**NEVER** guess at:
+- The cause of a bug
+- How an API works
+- What a function does based on its name
+- What "correct" output looks like
+
+### 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
+
+**"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.**
+
+---
+
+## PROHIBITION 5: Sequential File Editing
+
+**ALWAYS** edit files one at a time in sequence: Read file1 → Edit file1 → Read file2 → Edit file2.
+
+**NEVER** batch-read multiple files then batch-edit them. By the time you edit file 3, the 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
+5. **Build/test** after each sub-task
+
+---
+
+## PROHIBITION 6: No Deferred Tasks
+
+If a task is in the checklist, **implement it**. No exceptions.
+
+- **NEVER** mark tasks as "Deferred"
+- **NEVER** write "Deferred — requires X"
+- **NEVER** skip tasks with excuses
+- **NEVER** deliver partial implementations with "will do later"
+
+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, explain WHY in concrete terms and propose an alternative — do NOT just write "Deferred."
+
+---
+
+## PROHIBITION 7: Follow Task Sequence — No Reordering, No Cherry-Picking
+
+When a `tasks.md` checklist defines a sequence of items, **execute them in EXACTLY that order**.
+
+### Forbidden
+
+- **NEVER** skip ahead to "easier" or "more interesting" tasks
+- **NEVER** reorder tasks because you think a different order is better
+- **NEVER** cherry-pick tasks from the middle of a list
+- **NEVER** decide which tasks are "important enough" to do — do ALL of them, in order
+- **NEVER** group or batch tasks in a different sequence than listed
+- **NEVER** start 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 because upstream work wasn't done first
+- The human loses track of what's actually complete
+- Work has to be redone because it was built on missing foundations
+- Trust erodes — the human defined a plan and the AI ignored it
+
+**The task list is an ORDER, not a MENU. Execute sequentially.**
+
+<!-- TIER1_PROHIBITIONS:END -->

package/templates/core/TOKEN_OPTIMIZATION.md

@@ -0,0 +1,49 @@
+<!-- TOKEN_OPTIMIZATION:START -->
+# Token Optimization Rules
+
+Output verbosity rules calibrated by model capability tier.
+These rules ensure cost-efficient use of AI models without sacrificing quality.
+
+## Model Tier Assignment
+
+| Tier | Use For | Claude | Gemini | OpenAI |
+|------|---------|--------|--------|--------|
+| **Core** | Complex bugs, architecture, domain-critical code | opus | Pro | o3 |
+| **Standard** | Tests, implementation, build system, medium tasks | sonnet | Flash | 4o |
+| **Research** | Read-only exploration, docs, codebase search | haiku | Flash-Lite | 4o-mini |
+
+## Output Rules by Tier
+
+### Research Tier (cheapest — maximize context for work, not reports)
+- Output code, not explanations
+- Minimal reports: "Done" instead of detailed status
+- No markdown tables, emoji, or status sections
+- Combine outputs into one response
+- No "Next Steps" sections
+- No repeating back what was asked
+
+### Standard Tier (balanced — brief summaries)
+- Brief summaries (2-3 sentences max)
+- Code with inline comments (no separate explanation blocks)
+- Report only: what changed, what passed, what failed
+- Skip preamble and transitions
+
+### Core Tier (most capable — full reasoning when needed)
+- Full explanations welcome for complex decisions
+- Document reasoning for non-obvious choices
+- Detailed analysis for bug investigations
+- Still avoid unnecessary verbosity
+
+## Token Savings Reference
+
+| Pattern to Avoid | Tokens Wasted | Alternative |
+|-------------------|---------------|-------------|
+| Emoji status tables | ~500/task | Plain text "Done" |
+| "Next Steps" sections | ~100/task | Omit entirely |
+| Detailed quality reports | ~300/task | "Tests pass, coverage 95%" |
+| Repeating the question | ~200/task | Jump to the answer |
+| Markdown formatting abuse | ~200/task | Minimal formatting |
+
+**Total savings**: ~850 tokens/task for research tier agents
+
+<!-- TOKEN_OPTIMIZATION:END -->

package/templates/git/GIT_WORKFLOW.md

@@ -3,6 +3,41 @@
 
 **CRITICAL**: Specific rules and patterns for Git version control workflow.
 
+## Git Command Allow-List (Quick Reference)
+
+### ALLOWED (always safe — no authorization needed)
+| Command | Purpose |
+|---------|---------|
+| `git status` | Check repository state |
+| `git diff` | View changes |
+| `git log` | View history |
+| `git blame` | View line-by-line attribution |
+| `git add <files>` | Stage specific files |
+| `git commit` | Create commits (after quality checks) |
+| `git branch` (list) | List branches |
+| `git tag` (list) | List tags |
+
+### FORBIDDEN (require explicit user authorization)
+| Command | Risk | Why |
+|---------|------|-----|
+| `git stash` | Loses uncommitted work | Hidden state that gets forgotten |
+| `git rebase` | Rewrites history | Breaks shared branch history |
+| `git reset --hard` | Destroys changes | Irreversible data loss |
+| `git checkout -- .` | Discards all changes | Irreversible data loss |
+| `git restore .` | Discards all changes | Irreversible data loss |
+| `git revert` | Creates revert commits | May cause unexpected conflicts |
+| `git cherry-pick` | Duplicates commits | Can cause merge conflicts |
+| `git merge` | Can create conflicts | Requires human judgment |
+| `git branch -D` | Deletes branch | Permanent, may lose work |
+| `git push --force` | Overwrites remote | NEVER on main/master |
+| `git clean -f` | Deletes untracked files | Permanent file deletion |
+| `git checkout <branch>` | Switches branch | Breaks concurrent AI sessions |
+| `git switch <branch>` | Switches branch | Breaks concurrent AI sessions |
+
+**Why**: Multiple AI sessions may share the same working tree. Branch switching or destructive operations affect ALL concurrent sessions.
+
+---
+
 ## Git Workflow Overview
 
 This project follows a strict Git workflow to ensure code quality and proper version control.

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

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

package/templates/rules/git-safety.md

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

package/templates/rules/incremental-tests.md

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

package/templates/rules/no-deferred.md

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

package/templates/rules/no-shortcuts.md

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

package/templates/rules/research-first.md

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

package/templates/rules/sequential-editing.md

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

package/templates/rules/session-workflow.md

@@ -0,0 +1,24 @@
+---
+name: session-workflow
+tier: 2
+description: "Read PLANS.md at session start, save summary at session end"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Session Workflow — Preserve Context Across Sessions
+
+## At Session Start
+1. Read `.rulebook/PLANS.md` for current context and active task
+2. Search memory for relevant past work: `rulebook_memory_search` or `rulebook_session_start`
+3. Check `.rulebook/tasks/` for pending work
+
+## During Session
+- Update PLANS.md when making key decisions or discoveries
+- Save important context to memory as you go
+
+## At Session End
+1. Save session summary to PLANS.md: `rulebook_session_end`
+2. Summary should include: what was accomplished, key decisions, next steps
+3. Update tasks.md with completed items

package/templates/rules/task-decomposition.md

@@ -0,0 +1,32 @@
+---
+name: task-decomposition
+tier: 2
+description: "Decompose multi-file tasks into 1-2 file sub-tasks"
+alwaysApply: true
+filePatterns: ["*"]
+tools: ["all"]
+---
+
+# Task Decomposition
+
+When a task touches multiple subsystems, decompose into sub-tasks where each modifies **at most 1-2 files**.
+
+## Why
+
+AI agents lose accuracy when editing 3+ files in one pass. Context from earlier files gets compressed away.
+
+## Rules
+
+1. **Each sub-task modifies 1-2 files** — never more
+2. **Each sub-task is independently verifiable** — it compiles, it doesn't break existing behavior
+3. **Sub-tasks follow data flow order** — upstream first (component → buffer → renderer → shader)
+4. **Each sub-task has a clear "done when"** — not "implement X", but "field Y exists with default Z"
+5. **Build after each sub-task** — verify compilation before proceeding
+
+## When an Agent Receives a Multi-File Task
+
+1. **STOP** — do not start implementing
+2. **Create a change plan** listing all files and dependency order
+3. **Decompose** into sub-tasks following this rule
+4. **Report back** with the decomposition
+5. **Implement** one sub-task at a time