@codihaus/claude-skills 1.0.0

package/skills/utils/docs-graph/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: utils/docs-graph
+description: View and query the documentation knowledge graph
+version: 1.2.0
+---
+
+# /utils/docs-graph - Documentation Graph Viewer
+
+> **Skill Awareness**: See `skills/_registry.md` for all available skills.
+> - **Auto-updated**: By Claude Code hook on Write/Edit to plans/
+> - **Called by**: `/dev-specs`, `/debrief`, `/dev-arch` for relationships
+> - **Note**: Utility skill, typically called by other skills
+
+View and query relationships between planning documents.
+
+## When to Use
+
+- See overview of all plans and their relationships
+- Find related documents before making changes
+- Check impact of changes (what links to this?)
+- Verify graph is up-to-date
+
+## Usage
+
+```
+/utils/docs-graph                    # Show graph summary
+/utils/docs-graph auth               # Show nodes related to "auth"
+/utils/docs-graph --regenerate       # Force regenerate graph
+/utils/docs-graph --check            # Verify all links resolve
+```
+
+## How It Works
+
+The graph is automatically updated via Claude Code hooks whenever files in `plans/` are created or modified. This skill provides on-demand viewing and querying.
+
+### Automatic Updates
+
+PostToolUse hook triggers on Write/Edit to plans/:
+1. Hook detects file path contains `plans/`
+2. Runs `python3 scripts/graph.py --check-path <path>`
+3. Graph files updated before next Claude action
+
+### Graph Files
+
+```
+plans/
+├── docs-graph.json    # Machine-readable graph data
+└── docs-graph.md      # Mermaid visualization
+```
+
+## Workflow
+
+### Phase 1: Load Graph
+
+1. Check if `plans/docs-graph.json` exists
+2. If not, run `python3 scripts/graph.py` to generate
+3. Read graph data
+
+### Phase 2: Display or Query
+
+**Summary mode (default):**
+- Show node count by type
+- Show edge count
+- Display mermaid diagram from docs-graph.md
+- List any errors
+
+**Query mode (with argument):**
+- Filter nodes matching query
+- Show incoming links (what references this)
+- Show outgoing links (what this references)
+
+**Regenerate mode (--regenerate):**
+- Force full rescan of plans/
+- Update docs-graph.json and docs-graph.md
+- Show diff if changes detected
+
+**Check mode (--check):**
+- Verify all wikilinks resolve to existing nodes
+- Report broken links
+- Suggest fixes
+
+### Phase 3: Output
+
+Display results with:
+- Mermaid diagram (if summary)
+- Table of matching nodes (if query)
+- Broken link report (if check)
+
+## Wikilink Convention
+
+Documents use `[[wikilinks]]` to reference each other:
+
+```markdown
+# UC-AUTH-001: Login
+
+> **Feature**: [[feature-auth]]
+> **Related**: [[uc-auth-002]], [[uc-auth-003]]
+> **Spec**: [[spec-auth-001]]
+```
+
+**Link ID format:**
+- Use cases: `[[uc-auth-001]]` (lowercase, no slug)
+- Features: `[[feature-auth]]`
+- Specs: `[[spec-auth-001]]`
+- Change requests: `[[cr-001]]`
+
+## Node Types
+
+| Type | Source | Shape (Mermaid) |
+|------|--------|-----------------|
+| brd | `brd/README.md` | Stadium `[[]]` |
+| use-case | `brd/use-cases/**/*.md` | Rectangle `[]` |
+| change-request | `brd/changes/*.md` | Hexagon `{{}}` |
+| feature | `features/*/README.md` | Pill `([])` |
+| spec | `features/*/specs/**/*.md` | Parallelogram `[//]` |
+| scout | `**/scout.md` | Cylinder `[()]` |
+
+## Example Output
+
+### Summary
+
+```
+Documentation Graph Summary
+===========================
+Nodes: 12 | Edges: 18
+
+By Type:
+  use-case: 5
+  feature: 2
+  spec: 4
+  brd: 1
+
+View full graph: plans/docs-graph.md
+```
+
+### Query: `/utils/docs-graph auth`
+
+```
+Nodes matching "auth": 4
+
+uc-auth-001 (use-case) - Login
+  ← feature-auth, spec-auth-001
+  → feature-auth
+
+uc-auth-002 (use-case) - Signup
+  ← feature-auth
+  → uc-auth-001, feature-auth
+
+feature-auth (feature) - Authentication
+  ← uc-auth-001, uc-auth-002, uc-auth-003
+  → (none)
+
+spec-auth-001 (spec) - Login Spec
+  ← (none)
+  → uc-auth-001
+```
+
+### Check: `/utils/docs-graph --check`
+
+```
+Link Check Results
+==================
+✓ 16 valid links
+✗ 2 broken links
+
+Broken:
+  plans/brd/use-cases/auth/UC-AUTH-001-login.md:5
+    [[uc-auth-004]] - node not found
+
+  plans/features/auth/specs/UC-AUTH-001/README.md:12
+    [[feature-billing]] - node not found
+
+Suggestions:
+  - uc-auth-004: Did you mean uc-auth-003?
+  - feature-billing: Create plans/features/billing/README.md
+```
+
+## Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| `Bash` | Run graph.py script |
+| `Read` | Read docs-graph.json, docs-graph.md |
+| `Glob` | Find plan files |
+
+## Integration
+
+| Skill | Relationship |
+|-------|--------------|
+| `/debrief` | Creates use cases with wikilinks |
+| `/dev-specs` | Creates specs linking to use cases |
+| `/dev-scout` | Creates scout.md for features |
+
+## Troubleshooting
+
+**Graph not updating:**
+- Check hook is in `.claude/settings.local.json`
+- Verify `jq` is installed
+- Run `/utils/docs-graph --regenerate` to force update
+
+**Broken links:**
+- Run `/utils/docs-graph --check` to find issues
+- Update wikilinks to match node IDs
+- Node IDs are lowercase, no slug (e.g., `uc-auth-001` not `UC-AUTH-001-login`)

