@hivehub/rulebook 5.4.0 → 5.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hivehub/rulebook",
-  "version": "5.4.0",
+  "version": "5.5.0",
   "description": "Tool-agnostic AI development framework. Standardize projects across Claude Code, Cursor, Gemini, Codex, Windsurf, Copilot with automated templates, quality gates, persistent memory, and framework detection for 28 languages, 17 frameworks, 13 MCP modules, and 20 services",
   "type": "module",
   "main": "dist/index.js",

package/templates/cli/gemini-extension.json

@@ -1,77 +1,77 @@
-{
-  "$schema": "https://ai.google.dev/schemas/gemini-extension.json",
-  "name": "rulebook",
-  "displayName": "Rulebook Project Standards",
-  "version": "2.0.0",
-  "description": "Standardize AI-generated projects with skills, templates, and quality gates",
-  "author": "HiveLLM",
-  "license": "Apache-2.0",
-  "capabilities": {
-    "codeGeneration": true,
-    "taskManagement": true,
-    "projectValidation": true,
-    "skillsSystem": true
-  },
-  "commands": {
-    "init": {
-      "description": "Initialize rulebook for current project",
-      "command": "rulebook init --yes"
-    },
-    "update": {
-      "description": "Update project rules to latest version",
-      "command": "rulebook update --yes"
-    },
-    "validate": {
-      "description": "Validate project structure",
-      "command": "rulebook validate"
-    },
-    "health": {
-      "description": "Check project health score",
-      "command": "rulebook health"
-    },
-    "fix": {
-      "description": "Auto-fix common issues",
-      "command": "rulebook fix"
-    },
-    "skill-list": {
-      "description": "List available skills",
-      "command": "rulebook skill list"
-    },
-    "skill-add": {
-      "description": "Add a skill",
-      "command": "rulebook skill add"
-    },
-    "task-create": {
-      "description": "Create a new task",
-      "command": "rulebook task create"
-    },
-    "task-list": {
-      "description": "List all tasks",
-      "command": "rulebook task list"
-    }
-  },
-  "files": {
-    "instructions": "GEMINI.md",
-    "agents": "AGENTS.md",
-    "config": ".rulebook",
-    "rules": "rulebook/"
-  },
-  "integration": {
-    "type": "cli",
-    "install": "npm install -g @hivehub/rulebook",
-    "mcp": {
-      "enabled": true,
-      "server": "rulebook-mcp"
-    }
-  },
-  "skills": {
-    "enabled": true,
-    "categories": [
-      "languages",
-      "frameworks",
-      "modules",
-      "services",
-      "core"
-    ]
-  }
-}
+{
+  "$schema": "https://ai.google.dev/schemas/gemini-extension.json",
+  "name": "rulebook",
+  "displayName": "Rulebook Project Standards",
+  "version": "2.0.0",
+  "description": "Standardize AI-generated projects with skills, templates, and quality gates",
+  "author": "HiveLLM",
+  "license": "Apache-2.0",
+  "capabilities": {
+    "codeGeneration": true,
+    "taskManagement": true,
+    "projectValidation": true,
+    "skillsSystem": true
+  },
+  "commands": {
+    "init": {
+      "description": "Initialize rulebook for current project",
+      "command": "rulebook init --yes"
+    },
+    "update": {
+      "description": "Update project rules to latest version",
+      "command": "rulebook update --yes"
+    },
+    "validate": {
+      "description": "Validate project structure",
+      "command": "rulebook validate"
+    },
+    "health": {
+      "description": "Check project health score",
+      "command": "rulebook health"
+    },
+    "fix": {
+      "description": "Auto-fix common issues",
+      "command": "rulebook fix"
+    },
+    "skill-list": {
+      "description": "List available skills",
+      "command": "rulebook skill list"
+    },
+    "skill-add": {
+      "description": "Add a skill",
+      "command": "rulebook skill add"
+    },
+    "task-create": {
+      "description": "Create a new task",
+      "command": "rulebook task create"
+    },
+    "task-list": {
+      "description": "List all tasks",
+      "command": "rulebook task list"
+    }
+  },
+  "files": {
+    "instructions": "GEMINI.md",
+    "agents": "AGENTS.md",
+    "config": ".rulebook",
+    "rules": "rulebook/"
+  },
+  "integration": {
+    "type": "cli",
+    "install": "npm install -g @hivehub/rulebook",
+    "mcp": {
+      "enabled": true,
+      "server": "rulebook-mcp"
+    }
+  },
+  "skills": {
+    "enabled": true,
+    "categories": [
+      "languages",
+      "frameworks",
+      "modules",
+      "services",
+      "core"
+    ]
+  }
+}

