@hivehub/rulebook 5.7.0 → 5.8.1

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

@@ -1,17 +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
+---
+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/analysis/SKILL.md

@@ -1,19 +1,19 @@
----
-name: analysis
-description: Create structured analyses with numbered findings, execution plans, and task materialization
-model: opus
-context: fork
-agent: researcher
----
-Create a structured analysis for: $ARGUMENTS
-
-Steps:
-1. Call `rulebook_analysis_create` with the topic to scaffold `docs/analysis/<slug>/`
-2. Check existing knowledge: `rulebook_knowledge_list` and `rulebook_memory_search` for prior context
-3. Investigate the topic — read relevant files, search codebase, fetch docs as needed
-4. Fill `findings.md` with numbered findings (F-001..F-NNN), each with: title, evidence (file:line), impact, confidence
-5. Design phased execution plan in `execution-plan.md`
-6. Consolidate the executive summary in `README.md`
-7. Capture each key finding to the knowledge base: `rulebook_knowledge_add` for patterns/anti-patterns
-8. Save analysis summary to memory: `rulebook_memory_save` with type `observation` and tags `["analysis", "<slug>"]`
-9. Offer to materialize implementation tasks from the execution plan via `rulebook_task_create`
+---
+name: analysis
+description: Create structured analyses with numbered findings, execution plans, and task materialization
+model: opus
+context: fork
+agent: researcher
+---
+Create a structured analysis for: $ARGUMENTS
+
+Steps:
+1. Call `rulebook_analysis_create` with the topic to scaffold `docs/analysis/<slug>/`
+2. Check existing knowledge: `rulebook_knowledge_list` and `rulebook_memory_search` for prior context
+3. Investigate the topic — read relevant files, search codebase, fetch docs as needed
+4. Fill `findings.md` with numbered findings (F-001..F-NNN), each with: title, evidence (file:line), impact, confidence
+5. Design phased execution plan in `execution-plan.md`
+6. Consolidate the executive summary in `README.md`
+7. Capture each key finding to the knowledge base: `rulebook_knowledge_add` for patterns/anti-patterns
+8. Save analysis summary to memory: `rulebook_memory_save` with type `observation` and tags `["analysis", "<slug>"]`
+9. Offer to materialize implementation tasks from the execution plan via `rulebook_task_create`

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

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

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

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

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

@@ -1,15 +1,15 @@
----
-name: db-design
-description: Database schema design, migrations, and query optimization
-model: sonnet
-context: fork
-agent: database-architect
----
-Design or review the database for: $ARGUMENTS
-
-Steps:
-1. Understand the data model requirements
-2. Design or review the schema (tables, relationships, indexes)
-3. Plan migration strategy if schema changes are needed
-4. Review existing queries for optimization opportunities
-5. Document the schema decisions and trade-offs
+---
+name: db-design
+description: Database schema design, migrations, and query optimization
+model: sonnet
+context: fork
+agent: database-architect
+---
+Design or review the database for: $ARGUMENTS
+
+Steps:
+1. Understand the data model requirements
+2. Design or review the schema (tables, relationships, indexes)
+3. Plan migration strategy if schema changes are needed
+4. Review existing queries for optimization opportunities
+5. Document the schema decisions and trade-offs

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

@@ -1,16 +1,16 @@
----
-name: debug
-description: Systematic debugging workflow for bugs and test failures
-model: sonnet
-context: fork
-agent: researcher
----
-Debug the following issue: $ARGUMENTS
-
-Steps:
-1. Reproduce the issue by reading the error message or running the failing test
-2. Read the relevant source code and trace the execution path
-3. Form a hypothesis about the root cause
-4. Search for similar patterns in the codebase that work correctly
-5. Identify the exact root cause with file and line reference
-6. Propose a minimal fix with explanation
+---
+name: debug
+description: Systematic debugging workflow for bugs and test failures
+model: sonnet
+context: fork
+agent: researcher
+---
+Debug the following issue: $ARGUMENTS
+
+Steps:
+1. Reproduce the issue by reading the error message or running the failing test
+2. Read the relevant source code and trace the execution path
+3. Form a hypothesis about the root cause
+4. Search for similar patterns in the codebase that work correctly
+5. Identify the exact root cause with file and line reference
+6. Propose a minimal fix with explanation

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

