@hivehub/rulebook 4.2.1 → 4.3.0

package/templates/skills/core/documentation-rules/SKILL.md

@@ -1,47 +1,47 @@
----
-name: "Documentation Rules"
-description: "All documentation in English. Root README concise, detailed docs in `/docs`."
-version: "1.0.0"
-category: "core"
-author: "Rulebook"
-tags: ["core"]
-dependencies: []
-conflicts: []
----
-# Documentation Standards
-
-**CRITICAL**: All documentation in English. Root README concise, detailed docs in `/docs`.
-
-## Structure
-
-**Root-Level (ONLY):**
-- `README.md` - Overview + quick start
-- `CHANGELOG.md` - Version history
-- `AGENTS.md` - AI instructions
-- `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`
-
-**All Other Docs in `/docs`:**
-- `ARCHITECTURE.md`, `DEVELOPMENT.md`, `ROADMAP.md`
-- `specs/`, `guides/`, `diagrams/`, `benchmarks/`
-
-## Update Requirements by Commit Type
-
-| Type | Update |
-|------|--------|
-| `feat` | README features, API docs, CHANGELOG "Added" |
-| `fix` | Troubleshooting, CHANGELOG "Fixed" |
-| `breaking` | CHANGELOG + migration guide, version docs |
-| `perf` | Benchmarks, CHANGELOG "Performance" |
-| `security` | SECURITY.md, CHANGELOG "Security" |
-| `docs` | Verify spelling/links only |
-| `refactor` | Update if behavior changed |
-
-## Quality Checks (CI/CD)
-
-```bash
-markdownlint **/*.md         # Lint markdown
-markdown-link-check **/*.md  # Check links
-codespell **/*.md            # Spell check
-```
-
+---
+name: "Documentation Rules"
+description: "All documentation in English. Root README concise, detailed docs in `/docs`."
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["core"]
+dependencies: []
+conflicts: []
+---
+# Documentation Standards
+
+**CRITICAL**: All documentation in English. Root README concise, detailed docs in `/docs`.
+
+## Structure
+
+**Root-Level (ONLY):**
+- `README.md` - Overview + quick start
+- `CHANGELOG.md` - Version history
+- `AGENTS.md` - AI instructions
+- `LICENSE`, `CONTRIBUTING.md`, `SECURITY.md`
+
+**All Other Docs in `/docs`:**
+- `ARCHITECTURE.md`, `DEVELOPMENT.md`, `ROADMAP.md`
+- `specs/`, `guides/`, `diagrams/`, `benchmarks/`
+
+## Update Requirements by Commit Type
+
+| Type | Update |
+|------|--------|
+| `feat` | README features, API docs, CHANGELOG "Added" |
+| `fix` | Troubleshooting, CHANGELOG "Fixed" |
+| `breaking` | CHANGELOG + migration guide, version docs |
+| `perf` | Benchmarks, CHANGELOG "Performance" |
+| `security` | SECURITY.md, CHANGELOG "Security" |
+| `docs` | Verify spelling/links only |
+| `refactor` | Update if behavior changed |
+
+## Quality Checks (CI/CD)
+
+```bash
+markdownlint **/*.md         # Lint markdown
+markdown-link-check **/*.md  # Check links
+codespell **/*.md            # Spell check
+```
+
 **MUST pass before commit** (see AGENT_AUTOMATION).

package/templates/skills/core/quality-enforcement/SKILL.md

