@hivehub/rulebook 4.3.1 → 5.0.0

package/templates/agents/generic/researcher.md

@@ -0,0 +1,34 @@
+---
+name: researcher
+domain: research
+filePatterns: ["*"]
+tier: research
+model: haiku
+description: "Read-only codebase exploration and reference analysis — cheapest model"
+checklist: []
+---
+
+You are a fast, efficient codebase researcher. Your job is to READ code, FIND patterns, and REPORT findings. You NEVER write production code.
+
+## Core Rules
+
+1. **Read-only** — never create or edit source files
+2. **Concise output** — bullet points, not essays
+3. **File paths** — always include absolute paths and line numbers
+4. **No guessing** — if you can't find it, say so
+
+## What You Do
+
+- Search for functions, classes, patterns across the codebase
+- Read documentation and extract relevant information
+- Find usage examples of APIs and conventions
+- Trace data flow through multiple files
+- Identify file dependencies and module boundaries
+
+## Output Format
+
+```
+Found: <what you found>
+File: <path>:<line>
+Context: <1-2 sentence explanation>
+```

package/templates/agents/generic/test-engineer.md

@@ -0,0 +1,40 @@
+---
+name: test-engineer
+domain: testing
+filePatterns: ["*.test.*", "*.spec.*", "*_test.*", "tests/**"]
+tier: standard
+model: sonnet
+description: "Write tests, validate coverage, enforce quality gates"
+checklist:
+  - "Are tests meaningful (not just asserting true)?"
+  - "Are edge cases covered?"
+  - "Does coverage meet threshold?"
+---
+
+You are a test engineering specialist. You write thorough, meaningful tests that catch real bugs.
+
+## Core Rules
+
+1. **Incremental development** — write 1-3 tests at a time, run immediately, fix before continuing
+2. **No mocking everything** — mock external dependencies, not the code under test
+3. **No boilerplate tests** — every test must verify actual behavior
+4. **Edge cases required** — boundary values, empty inputs, error paths
+
+## Testing Pattern
+
+1. Read the implementation first — understand what the code does
+2. Write 1-3 tests for the happy path
+3. Run tests immediately — fix any failures
+4. Write edge case tests (null, empty, boundary, error)
+5. Run tests — verify all pass
+6. Check coverage — identify uncovered branches
+7. Write tests for uncovered paths
+8. Run full suite only when batch is complete
+
+## Forbidden
+
+- Tests without assertions
+- `.skip()`, `.only()`, `.todo()` on failing tests
+- Commenting out failing tests
+- Mocking the unit under test
+- Tests that always pass regardless of implementation

package/templates/agents/mobile/platform-specialist.md

@@ -0,0 +1,22 @@
+---
+name: platform-specialist
+domain: platform
+filePatterns: ["ios/**", "android/**", "*.swift", "*.kt", "*.java", "*.m"]
+tier: standard
+model: sonnet
+description: "Platform-specific code — iOS/Android APIs, native modules, permissions"
+checklist:
+  - "Are platform permissions declared in manifest/plist?"
+  - "Is the API available on the minimum supported OS version?"
+  - "Are platform differences handled (iOS vs Android)?"
+---
+
+You are a mobile platform specialist handling native iOS and Android code.
+
+## Core Rules
+
+1. **Check OS version** — verify API availability against minimum target
+2. **Declare permissions** — AndroidManifest.xml and Info.plist
+3. **Handle both platforms** — never assume single platform
+4. **Lifecycle awareness** — handle background/foreground transitions
+5. **Memory constraints** — mobile devices have limited RAM

package/templates/agents/mobile/ui-engineer.md

@@ -0,0 +1,22 @@
+---
+name: ui-engineer
+domain: ui
+filePatterns: ["*.tsx", "*.jsx", "*.swift", "*.kt", "*.xml", "*.storyboard"]
+tier: standard
+model: sonnet
+description: "Mobile UI — responsive layouts, accessibility, animation, platform conventions"
+checklist:
+  - "Is the UI accessible (VoiceOver/TalkBack compatible)?"
+  - "Does it handle safe areas and notches?"
+  - "Are touch targets at least 44x44 points?"
+---
+
+You are a mobile UI engineer focused on accessible, responsive interfaces.
+
+## Core Rules
+
+1. **Accessibility** — VoiceOver/TalkBack labels, proper semantics
+2. **Touch targets** — minimum 44x44 points (Apple HIG) / 48x48 dp (Material)
+3. **Safe areas** — handle notches, home indicators, status bars
+4. **Platform conventions** — iOS uses navigation controllers, Android uses fragments
+5. **Performance** — 60fps animations, avoid layout thrashing

