claude-all-hands 1.0.1 → 1.0.3

package/.claude/skills/documentation-taxonomy/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: documentation-taxonomy
+description: Reference documentation for the taxonomy-based documentation system. Covers envoy docs commands, segmentation strategies, complexity metrics, and symbol reference format.
+---
+
+<objective>
+Provide reference documentation for the taxonomy-based documentation system. Used by documentation-taxonomist and documentation-writer agents.
+</objective>
+
+<quick_start>
+```bash
+# Get documentation tree with coverage
+envoy docs tree src/ --depth 3
+
+# Get complexity metrics
+envoy docs complexity src/lib/
+
+# Format a symbol reference
+envoy docs format-reference src/auth.ts validateToken
+
+# Validate all documentation references
+envoy docs validate
+```
+</quick_start>
+
+<command_reference>
+## envoy docs tree
+
+Get directory tree with documentation coverage indicators.
+
+```bash
+envoy docs tree <path> [--depth <n>]
+```
+
+**Arguments:**
+- `path`: Directory to analyze
+- `--depth`: Max depth to traverse (default: 3)
+
+**Output:**
+```json
+{
+  "path": "src/",
+  "tree": [
+    {
+      "name": "auth",
+      "type": "directory",
+      "has_docs": true,
+      "doc_path": "docs/auth/README.md",
+      "children": [...]
+    }
+  ],
+  "coverage": {
+    "total": 42,
+    "covered": 15,
+    "percentage": 36
+  }
+}
+```
+
+## envoy docs complexity
+
+Get complexity metrics for file or directory.
+
+```bash
+envoy docs complexity <path>
+```
+
+**Output (file):**
+```json
+{
+  "path": "src/auth.ts",
+  "type": "file",
+  "metrics": {
+    "lines": 250,
+    "imports": 8,
+    "exports": 5,
+    "functions": 12,
+    "classes": 2
+  },
+  "estimated_tokens": 2500
+}
+```
+
+**Output (directory):**
+```json
+{
+  "path": "src/lib/",
+  "type": "directory",
+  "file_count": 15,
+  "metrics": {
+    "lines": 3200,
+    "imports": 45,
+    "exports": 32,
+    "functions": 78,
+    "classes": 12
+  },
+  "estimated_tokens": 32000
+}
+```
+
+## envoy docs format-reference
+
+Format a symbol reference with git blame hash.
+
+```bash
+envoy docs format-reference <file> <symbol>
+```
+
+**Arguments:**
+- `file`: Path to source file
+- `symbol`: Symbol name (function, class, variable, type, interface)
+
+**Output:**
+```json
+{
+  "reference": "[ref:src/auth.ts:validateToken:abc1234]",
+  "file": "src/auth.ts",
+  "symbol": "validateToken",
+  "hash": "abc1234",
+  "line_range": { "start": 42, "end": 67 },
+  "symbol_type": "function"
+}
+```
+
+**Supported symbol types by language:**
+| Language | Symbols |
+|----------|---------|
+| TypeScript/JavaScript | function, class, variable, type, interface, method, arrowFunction |
+| Python | function, class, variable, method |
+| Go | function, type, method, variable, const |
+| Rust | function, struct, enum, impl, trait, const |
+| Java | class, interface, method, field, enum |
+| Ruby | function, class, module |
+| Swift | function, class, struct, enum, protocol |
+
+## envoy docs validate
+
+Validate all documentation references for staleness/validity.
+
+```bash
+envoy docs validate [--path <docs_path>]
+```
+
+**Output:**
+```json
+{
+  "message": "Validated 42 references",
+  "total_refs": 42,
+  "stale_count": 3,
+  "invalid_count": 1,
+  "stale": [
+    {
+      "doc_file": "docs/auth/README.md",
+      "reference": "[ref:src/auth.ts:validateToken:abc1234]",
+      "stored_hash": "abc1234",
+      "current_hash": "def5678"
+    }
+  ],
+  "invalid": [
+    {
+      "doc_file": "docs/api/routes.md",
+      "reference": "[ref:src/routes.ts:deletedFunction:xyz789]",
+      "reason": "Symbol not found"
+    }
+  ]
+}
+```
+</command_reference>
+
+<reference_format>
+## Symbol Reference Format
+
+References use the format: `[ref:file:symbol:hash]`
+
+**Components:**
+- `file`: Relative path from project root
+- `symbol`: Symbol name (exact match required)
+- `hash`: Short git commit hash (7 chars) from blame
+
+**Regex pattern:** `/\[ref:([^:]+):([^:]+):([a-f0-9]+)\]/g`
+
+**Examples:**
+```markdown
+The authentication flow starts with [ref:src/auth.ts:validateToken:abc1234].
+
+Configuration is handled by [ref:src/config/index.ts:loadConfig:def5678].
+```
+
+**Why this format:**
+- Symbol-based: survives line number changes within file
+- Hash-tracked: enables staleness detection
+- Human-readable: visible in docs, clickable in IDEs
+- Parseable: regex-extractable for validation
+</reference_format>
+
+<segmentation_strategies>
+## Segmentation Principles
+
+**Size targets:**
+- 1000-3000 tokens per segment (source code)
+- Single segment documentable in one agent pass
+- Balance between parallelism and overhead
+
+**Domain grouping:**
+```
+authentication/     → single segment
+api/
+  routes/          → segment if > 2000 tokens
+  middleware/      → segment if > 2000 tokens
+  handlers/        → may need sub-segments
+lib/
+  utils/           → often single segment
+  core/            → often needs splitting
+```
+
+**Complexity thresholds:**
+| Complexity | Action |
+|------------|--------|
+| < 500 tokens | Combine with adjacent |
+| 500-3000 tokens | Single segment |
+| > 3000 tokens | Split by subdirectory |
+| > 50 functions | Split by functionality |
+
+**Depth guidance:**
+| Depth | When to use |
+|-------|-------------|
+| overview | Simple utilities, config, low complexity |
+| detailed | Core business logic, complex flows |
+| comprehensive | Public APIs, libraries, critical paths |
+</segmentation_strategies>
+
+<complexity_interpretation>
+## Interpreting Complexity Metrics
+
+**Lines of code:**
+- < 100: Simple module
+- 100-500: Standard module
+- 500-1000: Complex module
+- > 1000: Consider splitting
+
+**Functions/classes ratio:**
+- High functions, few classes: Utility module
+- Few functions, many classes: OOP-heavy module
+- Balanced: Standard module
+
+**Imports:**
+- < 5: Self-contained
+- 5-15: Normal coupling
+- > 15: Highly coupled, document dependencies
+
+**Exports:**
+- 1-5: Focused API surface
+- 5-15: Medium API
+- > 15: Large API, needs comprehensive docs
+
+**Estimated tokens:**
+- Rough guide: lines × 10
+- Used for segment sizing
+- Not exact, account for variance
+</complexity_interpretation>
+
+<parallel_writers>
+## Parallel Writer Pattern
+
+Writers work directly on the branch without worktrees. The taxonomist ensures non-overlapping output directories, preventing conflicts.
+
+**Segmentation rule:** Each segment gets a unique `output_path` (e.g., `docs/auth/`, `docs/api/`). Writers only modify files within their assigned output directory.
+
+**Why no worktrees:** Since each writer owns a distinct directory, there are no file conflicts. This simplifies the workflow and avoids worktree management overhead.
+</parallel_writers>
+
+<anti_patterns>
+- Creating docs without symbol references (no traceability)
+- Overlapping segments (causes merge conflicts)
+- Segments too large (> 5000 tokens, agent struggles)
+- Segments too small (< 500 tokens, overhead)
+- Skipping complexity analysis (poor segmentation)
+- Not searching existing docs (duplication)
+- Ignoring depth guidance (inconsistent detail)
+</anti_patterns>
+
+<success_criteria>
+- All code snippets have `[ref:...]` format
+- Segments are non-overlapping (enables parallel writers without conflicts)
+- Complexity informs depth decisions
+- Validation passes after commits
+</success_criteria>