package/skills/utils/gemini/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: utils/gemini
+description: Large context processing using Gemini Flash for codebase scanning and summarization
+version: 1.0.0
+---
+
+# /utils/gemini - Large Context Processing
+
+> **Skill Awareness**: See `skills/_registry.md` for all available skills.
+> - **Called by**: `/dev-scout` for large codebases
+> - **Purpose**: Use Gemini Flash (1M context) for tasks Claude's context can't fit
+> - **Note**: Utility skill, typically called by other skills
+
+Use Gemini Flash for large context tasks like scanning entire codebases.
+
+## Why Gemini?
+
+| Model | Context | Best For | Cost |
+|-------|---------|----------|------|
+| Claude | 200K | Reasoning, writing, precision | Higher |
+| Gemini Flash | 1M+ | Scanning, summarization, bulk reading | Lower |
+
+**Use case**: Codebase has 500+ files. Claude can't fit it all. Gemini scans and summarizes, Claude uses the summary.
+
+## Setup
+
+### Prerequisites
+
+1. **Google AI API Key**
+   - Go to: https://aistudio.google.com/app/apikey
+   - Create an API key
+   - Copy the key
+
+2. **Set Environment Variable**
+   ```bash
+   # Add to ~/.bashrc or ~/.zshrc
+   export GEMINI_API_KEY="your-api-key-here"
+
+   # Or create .env in project root
+   echo "GEMINI_API_KEY=your-api-key-here" >> .env
+   ```
+
+3. **Install Python Dependencies**
+   ```bash
+   pip install google-generativeai
+   ```
+
+### Quick Setup Script
+
+Run from this skill's folder:
+
+```bash
+# Interactive setup
+./scripts/setup.sh
+```
+
+This will:
+- Check for existing API key
+- Guide you to get one if missing
+- Test the connection
+- Verify everything works
+
+## Usage
+
+### Direct Script Usage
+
+```bash
+# Scan entire codebase
+python scripts/gemini-scan.py --path /path/to/project --output summary.md
+
+# Scan specific directory
+python scripts/gemini-scan.py --path /path/to/project/src --output src-summary.md
+
+# Custom prompt
+python scripts/gemini-scan.py --path /path/to/project --prompt "List all API endpoints" --output apis.md
+```
+
+### From Claude Code
+
+When `/dev-scout` detects a large codebase:
+
+```
+1. Scout detects 500+ files
+   → "Large codebase. Using Gemini for initial scan."
+
+2. Run Gemini scan
+   → Bash: python skills/utils/gemini/scripts/gemini-scan.py \
+       --path . \
+       --output plans/scout/gemini-summary.md
+
+3. Read Gemini output
+   → Read: plans/scout/gemini-summary.md
+
+4. Claude refines and creates final scout.md
+   → Uses Gemini summary as input
+   → Adds analysis, recommendations
+   → Creates structured scout output
+```
+
+## Script: gemini-scan.py
+
+Located at: `scripts/gemini-scan.py`
+
+### Features
+
+- Scans directory recursively
+- Respects .gitignore
+- Outputs structured markdown
+- Configurable file types
+- Progress indicator
+
+### Arguments
+
+| Arg | Description | Default |
+|-----|-------------|---------|
+| `--path` | Directory to scan | Current dir |
+| `--output` | Output file path | stdout |
+| `--prompt` | Custom prompt | Default scan prompt |
+| `--extensions` | File types to include | Common code files |
+| `--max-files` | Max files to process | 1000 |
+| `--ignore` | Additional ignore patterns | None |
+
+### Default Scan Prompt
+
+```
+Analyze this codebase and provide:
+
+1. **Project Overview**
+   - What does this project do?
+   - Main technologies used
+   - Project structure
+
+2. **File Organization**
+   - Key directories and their purposes
+   - Entry points
+   - Configuration files
+
+3. **Patterns Detected**
+   - Architecture patterns (MVC, component-based, etc.)
+   - Coding conventions
+   - Common utilities
+
+4. **Key Files**
+   - Most important files (entry points, configs)
+   - Core business logic locations
+   - API/route definitions
+
+5. **Dependencies**
+   - External packages
+   - Internal module dependencies
+
+Be concise but comprehensive. Use markdown formatting.
+```
+
+## Output Format
+
+Gemini outputs structured markdown:
+
+```markdown
+# Codebase Summary
+
+## Project Overview
+{description}
+
+## Technologies
+- Framework: Next.js 14
+- Database: PostgreSQL with Prisma
+- Auth: NextAuth.js
+- Styling: Tailwind CSS
+
+## Structure
+```
+src/
+├── app/          # Next.js App Router pages
+├── components/   # React components
+├── lib/          # Utilities and helpers
+└── prisma/       # Database schema
+```
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| src/app/layout.tsx | Root layout |
+| src/lib/auth.ts | Authentication logic |
+| prisma/schema.prisma | Database schema |
+
+## Patterns
+- Component-based architecture
+- Server Components with Client islands
+- API routes for backend logic
+
+## Recommendations for Scout
+- Focus on src/app/ for routes
+- Check src/components/ui/ for base components
+- Review prisma/schema.prisma for data model
+```
+
+## Integration with /dev-scout
+
+In `dev-scout/SKILL.md`, add:
+
+```markdown
+### Step 0.5: Large Codebase Check
+
+After counting files:
+
+1. If 500+ files → Use Gemini
+   ```bash
+   python skills/utils/gemini/scripts/gemini-scan.py \
+     --path . \
+     --output plans/scout/gemini-summary.md
+   ```
+
+2. Read Gemini summary
+   → Use as foundation for scout
+
+3. Deep dive key areas only
+   → Gemini identified important files
+   → Claude focuses on those
+```
+
+## Troubleshooting
+
+### API Key Not Found
+
+```
+Error: GEMINI_API_KEY not set
+```
+
+**Fix:**
+```bash
+export GEMINI_API_KEY="your-key"
+# Or add to .env file
+```
+
+### Rate Limit
+
+```
+Error: Rate limit exceeded
+```
+
+**Fix:**
+- Wait a few seconds and retry
+- Free tier has limits, consider paid tier for heavy use
+
+### Context Too Large
+
+```
+Error: Input too large for model
+```
+
+**Fix:**
+- Use `--max-files` to limit files
+- Use `--ignore` to skip directories
+- Split scan into multiple runs
+
+## Cost Considerations
+
+Gemini Flash pricing (as of 2024):
+- Input: ~$0.075 per 1M tokens
+- Output: ~$0.30 per 1M tokens
+
+**Typical codebase scan (500 files):**
+- ~100K tokens input
+- ~5K tokens output
+- Cost: ~$0.01-0.02 per scan
+
+Very affordable for occasional use.
+
+## Security Notes
+
+- API key should be in environment, not code
+- Don't commit .env files
+- Add to .gitignore: `.env`, `*.env.local`
+- Gemini processes code - consider sensitivity
+
+## Future: MCP Server
+
+If needed, this can be upgraded to an MCP server for tighter integration:
+
+```
+skills/utils/gemini/
+├── SKILL.md
+├── scripts/
+│   ├── setup.sh
+│   └── gemini-scan.py
+└── mcp-server/          # Future
+    ├── index.ts
+    └── package.json
+```
+
+For now, the Python script approach is simpler and works well.