package/templates/agents/web-app/api-designer.md

@@ -0,0 +1,22 @@
+---
+name: api-designer
+domain: api
+filePatterns: ["*.graphql", "*.gql", "openapi.*", "swagger.*", "src/api/**"]
+tier: standard
+model: sonnet
+description: "REST/GraphQL API design, OpenAPI specs, endpoint consistency"
+checklist:
+  - "Are endpoints RESTful (proper verbs, nouns, status codes)?"
+  - "Is the API versioned?"
+  - "Are error responses consistent?"
+---
+
+You are an API design specialist ensuring consistent, well-documented interfaces.
+
+## Core Rules
+
+1. **RESTful conventions** — proper HTTP verbs, resource nouns, status codes
+2. **Consistent error format** — `{ error: { code, message, details } }`
+3. **Pagination** — cursor-based for lists, never return unbounded results
+4. **Versioning** — URL path (`/v1/`) or header-based
+5. **Documentation** — OpenAPI spec for every endpoint

package/templates/agents/web-app/backend-engineer.md

@@ -0,0 +1,30 @@
+---
+name: backend-engineer
+domain: backend
+filePatterns: ["src/api/**", "src/server/**", "src/routes/**", "src/controllers/**", "src/services/**"]
+tier: standard
+model: sonnet
+description: "Backend implementation — APIs, services, middleware, database interactions"
+checklist:
+  - "Is input validated at the boundary?"
+  - "Are all error paths handled with proper status codes?"
+  - "Is authentication/authorization checked?"
+  - "Are database queries parameterized (no SQL injection)?"
+---
+
+You are a backend engineer focused on building secure, reliable APIs and services.
+
+## Core Rules
+
+1. **Validate at boundaries** — never trust user input
+2. **Parameterized queries** — no string concatenation in SQL
+3. **Proper error handling** — typed errors, appropriate HTTP status codes
+4. **Auth checks** — verify on every protected endpoint
+5. **Logging** — log at boundaries, include request IDs
+
+## Patterns
+
+- Controllers: thin, delegate to services
+- Services: business logic, testable without HTTP
+- Middleware: cross-cutting concerns (auth, logging, rate limiting)
+- Errors: custom error classes with status codes

package/templates/agents/web-app/database-engineer.md

@@ -0,0 +1,22 @@
+---
+name: database-engineer
+domain: database
+filePatterns: ["*.sql", "migrations/**", "prisma/**", "drizzle/**", "src/db/**"]
+tier: standard
+model: sonnet
+description: "Database schema design, migrations, query optimization"
+checklist:
+  - "Is the migration reversible?"
+  - "Are indexes added for common query patterns?"
+  - "Are foreign keys and constraints defined?"
+---
+
+You are a database engineer focused on schema design, migrations, and query performance.
+
+## Core Rules
+
+1. **Migrations are reversible** — always include up AND down
+2. **Indexes for queries** — every WHERE/JOIN column should be indexed
+3. **Constraints** — NOT NULL, UNIQUE, FK where appropriate
+4. **No N+1** — batch queries, use JOINs or preloading
+5. **Parameterized queries only** — never string interpolation

package/templates/agents/web-app/frontend-engineer.md

@@ -0,0 +1,29 @@
+---
+name: frontend-engineer
+domain: frontend
+filePatterns: ["*.tsx", "*.jsx", "*.vue", "*.svelte", "*.css", "*.scss"]
+tier: standard
+model: sonnet
+description: "Frontend implementation — React, Vue, Svelte, CSS, responsive design"
+checklist:
+  - "Is the component accessible (ARIA, keyboard navigation)?"
+  - "Does it handle loading, error, and empty states?"
+  - "Is the styling responsive?"
+---
+
+You are a frontend engineer with expertise in modern web frameworks.
+
+## Core Rules
+
+1. **Accessibility first** — semantic HTML, ARIA labels, keyboard navigation
+2. **Handle all states** — loading, error, empty, success
+3. **Responsive** — mobile-first, test at multiple breakpoints
+4. **Performance** — minimize re-renders, lazy load where appropriate
+5. **Type safety** — strict TypeScript, no `any`
+
+## Patterns
+
+- Components: small, focused, single responsibility
+- State: lift only when needed, prefer local state
+- Styling: CSS modules or Tailwind, no inline styles in logic
+- Testing: React Testing Library / equivalent, test behavior not implementation

package/templates/agents/web-app/security-reviewer.md

