@grimoire-cc/cli 0.6.3 → 0.7.1

package/packs/docs-pack/grimoire.json

@@ -0,0 +1,30 @@
+{
+  "name": "docs-pack",
+  "version": "1.0.0",
+  "agents": [],
+  "skills": [
+    {
+      "name": "grimoire:business-logic-docs",
+      "path": "skills/gr.business-logic-docs",
+      "description": "Create and maintain structured business logic documentation for AI assistants and developers. Use when documenting business rules, domain knowledge, invariants, workflows, state machines, entity relationships, decision logs, or building a business logic knowledge base.",
+      "triggers": {
+        "keywords": [],
+        "file_extensions": [],
+        "patterns": [
+          "document.*business",
+          "business.*logic",
+          "business.*rule",
+          "domain.*knowledge",
+          "knowledge.*base",
+          "document.*domain",
+          "document.*invariant",
+          "document.*workflow",
+          "decision.*log"
+        ],
+        "file_paths": [
+          "**/docs/business-logic/**"
+        ]
+      }
+    }
+  ]
+}

package/packs/docs-pack/skills/gr.business-logic-docs/SKILL.md

@@ -0,0 +1,278 @@
+---
+name: grimoire:business-logic-docs
+description: "Create, update, and audit structured business logic documentation for AI assistants and developers. Use when documenting business rules, domain knowledge, invariants, workflows, state machines, entity relationships, decision logs, building a business logic knowledge base, or reviewing docs for staleness."
+---
+
+# Business Logic Documentation
+
+Guide Claude through creating, updating, and auditing a structured knowledge base of a project's business logic. The knowledge base serves two audiences: AI coding assistants (so they understand domain context and make better decisions) and human developers (so they can recall and reason about business rules).
+
+All generated documentation lives in `docs/business-logic/` by default. Ask the developer if they prefer a different path before generating.
+
+**Core principle: business rules drive code, not vice versa.** Business logic documentation captures decisions that drive code changes — not descriptions of what code does. The flow is always: business decision → documentation → code implementation.
+
+## Workflow 1 — Create the Initial Knowledge Base
+
+Use this when a project has no business logic docs yet.
+
+### Step 1: Discover Domain Areas
+
+Examine the codebase to identify bounded contexts:
+
+- **Folder structure**: Top-level directories, module boundaries, feature folders
+- **Entity names**: Database models, domain classes, type definitions
+- **Route groupings**: API endpoints, controller organization
+- **Naming patterns**: Prefixes/suffixes that suggest domain separation (e.g., `order-`, `payment-`, `inventory-`)
+
+Produce a preliminary list of domain areas and share it with the developer for confirmation before proceeding.
+
+### Step 2: Interview the Developer
+
+Surface business rules that aren't obvious from code alone. Ask focused questions in small batches (3-5 at a time) to avoid overwhelming. Prioritize:
+
+1. **Domain terminology** — "What terms does your team use that have precise meanings? Any terms that are commonly confused?"
+2. **User roles and permissions** — "What roles exist, and what can each role do or not do?"
+3. **Critical invariants** — "What must always be true? What must never happen?"
+4. **Hard constraints** — "What things MUST NEVER happen in the system? What would cause the most damage if violated?"
+5. **Non-obvious edge cases** — "What scenarios have caused bugs or confusion before?"
+6. **Regulatory or legal rules** — "Are any business rules driven by compliance requirements?"
+
+After each batch of answers, ask follow-up questions if something needs clarification. Move to the next domain area once coverage feels sufficient.
+
+### Step 3: Generate the Documentation
+
+Create the three-tier structure described below. For each domain area identified:
+
+1. Create the Tier 2 file using the template from [references/tier2-template.md](references/tier2-template.md)
+2. Fill in what you learned from the interview. For rules surfaced from code analysis (not confirmed by the developer), mark with `[SOURCE: code-audit — unconfirmed]` — these MUST be confirmed before being treated as business rules.
+3. Mark sections where information is incomplete with `<!-- TODO: clarify with team -->`
+
+Then create the `_overview.md` (Tier 1) and `_decision-log.md` (Tier 3) files.
+
+### Step 4: Integrate with CLAUDE.md
+
+Add a reference to the knowledge base in the project's `CLAUDE.md` (create one if it doesn't exist). See [CLAUDE.md Integration](#claudemd-integration) below.
+
+## Workflow 2 — Update the Existing Knowledge Base
+
+Use this when business logic changes. Updates are driven by text input — user stories, change requests, discussion transcripts/summaries — not by code analysis.
+
+### Step 1: Understand the Change
+
+Read the provided input (user story, change request, discussion transcript/summary). Extract:
+
+- What business rules are being added, modified, or removed
+- Which domain area(s) and Tier 2 file(s) are affected
+
+Do NOT look at code to infer business rules — the provided input is the single source of truth. If the input is ambiguous or incomplete, ask the user for clarification before proceeding.
+
+### Step 2: Review Existing Documentation
+
+Read the affected Tier 2 file(s). For each change from Step 1, check:
+
+- Does it contradict any existing rule?
+- Does it modify an existing rule or add a new one?
+- Does it affect workflows, entities, or integration points?
+- Does it invalidate any existing constraints, examples, or counterexamples?
+
+Flag any conflicts or ambiguities to the user before making changes.
+
+### Step 3: Clarify Uncertainties
+
+If anything from the input is unclear, contradicts existing docs, or leaves gaps, ask the user targeted questions. Examples:
+
+- "The user story says X, but the current docs say Y — which is correct?"
+- "This change implies Z — is that intended?"
+- "Are there edge cases for this new rule?"
+- "Does this replace the existing rule or add a new exception?"
+
+NEVER proceed with uncertain information. NEVER fill gaps by guessing from code.
+
+### Step 4: Apply the Updates
+
+Only add information you are certain about from the provided input.
+
+- **Modified rules**: Replace the old rule with the new one. Don't annotate what changed — git tracks history.
+- **New rules**: Use the template format from [references/tier2-template.md](references/tier2-template.md). Include Source marker.
+- **Removed rules**: Delete them. Only keep a note about the removal if it carries business context that other rules depend on (e.g., "we no longer support gift cards" is useful if other rules reference gift cards).
+- **New domain areas**: Create a new Tier 2 file and add it to the table of contents in `_overview.md`.
+- **"Enforced in" fields**: Leave empty or mark with `<!-- TODO: add code location after implementation -->` — code locations are filled in after implementation, not before.
+- **Diagrams and glossary**: Update as needed to reflect changes.
+
+### Step 5: Validate and Present
+
+Verify:
+
+- No contradictions introduced across files
+- Diagrams reflect the changes
+- Table of contents is accurate
+- Terminology is consistent with the glossary
+- Decision log entry added if the change involves a non-obvious decision
+
+Present a summary to the user showing exactly what was changed and why, so they can confirm accuracy.
+
+## Workflow 3 — Audit Knowledge Base
+
+Use only when the user explicitly requests an audit or review of existing documentation.
+
+This is the one workflow where code comparison is appropriate — but only to flag potential gaps, never to infer new business rules.
+
+### Step 1: Review Documentation Completeness
+
+Check for structural issues using [references/audit-checklist.md](references/audit-checklist.md):
+
+- Unresolved `<!-- TODO -->` markers
+- Empty or placeholder sections
+- Rules missing "Why" explanations
+- Critical rules without counterexamples
+- Constraints section empty or missing
+
+### Step 2: Check Code Alignment
+
+**Only when the user explicitly asks to compare docs against code.** Check:
+
+- "Enforced in" references still point to existing code
+- State diagram transitions match actual code behavior
+- Entity attributes match current schema
+
+Flag undocumented code behavior as questions, not assertions: "This code seems to enforce X, but it's not documented — is this a business rule that should be captured?" Mark any rules surfaced this way with `[SOURCE: code-audit — unconfirmed]`.
+
+### Step 3: Check Terminology Consistency
+
+- Extract all glossary terms from `_overview.md`
+- Search Tier 2 files for inconsistent usage (synonyms, abbreviations, variant spellings)
+- Report inconsistencies in the format described in [references/audit-checklist.md](references/audit-checklist.md)
+
+### Step 4: Produce Audit Report
+
+Structured output with sections:
+
+1. **Incomplete Items** — Missing Why, missing examples, empty sections, unresolved TODOs
+2. **Terminology Issues** — Inconsistent term usage across files
+3. **Structural Issues** — ToC mismatches, missing template sections, duplicated rules
+4. **Potential Documentation Gaps** *(only if Step 2 was performed)* — Code behavior not reflected in docs
+
+Ask the developer to review and confirm before making any changes.
+
+## Three-Tier Documentation Structure
+
+### Tier 1 — `_overview.md`
+
+The entry point. Contains:
+
+- **Business summary**: 2-3 paragraphs — enough for a newcomer to orient.
+- **Glossary**: Domain terms with precise definitions. This prevents AI and humans from confusing terms.
+- **User roles**: Each role's capabilities and restrictions.
+- **Domain area map**: High-level view of how domain areas relate to each other. Use a mermaid diagram if relationships are non-trivial.
+- **Table of contents**: Links to every Tier 2 file.
+
+### Tier 2 — One File Per Domain Area
+
+E.g., `orders.md`, `payments.md`, `inventory.md`. Each follows the template in [references/tier2-template.md](references/tier2-template.md). Key sections:
+
+- **Purpose** — What this area does and why it exists.
+- **Key Entities** — Core entities, attributes, relationships. Use mermaid for non-trivial relationships.
+- **Constraints** — The highest-value content. MUST and MUST NOT rules with business reasons.
+- **Business Rules & Invariants** — Each rule states: what the rule is, why it exists (the business reason), where it's enforced in code, a concrete example including an edge case, and for critical rules a counterexample.
+- **Workflows & State Transitions** — Key processes with mermaid state diagrams for anything with 3+ states. Specify triggers and validations.
+- **Decision Trees** — Sequential if-then format for multi-branch conditional logic.
+- **Integration Points** — External systems, APIs, other domain areas. Note contracts and assumptions.
+- **Edge Cases & Known Gotchas** — Non-obvious behaviors that have caused bugs or confusion.
+
+### Tier 3 — `_decision-log.md`
+
+A chronological record of non-obvious business decisions. Append-only — new entries go at the top, old entries are never edited. If a decision is reversed, add a new entry referencing the original.
+
+Each entry follows:
+
+```markdown
+## YYYY-MM-DD — [Short title]
+**Context:** What situation prompted this decision.
+**Decision:** [Chosen option] because [justification], to achieve [desired outcome], accepting [tradeoff].
+**Alternatives considered:** What else was evaluated and why it was rejected.
+**Affected areas:** Which Tier 2 files are impacted.
+```
+
+## Writing Principles
+
+Follow these when writing or updating business logic docs:
+
+1. **Write for reasoning, not just reading.** Always include the "why" behind a rule. Instead of "Users can't delete invoices," write "Users can't delete invoices because downstream accounting reconciliation depends on invoice immutability. Soft-delete via `deleted_at` is used instead." The causal chain enables correct inferences.
+
+2. **Be explicit about invariants.** Things that must always or never be true are the highest-value content. Call them out prominently in the Constraints section of every domain area file.
+
+3. **Link business concepts to code landmarks.** Don't describe implementation details, but do say "Order state transitions are enforced in `OrderStateMachine` — never manipulate `order.status` directly." This bridges conceptual and concrete.
+
+4. **Use concrete examples over abstract rules.** Instead of "discounts are applied hierarchically," show: "A user with a 10% loyalty discount buying a product with a 20% sale: sale price first ($100 -> $80), then loyalty ($80 -> $72). Total discount is 28%, not 30%."
+
+5. **Prefer mermaid diagrams for state machines and entity relationships.** They're diffable in PRs, render in GitHub, and Claude can read and generate them.
+
+6. **Don't duplicate what git tracks.** No version headers, no changelogs inside docs. The decision log is the sole exception because chronological "why" context is its purpose.
+
+7. **Group by domain area, not by technical layer.** Everything about orders (validation, state machine, permissions, integrations) goes in `orders.md`, not split across "validations.md" and "permissions.md".
+
+8. **Constraints before capabilities.** Document what MUST NOT happen before documenting what should happen. Use explicit RFC-2119 language (MUST, MUST NOT, SHOULD, SHOULD NOT) for rules that carry enforcement weight.
+
+9. **Include counterexamples for critical rules.** For every invariant and constraint, show the wrong behavior and why it fails. Format: what the correct behavior is, what the incorrect behavior looks like, and why it matters.
+
+10. **Use decision trees for complex conditional logic.** Any logic with 3+ branches MUST use sequential if-then format. Mark mutually exclusive paths explicitly. No prose-only descriptions for multi-branch logic.
+
+11. **Mark information sources.** Tag rules with their origin: `[SOURCE: user-story]`, `[SOURCE: discussion]`, `[SOURCE: change-request]`. During audits (Workflow 3 only), rules surfaced from code analysis get `[SOURCE: code-audit — unconfirmed]` and MUST be confirmed with the user before being treated as business rules. Incorrect docs are worse than missing docs.
+
+12. **State machines over prose for workflows.** Any process with 3+ states MUST use a mermaid stateDiagram plus a transition table. No prose-only workflow descriptions for stateful processes.
+
+## Documentation Clarity
+
+Docs describe the current state, not history:
+
+- When a rule changes, **replace it** — don't annotate what it used to be. Git tracks history.
+- No "previously was", "changed from X to Y", "before it was" language.
+- Remove rules that no longer apply. Only keep a note about the removal if it carries business context other rules depend on (e.g., "we no longer support gift cards" is useful if other rules reference gift cards).
+- Use `<!-- TODO -->` markers only for genuinely incomplete information that needs user input.
+- Every statement in the docs should describe what IS true right now.
+
+## ALWAYS / NEVER
+
+### ALWAYS
+
+- ALWAYS confirm the output path before generating files
+- ALWAYS include "Why" for every rule and constraint
+- ALWAYS ask for clarification when input is ambiguous or incomplete
+- ALWAYS verify new information doesn't contradict existing rules
+- ALWAYS present a summary of all changes for user confirmation
+- ALWAYS update the Table of Contents when files are added or removed
+- ALWAYS add a decision log entry for non-obvious changes
+- ALWAYS leave "Enforced in" empty when the code location is unknown
+
+### NEVER
+
+- NEVER guess or infer business rules from code — business rules drive code, not vice versa
+- NEVER add information you are not certain about
+- NEVER proceed when the input contradicts existing documentation — ask first
+- NEVER reverse-engineer business rules from code changes unless the user explicitly requests it
+- NEVER use "previously was" / "changed from X to Y" / history annotations — docs describe current state, git tracks history
+- NEVER leave diagrams contradicting documented transitions
+- NEVER duplicate rules across files — reference the canonical location instead
+
+## CLAUDE.md Integration
+
+Add (or update) the following section in the project's `CLAUDE.md`:
+
+```markdown
+## Business Logic Documentation
+Before modifying business logic, read the relevant file in `docs/business-logic/`.
+When your changes affect business rules, update the corresponding doc in the same commit.
+If no file exists for the domain area, create one following the structure of existing files.
+Start with `docs/business-logic/_overview.md` for domain orientation.
+Rules marked `[SOURCE: code-audit — unconfirmed]` need human confirmation before relying on them.
+```
+
+If the developer chose a custom docs path, adjust the paths accordingly.
+
+## Limitations
+
+- This skill provides guidance for creating documentation, not executable code.
+- The knowledge base captures business rules at a point in time — it requires human input for rules that aren't visible in code.
+- Rules inferred from code (`[SOURCE: code-audit — unconfirmed]`) require human verification before they should be treated as authoritative business rules.
+- Mermaid diagrams may not render in all environments (they work in GitHub, VS Code, and most modern markdown viewers).
+- The decision log is only as valuable as the team's discipline in maintaining it.

package/packs/docs-pack/skills/gr.business-logic-docs/references/audit-checklist.md

@@ -0,0 +1,48 @@
+# Audit Checklist
+
+Use this checklist with [Workflow 3 — Audit Knowledge Base](../SKILL.md#workflow-3--audit-knowledge-base).
+
+## Code Alignment Checks
+
+Only perform when the user explicitly requests code comparison.
+
+- [ ] Every "Enforced in" reference points to a file/class/function that still exists
+- [ ] Mermaid state diagrams match actual state transitions in code
+- [ ] Entity attributes listed in docs match the current schema/model definitions
+- [ ] Integration contracts (endpoints, payloads) match actual API implementations
+- [ ] Decision trees match actual conditional logic in code
+
+Present findings as questions, not assertions. Example: "This code seems to enforce X, but it's not documented — is this a business rule that should be captured?"
+
+## Content Quality Checks
+
+- [ ] Every business rule has a "Why" explanation
+- [ ] Critical rules (invariants, constraints) have counterexamples
+- [ ] No unconfirmed `[SOURCE: code-audit — unconfirmed]` markers older than 30 days
+- [ ] Decision trees exist for multi-branch logic (3+ paths)
+- [ ] Constraints section populated with MUST / MUST NOT items
+- [ ] Examples use concrete values, not abstract descriptions
+
+## Structural Checks
+
+- [ ] Table of Contents in `_overview.md` lists all Tier 2 files
+- [ ] Each Tier 2 file has all template sections (even if marked TODO)
+- [ ] Glossary terms in `_overview.md` are consistent across all files
+- [ ] No business rules duplicated across multiple Tier 2 files
+- [ ] All `<!-- TODO -->` markers reviewed — resolve or confirm still pending
+- [ ] Decision log entries reference correct Tier 2 files in "Affected areas"
+
+## Terminology Consistency Check
+
+For each term in the glossary:
+
+1. Search all Tier 2 files for the term
+2. Search for common synonyms or abbreviations
+3. Flag any file that uses a synonym instead of the glossary term
+4. Check that the term's definition still matches how it's used in context
+
+Report format:
+
+| Term | Expected | Found | File | Line |
+|---|---|---|---|---|
+| `[glossary term]` | `[glossary term]` | `[synonym found]` | `[file]` | `[line]` |

package/packs/docs-pack/skills/gr.business-logic-docs/references/tier2-template.md

@@ -0,0 +1,129 @@
+# [Domain Area Name]
+
+## Table of Contents
+
+- [Purpose](#purpose)
+- [Key Entities](#key-entities)
+- [Constraints](#constraints)
+- [Business Rules & Invariants](#business-rules--invariants)
+- [Workflows & State Transitions](#workflows--state-transitions)
+- [Decision Trees](#decision-trees)
+- [Integration Points](#integration-points)
+- [Edge Cases & Known Gotchas](#edge-cases--known-gotchas)
+
+## Purpose
+
+One-paragraph summary of what this area does and why it exists.
+
+## Key Entities
+
+List the core entities, their key attributes, and relationships. Use a mermaid diagram if relationships are non-trivial.
+
+```mermaid
+erDiagram
+    ENTITY_A ||--o{ ENTITY_B : "relationship"
+    ENTITY_A {
+        string id
+        string name
+        datetime created_at
+    }
+    ENTITY_B {
+        string id
+        string entity_a_id
+        string status
+    }
+```
+
+## Constraints
+
+The highest-value content — what MUST and MUST NOT happen in this domain area.
+
+### MUST
+
+- **Constraint**: State what must always be true.
+  - **Why**: Business reason this constraint exists.
+  - **Enforced in**: File, class, or function name.
+
+### MUST NOT
+
+- **Constraint**: State what must never happen.
+  - **Why**: Business reason — what goes wrong if violated.
+  - **Enforced in**: File, class, or function name.
+
+## Business Rules & Invariants
+
+Each rule follows this pattern:
+
+- **Rule**: State the rule clearly.
+- **Why**: Explain the business reason (this enables AI to reason correctly in adjacent code).
+- **Enforced in**: Point to where in the codebase this is enforced (file, class, or function name). Leave empty or use `<!-- TODO: add code location after implementation -->` if not yet implemented.
+- **Example**: A concrete scenario illustrating the rule, including at least one edge case.
+- **Counterexample** *(critical rules)*: Show the wrong behavior and why it fails.
+- **Source**: `[SOURCE: user-story]`, `[SOURCE: discussion]`, `[SOURCE: change-request]`, or `[SOURCE: code-audit — unconfirmed]`.
+
+---
+
+- **Rule**: [Example] An order cannot be modified after it enters "shipped" status.
+- **Why**: Downstream logistics systems snapshot the order at shipment time; modifications would cause fulfillment mismatches.
+- **Enforced in**: `OrderStateMachine.validateTransition()` rejects edits on shipped orders.
+- **Example**: A customer tries to change their shipping address 5 minutes after shipment. The system returns a 409 Conflict with instructions to contact support for a redirect request instead.
+- **Counterexample**: If the system allowed edits after shipment, the warehouse would ship to the old address while the customer sees the new one — causing a lost package and a support ticket.
+- **Source**: `[SOURCE: user-story]`
+
+## Workflows & State Transitions
+
+Describe key processes. Use mermaid state diagrams for anything with 3+ states. Specify who/what triggers each transition and what validations occur.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Draft
+    Draft --> Pending : submit (user)
+    Pending --> Approved : approve (admin)
+    Pending --> Rejected : reject (admin)
+    Approved --> Completed : fulfill (system)
+    Rejected --> [*]
+    Completed --> [*]
+```
+
+| Transition | Triggered by | Validations |
+|---|---|---|
+| Draft -> Pending | User submits | All required fields present, passes schema validation |
+| Pending -> Approved | Admin approves | Admin has `approve` permission, item passes compliance check |
+| Pending -> Rejected | Admin rejects | Rejection reason is required |
+| Approved -> Completed | System fulfills | External service confirms fulfillment |
+
+## Decision Trees
+
+Use sequential if-then format for multi-branch conditional logic. Mark mutually exclusive paths explicitly.
+
+```
+IF [condition A]
+  THEN [action/outcome 1]
+ELSE IF [condition B]           ← mutually exclusive with A
+  IF [sub-condition B1]
+    THEN [action/outcome 2]
+  ELSE
+    THEN [action/outcome 3]
+ELSE                            ← default / fallback
+  THEN [action/outcome 4]
+```
+
+## Integration Points
+
+External systems, APIs, webhooks, or other domain areas this module interacts with. Note any contracts or assumptions.
+
+- **[System/API name]**: Brief description of the integration, what data flows in which direction, and any assumptions about availability or response format.
+
+## Edge Cases & Known Gotchas
+
+Non-obvious behaviors that have caused bugs or confusion before. These are extremely high-value for AI assistants.
+
+- **[Gotcha title]**: Description of the non-obvious behavior, why it exists, and what to watch out for when modifying related code.
+
+<!--
+Staleness markers — use these in comments to flag items for review:
+
+<!-- TODO: clarify with team -->
+<!-- TODO: add code location after implementation -->
+<!-- STALE? last verified YYYY-MM-DD — needs review -->
+-->