claude-all-hands 1.0.2 → 1.0.4

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/implementation-mode/SKILL.md

@@ -10,15 +10,15 @@ Execute individual prompts from an active plan. Read prompt → implement → tr
 <quick_start>
 ```bash
 # 1. Get prompt to implement
-.claude/envoy/envoy plans get-prompt <task-number>
+envoy plans get-prompt <task-number>
 
 # 2. Implement using Glob, Grep, Read for context
 
 # 3. Track progress
-.claude/envoy/envoy plans append-history <task> --summary "Added auth middleware" --files '["src/auth.ts"]'
+envoy plans append-history <task> --summary "Added auth middleware" --files '["src/auth.ts"]'
 
 # 4. Get review
-.claude/envoy/envoy plans review-prompt <task>
+envoy plans review-prompt <task>
 
 # 5. Commit when review passes
 git commit -m "task-<N>: <summary>"
@@ -28,7 +28,7 @@ git commit -m "task-<N>: <summary>"
 <workflow>
 ### 1. Get Prompt
 ```bash
-.claude/envoy/envoy plans get-prompt <task-number>
+envoy plans get-prompt <task-number>
 ```
 Returns: prompt content + existing history
 
@@ -46,14 +46,14 @@ git worktree add .worktrees/task-N-V <branch>
 ### 4. Track History
 After each significant change:
 ```bash
-.claude/envoy/envoy plans append-history <task> \
+envoy plans append-history <task> \
   --summary "Brief description of change" \
   --files '["path/to/changed.ts", "path/to/other.ts"]'
 ```
 
 ### 5. Get Review
 ```bash
-.claude/envoy/envoy plans review-prompt <task>
+envoy plans review-prompt <task>
 ```
 If changes needed → fix → append-history → review again
 
@@ -119,7 +119,7 @@ For each issue:
 
 ### 3. Review Changes
 ```bash