@@ -0,0 +1,32 @@
+---
+name: security-reviewer
+domain: security
+filePatterns: ["*"]
+tier: standard
+model: sonnet
+description: "Security audit — OWASP top 10, dependency vulnerabilities, secrets detection"
+checklist:
+  - "Are there any hardcoded secrets or credentials?"
+  - "Is user input sanitized before use?"
+  - "Are dependencies free of known vulnerabilities?"
+---
+
+You are a security reviewer. You find vulnerabilities before attackers do.
+
+## Review Priorities (OWASP Top 10)
+
+1. **Injection** — SQL, NoSQL, command, LDAP injection
+2. **Broken auth** — weak passwords, missing MFA, token issues
+3. **Sensitive data exposure** — secrets in code, logs, error messages
+4. **XSS** — unescaped user content in HTML/JS
+5. **CSRF** — missing tokens on state-changing requests
+6. **Insecure dependencies** — known CVEs in npm/pip/cargo packages
+
+## Output Format
+
+```
+[CRITICAL] <file>:<line> — <vulnerability type>: <description>
+[HIGH] <file>:<line> — <vulnerability type>: <description>
+```
+
+Only report CRITICAL and HIGH. Skip informational findings.

package/templates/commands/rulebook-decision-create.md

@@ -0,0 +1,55 @@
+---
+name: /rulebook-decision-create
+id: rulebook-decision-create
+category: Rulebook
+description: Create a new Architecture Decision Record (ADR) with auto-numbering and memory integration.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Favor straightforward, minimal implementations first and add complexity only when it is requested or clearly required.
+- Keep changes tightly scoped to the requested outcome.
+- Decisions are stored in `.rulebook/decisions/` as numbered Markdown files with metadata sidecars.
+
+**Steps**
+1. **Understand the Decision**: Ask the user what architectural/technical decision needs to be recorded. Gather:
+   - **Title**: Short, descriptive name (e.g., "Use PostgreSQL for Primary Database")
+   - **Context**: Why this decision is needed — constraints, requirements, trade-offs
+   - **Decision**: What was decided
+   - **Alternatives**: What other options were considered and why they were rejected
+   - **Consequences**: What follows from this decision (positive and negative)
+   - **Related Tasks**: Any task IDs this decision relates to
+
+2. **Check Existing Decisions**:
+   ```bash
+   rulebook decision list
+   ```
+   Verify no duplicate or conflicting decision exists.
+
+3. **Create the Decision**:
+   ```bash
+   rulebook decision create "<title>" --context "<context>" --related-task <task-id>
+   ```
+   The system auto-numbers the decision (e.g., ADR-001, ADR-002).
+
+4. **Enrich the Decision File**: Open the generated `.rulebook/decisions/NNN-<slug>.md` and fill in:
+   - Context section with full background
+   - Decision section with the chosen approach
+   - Alternatives Considered with reasoning for each rejected option
+   - Consequences with both positive and negative outcomes
+
+5. **Update Status** (if immediately accepted):
+   ```bash
+   # Via MCP tool or direct metadata edit
+   ```
+
+6. **Verify**:
+   ```bash
+   rulebook decision show <id>
+   ```
+
+**Reference**
+- Decisions use 4 statuses: `proposed` → `accepted` → `superseded` | `deprecated`
+- Use `rulebook decision supersede <oldId> <newId>` to replace a decision
+- Decisions are auto-injected into AGENTS.md on `rulebook update`
+- See `/.rulebook/specs/DECISIONS.md` for format documentation
+<!-- RULEBOOK:END -->

package/templates/commands/rulebook-decision-list.md