package/.claude/skills/hooks-development/SKILL.md

@@ -0,0 +1,332 @@
+---
+name: hooks-development
+description: Expert guidance for creating, refining, and auditing Claude Code hooks. Use when working with hooks, setting up event listeners, validating commands, automating workflows, adding notifications, or understanding hook types (PreToolUse, PostToolUse, Stop, SessionStart, UserPromptSubmit, etc).
+---
+
+<objective>
+Hooks are event-driven automation for Claude Code that execute shell commands or LLM prompts in response to tool usage, session events, and user interactions. This skill teaches you how to create, configure, and debug hooks for validating commands, automating workflows, injecting context, and implementing custom completion criteria.
+
+Hooks provide programmatic control over Claude's behavior without modifying core code, enabling project-specific automation, safety checks, and workflow customization.
+</objective>
+
+<context>
+Hooks are shell commands or LLM-evaluated prompts that execute in response to Claude Code events. They operate within an event hierarchy: events (PreToolUse, PostToolUse, Stop, etc.) trigger matchers (tool patterns) which fire hooks (commands or prompts). Hooks can block actions, modify tool inputs, inject context, or simply observe and log Claude's operations.
+</context>
+
+<quick_start>
+<workflow>
+1. Create hooks config file:
+   - Project: `.claude/hooks.json`
+   - User: `~/.claude/hooks.json`
+2. Choose hook event (when it fires)
+3. Choose hook type (command or prompt)
+4. Configure matcher (which tools trigger it)
+5. Test with `claude --debug`
+</workflow>
+
+<example>
+**Log all bash commands**:
+
+`.claude/hooks.json`:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "jq -r '\"\\(.tool_input.command) - \\(.tool_input.description // \\\"No description\\\")\"' >> ~/.claude/bash-log.txt"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+This hook:
+- Fires before (`PreToolUse`) every `Bash` tool use
+- Executes a `command` (not an LLM prompt)
+- Logs command + description to a file
+</example>
+</quick_start>
+
+<hook_types>
+| Event | When it fires | Can block? |
+|-------|---------------|------------|
+| **PreToolUse** | Before tool execution | Yes |
+| **PostToolUse** | After tool execution | No |
+| **UserPromptSubmit** | User submits a prompt | Yes |
+| **Stop** | Claude attempts to stop | Yes |
+| **SubagentStop** | Subagent attempts to stop | Yes |
+| **SessionStart** | Session begins | No |
+| **SessionEnd** | Session ends | No |
+| **PreCompact** | Before context compaction | Yes |
+| **Notification** | Claude needs input | No |
+
+Blocking hooks can return `"decision": "block"` to prevent the action. See [references/hook-types.md](references/hook-types.md) for detailed use cases.
+</hook_types>
+
+<hook_anatomy>
+<hook_type name="command">
+**Type**: Executes a shell command
+
+**Use when**:
+- Simple validation (check file exists)
+- Logging (append to file)
+- External tools (formatters, linters)
+- Desktop notifications
+
+**Input**: JSON via stdin
+**Output**: JSON via stdout (optional)
+
+```json
+{
+  "type": "command",
+  "command": "/path/to/script.sh",
+  "timeout": 30000
+}
+```
+</hook_type>
+
+<hook_type name="prompt">
+**Type**: LLM evaluates a prompt
+
+**Use when**:
+- Complex decision logic
+- Natural language validation
+- Context-aware checks
+- Reasoning required
+
+**Input**: Prompt with `$ARGUMENTS` placeholder
+**Output**: JSON with `decision` and `reason`
+
+```json
+{
+  "type": "prompt",
+  "prompt": "Evaluate if this command is safe: $ARGUMENTS\n\nReturn JSON: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
+}
+```
+</hook_type>
+</hook_anatomy>
+
+<matchers>
+Matchers filter which tools trigger the hook:
+
+```json
+{
+  "matcher": "Bash",           // Exact match
+  "matcher": "Write|Edit",     // Multiple tools (regex OR)
+  "matcher": "mcp__.*",        // All MCP tools
+  "matcher": "mcp__memory__.*" // Specific MCP server
+}
+```
+
+**No matcher**: Hook fires for all tools
+```json
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [...]  // No matcher - fires on every user prompt
+      }
+    ]
+  }
+}
+```
+</matchers>
+
+<input_output>
+Hooks receive JSON via stdin with session info, current directory, and event-specific data. Blocking hooks can return JSON to approve/block actions or modify inputs.
+
+**Example output** (blocking hooks):
+```json
+{
+  "decision": "approve" | "block",
+  "reason": "Why this decision was made"
+}
+```
+
+See [references/input-output-schemas.md](references/input-output-schemas.md) for complete schemas for each hook type.
+</input_output>
+
+<environment_variables>
+Available in hook commands:
+
+| Variable | Value |
+|----------|-------|
+| `$CLAUDE_PROJECT_DIR` | Project root directory |
+| `${CLAUDE_PLUGIN_ROOT}` | Plugin directory (plugin hooks only) |
+| `$ARGUMENTS` | Hook input JSON (prompt hooks only) |
+
+**Example**:
+```json
+{
+  "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/validate.sh"
+}
+```
+</environment_variables>
+
+<common_patterns>
+**Desktop notification when input needed**:
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "osascript -e 'display notification \"Claude needs input\" with title \"Claude Code\"'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Block destructive git commands**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "prompt",
+            "prompt": "Check if this command is destructive: $ARGUMENTS\n\nBlock if it contains: 'git push --force', 'rm -rf', 'git reset --hard'\n\nReturn: {\"decision\": \"approve\" or \"block\", \"reason\": \"explanation\"}"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Auto-format code after edits**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "prettier --write $CLAUDE_PROJECT_DIR",
+            "timeout": 10000
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Add context at session start**:
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"SessionStart\", \"additionalContext\": \"Current sprint: Sprint 23. Focus: User authentication\"}}'"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+</common_patterns>
+
+<debugging>
+Always test hooks with the debug flag:
+```bash
+claude --debug
+```
+
+This shows which hooks matched, command execution, and output. See [references/troubleshooting.md](references/troubleshooting.md) for common issues and solutions.
+</debugging>
+
+<reference_guides>
+**Hook types and events**: [references/hook-types.md](references/hook-types.md)
+- Complete list of hook events
+- When each event fires
+- Input/output schemas for each
+- Blocking vs non-blocking hooks
+
+**Command vs Prompt hooks**: [references/command-vs-prompt.md](references/command-vs-prompt.md)
+- Decision tree: which type to use
+- Command hook patterns and examples
+- Prompt hook patterns and examples
+- Performance considerations
+
+**Matchers and patterns**: [references/matchers.md](references/matchers.md)
+- Regex patterns for tool matching
+- MCP tool matching patterns
+- Multiple tool matching
+- Debugging matcher issues
+
+**Input/Output schemas**: [references/input-output-schemas.md](references/input-output-schemas.md)
+- Complete schema for each hook type
+- Field descriptions and types
+- Hook-specific output fields
+- Example JSON for each event
+
+**Working examples**: [references/examples.md](references/examples.md)
+- Desktop notifications
+- Command validation
+- Auto-formatting workflows
+- Logging and audit trails
+- Stop logic patterns
+- Session context injection
+
+**Troubleshooting**: [references/troubleshooting.md](references/troubleshooting.md)
+- Hooks not triggering
+- Command execution failures
+- Prompt hook issues
+- Permission problems
+- Timeout handling
+- Debug workflow
+</reference_guides>
+
+<security_checklist>
+**Critical safety requirements**:
+
+- **Infinite loop prevention**: Check `stop_hook_active` flag in Stop hooks to prevent recursive triggering
+- **Timeout configuration**: Set reasonable timeouts (default: 60s) to prevent hanging
+- **Permission validation**: Ensure hook scripts have executable permissions (`chmod +x`)
+- **Path safety**: Use absolute paths with `$CLAUDE_PROJECT_DIR` to avoid path injection
+- **JSON validation**: Validate hook config with `jq` before use to catch syntax errors
+- **Selective blocking**: Be conservative with blocking hooks to avoid workflow disruption
+
+**Testing protocol**:
+```bash
+# Always test with debug flag first
+claude --debug
+
+# Validate JSON config
+jq . .claude/hooks.json
+```
+</security_checklist>
+
+<success_criteria>
+A working hook configuration has:
+
+- Valid JSON in `.claude/hooks.json` (validated with `jq`)
+- Appropriate hook event selected for the use case
+- Correct matcher pattern that matches target tools
+- Command or prompt that executes without errors
+- Proper output schema (decision/reason for blocking hooks)
+- Tested with `--debug` flag showing expected behavior
+- No infinite loops in Stop hooks (checks `stop_hook_active` flag)
+- Reasonable timeout set (especially for external commands)
+- Executable permissions on script files if using file paths
+</success_criteria>