@grimoire-cc/cli 0.6.3 → 0.7.1

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"
+        ]
+      }
+    }
+  ]
+}

package/packs/meta-pack/skills/gr.context-file-guide/SKILL.md

@@ -0,0 +1,201 @@
+---
+name: grimoire: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."
+---
+
+# CLAUDE.md Best Practices Guide
+
+This skill provides best practices for writing effective CLAUDE.md files that give Claude Code the right context about your project.
+
+## What is CLAUDE.md?
+
+CLAUDE.md is a special file that Claude Code automatically reads when starting a conversation. It provides project-specific context, conventions, and instructions that help Claude understand your codebase and work more effectively.
+
+## File Locations
+
+Claude Code reads CLAUDE.md files from multiple locations (in order of precedence):
+
+1. **Project root**: `./CLAUDE.md` - Primary project context
+2. **Parent directories**: `../CLAUDE.md` - Shared context for monorepos
+3. **Home directory**: `~/.claude/CLAUDE.md` - Personal global preferences
+
+All found files are concatenated, so use each level appropriately.
+
+## Recommended Structure
+
+Use this battle-tested structure:
+
+```markdown
+# Project: {Project Name}
+
+## Tech Stack
+- Backend: {frameworks, runtime, database}
+- Frontend: {frameworks, language, styling}
+- Testing: {test frameworks}
+
+## Commands
+- {command}: {description}
+- {command}: {description}
+- {command}: {description}
+
+## Code Conventions
+- {convention 1}
+- {convention 2}
+- {convention 3}
+
+## Architecture
+- {pattern}: {brief description}
+- {routes/structure}: {pattern}
+- See {doc reference} for details
+
+## Workflow
+- {pre-commit steps}
+- {development approach}
+- {commit guidelines}
+```
+
+## Example
+
+```markdown
+# Project: E-commerce API
+
+## Tech Stack
+- Backend: .NET 8, Entity Framework Core 8, PostgreSQL
+- Frontend: Vue 3 Composition API, TypeScript, Tailwind CSS
+- Testing: xUnit, Playwright, Vue Test Utils
+
+## Commands
+- dotnet build: Build backend
+- dotnet test --filter "Category=Unit": Run unit tests
+- pnpm dev: Start frontend dev server
+- pnpm test:unit: Run Vue tests
+
+## Code Conventions
+- Use records for DTOs and value objects
+- Prefer async/await with ConfigureAwait(false)
+- Use Composition API with <script setup> in Vue
+- Name test files *.spec.ts (frontend) or *Tests.cs (backend)
+
+## Architecture
+- Clean Architecture: Adapters → Application → Domain
+- API routes: /api/v1/{resource}
+- See docs/architecture.md for detailed diagrams
+
+## Workflow
+- Run dotnet format and pnpm lint before committing
+- Write tests before implementation (TDD)
+- One logical change per commit
+```
+
+## Section Guidelines
+
+### Tech Stack
+- List primary technologies with versions
+- Group by concern (backend, frontend, testing, infrastructure)
+- Include database, ORM, and major libraries
+
+### Commands
+- Use format: `command: description`
+- Include build, test, lint, and dev commands
+- Add flags for common variations (e.g., unit vs integration tests)
+
+### Code Conventions
+- Focus on project-specific patterns
+- Include naming conventions for files and code
+- Note any non-obvious practices
+
+### Architecture
+- Name the architectural pattern
+- Describe layer organization
+- Reference detailed documentation if it exists
+
+### Workflow
+- Pre-commit checklist items
+- Development methodology (TDD, etc.)
+- Commit message guidelines
+
+## Best Practices
+
+### Keep It Concise
+- **Maximum 100 lines** - anything longer should use imports
+- Aim for 30-60 lines for most projects
+- Focus on frequently-needed information
+- Update as project evolves
+
+### Be Specific and Actionable
+```markdown
+# Good
+- dotnet test --filter "Category=Unit": Run unit tests
+
+# Bad
+- Tests are important
+```
+
+### Include Context That Saves Time
+- Explain non-obvious architectural decisions
+- Document project-specific terminology
+- Note any unusual patterns or exceptions
+
+## Advanced Context Management
+
+Use imports for detailed context without bloating CLAUDE.md. The `@docs/file.md` syntax pulls in additional files when Claude needs them.
+
+### Memory Bank Structure
+
+For complex projects, create a docs folder with specialized context files:
+
+```
+docs/
+├── architecture.md      # System design decisions
+├── api-conventions.md   # REST patterns, error handling
+├── testing-guide.md     # Test patterns and fixtures
+└── plan.md              # Current implementation checklist
+```
+
+### Using Imports
+
+Reference these files in CLAUDE.md with the `@` syntax:
+
+```markdown
+## Architecture
+- Clean Architecture: Adapters → Application → Domain
+- @docs/architecture.md for detailed diagrams
+
+## API Design
+- @docs/api-conventions.md
+```
+
+This keeps the main CLAUDE.md lean while providing deep context on demand.
+
+## Validation
+
+Validate your CLAUDE.md meets the 100-line limit:
+
+```bash
+./scripts/validate-context-file.sh CLAUDE.md
+```
+
+The script checks line count and suggests using imports if the file is too long.
+
+## Anti-Patterns to Avoid
+
+1. **Too verbose**: Don't include entire documentation
+2. **Too generic**: Avoid boilerplate that applies to any project
+3. **Outdated**: Remove references to deleted files/features
+4. **Instruction overload**: Don't micromanage every decision
+5. **Security information**: Never include secrets or credentials
+
+## When to Update CLAUDE.md
+
+- Adding new major dependencies
+- Changing build or test commands
+- Introducing new architectural patterns
+- After significant refactoring
+- When onboarding reveals missing context
+
+## Limitations
+
+- CLAUDE.md is read at conversation start (not refreshed mid-conversation)
+- Very large files may impact context window efficiency
+- Cannot include executable code or scripts
+- Content is shared with Claude - avoid sensitive information

package/packs/meta-pack/skills/gr.context-file-guide/scripts/validate-context-file.sh

@@ -0,0 +1,29 @@
+#!/bin/bash
+# Validates CLAUDE.md files meet size requirements.
+
+MAX_LINES=100
+
+validate() {
+    local file_path="$1"
+
+    if [ ! -f "$file_path" ]; then
+        echo "Error: File not found: $file_path"
+        return 1
+    fi
+
+    local line_count
+    line_count=$(wc -l < "$file_path" | tr -d ' ')
+
+    if [ "$line_count" -gt "$MAX_LINES" ]; then
+        echo -e "\033[0;31m✗ $file_path has $line_count lines (max: $MAX_LINES)\033[0m"
+        echo "  Consider moving detailed content to docs/ and using @imports"
+        return 1
+    fi
+
+    echo -e "\033[0;32m✓ $file_path has $line_count lines (max: $MAX_LINES)\033[0m"
+    return 0
+}
+
+file_path="${1:-CLAUDE.md}"
+validate "$file_path"
+exit $?