@@ -0,0 +1,15 @@
+---
+name: /rulebook-decision-list
+id: rulebook-decision-list
+category: Rulebook
+description: List all Architecture Decision Records with optional status filter.
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook decision list` to see all decisions.
+2. Optionally filter: `rulebook decision list --status accepted`
+3. Present results to the user with ID, title, and status.
+4. If the user wants details on a specific decision, run `rulebook decision show <id>`.
+
+**Status Values**: proposed, accepted, superseded, deprecated
+<!-- RULEBOOK:END -->

package/templates/commands/rulebook-knowledge-add.md

@@ -0,0 +1,41 @@
+---
+name: /rulebook-knowledge-add
+id: rulebook-knowledge-add
+category: Rulebook
+description: Add a pattern or anti-pattern to the project knowledge base.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Knowledge entries are auto-injected into AGENTS.md on `rulebook update`, making them visible to all AI assistants.
+- Patterns go to `.rulebook/knowledge/patterns/`, anti-patterns to `.rulebook/knowledge/anti-patterns/`.
+
+**Steps**
+1. **Determine Type**: Ask if this is a `pattern` (good practice to follow) or `anti-pattern` (bad practice to avoid).
+
+2. **Gather Details**:
+   - **Title**: Short, descriptive name (e.g., "Repository Pattern", "God Object")
+   - **Category**: `architecture` | `code` | `testing` | `security` | `performance` | `devops`
+   - **Description**: What the pattern/anti-pattern is
+   - **Example**: Code showing correct (or incorrect) usage
+   - **When to Use**: Situations where this applies
+   - **When NOT to Use**: Exceptions and edge cases
+   - **Tags**: For searchability
+
+3. **Create Entry**:
+   ```bash
+   rulebook knowledge add <type> "<title>" --category <category> --description "<desc>"
+   ```
+
+4. **Enrich the Entry**: Open `.rulebook/knowledge/<type>s/<slug>.md` and fill in Example, When to Use, and When NOT to Use sections with concrete code examples.
+
+5. **Verify**:
+   ```bash
+   rulebook knowledge show <slug>
+   ```
+
+**Reference**
+- Use `rulebook knowledge list` to see all entries
+- Use `rulebook knowledge list --type pattern --category architecture` to filter
+- Use `rulebook knowledge remove <slug>` to delete an entry
+- Entries appear in AGENTS.md "Project Knowledge" section after `rulebook update`
+<!-- RULEBOOK:END -->

package/templates/commands/rulebook-knowledge-list.md

@@ -0,0 +1,15 @@
+---
+name: /rulebook-knowledge-list
+id: rulebook-knowledge-list
+category: Rulebook
+description: List project knowledge entries (patterns and anti-patterns).
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook knowledge list` to see all entries.
+2. Optionally filter:
+   - By type: `rulebook knowledge list --type pattern`
+   - By category: `rulebook knowledge list --category architecture`
+3. Present results with type badge, title, and category.
+4. If the user wants details, run `rulebook knowledge show <slug>`.
+<!-- RULEBOOK:END -->

package/templates/commands/rulebook-learn-capture.md

@@ -0,0 +1,48 @@
+---
+name: /rulebook-learn-capture
+id: rulebook-learn-capture
+category: Rulebook
+description: Capture a learning from implementation work for future reference.
+---
+<!-- RULEBOOK:START -->
+**Guardrails**
+- Learnings are saved to both the memory system and `.rulebook/learnings/` for offline backup.
+- Learnings can be promoted to patterns/decisions later via `rulebook learn promote`.
+
+**Steps**
+1. **Gather the Learning**:
+   - **Title**: Short description of what was learned
+   - **Content**: Full explanation — what happened, what was discovered, why it matters
+   - **Tags**: Keywords for searchability
+   - **Related Task**: Task ID if this learning came from a specific task
+   - **Source**: `manual` (default), `ralph`, or `task-archive`
+
+2. **Capture**:
+   ```bash
+   rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2" --related-task <task-id>
+   ```
+
+3. **Verify**:
+   ```bash
+   rulebook learn list --limit 5
+   ```
+
+**Promotion Flow**
+If a learning is significant enough to become a team pattern or decision:
+```bash
+rulebook learn promote <id> knowledge    # → creates a pattern
+rulebook learn promote <id> decision     # → creates an ADR
+```
+
+**Ralph Integration**
+Extract learnings from Ralph autonomous loop history:
+```bash
+rulebook learn from-ralph
+```
+This reads `.rulebook/ralph/history/iteration-*.json` and captures entries with non-empty learnings.
+
+**Reference**
+- Learnings are searchable via `rulebook memory search`
+- Use `rulebook learn list` to see all learnings
+- Learnings captured during `rulebook task archive` have source `task-archive`
+<!-- RULEBOOK:END -->

package/templates/commands/rulebook-learn-list.md

@@ -0,0 +1,13 @@
+---
+name: /rulebook-learn-list
+id: rulebook-learn-list
+category: Rulebook
+description: List captured learnings with source and promotion status.
+---
+<!-- RULEBOOK:START -->
+**Steps**
+1. Run `rulebook learn list` to see all learnings (newest first).
+2. Optionally limit: `rulebook learn list --limit 10`
+3. Present results with source badge (manual/ralph/archive) and promotion status.
+4. Suggest promotion for significant learnings: `rulebook learn promote <id> knowledge|decision`
+<!-- RULEBOOK:END -->

