@codihaus/claude-skills 1.0.0

package/skills/dev-scout/SKILL.md

@@ -0,0 +1,723 @@
+---
+name: dev-scout
+description: Explore and document existing codebases at various depths
+version: 2.7.0
+---
+
+# /dev-scout - Codebase Explorer
+
+> **Skill Awareness**: See `skills/_registry.md` for all available skills.
+> - **Before**: Use `/debrief` if requirements unclear
+> - **After**: Use `/dev-specs` for implementation plans
+> - **Utils**: `/utils/diagram` for architecture visualization
+
+Explore and document codebases. Works at project level or per feature.
+
+## When to Use
+
+- Understand existing codebase before adding features
+- Document current state for team
+- Analyze specific area before implementation
+- Update scout after implementation
+
+## Usage
+
+```
+/dev-scout                      # Project-level, medium mode
+/dev-scout deep                 # Project-level, deep mode
+/dev-scout auth                 # Feature-level (plans/features/auth/)
+/dev-scout deep billing         # Feature-level, deep mode
+/dev-scout /path/to/code        # Custom path
+```
+
+## Output Structure
+
+Outputs to unified `plans/` structure:
+
+```
+plans/
+├── scout/                       # Project-level (/dev-scout)
+│   ├── README.md                # Current summary
+│   ├── structure.md             # File tree, tech stack
+│   ├── features.md              # Existing features
+│   └── history/                 # Previous snapshots
+│       └── {date}.md
+│
+└── features/
+    └── {feature}/
+        ├── scout.md             # Feature-level (/dev-scout {feature})
+        └── ...
+```
+
+## Modes
+
+| Mode | What It Does | When to Use |
+|------|--------------|-------------|
+| **medium** (default) | Structure, files, UI inventory | Quick overview |
+| **deep** | + API, models, logic, patterns | Before implementation |
+
+## Exploration Strategy
+
+### Large Codebase Strategy (500+ files)
+
+For very large codebases, use `/utils/gemini` for initial scan:
+
+```
+1. Count files
+   → find . -type f | wc -l
+   → If 500+, use Gemini
+
+2. Run Gemini scan
+   → python skills/utils/gemini/scripts/gemini-scan.py \
+       --path . \
+       --output plans/scout/gemini-summary.md
+
+3. Read Gemini output
+   → Gemini provides: structure, patterns, key files
+
+4. Claude refines
+   → Deep dive on key files Gemini identified
+   → Add analysis and recommendations
+   → Create final scout.md
+```
+
+**Why Gemini for large codebases?**
+- Gemini Flash: 1M token context (can fit entire codebase)
+- Claude: 200K context (may not fit all files)
+- Gemini scans cheap/fast, Claude analyzes precisely
+
+### Parallel Directory Search
+
+For medium codebases (100-500 files), use parallel exploration:
+
+```
+Divide codebase into logical sections:
+- Agent 1: src/app/, src/pages/ (routes & pages)
+- Agent 2: src/components/, src/ui/ (UI components)
+- Agent 3: src/lib/, src/utils/, src/services/ (utilities)
+- Agent 4: src/api/, prisma/, db/ (backend)
+```
+
+**When to use which strategy:**
+
+| Files | Strategy |
+|-------|----------|
+| <50 | Sequential (simple) |
+| 50-100 | Sequential or parallel |
+| 100-500 | Parallel agents |
+| 500+ | Gemini first, then focused Claude analysis |
+
+**When to stay sequential:**
+- Small codebases (<50 files)
+- Feature-level scout (focused area)
+- Simple structure
+
+### Priority Directories
+
+Search high-value directories first based on task:
+
+| Task | Priority Directories |
+|------|---------------------|
+| General overview | README, package.json, src/app/ |
+| Feature analysis | Feature folder, related components, API routes |
+| API understanding | api/, routes/, controllers/, services/ |
+| Data model | prisma/, models/, schema/, types/ |
+| UI inventory | components/, ui/, views/, pages/ |
+
+### Resilience
+
+Handle exploration failures gracefully:
+
+- **If a directory doesn't exist**: Skip, note in coverage
+- **If file read fails**: Continue, mark as "unreadable"
+- **If pattern returns nothing**: Try alternative patterns
+- **If timeout on large dir**: Summarize what was found, note gap
+
+Track coverage in output:
+```markdown
+## Coverage
+| Area | Status | Notes |
+|------|--------|-------|
+| src/app/ | ✓ Complete | 45 files |
+| src/lib/ | ✓ Complete | 12 files |
+| src/legacy/ | ⚠ Partial | Timeout after 50 files |
+| docs/ | ✗ Skipped | Directory not found |
+```
+
+## Workflow
+
+### Step 0: Check Documentation Graph
+
+Before exploring code, check existing documentation context:
+
+```
+1. Read plans/docs-graph.json (if exists)
+2. Find related nodes:
+   - For feature scout: Find use cases, existing specs for that feature
+   - For project scout: Get overview of documented features
+3. Use relationships to focus exploration
+```
+
+**How docs-graph helps:**
+
+| Scout Type | Graph Provides |
+|------------|----------------|
+| Project | List of documented features, existing UCs to validate |
+| Feature | Related use cases, specs, dependencies |
+
+**Example: `/dev-scout auth`**
+```
+From docs-graph.json:
+- uc-auth-001 (Login) → focus on login flow
+- uc-auth-002 (Signup) → focus on registration
+- [[feature-billing]] referenced → check billing integration
+```
+
+This context helps:
+- Focus exploration on relevant areas
+- Validate discovered features against documented UCs
+- Find integration points via graph edges
+
+### Step 0.5: Initial Assessment
+
+Before diving in, run quick assessment:
+
+```bash
+# Option 1: Use scout-analyze script (recommended)
+./scripts/scout-analyze.sh . --check
+
+# If tools missing, ask user:
+# "Missing tools: tree, scc. Install for better analysis? (--install)"
+
+# Run full analysis
+./scripts/scout-analyze.sh .
+```
+
+```bash
+# Option 2: Manual (if script not available)
+find . -type f | wc -l
+ls -la && ls -d */
+```
+
+**Determine strategy based on file count:**
+| File Count | Strategy |
+|------------|----------|
+| <50 | Sequential, thorough |
+| 50-200 | Sequential, prioritized |
+| 200+ | Parallel exploration |
+
+**Check for existing docs:**
+- README.md → Project description
+- CLAUDE.md → AI instructions, patterns
+- docs/ → Additional documentation
+- package.json / requirements.txt → Dependencies
+
+### Step 1: Determine Scope
+
+**Project-level** (`/dev-scout`):
+- Scans entire codebase
+- Outputs to `plans/scout/`
+- Creates history snapshot if scout exists
+
+**Feature-level** (`/dev-scout auth`):
+- Scans specific area only
+- Outputs to `plans/features/auth/scout.md`
+- Links to BRD use cases
+
+### Step 2: Check for Existing Scout
+
+**If `plans/scout/` exists:**
+1. Move current README.md to `history/{date}.md`
+2. Create fresh analysis
+3. Note what changed since last scout
+
+**If first scout:**
+1. Create `plans/scout/` folder
+2. Generate initial analysis
+
+### Step 3: Medium Mode Analysis
+
+#### 3.1 Documentation Check
+
+```
+Patterns:
+- README.md, CLAUDE.md
+- docs/**/*.md
+- package.json, requirements.txt
+```
+
+Extract:
+- App description
+- Tech stack
+- Setup instructions
+
+#### 3.2 File Structure Scan
+
+```
+Get folder tree (depth 3):
+- /src, /app, /pages
+- /components, /views
+- /lib, /utils
+- /api, /server
+```
+
+#### 3.3 Frontend File Inventory
+
+See `references/file-patterns.md`:
+
+```
+Include: **/*.vue, **/*.tsx, **/*.jsx
+Exclude: node_modules/**, dist/**
+```
+
+Group by:
+- Pages/Routes → Screens
+- Components → UI inventory
+- Views → Layouts
+
+#### 3.4 Feature Inference
+
+See `references/feature-patterns.md`:
+
+| Pattern | Feature |
+|---------|---------|
+| `auth/`, `login.*` | Authentication |
+| `payment/`, `checkout/` | Payments |
+| `dashboard/` | Dashboard |
+
+#### 3.5 Tech Stack Detection
+
+See `references/tech-detection.md`:
+
+| File | Tech |
+|------|------|
+| `next.config.*` | Next.js |
+| `prisma/schema.prisma` | Prisma |
+
+### Step 4: Deep Mode Analysis (if requested)
+
+Additional to medium mode:
+
+#### 4.1 API Analysis
+
+```
+Patterns:
+- **/api/**/*.ts
+- **/routes/**/*.ts
+```
+
+Document:
+- Endpoints (method, path)
+- Authentication requirements
+- Patterns used
+
+#### 4.2 Data Model Analysis
+
+```
+Patterns:
+- prisma/schema.prisma
+- **/models/**/*.ts
+```
+
+Document:
+- Entities
+- Relationships
+- Key fields
+
+#### 4.3 Code Pattern Identification
+
+Read representative files for:
+- State management
+- API client patterns
+- Authentication flow
+- Error handling
+
+#### 4.4 Project Conventions Detection
+
+**Code Style** (read from config or infer from code):
+
+```
+Check for configs:
+- .eslintrc.* → Linting rules
+- .prettierrc.* → Formatting
+- tsconfig.json → TypeScript strictness
+- .editorconfig → Tabs/spaces, line endings
+
+Infer from code (sample 3-5 files):
+- Naming: camelCase, PascalCase, snake_case
+- File naming: Component.tsx vs component.tsx
+- Import style: absolute (@/) vs relative (./)
+- Quote style: single vs double
+- Semicolons: yes/no
+```
+
+**Git Conventions** (read from history):
+
+```bash
+# Check commit style
+git log --oneline -20
+
+Detect patterns:
+- Conventional commits? (feat:, fix:, chore:)
+- Emoji commits? (✨, 🐛, 🔧)
+- Ticket refs? (JIRA-123, #123)
+- Simple messages? (no pattern)
+
+# Check branch naming
+git branch -a | head -20
+
+Detect patterns:
+- feature/*, bugfix/*, hotfix/*
+- feat/*, fix/*
+- username/feature-name
+- No pattern
+```
+
+**Project Conventions**:
+
+```
+Check for:
+- CLAUDE.md → AI instructions (HIGH VALUE)
+- CONTRIBUTING.md → Team guidelines
+- .github/PULL_REQUEST_TEMPLATE.md → PR format
+- .github/ISSUE_TEMPLATE/* → Issue format
+
+Document:
+- How to name files
+- How to structure components
+- How to write tests
+- PR/commit requirements
+```
+
+### Step 5: Generate Output
+
+#### Project-Level Output
+
+**plans/scout/README.md:**
+```markdown
+# Codebase Analysis
+
+> **Last Updated**: {date}
+> **Mode**: Medium | Deep
+> **Previous**: [→ history/]
+
+## Summary
+{Brief description of the app}
+
+## Tech Stack
+| Layer | Technology |
+|-------|------------|
+| Frontend | {framework} |
+| Backend | {framework} |
+| Database | {db} |
+| Auth | {method} |
+
+## Conventions (deep mode)
+
+### Code Style
+| Aspect | Convention |
+|--------|------------|
+| Naming | camelCase (variables), PascalCase (components) |
+| File naming | kebab-case.tsx |
+| Imports | Absolute (@/lib/*) |
+| Quotes | Single |
+| Semicolons | No |
+
+### Git Conventions
+| Aspect | Convention |
+|--------|------------|
+| Commits | Conventional (feat:, fix:, chore:) |
+| Branches | feature/*, bugfix/* |
+| PR template | Yes (.github/PULL_REQUEST_TEMPLATE.md) |
+
+### Project Rules
+{From CLAUDE.md or CONTRIBUTING.md}
+- {Rule 1}
+- {Rule 2}
+
+## Structure Overview
+```
+src/
+├── app/         # {description}
+├── components/  # {description}
+└── lib/         # {description}
+```
+
+## Existing Features
+| Feature | Evidence | Confidence |
+|---------|----------|------------|
+| Auth | `app/auth/`, `LoginForm.tsx` | High |
+| Dashboard | `app/dashboard/` | High |
+
+## Pages/Routes
+| Path | File | Description |
+|------|------|-------------|
+| / | `app/page.tsx` | Home |
+| /login | `app/login/page.tsx` | Login |
+
+## Components ({count})
+{List key components}
+
+## API Endpoints (deep mode)
+| Method | Path | Handler |
+|--------|------|---------|
+| GET | /api/users | users.list |
+
+## Integration Points
+{How to connect new features}
+
+## Coverage
+| Area | Status | Files | Notes |
+|------|--------|-------|-------|
+| src/app/ | ✓ | 45 | Routes, pages |
+| src/components/ | ✓ | 32 | UI components |
+| src/lib/ | ✓ | 8 | Utilities |
+
+## Gaps / Unresolved
+- {Any areas not fully explored}
+- {Questions for follow-up}
+
+## Notes
+{Observations, potential issues}
+```
+
+**plans/scout/structure.md:**
+```markdown
+# File Structure
+
+## Directory Tree
+```
+{full tree output}
+```
+
+## Key Directories
+| Directory | Purpose | File Count |
+|-----------|---------|------------|
+
+## Config Files
+| File | Purpose |
+|------|---------|
+```
+
+**plans/scout/features.md:**
+```markdown
+# Existing Features
+
+## Feature Inventory
+
+### {Feature 1}
+- **Status**: Complete | Partial | Planned
+- **Files**: {list}
+- **Depends on**: {other features}
+
+### {Feature 2}
+...
+
+## Feature Relationships
+```mermaid
+graph LR
+    Auth --> User
+    User --> Dashboard
+    Billing --> User
+```
+```
+
+#### Feature-Level Output
+
+**plans/features/{feature}/scout.md:**
+```markdown
+# {Feature} - Scout Analysis
+
+> **Date**: {date}
+> **Mode**: Medium | Deep
+> **Feature**: [[feature-{feature}]]
+> **Related UCs**: [[uc-{group}-001]], [[uc-{group}-002]]
+
+## Summary
+{What this feature does currently}
+
+## Files
+| File | Purpose |
+|------|---------|
+| {path} | {description} |
+
+## Current Implementation
+{How it works}
+
+## API Endpoints (if applicable)
+| Method | Path | Description |
+|--------|------|-------------|
+
+## Data Models (if applicable)
+| Model | Fields | Relations |
+|-------|--------|-----------|
+
+## Integration Points
+{How to extend or modify}
+
+## For Implementation
+- Entry point: {file}
+- Key patterns: {patterns used}
+- Dependencies: {what to be aware of}
+```
+
+### Step 6: Update History (project-level)
+
+If updating existing scout:
+
+1. Move current to `history/{date}.md`
+2. In new README.md, add:
+
+```markdown
+## Changes Since Last Scout
+- Added: {new files/features}
+- Modified: {changed areas}
+- Removed: {deleted items}
+```
+
+## Tools Used
+
+| Tool | Purpose |
+|------|---------|
+| `Task` | Parallel exploration (Explore agents) |
+| `Glob` | Find files by pattern |
+| `Grep` | Search code patterns |
+| `Read` | Read file contents |
+| `Bash` | Directory listing, file counts |
+| `Write` | Output files |
+| `Playwright` | Capture UI screenshots |
+
+### Playwright for Visual Documentation
+
+When scouting a web app, capture screenshots of key UI:
+
+```
+1. Start the dev server (if not running)
+   → Bash: npm run dev
+
+2. Navigate to app
+   → mcp__playwright__browser_navigate({ url: "http://localhost:3000" })
+
+3. Take screenshots of key pages
+   → mcp__playwright__browser_take_screenshot({
+       filename: "plans/scout/screenshots/home.png"
+     })
+
+4. Capture different states
+   → Login page
+   → Dashboard (if accessible)
+   → Key feature pages
+```
+
+**When to capture UI:**
+- Initial project scout (what does app look like?)
+- Before major UI changes (for comparison)
+- Feature scout (existing UI in that area)
+
+**Output:**
+```
+plans/scout/screenshots/
+├── home.png
+├── login.png
+├── dashboard.png
+└── feature-{name}.png
+```
+
+Include in scout.md:
+```markdown
+## Current UI
+
+### Home Page
+![Home](./screenshots/home.png)
+
+### Dashboard
+![Dashboard](./screenshots/dashboard.png)
+```
+
+### Parallel Exploration Example
+
+For large codebases (200+ files), spawn parallel agents:
+
+```
+Task 1 (Explore): "Search src/app/ and src/pages/ for route definitions, page components. List files with brief purpose."
+
+Task 2 (Explore): "Search src/components/ for UI components. Group by type (forms, buttons, layouts, etc.)."
+
+Task 3 (Explore): "Search src/lib/, src/utils/, src/services/ for utilities. Identify patterns, shared logic."
+
+Task 4 (Explore): "Search api/, prisma/, db/ for backend code. Document endpoints, models."
+```
+
+Synthesize results from all agents into unified scout output.
+
+## Tips
+
+**General:**
+- Run project-level scout first for overview
+- Use feature-level before `/dev-specs`
+- Update scout after major implementations
+- History helps track codebase evolution
+
+**For large codebases:**
+- Start with Step 0 assessment to choose strategy
+- Parallelize with 3-5 agents max (diminishing returns beyond)
+- Focus deep analysis on areas relevant to task
+- Accept partial coverage if codebase is huge - note gaps
+
+**For monorepos:**
+- Treat each package/app as separate scout target
+- Document inter-package dependencies
+- Use feature-level scout for specific packages
+
+**Quality over speed:**
+- Better to have thorough analysis of key areas than shallow scan of everything
+- Flag uncertainties rather than guessing
+- Include "Gaps / Unresolved" section honestly
+
+## Scripts
+
+### scout-analyze.sh
+
+Quick codebase analysis with optional tool installation:
+
+```bash
+# Check available tools
+./scripts/scout-analyze.sh . --check
+
+# Run analysis with available tools
+./scripts/scout-analyze.sh /path/to/code
+
+# Auto-install missing tools and analyze
+./scripts/scout-analyze.sh . --install
+
+# Output as JSON (for parsing)
+./scripts/scout-analyze.sh . --json
+```
+
+**Tools checked:**
+| Tool | Purpose | Fallback |
+|------|---------|----------|
+| `tree` | Visual directory structure | `find -type d` |
+| `scc` | Code stats (fast, accurate) | `wc -l` |
+| `jq` | Parse JSON configs | `grep` |
+| `rg` | Fast search | `grep -r` |
+
+**Output includes:**
+- File/directory counts
+- Directory structure (depth 2)
+- Code statistics by language
+- Top file extensions
+- Dependencies (package.json, requirements.txt, go.mod)
+- Git activity (recent commits, active files, contributors)
+- Config files detected
+
+**Usage in workflow:**
+1. Run `./scripts/scout-analyze.sh . --check` in Step 0
+2. Offer user to install missing tools
+3. Run full analysis to inform exploration strategy
+
+## References
+
+- `references/file-patterns.md` - Search patterns
+- `references/feature-patterns.md` - Feature inference
+- `references/tech-detection.md` - Tech stack detection