package/templates/core/AGENTS_LEAN.md

@@ -16,6 +16,15 @@ These override everything else. Violation = output rejected.
 7. **Follow task sequence.** Execute `tasks.md` items in the EXACT order listed. No reordering, no cherry-picking, no starting Phase N+1 before Phase N is 100% done. The list is an ORDER, not a MENU.
 8. **Execute the full task in one turn.** Never stop mid-task to ask "should I proceed?" or "want me to also...?". Make autonomous decisions within scope. Only ask for genuine ambiguity, destructive ops, or impossible tasks.
 
+## Editing Discipline (Karpathy-inspired)
+
+Behavioral guidelines that reduce common LLM coding mistakes. Adapted from [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills), grounded in [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876).
+
+1. **Think before coding.** State assumptions explicitly. If multiple interpretations exist, present them — don't pick silently. If a simpler approach exists, say so. If something is unclear, stop and ask. Don't hide confusion.
+2. **Simplicity first.** Minimum code that solves the problem. No features beyond what was asked, no abstractions for single-use code, no "flexibility" that wasn't requested, no error handling for impossible scenarios. If you write 200 lines and 50 would do, rewrite.
+3. **Surgical changes.** Touch only what you must. Don't "improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style. If you notice unrelated dead code, mention it — don't delete it. Every changed line must trace directly to the user's request.
+4. **Goal-driven execution.** Define verifiable success criteria upfront. "Add validation" → "write tests for invalid inputs, then make them pass." For multi-step tasks, state a brief plan: `[step] → verify: [check]`. Strong criteria let you loop independently; weak criteria require constant clarification.
+
 ## Critical Rules
 
 - **ALWAYS read `/.rulebook/specs/RULEBOOK.md`** before creating tasks.

package/templates/core/CLAUDE_MD_v2.md

