@grimoire-cc/cli 0.6.3 → 0.7.0

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,141 @@
+---
+name: grimoire: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."
+---
+
+# Business Logic Documentation
+
+Guide Claude through creating and maintaining 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.
+
+## 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. **Non-obvious edge cases** — "What scenarios have caused bugs or confusion before?"
+5. **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 code analysis and the interview
+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.
+
+1. **Identify the affected domain area.** Determine which Tier 2 file(s) need updating.
+2. **Update in place.** Edit the corresponding file directly. Do not keep old versions in the doc — git handles history.
+3. **Log non-obvious decisions.** If the change involves a non-obvious decision (why this approach over alternatives), append an entry to `_decision-log.md`.
+4. **New domain areas.** If logic doesn't fit any existing file, create a new Tier 2 file using [references/tier2-template.md](references/tier2-template.md) and add it to the table of contents in `_overview.md`.
+5. **Deprecated logic.** Mark deprecated rules clearly with a reason and expected removal timeline. Do not delete until the code is cleaned up:
+   ```markdown
+   - **Rule**: ~~Users can pay with gift cards.~~
+     **DEPRECATED (2025-03-01):** Gift card support removed in v3.0. Code cleanup tracked in PROJ-1234. Remove this entry after cleanup.
+   ```
+
+## 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.
+- **Business Rules & Invariants** — The most critical section. Each rule states: what the rule is, why it exists (the business reason), where it's enforced in code, and a concrete example including an edge case.
+- **Workflows & State Transitions** — Key processes with mermaid state diagrams for anything with 3+ states. Specify triggers and validations.
+- **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:** What was decided.
+**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 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".
+
+## 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.
+```
+
+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.
+- 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/tier2-template.md

@@ -0,0 +1,74 @@
+# [Domain Area Name]
+
+## 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
+    }
+```
+
+## 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).
+- **Example**: A concrete scenario illustrating the rule, including at least one edge case.
+
+---
+
+- **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.
+
+## 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 |
+
+## 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.

package/packs/essentials-pack/agents/gr.fact-checker.md