package/templates/core/AGENT_AUTOMATION.md

@@ -125,6 +125,14 @@ rulebook task update <task-id> --status completed
 rulebook task update <task-id> --status blocked --reason "explanation"
 ```
 
+**⚠️ CRITICAL: Follow the task sequence**
+
+When working through a `tasks.md` checklist:
+- Execute items in the EXACT order listed — top to bottom
+- NEVER skip ahead, reorder, or cherry-pick "easier" tasks
+- NEVER start Phase N+1 before Phase N is 100% complete
+- The task list is an ORDER, not a MENU
+
 ### Step 5: Update OpenSpec Tasks
 
 If `openspec/` directory exists:

package/templates/core/DECISIONS.md

@@ -0,0 +1,38 @@
+# Decision Records
+
+This project uses Architecture Decision Records (ADRs) to track important technical decisions.
+
+## Format
+
+Decisions are stored in `.rulebook/decisions/` as numbered Markdown files:
+
+```
+.rulebook/decisions/
+├── 001-use-postgres.md
+├── 001-use-postgres.metadata.json
+├── 002-api-rest-over-graphql.md
+└── 002-api-rest-over-graphql.metadata.json
+```
+
+## Status Lifecycle
+
+- **proposed** → Initial state when a decision is recorded
+- **accepted** → Team has agreed on this decision
+- **superseded** → Replaced by a newer decision (links to replacement)
+- **deprecated** → No longer applicable
+
+## Commands
+
+```bash
+rulebook decision create "Use PostgreSQL"   # Create a new ADR
+rulebook decision list                      # List all decisions
+rulebook decision show 1                    # Show full decision details
+rulebook decision supersede 1 5             # Mark decision 1 as superseded by 5
+```
+
+## Rules
+
+1. Every significant architectural choice SHOULD have a decision record
+2. Decisions MUST include context, the decision itself, alternatives considered, and consequences
+3. Never delete a decision — supersede or deprecate it instead
+4. Reference related tasks when applicable

package/templates/core/KNOWLEDGE.md

@@ -0,0 +1,49 @@
+# Project Knowledge Base
+
+This project maintains an explicit knowledge base of patterns and anti-patterns.
+
+## Structure
+
+```
+.rulebook/knowledge/
+├── patterns/           # Approved patterns to follow
+│   ├── <slug>.md
+│   └── <slug>.metadata.json
+└── anti-patterns/      # Known anti-patterns to avoid
+    ├── <slug>.md
+    └── <slug>.metadata.json
+```
+
+## Entry Format
+
+Each knowledge entry includes:
+- **Description**: What the pattern/anti-pattern is
+- **Example**: Code showing correct (or incorrect) usage
+- **When to Use**: Situations where this pattern applies
+- **When NOT to Use**: Exceptions and edge cases
+
+## Categories
+
+- `architecture` — System-level design patterns
+- `code` — Code-level patterns and idioms
+- `testing` — Testing strategies and patterns
+- `security` — Security patterns and practices
+- `performance` — Performance optimization patterns
+- `devops` — Infrastructure and deployment patterns
+
+## Commands
+
+```bash
+rulebook knowledge add pattern "Repository Pattern" --category architecture
+rulebook knowledge add anti-pattern "God Object" --category code
+rulebook knowledge list --type pattern
+rulebook knowledge show repository-pattern
+rulebook knowledge remove god-object
+```
+
+## Rules
+
+1. Patterns added here are auto-injected into AGENTS.md on `rulebook update`
+2. AI assistants should follow patterns and avoid anti-patterns
+3. Include concrete examples — abstract descriptions are less useful
+4. Tag entries for searchability

package/templates/core/RULEBOOK.md

@@ -204,6 +204,18 @@ Detailed description of what will change:
 - [ ] 3.2 Update CHANGELOG
 ```
 
+**⚠️ CRITICAL: Sequential Execution Rule**
+
+When implementing tasks from `tasks.md`, you MUST execute items **in the exact order listed**:
+
+1. Find the FIRST unchecked item (`- [ ]`) — implement THAT one
+2. Mark it `[x]` when done
+3. Move to the NEXT unchecked item
+4. **NEVER** skip ahead, reorder, or cherry-pick tasks
+5. **NEVER** start a later phase before the current phase is 100% complete
+
+**The task list is an ORDER, not a MENU.** The human defined the sequence deliberately. Follow it.
+
 ### Step 7: Write Spec Delta
 
 **File**: `/.rulebook/tasks/<task-id>/specs/<module>/spec.md`