@@ -1,17 +1,17 @@
----
-name: deploy
-description: Prepare deployment artifacts and verify CI/CD readiness
-model: sonnet
-context: fork
-agent: devops-engineer
----
-Prepare the project for deployment.
-
-If $ARGUMENTS is provided, focus on that specific deployment target or environment.
-
-Steps:
-1. Verify the build succeeds with no errors
-2. Check CI/CD pipeline configuration is valid
-3. Validate environment variables and secrets are documented
-4. Review Dockerfile or deployment configs if present
-5. Generate a deployment checklist with any missing items
+---
+name: deploy
+description: Prepare deployment artifacts and verify CI/CD readiness
+model: sonnet
+context: fork
+agent: devops-engineer
+---
+Prepare the project for deployment.
+
+If $ARGUMENTS is provided, focus on that specific deployment target or environment.
+
+Steps:
+1. Verify the build succeeds with no errors
+2. Check CI/CD pipeline configuration is valid
+3. Validate environment variables and secrets are documented
+4. Review Dockerfile or deployment configs if present
+5. Generate a deployment checklist with any missing items

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

@@ -1,17 +1,17 @@
----
-name: docs
-description: Generate or update project documentation based on recent changes
-model: haiku
-context: fork
-agent: docs-writer
----
-Analyze recent code changes and update project documentation accordingly.
-
-If $ARGUMENTS is provided, focus documentation on that specific topic or file.
-
-Steps:
-1. Run `git diff HEAD~5 --name-only` to find recently changed files
-2. Read the changed files to understand what was modified
-3. Check existing docs for sections that need updating
-4. Update or create documentation to reflect the changes
-5. Ensure code examples are accurate and up-to-date
+---
+name: docs
+description: Generate or update project documentation based on recent changes
+model: haiku
+context: fork
+agent: docs-writer
+---
+Analyze recent code changes and update project documentation accordingly.
+
+If $ARGUMENTS is provided, focus documentation on that specific topic or file.
+
+Steps:
+1. Run `git diff HEAD~5 --name-only` to find recently changed files
+2. Read the changed files to understand what was modified
+3. Check existing docs for sections that need updating
+4. Update or create documentation to reflect the changes
+5. Ensure code examples are accurate and up-to-date

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

@@ -1,27 +1,27 @@
----
-name: handoff
-description: Save session state to .rulebook/handoff/_pending.md for cross-session continuity
-model: sonnet
-context: fork
-agent: researcher
----
-Save a session handoff to `.rulebook/handoff/_pending.md`.
-
-The handoff file MUST contain:
-
-1. **Active task**: current task ID + phase + which checklist items are done
-2. **Decisions made this session**: architectural choices, trade-offs, rejected alternatives
-3. **Files touched**: list of files modified with one-line reason each
-4. **Next steps**: concrete, actionable items (not vague "continue working")
-5. **Exact resume command**: what to tell the next session to do first
-6. **Open questions / blockers**: anything unresolved that needs the user's input
-
-Write the file to `.rulebook/handoff/_pending.md` using the Write tool.
-
-After writing successfully, display this message prominently:
-
->>> TYPE /clear NOW — your context will be auto-restored in the next session <<<
-
-If the file `.rulebook/handoff/.urgent` exists, skip any confirmations and write immediately.
-
-The SessionStart hook (`resume-from-handoff.sh`) will automatically inject the handoff content into the next session and archive the file.
+---
+name: handoff
+description: Save session state to .rulebook/handoff/_pending.md for cross-session continuity
+model: sonnet
+context: fork
+agent: researcher
+---
+Save a session handoff to `.rulebook/handoff/_pending.md`.
+
+The handoff file MUST contain:
+
+1. **Active task**: current task ID + phase + which checklist items are done
+2. **Decisions made this session**: architectural choices, trade-offs, rejected alternatives
+3. **Files touched**: list of files modified with one-line reason each
+4. **Next steps**: concrete, actionable items (not vague "continue working")
+5. **Exact resume command**: what to tell the next session to do first
+6. **Open questions / blockers**: anything unresolved that needs the user's input
+
+Write the file to `.rulebook/handoff/_pending.md` using the Write tool.
+
+After writing successfully, display this message prominently:
+
+>>> TYPE /clear NOW — your context will be auto-restored in the next session <<<
+
+If the file `.rulebook/handoff/.urgent` exists, skip any confirmations and write immediately.
+
+The SessionStart hook (`resume-from-handoff.sh`) will automatically inject the handoff content into the next session and archive the file.

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

@@ -1,15 +1,15 @@
----
-name: migrate
-description: Plan and execute migrations (database, API, framework)
-model: sonnet
-context: fork
-agent: migration-engineer
----
-Plan and execute migration for: $ARGUMENTS
-
-Steps:
-1. Assess the scope and impact of the migration
-2. Create a step-by-step migration plan with rollback strategy
-3. Write migration scripts or code changes
-4. Test the migration including rollback path
-5. Document breaking changes and migration guide
+---
+name: migrate
+description: Plan and execute migrations (database, API, framework)
+model: sonnet
+context: fork
+agent: migration-engineer
+---
+Plan and execute migration for: $ARGUMENTS
+
+Steps:
+1. Assess the scope and impact of the migration
+2. Create a step-by-step migration plan with rollback strategy
+3. Write migration scripts or code changes
+4. Test the migration including rollback path
+5. Document breaking changes and migration guide

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