@@ -1,78 +1,78 @@
----
-name: "Quality Enforcement"
-description: "These rules are NON-NEGOTIABLE and MUST be followed without exception."
-version: "1.0.0"
-category: "core"
-author: "Rulebook"
-tags: ["core"]
-dependencies: []
-conflicts: []
----
-<!-- QUALITY_ENFORCEMENT:START -->
-# Quality Enforcement Rules
-
-**CRITICAL**: These rules are NON-NEGOTIABLE and MUST be followed without exception.
-
-## Absolute Prohibitions
-
-### Test Bypassing - STRICTLY FORBIDDEN
-- NEVER use .skip(), .only(), or .todo() to bypass failing tests
-- NEVER comment out failing tests
-- NEVER use @ts-ignore, @ts-expect-error, or similar to hide test errors
-- NEVER mock/stub functionality just to make tests pass without fixing root cause
-- FIX the actual problem causing test failures
-
-### Git Hook Bypassing - STRICTLY FORBIDDEN  
-- NEVER use --no-verify flag on git commit
-- NEVER use --no-verify flag on git push
-- NEVER disable or skip pre-commit hooks
-- NEVER disable or skip pre-push hooks
-- FIX the issues that hooks are detecting
-
-### Test Implementation - STRICTLY FORBIDDEN
-- NEVER create boilerplate tests that don't actually test behavior
-- NEVER write tests that always pass regardless of implementation
-- NEVER write tests without assertions
-- NEVER mock everything to avoid testing real behavior
-- WRITE meaningful tests that verify actual functionality
-
-### Problem Solving Approach - REQUIRED
-- DO NOT seek the simplest bypass or workaround
-- DO NOT be creative with shortcuts that compromise quality
-- DO solve problems properly following best practices
-- DO use proven, established solutions from decades of experience
-- DO fix root causes, not symptoms
-
-### Temporary Files and Scripts - STRICTLY FORBIDDEN
-- **NEVER** create temporary files in project root or any directory outside `/scripts`
-- **NEVER** create test files, log files, or debug files outside `/scripts`
-- **NEVER** leave temporary files after use - they MUST be deleted immediately
-- **ALWAYS** create all scripts inside `/scripts` directory
-- **ALWAYS** remove temporary files immediately after use (MANDATORY)
-- **ALWAYS** clean up test artifacts, log files, and debug files before committing
-- **ALWAYS** use `/scripts` directory for any temporary scripts or test files
-
-**Why This Matters:**
-LLM assistants often create temporary files for testing but forget to remove them, accumulating dozens of junk files that pollute the repository. All temporary work MUST be done in `/scripts` and cleaned up immediately.
-
-**Examples:**
-- ❌ Creating `test.js`, `debug.log`, `temp.json` in project root
-- ❌ Leaving test files after debugging
-- ❌ Creating scripts outside `/scripts` directory
-- ✅ Creating `/scripts/test-feature.js` and removing it after use
-- ✅ Using `/scripts` for all temporary work
-- ✅ Cleaning up all temporary files before committing
-
-## Enforcement
-
-These rules apply to ALL implementations:
-- Bug fixes
-- New features  
-- Refactoring
-- Documentation changes
-- Any code modifications
-
-**Violation = Implementation Rejected**
-
-<!-- QUALITY_ENFORCEMENT:END -->
-
+---
+name: "Quality Enforcement"
+description: "These rules are NON-NEGOTIABLE and MUST be followed without exception."
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["core"]
+dependencies: []
+conflicts: []
+---
+<!-- QUALITY_ENFORCEMENT:START -->
+# Quality Enforcement Rules
+
+**CRITICAL**: These rules are NON-NEGOTIABLE and MUST be followed without exception.
+
+## Absolute Prohibitions
+
+### Test Bypassing - STRICTLY FORBIDDEN
+- NEVER use .skip(), .only(), or .todo() to bypass failing tests
+- NEVER comment out failing tests
+- NEVER use @ts-ignore, @ts-expect-error, or similar to hide test errors
+- NEVER mock/stub functionality just to make tests pass without fixing root cause
+- FIX the actual problem causing test failures
+
+### Git Hook Bypassing - STRICTLY FORBIDDEN  
+- NEVER use --no-verify flag on git commit
+- NEVER use --no-verify flag on git push
+- NEVER disable or skip pre-commit hooks
+- NEVER disable or skip pre-push hooks
+- FIX the issues that hooks are detecting
+
+### Test Implementation - STRICTLY FORBIDDEN
+- NEVER create boilerplate tests that don't actually test behavior
+- NEVER write tests that always pass regardless of implementation
+- NEVER write tests without assertions
+- NEVER mock everything to avoid testing real behavior
+- WRITE meaningful tests that verify actual functionality
+
+### Problem Solving Approach - REQUIRED
+- DO NOT seek the simplest bypass or workaround
+- DO NOT be creative with shortcuts that compromise quality
+- DO solve problems properly following best practices
+- DO use proven, established solutions from decades of experience
+- DO fix root causes, not symptoms
+
+### Temporary Files and Scripts - STRICTLY FORBIDDEN
+- **NEVER** create temporary files in project root or any directory outside `/scripts`
+- **NEVER** create test files, log files, or debug files outside `/scripts`
+- **NEVER** leave temporary files after use - they MUST be deleted immediately
+- **ALWAYS** create all scripts inside `/scripts` directory
+- **ALWAYS** remove temporary files immediately after use (MANDATORY)
+- **ALWAYS** clean up test artifacts, log files, and debug files before committing
+- **ALWAYS** use `/scripts` directory for any temporary scripts or test files
+
+**Why This Matters:**
+LLM assistants often create temporary files for testing but forget to remove them, accumulating dozens of junk files that pollute the repository. All temporary work MUST be done in `/scripts` and cleaned up immediately.
+
+**Examples:**
+- ❌ Creating `test.js`, `debug.log`, `temp.json` in project root
+- ❌ Leaving test files after debugging
+- ❌ Creating scripts outside `/scripts` directory
+- ✅ Creating `/scripts/test-feature.js` and removing it after use
+- ✅ Using `/scripts` for all temporary work
+- ✅ Cleaning up all temporary files before committing
+
+## Enforcement
+
+These rules apply to ALL implementations:
+- Bug fixes
+- New features  
+- Refactoring
+- Documentation changes
+- Any code modifications
+
+**Violation = Implementation Rejected**
+
+<!-- QUALITY_ENFORCEMENT:END -->
+

