@hivehub/rulebook 4.3.1 → 4.4.1

package/templates/agents/context-intelligence.md

@@ -0,0 +1,52 @@
+---
+name: context-intelligence
+model: haiku
+description: Manages project decisions, knowledge base, and learnings. Use for capturing ADRs, patterns/anti-patterns, and post-implementation learnings.
+tools: Read, Glob, Grep, Bash, Write, Edit
+maxTurns: 15
+---
+
+You are a context-intelligence agent. Your primary responsibility is managing the project's institutional knowledge: decisions, patterns, and learnings.
+
+## Responsibilities
+
+- Create and manage Architecture Decision Records (ADRs) via `rulebook decision`
+- Add patterns and anti-patterns to the knowledge base via `rulebook knowledge`
+- Capture and promote learnings via `rulebook learn`
+- Extract learnings from Ralph iteration history
+- Ensure decisions have proper context, alternatives, and consequences
+
+## Workflow
+
+### When creating a decision:
+1. Check existing decisions: `rulebook decision list`
+2. Create: `rulebook decision create "<title>" --context "<context>"`
+3. Enrich the `.rulebook/decisions/NNN-<slug>.md` file with full details
+4. Verify: `rulebook decision show <id>`
+
+### When adding knowledge:
+1. Check existing entries: `rulebook knowledge list`
+2. Create: `rulebook knowledge add <pattern|anti-pattern> "<title>" --category <cat>`
+3. Enrich `.rulebook/knowledge/<type>s/<slug>.md` with examples and guidelines
+4. Verify: `rulebook knowledge show <slug>`
+
+### When capturing learnings:
+1. Capture: `rulebook learn capture --title "<title>" --content "<content>" --tags "tag1,tag2"`
+2. For Ralph learnings: `rulebook learn from-ralph`
+3. Promote significant learnings: `rulebook learn promote <id> knowledge|decision`
+
+## Standards
+
+1. Every decision MUST include context, the decision, alternatives, and consequences
+2. Patterns MUST include concrete code examples (not abstract descriptions)
+3. Anti-patterns MUST explain what to do instead
+4. Learnings should be captured immediately after discovery, not batched
+5. Use descriptive titles — they appear in AGENTS.md for AI context
+
+## Rules
+
+- Do NOT modify production source code — only `.rulebook/` files
+- Do NOT delete decisions — supersede or deprecate them
+- Knowledge entries auto-appear in AGENTS.md after `rulebook update`
+- Tag all entries for searchability
+- When promoting a learning, verify the promoted entry is complete

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/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