@@ -1,17 +1,17 @@
----
-name: perf
-description: Performance analysis, profiling, and optimization
-model: sonnet
-context: fork
-agent: performance-engineer
----
-Analyze performance for: $ARGUMENTS
-
-If no arguments, do a general performance review of the project.
-
-Steps:
-1. Identify the performance bottleneck or area of concern
-2. Profile the code (check for N+1 queries, unnecessary allocations, blocking I/O)
-3. Benchmark the current performance baseline
-4. Propose optimizations with expected impact
-5. Implement the optimization and measure improvement
+---
+name: perf
+description: Performance analysis, profiling, and optimization
+model: sonnet
+context: fork
+agent: performance-engineer
+---
+Analyze performance for: $ARGUMENTS
+
+If no arguments, do a general performance review of the project.
+
+Steps:
+1. Identify the performance bottleneck or area of concern
+2. Profile the code (check for N+1 queries, unnecessary allocations, blocking I/O)
+3. Benchmark the current performance baseline
+4. Propose optimizations with expected impact
+5. Implement the optimization and measure improvement

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

@@ -1,17 +1,17 @@
----
-name: refactor
-description: Identify code smells and execute safe refactorings
-model: sonnet
-context: fork
-agent: refactoring-agent
----
-Analyze and refactor the specified code.
-
-Target: $ARGUMENTS (file path, module, or area to refactor)
-
-Steps:
-1. Read the target code and understand its purpose
-2. Identify code smells (long functions, duplication, high complexity)
-3. Propose specific refactorings with rationale
-4. Implement refactorings one at a time, verifying tests pass after each
-5. Report what was changed and why
+---
+name: refactor
+description: Identify code smells and execute safe refactorings
+model: sonnet
+context: fork
+agent: refactoring-agent
+---
+Analyze and refactor the specified code.
+
+Target: $ARGUMENTS (file path, module, or area to refactor)
+
+Steps:
+1. Read the target code and understand its purpose
+2. Identify code smells (long functions, duplication, high complexity)
+3. Propose specific refactorings with rationale
+4. Implement refactorings one at a time, verifying tests pass after each
+5. Report what was changed and why

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

@@ -1,14 +1,14 @@
----
-name: research
-description: Explore codebase and gather context about a topic or area
-model: haiku
-context: fork
-agent: researcher
----
-Research the following topic in this codebase: $ARGUMENTS
-
-Steps:
-1. Search for relevant files, types, and patterns related to the topic
-2. Read key files to understand the architecture and conventions
-3. Identify dependencies and relationships between components
-4. Report findings with file paths, key types, and patterns discovered
+---
+name: research
+description: Explore codebase and gather context about a topic or area
+model: haiku
+context: fork
+agent: researcher
+---
+Research the following topic in this codebase: $ARGUMENTS
+
+Steps:
+1. Search for relevant files, types, and patterns related to the topic
+2. Read key files to understand the architecture and conventions
+3. Identify dependencies and relationships between components
+4. Report findings with file paths, key types, and patterns discovered

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

@@ -1,18 +1,18 @@
----
-name: review
-description: Deep code review of recent changes or specified files
-model: sonnet
-context: fork
-agent: code-reviewer
----
-Perform a thorough code review.
-
-If $ARGUMENTS is provided, review those specific files or the given PR/commit.
-Otherwise, review uncommitted changes via `git diff`.
-
-Steps:
-1. Get the diff (git diff or specified files)
-2. Review for correctness, bugs, and edge cases
-3. Check adherence to project patterns and conventions
-4. Identify security concerns
-5. Report findings as: blocker / suggestion / nit with file:line references
+---
+name: review
+description: Deep code review of recent changes or specified files
+model: sonnet
+context: fork
+agent: code-reviewer
+---
+Perform a thorough code review.
+
+If $ARGUMENTS is provided, review those specific files or the given PR/commit.
+Otherwise, review uncommitted changes via `git diff`.
+
+Steps:
+1. Get the diff (git diff or specified files)
+2. Review for correctness, bugs, and edge cases
+3. Check adherence to project patterns and conventions
+4. Identify security concerns
+5. Report findings as: blocker / suggestion / nit with file:line references

package/templates/skills/dev/security-audit/SKILL.md