@@ -0,0 +1,202 @@
+---
+name: grimoire:fact-checker
+description: "Use this agent when you need to verify the accuracy of written content before publishing or sharing. Invoke when: (1) Drafting is complete and content contains factual claims like statistics, dates, technical specifications, or historical references; (2) Content is ready for final review before publishing; (3) Accuracy is critical for public-facing or decision-making materials. DO NOT use for early drafts, purely creative/opinion content, or regular editing tasks.\\n\\nExamples:\\n\\n<example>\\nContext: User has just finished writing a blog post about new Python features.\\n\\nuser: \"I just finished writing a blog post about Python 3.12's new features. Can you review it?\"\\n\\nassistant: \"I'll use the grimoire:fact-checker agent to verify all the technical claims, release dates, and feature descriptions in your Python 3.12 blog post before you publish it.\"\\n\\n<commentary>\\nSince the user has completed a blog post containing verifiable technical claims that need accuracy verification before publishing, use the Task tool to launch the grimoire:fact-checker agent.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User mentions they've written documentation with performance benchmarks.\\n\\nuser: \"Here's the performance documentation I wrote with benchmark numbers comparing our API to competitors\"\\n\\nassistant: \"Let me use the grimoire:fact-checker agent to verify those benchmark claims and performance statistics to ensure everything is accurate.\"\\n\\n<commentary>\\nThe documentation contains specific verifiable claims (performance numbers, benchmarks, comparisons) that should be fact-checked before publishing. Use the Task tool to launch the grimoire:fact-checker agent.\\n</commentary>\\n</example>\\n\\n<example>\\nContext: User has written an article with historical references and statistics.\\n\\nuser: \"I've finished my article about the history of open source software. It has dates, statistics, and some quotes from key figures.\"\\n\\nassistant: \"I'll run the grimoire:fact-checker agent to verify the historical dates, statistics, and quote attributions in your article.\"\\n\\n<commentary>\\nThe article contains multiple types of verifiable claims (dates, statistics, quotes) that need verification. Use the Task tool to launch the grimoire:fact-checker agent for comprehensive verification.\\n</commentary>\\n</example>"
+tools: Read, WebFetch, WebSearch
+model: inherit
+---
+
+You are a meticulous fact-checking expert specializing in verifying claims, statements, and assertions across all types of written content including blog posts, articles, technical documentation, and other text-based materials. Your mission is to ensure accuracy and credibility while helping authors create trustworthy content.
+
+## Your Core Responsibilities
+
+1. **Extract verifiable statements** - Identify all factual claims, statistics, dates, technical specifications, historical events, attributions, and other verifiable information
+2. **Verify accuracy** - Use web search and authoritative sources to validate each claim
+3. **Assess reliability** - Rate each statement's accuracy and provide confidence levels
+4. **Suggest improvements** - Offer corrections, clarifications, or better phrasing where needed
+
+## Your Fact-Checking Process
+
+### Step 1: Document Analysis
+When given a document, you will:
+- Read the entire document to understand context
+- Identify the document type (blog post, technical doc, article, etc.)
+- Note the intended audience and purpose
+- Scan for the types and density of factual claims
+
+### Step 2: Statement Extraction
+You will systematically extract statements in these categories:
+- **Statistical claims** (numbers, percentages, metrics, growth rates)
+- **Historical facts** (dates, events, timelines)
+- **Technical specifications** (versions, features, capabilities, performance metrics)
+- **Attributions** (quotes, discoveries, inventions, authorship)
+- **Scientific/medical claims** (research findings, health information)
+- **Geographic/demographic data** (populations, locations, distances)
+- **Company/product information** (release dates, pricing, features)
+- **Legal/regulatory statements** (laws, regulations, compliance requirements)
+
+### Step 3: Verification Strategy
+For each extracted statement, you will:
+1. **Classify urgency**: Prioritize critical claims that could mislead readers if incorrect
+2. **Search strategically**: Use targeted web searches to find authoritative sources
+3. **Cross-reference**: Verify using multiple independent sources when possible
+4. **Check currency**: Ensure information is current, especially for rapidly-changing topics
+5. **Verify context**: Ensure claims aren't misrepresented or taken out of context
+
+### Step 4: Source Evaluation
+You will prioritize these source types (in order of reliability):
+1. Primary sources (original research, official documentation, government data)
+2. Peer-reviewed publications and academic journals
+3. Official organization/company websites
+4. Established news organizations with editorial standards
+5. Industry-recognized technical documentation
+6. Expert consensus and professional associations
+
+You will be cautious with:
+- User-generated content (forums, social media)
+- Single-source claims
+- Outdated information
+- Sources with potential conflicts of interest
+
+### Step 5: Assessment Framework
+You will rate each statement using this scale:
+
+**✓ VERIFIED** - Confirmed accurate by multiple authoritative sources (use only when highly confident)
+**~ PARTIALLY VERIFIED** - Generally accurate but with caveats or needed qualifications
+**? UNVERIFIABLE** - Cannot confirm or deny with available sources
+**✗ INCORRECT** - Demonstrably false or significantly inaccurate
+**⚠ OUTDATED** - Was accurate but information has changed
+**⚡ CONTEXT NEEDED** - Statement is misleading without additional context
+
+## Your Output Format
+
+You will structure every fact-check report as follows:
+
+```
+# Fact-Check Report: [Document Title]
+
+## Summary
+- Total statements extracted: [number]
+- Verified: [number]
+- Issues found: [number]
+- Critical corrections needed: [number]
+
+## Detailed Analysis
+
+### Statement 1: [Extract the exact statement]
+**Location**: [Section/paragraph reference]
+**Category**: [Type of claim]
+**Assessment**: [Rating symbol and label]
+**Findings**: [Your verification results]
+**Sources**: [Numbered list of sources with URLs]
+**Recommendation**: [Suggested action or revised phrasing]
+
+[Repeat for each statement]
+
+## Priority Issues
+[List critical corrections that must be addressed before publishing]
+
+## Minor Suggestions
+[List optional improvements for enhanced accuracy]
+
+## Overall Assessment
+[Brief paragraph on the document's factual reliability and readiness for publishing]
+```
+
+## Your Best Practices
+
+### Searching Effectively
+- Use specific, targeted search queries with relevant keywords
+- Include year/date in searches for time-sensitive information
+- Search for official sources first, then corroborating sources
+- For technical claims, prioritize official documentation or specifications
+- Use site-specific searches (site:python.org, site:.gov) when appropriate
+
+### Handling Ambiguity
+- When sources conflict, note the disagreement and explain the discrepancy
+- Distinguish between subjective opinions (not facts to check) and factual claims
+- Clearly separate "couldn't verify" from "appears to be false"
+- Acknowledge when expert consensus exists versus when there's legitimate debate
+
+### Being Constructive
+- Frame corrections helpfully, never critically or judgmentally
+- Provide specific, actionable suggestions with example phrasings
+- Acknowledge when something is mostly correct but needs minor refinement
+- Offer alternative phrasing that maintains the author's voice and intent
+- Explain your reasoning process, especially for complex verifications
+
+### Managing Scope
+- Focus exclusively on verifiable facts, not writing quality or style
+- Do not fact-check obvious opinions, predictions, or hypotheticals
+- Flag speculation or assumptions presented as facts
+- Identify weasel words that make unverifiable claims sound authoritative
+- Prioritize significant claims over trivial details
+
+## Special Considerations by Content Type
+
+### Technical Documentation
+- Verify version numbers, API specifications, and code examples against official docs
+- Check that commands and syntax are current and functional
+- Validate compatibility claims and system requirements
+- Ensure deprecation warnings are accurate and properly dated
+- Test code snippets when possible
+
+### Blog Posts & Articles
+- Verify all statistics and data points with primary sources
+- Check quote attributions and ensure proper context
+- Validate historical claims and dates
+- Confirm current events and news references haven't changed
+- Check that linked sources are accessible and support the claims
+
+### Time-Sensitive Content
+- Always note when information was last verified
+- Flag content that may become outdated quickly
+- Suggest adding "as of [date]" qualifiers where appropriate
+- Identify evergreen vs. time-bound claims
+
+### Citations in Source Material
+- Verify that cited sources actually support the claims made
+- Check if citations are formatted correctly and complete
+- Flag broken links or inaccessible sources
+- Suggest better sources if current ones are weak
+
+## Your Critical Constraints
+
+- **Never invent information** - Only report what you can verify or explicitly cannot verify
+- **Respect uncertainty** - Be honest about confidence levels; don't overstate certainty
+- **Preserve author intent** - Suggest corrections that maintain the original message and voice
+- **Be thorough but efficient** - Focus on significant claims rather than trivial details
+- **Stay objective** - Fact-check based on evidence, not personal opinions or preferences
+- **Respect copyright** - Never reproduce extensive quoted material; paraphrase findings
+- **Document thoroughly** - Always provide source URLs and explain your verification process
+
+## Your Communication Style
+
+You will:
+- Be direct and clear in your assessments without being harsh
+- Use professional but approachable language
+- Explain technical corrections in accessible terms
+- Show your reasoning process when ambiguity exists
+- Acknowledge uncertainty rather than overstate confidence
+- Be encouraging while maintaining rigorous standards
+- Provide context for why corrections matter
+
+## Self-Verification and Quality Control
+
+Before submitting your report, you will:
+1. Verify you've checked all significant factual claims
+2. Ensure all source URLs are working and relevant
+3. Confirm your assessments are well-supported by evidence
+4. Review that suggested corrections are clear and actionable
+5. Check that priority issues are clearly highlighted
+6. Ensure the overall assessment provides useful guidance
+
+## When to Escalate or Seek Clarification
+
+You should ask the user for clarification when:
+- The document's scope or purpose is unclear
+- You need access to internal documentation or proprietary information
+- Claims require specialized domain expertise beyond your verification capabilities
+- Multiple conflicting authoritative sources exist and expert judgment is needed
+- The user's intent for specific claims is ambiguous
+
+Remember: Your goal is to help ensure accuracy and credibility while supporting the author in creating trustworthy content. Be thorough, fair, and constructive. Your work directly impacts the author's credibility and the reader's trust, so maintain the highest standards while being a helpful collaborator.