package/templates/skills/core/rulebook/SKILL.md

@@ -1,176 +1,176 @@
----
-name: "Rulebook Task Management"
-description: "Spec-driven task management for features and breaking changes with OpenSpec-compatible format"
-version: "1.0.0"
-category: "core"
-author: "Rulebook"
-tags: ["task-management", "openspec", "spec-driven", "workflow"]
-dependencies: []
-conflicts: []
----
-
-# Rulebook Task Management
-
-**CRITICAL**: Use Rulebook's built-in task management system for spec-driven development of new features and breaking changes.
-
-## When to Use
-
-Create tasks for:
-- New features/capabilities
-- Breaking changes
-- Architecture changes
-- Performance/security work
-
-Skip for:
-- Bug fixes (restore intended behavior)
-- Typos, formatting, comments
-- Dependency updates (non-breaking)
-
-## Task Creation is MANDATORY Before Implementation
-
-**ABSOLUTE RULE**: You MUST create a task BEFORE implementing ANY feature.
-
-### MANDATORY Workflow
-
-**NEVER start implementation without creating a task first:**
-
-```bash
-# WRONG: Starting implementation directly
-# ... writing code without task ...
-
-# CORRECT: Create task first
-rulebook task create <task-id>
-# Write proposal.md
-# Write tasks.md
-# Write spec deltas
-rulebook task validate <task-id>
-# NOW you can start implementation
-```
-
-### Task Creation Steps
-
-**When a feature is requested:**
-
-1. **STOP** - Do not start coding
-2. **Create task** - `rulebook task create <task-id>`
-3. **Plan** - Write proposal.md and tasks.md
-4. **Spec** - Write spec deltas
-5. **Validate** - `rulebook task validate <task-id>`
-6. **THEN** - Start implementation
-
-## Task Directory Structure
-
-```
-.rulebook/tasks/<task-id>/
-├── proposal.md         # Why and what changes
-├── tasks.md            # Implementation checklist
-├── design.md           # Technical design (optional)
-└── specs/
-    └── <module>/
-        └── spec.md     # Technical specifications
-```
-
-## Task Commands
-
-```bash
-# Create new task
-rulebook task create <task-id>
-
-# List all tasks
-rulebook task list
-
-# Show task details
-rulebook task show <task-id>
-
-# Validate task structure
-rulebook task validate <task-id>
-
-# Archive completed task
-rulebook task archive <task-id>
-```
-
-## Proposal Format (proposal.md)
-
-```markdown
-# Proposal: <Task Title>
-
-## Why
-<Explain the problem or opportunity>
-
-## What Changes
-<List of changes with ADDED/MODIFIED/REMOVED markers>
-
-## Impact
-- Affected specs: <list spec files>
-- Affected code: <list source files>
-- Breaking change: YES/NO
-- User benefit: <describe benefit>
-```
-
-## Tasks Format (tasks.md)
-
-**CRITICAL**: Only simple checklist items. Technical details go in specs.
-
-```markdown
-## 1. <Phase Name>
-- [ ] 1.1 <Simple task description>
-- [ ] 1.2 <Simple task description>
-
-## 2. <Phase Name>
-- [ ] 2.1 <Simple task description>
-```
-
-## Spec Delta Format (specs/<module>/spec.md)
-
-```markdown
-# <Module> Specification
-
-## ADDED Requirements
-
-### Requirement: <Name>
-<Description>
-
-#### Scenario: <Name>
-Given <context>
-When <action>
-Then <expected result>
-
-## MODIFIED Requirements
-
-### Requirement: <Original Name>
-<Description of modification>
-
-## REMOVED Requirements
-
-### Requirement: <Name to Remove>
-<Reason for removal>
-```
-
-## MCP Integration
-
-If MCP server is enabled, use programmatic task management:
-
-```typescript
-// Create task
-await mcp.rulebook_task_create({ taskId: "my-task" });
-
-// List tasks
-await mcp.rulebook_task_list({});
-
-// Show task
-await mcp.rulebook_task_show({ taskId: "my-task" });
-
-// Validate task
-await mcp.rulebook_task_validate({ taskId: "my-task" });
-
-// Archive task
-await mcp.rulebook_task_archive({ taskId: "my-task" });
-```
-
-## Best Practices
-
-1. **Always create task first** - Never implement without documentation
-2. **Keep tasks.md simple** - Only checklist items, no explanations
-3. **Put details in specs** - Technical requirements go in spec files
-4. **Validate before implementing** - Run `rulebook task validate`
-5. **Archive when done** - Move completed tasks to archive
+---
+name: "Rulebook Task Management"
+description: "Spec-driven task management for features and breaking changes with OpenSpec-compatible format"
+version: "1.0.0"
+category: "core"
+author: "Rulebook"
+tags: ["task-management", "openspec", "spec-driven", "workflow"]
+dependencies: []
+conflicts: []
+---
+
+# Rulebook Task Management
+
+**CRITICAL**: Use Rulebook's built-in task management system for spec-driven development of new features and breaking changes.
+
+## When to Use
+
+Create tasks for:
+- New features/capabilities
+- Breaking changes
+- Architecture changes
+- Performance/security work
+
+Skip for:
+- Bug fixes (restore intended behavior)
+- Typos, formatting, comments
+- Dependency updates (non-breaking)
+
+## Task Creation is MANDATORY Before Implementation
+
+**ABSOLUTE RULE**: You MUST create a task BEFORE implementing ANY feature.
+
+### MANDATORY Workflow
+
+**NEVER start implementation without creating a task first:**
+
+```bash
+# WRONG: Starting implementation directly
+# ... writing code without task ...
+
+# CORRECT: Create task first
+rulebook task create <task-id>
+# Write proposal.md
+# Write tasks.md
+# Write spec deltas
+rulebook task validate <task-id>
+# NOW you can start implementation
+```
+
+### Task Creation Steps
+
+**When a feature is requested:**
+
+1. **STOP** - Do not start coding
+2. **Create task** - `rulebook task create <task-id>`
+3. **Plan** - Write proposal.md and tasks.md
+4. **Spec** - Write spec deltas
+5. **Validate** - `rulebook task validate <task-id>`
+6. **THEN** - Start implementation
+
+## Task Directory Structure
+
+```
+.rulebook/tasks/<task-id>/
+├── proposal.md         # Why and what changes
+├── tasks.md            # Implementation checklist
+├── design.md           # Technical design (optional)
+└── specs/
+    └── <module>/
+        └── spec.md     # Technical specifications
+```
+
+## Task Commands
+
+```bash
+# Create new task
+rulebook task create <task-id>
+
+# List all tasks
+rulebook task list
+
+# Show task details
+rulebook task show <task-id>
+
+# Validate task structure
+rulebook task validate <task-id>
+
+# Archive completed task
+rulebook task archive <task-id>
+```
+
+## Proposal Format (proposal.md)
+
+```markdown
+# Proposal: <Task Title>
+
+## Why
+<Explain the problem or opportunity>
+
+## What Changes
+<List of changes with ADDED/MODIFIED/REMOVED markers>
+
+## Impact
+- Affected specs: <list spec files>
+- Affected code: <list source files>
+- Breaking change: YES/NO
+- User benefit: <describe benefit>
+```
+
+## Tasks Format (tasks.md)
+
+**CRITICAL**: Only simple checklist items. Technical details go in specs.
+
+```markdown
+## 1. <Phase Name>
+- [ ] 1.1 <Simple task description>
+- [ ] 1.2 <Simple task description>
+
+## 2. <Phase Name>
+- [ ] 2.1 <Simple task description>
+```
+
+## Spec Delta Format (specs/<module>/spec.md)
+
+```markdown
+# <Module> Specification
+
+## ADDED Requirements
+
+### Requirement: <Name>
+<Description>
+
+#### Scenario: <Name>
+Given <context>
+When <action>
+Then <expected result>
+
+## MODIFIED Requirements
+
+### Requirement: <Original Name>
+<Description of modification>
+
+## REMOVED Requirements
+
+### Requirement: <Name to Remove>
+<Reason for removal>
+```
+
+## MCP Integration
+
+If MCP server is enabled, use programmatic task management:
+
+```typescript
+// Create task
+await mcp.rulebook_task_create({ taskId: "my-task" });
+
+// List tasks
+await mcp.rulebook_task_list({});
+
+// Show task
+await mcp.rulebook_task_show({ taskId: "my-task" });
+
+// Validate task
+await mcp.rulebook_task_validate({ taskId: "my-task" });
+
+// Archive task
+await mcp.rulebook_task_archive({ taskId: "my-task" });
+```
+
+## Best Practices
+
+1. **Always create task first** - Never implement without documentation
+2. **Keep tasks.md simple** - Only checklist items, no explanations
+3. **Put details in specs** - Technical requirements go in spec files
+4. **Validate before implementing** - Run `rulebook task validate`
+5. **Archive when done** - Move completed tasks to archive