-.claude/envoy/envoy vertex review --last-commit
+envoy vertex review --last-commit
 ```
 
 | Response | Action |

package/.claude/skills/knowledge-discovery/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: knowledge-discovery
+description: Semantic codebase exploration using knowledge base + LSP. Use for context gathering, understanding design decisions, finding implementation patterns. Combines "why" from docs with "where" from code references.
+---
+
+<objective>
+Enable context-efficient codebase exploration by leveraging semantic knowledge search before raw file reads. Knowledge docs capture motivations and design decisions that grep/glob cannot surface. File references in results guide targeted code exploration via LSP or direct reads.
+</objective>
+
+<motivation>
+Traditional search (grep, glob) finds **what** exists but not **why**. Knowledge base docs encode:
+- Design motivations and tradeoffs
+- Pattern explanations with rationale
+- Cross-cutting concerns that span multiple files
+- "How we do X" institutional knowledge
+
+Searching knowledge first provides semantic context that informs subsequent code exploration. File references embedded in knowledge docs point to implementations, enabling LSP-guided exploration that minimizes context consumption.
+</motivation>
+
+<quick_start>
+```bash
+# Semantic search - use full descriptive phrases, not keywords
+envoy knowledge search "how does retry logic handle rate limits in external API calls"
+
+# NOT: envoy knowledge search "retry rate limit"
+```
+
+Result interpretation:
+- **High similarity (>0.8)**: Full `full_resource_context` included - read directly
+- **Lower similarity**: Only `description` provided - may need `envoy knowledge read <path>` for full content
+</quick_start>
+
+<constraints>
+- Use full phrases for semantic search, not keywords
+- Always check file references in results before doing raw codebase searches
+- LSP required when symbol references present (context-light first)
+- Estimate context cost before large file reads
+</constraints>
+
+<workflow>
+### 1. Semantic Search First
+```bash
+envoy knowledge search "<descriptive question about the requirement or concept>"
+```
+
+### 2. Interpret Results
+
+**High-confidence matches** return full content:
+```json
+{
+  "similarity": 0.85,
+  "full_resource_context": "---\ndescription: ...\n---\n\n# Full doc content..."
+}
+```
+
+**Lower-confidence matches** return descriptions only:
+```json
+{
+  "similarity": 0.72,
+  "description": "Brief description of what the doc covers"
+}
+```
+
+If description seems relevant, fetch full content:
+```bash
+envoy knowledge read "docs/path/to/file.md"
+```
+
+### 3. Follow File References
+
+Knowledge docs embed file references in two forms:
+
+**Path + Symbol** (LSP required):
+```
+[ref:.claude/envoy/src/lib/retry.ts:withRetry:fc672da]
+```
+→ Use LSP to explore symbol before reading file
+
+**Path Only** (direct read permitted):
+```
+[ref:.claude/envoy/src/commands/gemini.ts::fc672da]
+```
+→ Full file read acceptable
+
+### 4. LSP Exploration (when symbol present)
+
+Match LSP operation to information need:
+
+| Need | LSP Operation |
+|------|---------------|
+| Find callers/usage | `incomingCalls` |
+| Find dependants | `findReferences` |
+| Get signature/types | `hover` |
+| Jump to definition | `goToDefinition` |
+| All symbols in file | `documentSymbol` |
+
+**Example flow**:
+```bash
+# 1. Find symbol location
+LSP goToDefinition → retry.ts:78
+
+# 2. Understand usage patterns
+LSP incomingCalls → 6 callers in gemini.ts
+
+# 3. Only then read relevant implementation
+Read retry.ts (lines 78-120)
+```
+
+### 5. Context-Aware Reading
+
+After LSP exploration, read only what's needed:
+- Specific function/class implementations
+- Caller contexts that inform usage patterns
+- Avoid reading entire files when LSP provides structure
+</workflow>
+
+<examples>
+<example name="Investigating retry patterns">
+```bash
+# 1. Semantic search
+envoy knowledge search "how do we handle retries for external API calls in envoy"
+
+# Result includes ref: .claude/envoy/src/lib/retry.ts:withRetry:fc672da
+
+# 2. LSP exploration
+LSP documentSymbol retry.ts → find withRetry at line 78
+LSP incomingCalls line 78 → 6 callers in gemini.ts
+
+# 3. Targeted read
+Read retry.ts lines 36-125 (isRetryableError + withRetry only)
+```
+</example>
+
+<example name="Understanding protocol extension">
+```bash
+# 1. Semantic search
+envoy knowledge search "how are protocols maintained for reusability and extension"
+
+# Result includes full context explaining:
+# - extends keyword for inheritance
+# - Step numbering (6.1, 6.2 for insertions, 6+ for augments)
+# - File refs to protocols/debugging.yaml, protocols/implementation.yaml
+
+# 2. Path-only reference → direct read
+Read .claude/protocols/debugging.yaml (extends field visible)
+```
+</example>
+
+<decision_tree>
+```
+Need codebase context?
+├─ Know specific file/symbol? → Read/LSP directly
+├─ Conceptual question? → envoy knowledge search
+│   ├─ High similarity result? → Use full_resource_context
+│   └─ Lower similarity? → envoy knowledge read if relevant
+│       └─ File references in result?
+│           ├─ Has symbol (path:symbol:hash)? → LSP first
+│           └─ Path only (path::hash)? → Direct read OK
+└─ No knowledge matches? → Fallback to grep/glob
+```
+</decision_tree>
+</examples>
+
+<anti_patterns>
+- Using keywords instead of descriptive phrases in knowledge search
+- Reading entire files when LSP can provide structure first
+- Skipping knowledge search and going straight to grep
+- Ignoring file references and re-searching codebase
+- Using findReferences when incomingCalls would suffice (findReferences includes definition)
+</anti_patterns>
+
+<success_criteria>
+- Knowledge search invoked before raw codebase exploration
+- File references from knowledge docs used to guide code exploration
+- LSP used for symbol references before large file reads
+- Context budget preserved through targeted reads
+- Design motivations ("why") understood alongside implementation ("what")
+</success_criteria>

package/bin/cli.js

@@ -4857,7 +4857,8 @@ var yargs_default = Yargs;
 
 // src/commands/init.ts
 import { spawnSync as spawnSync2 } from "child_process";
-import { copyFileSync, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync5, renameSync, writeFileSync } from "fs";
+import { appendFileSync, copyFileSync, existsSync as existsSync3, mkdirSync, readFileSync as readFileSync5, renameSync, writeFileSync } from "fs";
+import { homedir } from "os";
 import { dirname as dirname4, join as join2, resolve as resolve6 } from "path";
 import * as readline from "readline";
 
@@ -6600,6 +6601,12 @@ function getAllhandsRoot() {
 }
 
 // src/commands/init.ts
+var ENVOY_SHELL_FUNCTION = `
+# AllHands envoy command - resolves to .claude/envoy/envoy from current directory
+envoy() {
+  "$PWD/.claude/envoy/envoy" "$@"
+}
+`;
 var MIGRATION_MAP = {
   "CLAUDE.md": "CLAUDE.project.md",
   ".claude/settings.json": ".claude/settings.local.json"
@@ -6653,6 +6660,28 @@ async function confirm(message) {
     });
   });
 }
+function setupEnvoyShellFunction() {
+  const shell = process.env.SHELL || "";
+  let shellRc = null;
+  if (shell.includes("zsh")) {
+    shellRc = join2(homedir(), ".zshrc");
+  } else if (shell.includes("bash")) {
+    const bashProfile = join2(homedir(), ".bash_profile");
+    const bashRc = join2(homedir(), ".bashrc");
+    shellRc = existsSync3(bashProfile) ? bashProfile : bashRc;
+  }
+  if (!shellRc) {
+    return { added: false, shellRc: null };
+  }
+  if (existsSync3(shellRc)) {
+    const content = readFileSync5(shellRc, "utf-8");
+    if (content.includes("envoy()") || content.includes(".claude/envoy/envoy")) {
+      return { added: false, shellRc };
+    }
+  }
+  appendFileSync(shellRc, ENVOY_SHELL_FUNCTION);
+  return { added: true, shellRc };
+}
 function migrateExistingFiles(target) {
   const migrated = {};
   for (const [orig, dest] of Object.entries(MIGRATION_MAP)) {
@@ -6824,6 +6853,17 @@ CLAUDE.project.md
       console.log(`  Details: ${result.stderr.trim()}`);
     }
   }
+  console.log("\nSetting up envoy shell command...");
+  const envoyResult = setupEnvoyShellFunction();
+  if (envoyResult.added && envoyResult.shellRc) {
+    console.log(`  Added envoy function to ${envoyResult.shellRc}`);
+    console.log("  Run `source " + envoyResult.shellRc + "` or restart terminal to use");
+  } else if (envoyResult.shellRc) {
+    console.log("  envoy function already configured");
+  } else {
+    console.log("  Could not detect shell config (add manually to your shell rc):");
+    console.log('    envoy() { "$PWD/.claude/envoy/envoy" "$@"; }');
+  }
   if (!autoYes) {
     const remoteResult = git(["remote", "get-url", "origin"], resolvedTarget);
     const hasGitHubRemote = remoteResult.success && remoteResult.stdout.includes("github.com");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-all-hands",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "description": "CLI for syncing Claude agent configurations to all-hands repository",
   "type": "module",
   "bin": {