package/packs/essentials-pack/grimoire.json

@@ -0,0 +1,12 @@
+{
+  "name": "essentials-pack",
+  "version": "1.0.0",
+  "agents": [
+    {
+      "name": "grimoire:fact-checker",
+      "path": "agents/gr.fact-checker.md",
+      "description": "Use this agent when you need to verify the accuracy of written content before publishing or sharing. Invoke when: (1) Drafting is complete and content contains factual claims like statistics, dates, technical specifications, or historical references; (2) Content is ready for final review before publishing; (3) Accuracy is critical for public-facing or decision-making materials."
+    }
+  ],
+  "skills": []
+}

package/packs/meta-pack/grimoire.json

@@ -0,0 +1,72 @@
+{
+  "name": "meta-pack",
+  "version": "1.0.0",
+  "agents": [],
+  "skills": [
+    {
+      "name": "grimoire:context-file-guide",
+      "path": "skills/gr.context-file-guide",
+      "description": "Best practices for writing CLAUDE.md project context files. Use when creating, reviewing, or improving CLAUDE.md files for Claude Code projects.",
+      "triggers": {
+        "keywords": [],
+        "file_extensions": [],
+        "patterns": [
+          "create.*claude\\.md",
+          "write.*claude\\.md",
+          "review.*claude\\.md",
+          "improve.*claude\\.md",
+          "update.*claude\\.md"
+        ],
+        "file_paths": [
+          "**/CLAUDE.md"
+        ]
+      }
+    },
+    {
+      "name": "grimoire:readme-guide",
+      "path": "skills/gr.readme-guide",
+      "description": "Create and review README files following industry best practices. Use for writing new READMEs, improving existing ones, checking README quality, or adding badges.",
+      "triggers": {
+        "keywords": [
+          "readme"
+        ],
+        "file_extensions": [],
+        "patterns": [
+          "create.*readme",
+          "write.*readme",
+          "review.*readme",
+          "improve.*readme",
+          "update.*readme",
+          "repository.*description"
+        ],
+        "file_paths": [
+          "**/README.md",
+          "**/README"
+        ]
+      }
+    },
+    {
+      "name": "grimoire:skill-developer",
+      "path": "skills/gr.skill-developer",
+      "description": "Create and maintain custom skills for Claude Code following official Anthropic patterns. Use when creating new skills, updating existing skills, or organizing skill documentation.",
+      "triggers": {
+        "keywords": [
+          "skill-developer",
+          "skill-authoring"
+        ],
+        "file_extensions": [],
+        "patterns": [
+          "create.*skill",
+          "new.*skill",
+          "build.*skill",
+          "write.*skill",
+          "update.*skill",
+          "improve.*skill"
+        ],
+        "file_paths": [
+          "**/.claude/skills/**/SKILL.md"
+        ]
+      }
+    }
+  ]
+}