package/templates/skills/dev/accessibility/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: accessibility
+description: Accessibility audit for WCAG compliance and usability
+model: haiku
+context: fork
+agent: accessibility-reviewer
+---
+Audit accessibility for: $ARGUMENTS
+
+If no arguments, audit the entire frontend codebase.
+
+Steps:
+1. Check semantic HTML usage (headings, landmarks, labels)
+2. Verify ARIA attributes are correct and complete
+3. Test keyboard navigation flow
+4. Check color contrast ratios meet WCAG 2.1 AA
+5. Report violations with severity and remediation steps

package/templates/skills/dev/api-design/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: api-design
+description: Design or review API endpoints (REST/GraphQL)
+model: sonnet
+context: fork
+agent: api-designer
+---
+Design or review the API for: $ARGUMENTS
+
+Steps:
+1. Gather requirements from the codebase and any existing API patterns
+2. Design endpoints following REST conventions (or GraphQL schema)
+3. Define request/response schemas with types
+4. Document error responses and status codes
+5. Write or update OpenAPI spec if applicable

package/templates/skills/dev/architect/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: architect
+description: Architecture review, design decisions, and ADR writing
+model: opus
+context: fork
+agent: architect
+---
+Analyze architecture for: $ARGUMENTS
+
+If no arguments, do a general architecture review of the project.
+
+Steps:
+1. Map the current system architecture (modules, dependencies, data flow)
+2. Identify architectural concerns (coupling, scalability, complexity)
+3. Evaluate alternative approaches with trade-offs
+4. Write an Architecture Decision Record (ADR) if a decision is needed
+5. Present recommendations with clear rationale

package/templates/skills/dev/build-fix/SKILL.md

@@ -0,0 +1,17 @@
+---
+name: build-fix
+description: Diagnose and fix build failures or CI issues
+model: sonnet
+context: fork
+agent: build-engineer
+---
+Diagnose and fix the current build failure.
+
+If $ARGUMENTS is provided, focus on that specific build error or CI job.
+
+Steps:
+1. Run the build command and capture the error output
+2. Read the error message and trace to the source file
+3. Identify the root cause (missing dep, type error, config issue)
+4. Apply the minimal fix
+5. Re-run the build to verify the fix works