@@ -31,6 +31,15 @@ automatically at session start (see [Anthropic memory docs](https://code.claude.
 7. **Capture learnings**: at the end of significant work, save patterns and anti-patterns to `.rulebook/knowledge/` and insights to `.rulebook/learnings/`.
 8. **Never archive a task** without docs updated, tests written, and tests passing — the task tail enforces this structurally.
 
+## Editing discipline (Karpathy-inspired)
+
+Behavioral guidelines that reduce common LLM coding mistakes. Adapted from [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills), grounded in [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876).
+
+1. **Think before coding.** State assumptions explicitly. If multiple interpretations exist, present them — don't pick silently. If a simpler approach exists, say so. If something is unclear, stop and ask. Don't hide confusion.
+2. **Simplicity first.** Minimum code that solves the problem. No features beyond what was asked, no abstractions for single-use code, no "flexibility" that wasn't requested, no error handling for impossible scenarios. If you write 200 lines and 50 would do, rewrite.
+3. **Surgical changes.** Touch only what you must. Don't "improve" adjacent code, comments, or formatting. Don't refactor things that aren't broken. Match existing style. If you notice unrelated dead code, mention it — don't delete it. Every changed line must trace directly to the user's request.
+4. **Goal-driven execution.** Define verifiable success criteria upfront. "Add validation" → "write tests for invalid inputs, then make them pass." For multi-step tasks, state a brief plan: `[step] → verify: [check]`. Strong criteria let you loop independently; weak criteria require constant clarification.
+
 ## Persistent memory
 
 This project uses the Rulebook MCP server for persistent memory across sessions.

package/templates/core/WORKSPACE.md

@@ -1,69 +1,69 @@
-<!-- RULEBOOK:START -->
-# Workspace Mode
-
-**This project is part of a multi-project workspace managed by Rulebook.**
-
-## CRITICAL: Project Routing
-
-When calling ANY Rulebook MCP tool, you MUST pass the `projectId` parameter to target the correct project.
-
-### How to determine the current project
-
-1. **Check which files you are editing** — the file path tells you which project you are in
-2. **Use `rulebook_workspace_list`** to see all available projects and their paths
-3. **Match the file path to a project path** to determine the `projectId`
-
-### Examples
-
-```
-# You are editing files in /path/to/frontend/src/App.tsx
-# → projectId = "frontend"
-
-rulebook_task_create({ taskId: "add-auth", projectId: "frontend" })
-rulebook_task_list({ projectId: "frontend" })
-rulebook_memory_save({ ..., projectId: "frontend" })
-rulebook_memory_search({ query: "auth", projectId: "frontend" })
-```
-
-### Cross-project operations
-
-Use these dedicated workspace tools for operations across ALL projects:
-
-- `rulebook_workspace_list` — List all projects in the workspace
-- `rulebook_workspace_status` — Status of each project (active workers, task count)
-- `rulebook_workspace_search` — Search memory across ALL projects at once
-- `rulebook_workspace_tasks` — List tasks from ALL projects at once
-
-### Default project
-
-If you omit `projectId`, the **default project** is used: `{{DEFAULT_PROJECT}}`.
-Only omit `projectId` when you are certain the operation targets the default project.
-
-## Workspace Projects
-
-{{WORKSPACE_PROJECTS}}
-
-## Rules
-
-1. **NEVER save memory to the wrong project** — always verify `projectId` before calling `rulebook_memory_save`
-2. **NEVER create tasks in the wrong project** — check which project the feature belongs to
-3. **When working across projects** (e.g., shared types), save memory to BOTH relevant projects
-4. **Use `rulebook_workspace_search`** to find related context across all projects before starting work
-5. **Each project has its own `.rulebook/`** directory — configs, tasks, and memory are fully isolated
-
-## CLI Commands
-
-```bash
-# List tasks from a specific project
-rulebook task list --project frontend
-
-# List tasks from ALL projects
-rulebook task list --all-projects
-
-# Create task in specific project
-rulebook task create my-task --project backend
-
-# Update all projects at once
-rulebook update
-```
-<!-- RULEBOOK:END -->
+<!-- RULEBOOK:START -->
+# Workspace Mode
+
+**This project is part of a multi-project workspace managed by Rulebook.**
+
+## CRITICAL: Project Routing
+
+When calling ANY Rulebook MCP tool, you MUST pass the `projectId` parameter to target the correct project.
+
+### How to determine the current project
+
+1. **Check which files you are editing** — the file path tells you which project you are in
+2. **Use `rulebook_workspace_list`** to see all available projects and their paths
+3. **Match the file path to a project path** to determine the `projectId`
+
+### Examples
+
+```
+# You are editing files in /path/to/frontend/src/App.tsx
+# → projectId = "frontend"
+
+rulebook_task_create({ taskId: "add-auth", projectId: "frontend" })
+rulebook_task_list({ projectId: "frontend" })
+rulebook_memory_save({ ..., projectId: "frontend" })
+rulebook_memory_search({ query: "auth", projectId: "frontend" })
+```
+
+### Cross-project operations
+
+Use these dedicated workspace tools for operations across ALL projects:
+
+- `rulebook_workspace_list` — List all projects in the workspace
+- `rulebook_workspace_status` — Status of each project (active workers, task count)
+- `rulebook_workspace_search` — Search memory across ALL projects at once
+- `rulebook_workspace_tasks` — List tasks from ALL projects at once
+
+### Default project
+
+If you omit `projectId`, the **default project** is used: `{{DEFAULT_PROJECT}}`.
+Only omit `projectId` when you are certain the operation targets the default project.
+
+## Workspace Projects
+
+{{WORKSPACE_PROJECTS}}
+
+## Rules
+
+1. **NEVER save memory to the wrong project** — always verify `projectId` before calling `rulebook_memory_save`
+2. **NEVER create tasks in the wrong project** — check which project the feature belongs to
+3. **When working across projects** (e.g., shared types), save memory to BOTH relevant projects
+4. **Use `rulebook_workspace_search`** to find related context across all projects before starting work
+5. **Each project has its own `.rulebook/`** directory — configs, tasks, and memory are fully isolated
+
+## CLI Commands
+
+```bash
+# List tasks from a specific project
+rulebook task list --project frontend
+
+# List tasks from ALL projects
+rulebook task list --all-projects
+
+# Create task in specific project
+rulebook task create my-task --project backend
+
+# Update all projects at once
+rulebook update
+```
+<!-- RULEBOOK:END -->

package/templates/skills/core/karpathy-guidelines/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: "Karpathy Guidelines"
+description: "Behavioral guidelines to reduce common LLM coding mistakes — overcomplication, sloppy refactors, hidden assumptions, weak goals. Use when writing, reviewing, or refactoring code. Auto-applies; invoke explicitly via /karpathy-guidelines or 'follow karpathy discipline'."
+version: "1.0.0"
+category: "core"
+author: "Andrej Karpathy (originator) / forrestchang (skill packaging) / Rulebook (Rulebook adaptation)"
+tags: ["core", "discipline", "quality"]
+dependencies: []
+conflicts: []
+license: "MIT"
+upstream: "https://github.com/forrestchang/andrej-karpathy-skills"
+source: "https://x.com/karpathy/status/2015883857489522876"
+---
+<!-- KARPATHY_GUIDELINES:START -->
+# Karpathy Guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes, derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876) on LLM coding pitfalls.
+
+**Tradeoff:** these guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them — don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it — don't delete it.
+
+When your changes create orphans:
+
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+
+- "Add validation" → "write tests for invalid inputs, then make them pass."
+- "Fix the bug" → "write a test that reproduces it, then make it pass."
+- "Refactor X" → "ensure tests pass before and after."
+
+For multi-step tasks, state a brief plan:
+
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+## Interaction with Rulebook
+
+This skill complements existing Rulebook rules:
+
+- `no-shortcuts.md` forbids stubs/TODOs; **Simplicity First** forbids the opposite — bloat.
+- `research-first.md` requires investigating unknowns; **Think Before Coding** adds *surfacing* what was investigated.
+- `incremental-implementation.md` tests each step; **Goal-Driven Execution** adds defining the test up front.
+- **Surgical Changes** has no Rulebook counterpart and fills a real gap: no rule today forbids opportunistic refactor of adjacent code.
+
+Skill body is deliberately small (≤80 lines) so it adds < 1KB to the context budget per session.
+
+<!-- KARPATHY_GUIDELINES:END -->

package/templates/workflows/codespell.yml

@@ -1,31 +1,31 @@
-name: Codespell
-
-on:
-  push:
-    branches: [ master, main, develop ]
-  pull_request:
-    branches: [ master, main, develop ]
-
-permissions:
-  contents: read
-
-jobs:
-  codespell:
-    name: Check for spelling errors
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v5
-
-      - name: Install Codespell
-        run: python -m pip install --upgrade 'codespell[toml]'
-
-      - name: Run Codespell
-        run: |
-          codespell \
-            --skip="*.lock,*.json,*.map,*.yaml,*.yml,*.csv,*.bib,target,node_modules,.git,dist,venv,build,benchmarks,coverage" \
-            --ignore-words-list="crate,ser,deser,upToDate,optIn,shouldBe,Bloc"
-          # MONOREPO NOTE: Add multilingual stopwords to ignore-words-list if needed
-          # Example: --ignore-words-list="crate,ser,deser,meu,oder,ist,alle" (Portuguese,German,etc)
-
+name: Codespell
+
+on:
+  push:
+    branches: [ master, main, develop ]
+  pull_request:
+    branches: [ master, main, develop ]
+
+permissions:
+  contents: read
+
+jobs:
+  codespell:
+    name: Check for spelling errors
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+
+      - name: Install Codespell
+        run: python -m pip install --upgrade 'codespell[toml]'
+
+      - name: Run Codespell
+        run: |
+          codespell \
+            --skip="*.lock,*.json,*.map,*.yaml,*.yml,*.csv,*.bib,target,node_modules,.git,dist,venv,build,benchmarks,coverage" \
+            --ignore-words-list="crate,ser,deser,upToDate,optIn,shouldBe,Bloc"
+          # MONOREPO NOTE: Add multilingual stopwords to ignore-words-list if needed
+          # Example: --ignore-words-list="crate,ser,deser,meu,oder,ist,alle" (Portuguese,German,etc)
+

package/templates/workflows/cpp-lint.yml

@@ -1,47 +1,47 @@
-name: C++ Lint
-
-on:
-  push:
-    branches: [ master, main, develop ]
-  pull_request:
-    branches: [ '**' ]
-
-jobs:
-  lint:
-    runs-on: ubuntu-latest
-    
-    steps:
-    - uses: actions/checkout@v5
-    
-    - name: Install dependencies
-      run: |
-        sudo apt-get update
-        sudo apt-get install -y clang-format-15 clang-tidy-15 cppcheck cmake ninja-build
-    
-    - name: Check formatting
-      run: |
-        find src include tests -name '*.cpp' -o -name '*.hpp' -o -name '*.h' | \
-        xargs clang-format-15 --dry-run --Werror
-    
-    - name: Configure CMake (for compile commands)
-      run: cmake -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
-    
-    - name: Run clang-tidy
-      run: |
-        find src -name '*.cpp' | \
-        xargs clang-tidy-15 -p build --warnings-as-errors='*'
-    
-    - name: Run cppcheck
-      run: |
-        cppcheck --enable=all --error-exitcode=1 \
-          --suppress=missingIncludeSystem \
-          --suppress=unmatchedSuppression \
-          --inline-suppr \
-          -I include \
-          src/ tests/
-    
-    - name: Build with warnings as errors
-      run: |
-        cmake -B build -G Ninja -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic -Werror"
-        cmake --build build
-
+name: C++ Lint
+
+on:
+  push:
+    branches: [ master, main, develop ]
+  pull_request:
+    branches: [ '**' ]
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    
+    steps:
+    - uses: actions/checkout@v5
+    
+    - name: Install dependencies
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y clang-format-15 clang-tidy-15 cppcheck cmake ninja-build
+    
+    - name: Check formatting
+      run: |
+        find src include tests -name '*.cpp' -o -name '*.hpp' -o -name '*.h' | \
+        xargs clang-format-15 --dry-run --Werror
+    
+    - name: Configure CMake (for compile commands)
+      run: cmake -B build -G Ninja -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
+    
+    - name: Run clang-tidy
+      run: |
+        find src -name '*.cpp' | \
+        xargs clang-tidy-15 -p build --warnings-as-errors='*'
+    
+    - name: Run cppcheck
+      run: |
+        cppcheck --enable=all --error-exitcode=1 \
+          --suppress=missingIncludeSystem \
+          --suppress=unmatchedSuppression \
+          --inline-suppr \
+          -I include \
+          src/ tests/
+    
+    - name: Build with warnings as errors
+      run: |
+        cmake -B build -G Ninja -DCMAKE_CXX_FLAGS="-Wall -Wextra -Wpedantic -Werror"
+        cmake --build build
+