@@ -1,17 +1,17 @@
----
-name: security-audit
-description: Run a security audit on the project (dependencies, secrets, OWASP)
-model: haiku
-context: fork
-agent: security-reviewer
----
-Perform a comprehensive security audit of this project.
-
-If $ARGUMENTS is provided, focus the audit on that specific area.
-
-Steps:
-1. Run dependency audit (npm audit, pip-audit, cargo audit, etc.)
-2. Scan for hardcoded secrets, API keys, and credentials
-3. Review authentication and authorization patterns
-4. Check for OWASP Top 10 vulnerabilities in the codebase
-5. Report findings categorized by severity (critical/high/medium/low)
+---
+name: security-audit
+description: Run a security audit on the project (dependencies, secrets, OWASP)
+model: haiku
+context: fork
+agent: security-reviewer
+---
+Perform a comprehensive security audit of this project.
+
+If $ARGUMENTS is provided, focus the audit on that specific area.
+
+Steps:
+1. Run dependency audit (npm audit, pip-audit, cargo audit, etc.)
+2. Scan for hardcoded secrets, API keys, and credentials
+3. Review authentication and authorization patterns
+4. Check for OWASP Top 10 vulnerabilities in the codebase
+5. Report findings categorized by severity (critical/high/medium/low)

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

@@ -0,0 +1,65 @@
+---
+name: spec
+description: Author a rulebook task spec interactively — research, draft, ask the user clarifying questions, confirm, then create the tasks in rulebook ready for /rulebook-driver. Use when the user wants to plan/spec a feature before implementing.
+model: opus
+context: main
+---
+Author a rulebook task spec for: $ARGUMENTS
+
+This skill runs in the MAIN conversation (not a forked subagent) so it CAN ask
+the user questions with the AskUserQuestion tool. It drives the `spec-author`
+workflow as its drafting/critique engine, loops with the user until the spec is
+solid, confirms, then creates the rulebook tasks and hands off to
+`/rulebook-driver`.
+
+## Steps
+
+1. **Pre-flight.** If `$ARGUMENTS` is empty, ask the user what they want to spec.
+   Read `.rulebook/specs/RULEBOOK.md` for the required spec format
+   (## ADDED/MODIFIED, "### Requirement: <name>" with SHALL/MUST, "#### Scenario:"
+   with Given/When/Then).
+
+2. **Draft + critique loop.** Run the `spec-author` workflow with the topic:
+   `Workflow({ name: "spec-author", args: { topic: "<topic>" } })`.
+   It returns `{ draft, ready, questions[], gaps[], missingScenarios[] }`.
+
+3. **Ask the user.** If `ready` is false, take the returned `questions` (each has
+   `question`, `why`, `options`) and present them with the **AskUserQuestion**
+   tool — one question per item, using the provided `options` as choices (the
+   user can always answer free-form). Also surface `gaps` and `missingScenarios`
+   so the user can react to them.
+
+4. **Iterate.** Re-run the workflow feeding the answers back:
+   `Workflow({ name: "spec-author", args: { topic: "<topic>", answers: [{ question, answer }, ...] } })`.
+   Accumulate ALL answers across rounds (don't drop earlier ones). Repeat steps
+   3–4 until the workflow returns `ready: true` (no open questions).
+
+5. **Confirm with the user.** Show the final proposal + spec (the workflow's
+   `draft`). Ask the user to confirm with AskUserQuestion: **"Create these
+   rulebook tasks?"** options: Create / Revise (more questions) / Cancel.
+   - Revise → go back to step 3.
+   - Cancel → stop, leave nothing created.
+   - Create → continue.
+
+6. **Create the tasks.** ONLY after explicit confirmation, create the task(s) in
+   rulebook using the MCP tools — never `mkdir`/`Write` by hand:
+   - `rulebook_task_create` for each task (phase-prefixed id, e.g.
+     `phase1_<slug>`), writing the confirmed proposal.md, tasks.md checklist,
+     and specs/<module>/spec.md from the draft.
+   - `rulebook_task_validate` each created task; fix format issues and re-validate
+     until clean.
+
+7. **Hand off to the driver.** Report the created task ids and tell the user the
+   spec is ready. Offer to start implementation now by running the
+   `rulebook-driver` workflow: `/rulebook-driver` (drains the whole backlog) or
+   `/rulebook-driver { "once": true }` for one item. Do NOT auto-start it without
+   the user's go-ahead.
+
+## Rules
+
+- The user MUST confirm (step 5) before any task is created. No silent creation.
+- Workflow subagents can't prompt the user — that's why the asking happens here
+  in the main loop. Always relay the workflow's questions verbatim where useful.
+- Keep accumulating answers across iterations; the workflow folds them into the
+  draft as settled decisions.
+- Specs and tasks are created via `rulebook_*` MCP tools only.