claude-all-hands 1.0.5 → 1.0.6

package/.claude/agents/documentation-taxonomist.md

@@ -35,14 +35,14 @@ Your assignments should guide writers toward capturing KNOWLEDGE that isn't obvi
 - `mode`: "init"
 - `scope_paths`: optional paths to scope (default: entire codebase)
 - `user_request`: optional user-specified context
-- `feature_branch`: branch name for worktree naming
+- `feature_branch`: branch name (used for context only)
 
 **OUTPUTS** (to main agent):
-- `{ success: true, structure_committed: true, assignments: [...] }` - ready for writers
+- `{ success: true, structure_created: true, assignments: [...] }` - ready for writers
 
 **STEPS:**
 
-1. **Analyze codebase AND existing docs** - Run envoy commands directly (no chaining):
+1. **Analyze codebase AND existing docs** - Run as parallel tool calls or join with `;` (not `&&`, want all outputs):
    ```bash
    # Understand codebase structure
    envoy docs tree <path> --depth 4
@@ -85,22 +85,20 @@ Your assignments should guide writers toward capturing KNOWLEDGE that isn't obvi
    - Subdomains should represent distinct subsystems, not directories
    - One writer can handle parent + children if simple enough
 
-4. **Create and commit directory structure:**
+4. **Create directory structure:**
    ```bash
    mkdir -p docs/<product>/<subdomain>
-   git add docs/
-   git commit -m "docs: create documentation structure for <products>"
    ```
 
    This happens BEFORE delegation - writers receive existing directories.
+   Note: Do NOT create .gitkeep files. Writers will add content shortly - empty directories are fine temporarily.
 
 5. **Assign writers to directories:**
    ```yaml
-   structure_committed: true
+   structure_created: true
    assignments:
      - directory: "docs/<product>/"
        files: ["<source-glob-patterns>"]
-       worktree_branch: "<feature_branch>/docs-<product>"
        responsibilities:
          - "Key design decisions and rationale"
          - "Patterns observers should know"
@@ -110,7 +108,6 @@ Your assignments should guide writers toward capturing KNOWLEDGE that isn't obvi
 
      - directory: "docs/<product>/<subdomain>/"
        files: ["<source-glob-patterns>"]
-       worktree_branch: "<feature_branch>/docs-<product>-<subdomain>"
        responsibilities:
          - "Implementation rationale for subsystem"
          - "Key patterns with reference examples"
@@ -133,13 +130,23 @@ Your assignments should guide writers toward capturing KNOWLEDGE that isn't obvi
 - `use_diff`: boolean - if true, get changed files from git
 - `scope_paths`: optional list of paths to scope
 - `user_request`: optional user-specified context
-- `feature_branch`: branch name for worktree naming
+- `feature_branch`: branch name (used for context only)
+- `walkthroughs`: optional array from `envoy plan get-all-walkthroughs` containing:
+  - `prompt_num`, `variant`, `id`: prompt identifiers
+  - `description`: what the prompt implemented
+  - `walkthrough`: array of implementation iterations with decisions/rationale
+  - `relevant_files`: files affected by this prompt
 
 **OUTPUTS** (to main agent):
-- `{ success: true, structure_committed: true, assignments: [...] }` - targeted updates
+- `{ success: true, structure_created: true, assignments: [...] }` - targeted updates
 
 **STEPS:**
-1. **Discover what needs documenting:**
+1. **Analyze walkthroughs for rationale** (if provided):
+   - Extract design decisions, patterns chosen, and rationale from walkthrough entries
+   - Map prompts to affected files via `relevant_files`
+   - This context informs what knowledge to capture (WHY decisions were made)
+
+2. **Discover what needs documenting:**
    ```bash
    # If use_diff is true, get changed files from git
    envoy git diff-base --name-only
@@ -153,25 +160,24 @@ Your assignments should guide writers toward capturing KNOWLEDGE that isn't obvi
 
    # Check if changed concepts are already documented
    envoy knowledge search "<changed-feature>" --metadata-only
-   envoy knowledge search "<affected-product>" --metadata-only
    ```
 
-2. Identify affected products/features from the changes
-3. Check existing doc structure - which directories need updates vs new sections
-4. Create any new directories needed (and commit)
-5. Assign writers to affected directories with update responsibilities
+3. Identify affected products/features from changes + walkthrough context
+4. Check existing doc structure - which directories need updates vs new sections
+5. Create any new directories needed
+6. Assign writers with walkthrough rationale included in notes:
 
 ```yaml
-structure_committed: true
+structure_created: true
 assignments:
   - directory: "docs/<product>/"
     files: ["<changed-source-patterns>"]
-    worktree_branch: "<feature_branch>/docs-<product>"
     responsibilities:
       - "update README.md for new features"
       - "add documentation for new commands"
     action: "update"
-    notes: "<what changed and needs documenting>"
+    notes: "<what changed, plus rationale from walkthroughs>"
+    walkthrough_context: "<relevant decisions/rationale from prompt walkthroughs>"
 ```
 </adjust_workflow>
 
@@ -230,9 +236,9 @@ assignments:
 - MUST run `envoy docs tree docs/` to see existing documentation hierarchies before planning
 - MUST use `envoy knowledge search` to check if concepts are already documented
 - MUST use product/feature names, not directory names
-- MUST create and commit directory structure BEFORE returning assignments
+- MUST create directory structure BEFORE returning assignments
 - MUST assign writers to existing directories with clear responsibilities
-- MUST run envoy commands directly - no chaining
+- MUST run envoy commands via parallel tool calls or `;` joins (avoid `&&` - want all outputs)
 - MUST use --metadata-only for knowledge searches
 - NEVER mirror source directory structure in domain names
 - NEVER over-distribute - prefer fewer writers handling more
@@ -244,12 +250,12 @@ assignments:
 **Init workflow complete when:**
 - Products/features identified (not directories)
 - Meaningful domain names chosen
-- Directory structure created and committed
+- Directory structure created
 - Writer assignments defined with responsibilities
 - Each assignment has directory, files, responsibilities, depth
 
 **Adjust workflow complete when:**
 - Affected products identified
-- New directories created if needed (and committed)
+- New directories created if needed
 - Writer assignments target specific update responsibilities
 </success_criteria>

package/.claude/agents/documentation-writer.md

@@ -2,7 +2,7 @@
 name: documentation-writer
 description: |
   Documentation writer specialist. Writes knowledge-base documentation using file references. Triggers: "write docs", "document domain".
-tools: Read, Glob, Grep, Bash, Write, Edit
+tools: Read, Glob, Grep, Bash, Write, Edit, LSP
 model: inherit
 color: yellow
 ---
@@ -121,7 +121,7 @@ Authentication uses JWT for stateless sessions. The signing implementation [ref:
 - `notes`: guidance from taxonomist
 
 **OUTPUTS** (to main agent):
-- `{ success: true }` - documentation written and committed
+- `{ success: true }` - documentation written (main agent commits after all writers complete)
 
 **STEPS:**
 1. Search existing knowledge: `envoy knowledge search "<domain> decisions patterns"`
@@ -158,7 +158,7 @@ Authentication uses JWT for stateless sessions. The signing implementation [ref:
    - `detailed`: + rationale, tradeoffs, edge cases
    - `comprehensive`: + all major patterns, troubleshooting
 
-6. Validate before commit:
+6. Validate before returning:
 
    a. Run: `envoy docs validate --path docs/<domain>/`
    b. Check response:
@@ -171,18 +171,14 @@ Authentication uses JWT for stateless sessions. The signing implementation [ref:
    d. If any check fails:
       - Fix the issue
       - Re-validate
-      - Do NOT commit until all checks pass
 
-7. Commit changes:
-   - `git add docs/`
-   - `git commit -m "docs(<domain>): <summary>"`
-   - Commit hook validates references
+7. Return `{ success: true }`
 
-8. Return `{ success: true }`
+**IMPORTANT:** Do NOT commit. Main agent commits all writer changes together after parallel execution completes.
 
 **On failure:**
 - If AST symbol not found: use file-only ref `[ref:file::hash]`
-- If commit validation fails: fix references, retry commit
+- If validation fails: fix references, re-validate
 </write_workflow>
 
 <fix_workflow>
@@ -207,9 +203,7 @@ Authentication uses JWT for stateless sessions. The signing implementation [ref:
    - If file moved: update file path
    - If file deleted: remove ref, update knowledge
 
-3. Commit fixes: `git commit -m "docs: update stale references"`
-
-4. Return fix summary
+3. Return fix summary (main agent commits)
 </fix_workflow>
 
 <audit_fix_workflow>
@@ -291,9 +285,7 @@ changes:
 
 5. Validate changes: `envoy docs validate --path <doc_file>`
 
-6. Commit: `git commit -m "docs: fix stale/invalid refs in <doc_file>"`
-
-7. Return changes summary
+6. Return changes summary (main agent commits)
 </audit_fix_workflow>
 
 <documentation_format>
@@ -304,6 +296,15 @@ description: 1-2 sentence summary enabling semantic search discovery
 ---
 ```
 
+**Description quality guidelines:**
+- GOOD: "Authentication system using JWT tokens with refresh rotation and Redis session storage"
+- GOOD: "CLI argument parsing with subcommand routing and help generation"
+- BAD: "Documentation for auth" (too vague)
+- BAD: "Code documentation" (useless for search)
+- BAD: "This file documents the system" (describes the doc, not the code)
+
+The description should answer: "What would someone search for to find this?"
+
 **Structure (REQUIRED sections marked with *):**
 
 ```markdown
@@ -348,7 +349,8 @@ Adjust structure based on domain. The structure serves knowledge transfer, not c
 - MUST include `description` in front-matter
 - MUST include Overview, Key Decisions, and Use Cases sections
 - MUST focus on decisions, rationale, patterns - NOT capabilities
-- MUST validate with `envoy docs validate` before committing
+- MUST validate with `envoy docs validate` before returning
+- MUST NOT commit - main agent commits after all writers complete
 - NEVER write inline code blocks (zero fenced blocks allowed)
 - NEVER document what's obvious from reading code
 - NEVER create capability tables (Command/Purpose, Option/Description)

package/.claude/commands/{docs-audit.md → audit-docs.md}

@@ -129,14 +129,20 @@ changes:
 <step name="verify_and_report">
 After all agents complete:
 
-1. Run validation again:
+1. Commit all documentation fixes:
+```bash
+git add docs/
+git commit -m "docs: fix stale/invalid references"
+```
+
+2. Run validation again:
 ```bash
 envoy docs validate [--path <docs_path>]
 ```
 
-2. If issues remain, report which failed and why
+3. If issues remain, report which failed and why
 
-3. Report completion:
+4. Report completion:
 ```markdown
 ## Audit Complete
 

package/.claude/commands/continue.md

@@ -42,17 +42,8 @@ For each prompt from next:
 3. **Parallel execution**: If multiple prompts/variants returned, delegate all in parallel
 </step>
 
-<step name="extract_documentation">
-After each specialist returns (prompt merged):
-
-Call `/docs adjust --diff` to update documentation based on changes.
-* Uses taxonomy-based approach to identify changed areas
-* Writers update relevant documentation with symbol references
-* Returns: `{ success: true }`
-</step>
-
 <step name="loop">
-Repeat steps 1-3 until:
+Repeat steps 1-2 until:
 - No more prompts returned from next
 - No prompts in_progress status
 </step>
@@ -80,8 +71,38 @@ If verdict = "failed" OR suggested_fixes exist:
 4. Rerun full review (repeat until passes)
 </step>
 
+<step name="extract_documentation">
+After full review passes, delegate to **documentation-taxonomist** agent with adjust mode:
+
+1. Get prompt walkthroughs for rationale context:
+   ```bash
+   envoy plan get-all-walkthroughs
+   ```
+
+2. Delegate to taxonomist with inputs:
+   ```yaml
+   mode: "adjust"
+   use_diff: true
+   feature_branch: "<current_branch>"
+   walkthroughs: <output from get-all-walkthroughs>
+   ```
+
+3. Taxonomist identifies affected domains, delegates to writers (writers do NOT commit)
+
+4. After ALL writers complete, commit documentation changes:
+   ```bash
+   git add docs/
+   git commit -m "docs: update documentation for feature"
+   ```
+
+5. Mark prompts documented:
+   ```bash
+   envoy plan mark-all-documented
+   ```
+</step>
+
 <step name="mandatory_doc_audit">
-Call `/docs audit` to validate all documentation symbol references.
+Call `/audit-docs` to validate all documentation symbol references.
 * Checks for stale (hash changed) and invalid (symbol deleted) references
 * If issues found: fix automatically or present to user
 * Returns: `{ success: true }`
@@ -104,7 +125,7 @@ Call /whats-next command
 <success_criteria>
 - All prompts implemented via specialist delegation
 - Variants executed in parallel
-- Documentation extracted for each prompt
+- Documentation updated from all changes (once, after review passes)
 - Full review passes
 - Documentation audit completed
 - Plan marked complete with PR created
@@ -114,7 +135,7 @@ Call /whats-next command
 <constraints>
 - MUST respect prompt dependencies (use envoy next)
 - MUST run all variants in parallel
-- MUST extract documentation after each prompt
+- MUST extract documentation once after full review passes
 - MUST loop until no prompts remain
 - MUST pass full review before completing
 - MUST run doc audit before completion

package/.claude/commands/{docs-init.md → document.md}

@@ -120,7 +120,7 @@ notes: "<segment.notes>"
 success: true
 ```
 
-Writers work directly on the branch. Taxonomist ensures non-overlapping output directories, so no conflicts occur.
+Writers work directly on the branch without committing. Taxonomist ensures non-overlapping output directories, so no conflicts occur. Main agent commits all changes after writers complete.
 </step>
 
 <step name="validate_docs">
@@ -132,7 +132,7 @@ If stale/invalid refs found:
 </step>
 
 <step name="commit_documentation">
-Commit any uncommitted documentation changes (e.g., validation fixes):
+Commit ALL documentation changes from parallel writers:
 
 1. Check for uncommitted changes in docs/:
    ```bash
@@ -168,7 +168,7 @@ Update semantic search index with new documentation:
 
 2. Call reindex:
    ```bash
-   envoy knowledge reindex-from-changes docs --files '<json_array>'
+   envoy knowledge reindex-from-changes --files '<json_array>'
    ```
 
 3. If reindex reports missing references:

package/.claude/envoy/package-lock.json

@@ -34,6 +34,9 @@
         "@types/pino": "^7.0.4",
         "tsx": "^4.7.0",
         "typescript": "^5.3.0"
+      },
+      "engines": {
+        "node": ">=20.0.0"
       }
     },
     "node_modules/@esbuild/aix-ppc64": {

package/.claude/envoy/package.json

@@ -3,6 +3,9 @@
   "version": "0.1.0",
   "private": true,
   "type": "module",
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "scripts": {
     "start": "tsx src/cli.ts",
     "typecheck": "tsc --noEmit"

package/.claude/envoy/src/commands/docs.ts

@@ -16,7 +16,6 @@ import matter from "gray-matter";
 import { BaseCommand, CommandResult } from "./base.js";
 import {
   findSymbol,
-  symbolExists,
   getFileComplexity,
 } from "../lib/tree-sitter-utils.js";
 import { getSupportedExtensions } from "../lib/ast-queries.js";
@@ -514,9 +513,9 @@ const codeBlockPattern = /^```[a-z0-9_+-]*$/gm;
         continue;
       }
 
-      // Check if symbol exists
-      const symbolFound = await symbolExists(absoluteRefFile, ref.refSymbol!);
-      if (!symbolFound) {
+      // Check if symbol exists and get its location
+      const symbol = await findSymbol(absoluteRefFile, ref.refSymbol!);
+      if (!symbol) {
         const reason = "Symbol not found";
         invalid.push({
           doc_file: ref.file,
@@ -530,12 +529,6 @@ const codeBlockPattern = /^```[a-z0-9_+-]*$/gm;
         continue;
       }
 
-      // Get current hash for symbol
-      const symbol = await findSymbol(absoluteRefFile, ref.refSymbol!);
-      if (!symbol) {
-        continue; // Already validated above
-      }
-
       const { hash: mostRecentHash, success } = getMostRecentHashForRange(
         absoluteRefFile,
         symbol.startLine,

package/.claude/envoy/src/commands/plan/index.ts

@@ -35,6 +35,8 @@ export {
   CompletePromptCommand,
   GetPromptWalkthroughCommand,
   MarkPromptExtractedCommand,
+  GetAllWalkthroughsCommand,
+  MarkAllDocumentedCommand,
   ReleaseAllPromptsCommand,
   CompleteCommand,
 } from "./lifecycle.js";
@@ -77,6 +79,8 @@ import {
   CompletePromptCommand,
   GetPromptWalkthroughCommand,
   MarkPromptExtractedCommand,
+  GetAllWalkthroughsCommand,
+  MarkAllDocumentedCommand,
   ReleaseAllPromptsCommand,
   CompleteCommand,
 } from "./lifecycle.js";
@@ -121,6 +125,8 @@ export const COMMANDS = {
   "complete-prompt": CompletePromptCommand,
   "get-prompt-walkthrough": GetPromptWalkthroughCommand,
   "mark-prompt-extracted": MarkPromptExtractedCommand,
+  "get-all-walkthroughs": GetAllWalkthroughsCommand,
+  "mark-all-documented": MarkAllDocumentedCommand,
   "release-all-prompts": ReleaseAllPromptsCommand,
   complete: CompleteCommand,
   // Gates

package/.claude/envoy/src/commands/plan/lifecycle.ts

@@ -452,6 +452,91 @@ export class MarkPromptExtractedCommand extends BaseCommand {
   }
 }
 
+/**
+ * Get all walkthroughs from prompts not yet documented.
+ * Returns walkthroughs for all prompts where documentation_extracted is false.
+ */
+export class GetAllWalkthroughsCommand extends BaseCommand {
+  readonly name = "get-all-walkthroughs";
+  readonly description = "Get walkthroughs from all undocumented prompts";
+
+  defineArguments(_cmd: Command): void {
+    // No arguments
+  }
+
+  async execute(_args: Record<string, unknown>): Promise<CommandResult> {
+    const branch = getBranch();
+    if (!branch) {
+      return this.error("no_branch", "Not in a git repository or no branch checked out");
+    }
+
+    if (!planExists()) {
+      return this.error("no_plan", "No plan directory exists for this branch");
+    }
+
+    const prompts = readAllPrompts();
+    const undocumented = prompts.filter((p) => !p.frontMatter.documentation_extracted);
+
+    const walkthroughs = undocumented.map((p) => ({
+      prompt_num: p.number,
+      variant: p.variant,
+      id: getPromptId(p.number, p.variant),
+      description: p.frontMatter.description,
+      walkthrough: p.frontMatter.walkthrough || [],
+      relevant_files: p.frontMatter.relevant_files || [],
+    }));
+
+    return this.success({
+      count: walkthroughs.length,
+      walkthroughs,
+    });
+  }
+}
+
+/**
+ * Mark all undocumented prompts as documentation_extracted.
+ */
+export class MarkAllDocumentedCommand extends BaseCommand {
+  readonly name = "mark-all-documented";
+  readonly description = "Mark all undocumented prompts as documentation extracted";
+
+  defineArguments(_cmd: Command): void {
+    // No arguments
+  }
+
+  async execute(_args: Record<string, unknown>): Promise<CommandResult> {
+    const branch = getBranch();
+    if (!branch) {
+      return this.error("no_branch", "Not in a git repository or no branch checked out");
+    }
+
+    if (!planExists()) {
+      return this.error("no_plan", "No plan directory exists for this branch");
+    }
+
+    const prompts = readAllPrompts();
+    const undocumented = prompts.filter((p) => !p.frontMatter.documentation_extracted);
+    const marked: string[] = [];
+
+    for (const p of undocumented) {
+      const prompt = readPrompt(p.number, p.variant);
+      if (prompt) {
+        const updatedFrontMatter: PromptFrontMatter = {
+          ...prompt.frontMatter,
+          documentation_extracted: true,
+        };
+        writePrompt(p.number, p.variant, updatedFrontMatter, prompt.content);
+        marked.push(getPromptId(p.number, p.variant));
+      }
+    }
+
+    return this.success({
+      marked_count: marked.length,
+      marked_prompts: marked,
+    });
+  }
+}
+
 /**
  * Release all prompts from in_progress status.
  */

package/.claude/envoy/src/lib/ast-queries.ts

@@ -8,6 +8,7 @@ export type SymbolType = "function" | "class" | "variable" | "type" | "export" |
 export interface SymbolQuery {
   query: string;
   nameCapture: string;
+  defCapture?: string; // Capture for full definition range (optional, falls back to name)
 }
 
 export interface LanguageQueries {
@@ -21,195 +22,236 @@ export interface LanguageQueries {
 export const languageQueries: Record<string, LanguageQueries> = {
   typescript: {
     function: {
-      query: `(function_declaration name: (identifier) @name)`,
+      query: `(function_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     class: {
-      query: `(class_declaration name: (type_identifier) @name)`,
+      query: `(class_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     variable: {
-      query: `(variable_declarator name: (identifier) @name)`,
+      query: `(variable_declarator name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     type: {
-      query: `(type_alias_declaration name: (type_identifier) @name)`,
+      query: `(type_alias_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     interface: {
-      query: `(interface_declaration name: (type_identifier) @name)`,
+      query: `(interface_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     method: {
-      query: `(method_definition name: (property_identifier) @name)`,
+      query: `(method_definition name: (property_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     export: {
-      query: `(export_statement declaration: (function_declaration name: (identifier) @name))`,
+      query: `(export_statement declaration: (function_declaration name: (identifier) @name)) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     arrowFunction: {
       query: `(lexical_declaration
         (variable_declarator
           name: (identifier) @name
-          value: (arrow_function)))`,
+          value: (arrow_function))) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   javascript: {
     function: {
-      query: `(function_declaration name: (identifier) @name)`,
+      query: `(function_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     class: {
-      query: `(class_declaration name: (identifier) @name)`,
+      query: `(class_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     variable: {
-      query: `(variable_declarator name: (identifier) @name)`,
+      query: `(variable_declarator name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     method: {
-      query: `(method_definition name: (property_identifier) @name)`,
+      query: `(method_definition name: (property_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     arrowFunction: {
       query: `(lexical_declaration
         (variable_declarator
           name: (identifier) @name
-          value: (arrow_function)))`,
+          value: (arrow_function))) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   python: {
     function: {
-      query: `(function_definition name: (identifier) @name)`,
+      query: `(function_definition name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     class: {
-      query: `(class_definition name: (identifier) @name)`,
+      query: `(class_definition name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     variable: {
-      query: `(assignment left: (identifier) @name)`,
+      query: `(assignment left: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     method: {
-      query: `(function_definition name: (identifier) @name)`,
+      query: `(function_definition name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   go: {
     function: {
-      query: `(function_declaration name: (identifier) @name)`,
+      query: `(function_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     type: {
-      query: `(type_declaration (type_spec name: (type_identifier) @name))`,
+      query: `(type_declaration (type_spec name: (type_identifier) @name)) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     method: {
-      query: `(method_declaration name: (field_identifier) @name)`,
+      query: `(method_declaration name: (field_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     variable: {
-      query: `(var_declaration (var_spec name: (identifier) @name))`,
+      query: `(var_declaration (var_spec name: (identifier) @name)) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     const: {
-      query: `(const_declaration (const_spec name: (identifier) @name))`,
+      query: `(const_declaration (const_spec name: (identifier) @name)) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   rust: {
     function: {
-      query: `(function_item name: (identifier) @name)`,
+      query: `(function_item name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     struct: {
-      query: `(struct_item name: (type_identifier) @name)`,
+      query: `(struct_item name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     enum: {
-      query: `(enum_item name: (type_identifier) @name)`,
+      query: `(enum_item name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     impl: {
-      query: `(impl_item type: (type_identifier) @name)`,
+      query: `(impl_item type: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     trait: {
-      query: `(trait_item name: (type_identifier) @name)`,
+      query: `(trait_item name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     const: {
-      query: `(const_item name: (identifier) @name)`,
+      query: `(const_item name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   java: {
     class: {
-      query: `(class_declaration name: (identifier) @name)`,
+      query: `(class_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     interface: {
-      query: `(interface_declaration name: (identifier) @name)`,
+      query: `(interface_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     method: {
-      query: `(method_declaration name: (identifier) @name)`,
+      query: `(method_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     field: {
-      query: `(field_declaration declarator: (variable_declarator name: (identifier) @name))`,
+      query: `(field_declaration declarator: (variable_declarator name: (identifier) @name)) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     enum: {
-      query: `(enum_declaration name: (identifier) @name)`,
+      query: `(enum_declaration name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   ruby: {
     function: {
-      query: `(method name: (identifier) @name)`,
+      query: `(method name: (identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     class: {
-      query: `(class name: (constant) @name)`,
+      query: `(class name: (constant) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     module: {
-      query: `(module name: (constant) @name)`,
+      query: `(module name: (constant) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 
   swift: {
     function: {
-      query: `(function_declaration name: (simple_identifier) @name)`,
+      query: `(function_declaration name: (simple_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     class: {
-      query: `(class_declaration name: (type_identifier) @name)`,
+      query: `(class_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     struct: {
-      query: `(struct_declaration name: (type_identifier) @name)`,
+      query: `(struct_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     enum: {
-      query: `(enum_declaration name: (type_identifier) @name)`,
+      query: `(enum_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
     protocol: {
-      query: `(protocol_declaration name: (type_identifier) @name)`,
+      query: `(protocol_declaration name: (type_identifier) @name) @def`,
       nameCapture: "name",
+      defCapture: "def",
     },
   },
 };

package/.claude/envoy/src/lib/tree-sitter-utils.ts

@@ -23,6 +23,7 @@ export interface ParseResult {
   language?: string;
   symbols?: SymbolLocation[];
   error?: string;
+  warnings?: string[]; // Non-fatal issues during parsing (e.g., query failures)
 }
 
 // Tree-sitter Query types
@@ -111,7 +112,23 @@ async function getParser(language: string): Promise<ParserData | null> {
     parserCache.set(language, cached);
     return cached;
   } catch (e) {
-    console.error(`Failed to load parser for ${language}:`, e);
+    // Detect native binding failures
+    const errorMsg = e instanceof Error ? e.message : String(e);
+    if (
+      errorMsg.includes("MODULE_NOT_FOUND") ||
+      errorMsg.includes("invalid ELF header") ||
+      errorMsg.includes("was compiled against a different Node.js version") ||
+      errorMsg.includes("dlopen") ||
+      errorMsg.includes(".node")
+    ) {
+      console.error(
+        `Native binding error for ${language} parser. ` +
+        `This usually means tree-sitter was compiled for a different Node.js version. ` +
+        `Try: rm -rf node_modules && npm install`
+      );
+    } else {
+      console.error(`Failed to load parser for ${language}:`, e);
+    }
     return null;
   }
 }
@@ -157,12 +174,13 @@ export async function parseFile(filePath: string): Promise<ParseResult> {
       };
     }
 
-    const symbols = extractSymbols(tree, queries, parserData.grammar, parserData.QueryClass);
+    const { symbols, warnings } = extractSymbols(tree, queries, parserData.grammar, parserData.QueryClass);
 
     return {
       success: true,
       language,
       symbols,
+      warnings: warnings.length > 0 ? warnings : undefined,
     };
   } catch (e) {
     return {
@@ -202,6 +220,11 @@ export async function symbolExists(
 // Cache compiled queries to avoid recompilation
 const queryCache = new Map<string, Query>();
 
+interface ExtractResult {
+  symbols: SymbolLocation[];
+  warnings: string[];
+}
+
 /**
  * Extract symbols from a parsed tree using tree-sitter's Query API.
  * This uses the declarative query patterns from ast-queries.ts.
@@ -211,8 +234,9 @@ function extractSymbols(
   queries: LanguageQueries,
   grammar: unknown,
   QueryClass: QueryConstructor
-): SymbolLocation[] {
+): ExtractResult {
   const symbols: SymbolLocation[] = [];
+  const warnings: string[] = [];
   const root = (tree as { rootNode: unknown }).rootNode;
 
   for (const [symbolType, queryDef] of Object.entries(queries)) {
@@ -224,8 +248,8 @@ function extractSymbols(
         query = new QueryClass(grammar, queryDef.query);
         queryCache.set(cacheKey, query);
       } catch (e) {
-        // Query compilation failed - skip this symbol type
-        console.error(`Failed to compile query for ${symbolType}:`, e);
+        const msg = `Query compile failed for ${symbolType}: ${e instanceof Error ? e.message : String(e)}`;
+        warnings.push(msg);
         continue;
       }
     }
@@ -234,23 +258,28 @@ function extractSymbols(
       const matches = query.matches(root);
       for (const match of matches) {
         const nameCapture = match.captures.find(c => c.name === queryDef.nameCapture);
-        if (nameCapture) {
+        // Use defCapture for range if available, otherwise fall back to nameCapture
+        const defCaptureName = queryDef.defCapture || queryDef.nameCapture;
+        const defCapture = match.captures.find(c => c.name === defCaptureName);
+        const rangeNode = defCapture?.node || nameCapture?.node;
+
+        if (nameCapture && rangeNode) {
           symbols.push({
             name: nameCapture.node.text,
-            startLine: nameCapture.node.startPosition.row + 1,
-            endLine: nameCapture.node.endPosition.row + 1,
+            startLine: rangeNode.startPosition.row + 1,
+            endLine: rangeNode.endPosition.row + 1,
             type: symbolType,
           });
         }
       }
     } catch (e) {
-      // Query execution failed - skip this symbol type
-      console.error(`Failed to execute query for ${symbolType}:`, e);
+      const msg = `Query exec failed for ${symbolType}: ${e instanceof Error ? e.message : String(e)}`;
+      warnings.push(msg);
       continue;
     }
   }
 
-  return symbols;
+  return { symbols, warnings };
 }
 
 /**

package/package.json

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

package/.claude/commands/docs-adjust.md

@@ -1,214 +0,0 @@
----
-description: Update documentation incrementally based on code changes
-argument-hint: [--diff] [optional paths or context]
----
-
-<objective>
-Update documentation incrementally based on recent code changes or user-specified scope. Uses taxonomy-based approach for targeted documentation updates.
-</objective>
-
-<context>
-Current branch: !`git branch --show-current`
-Base branch: !`envoy git get-base-branch`
-</context>
-
-<main_agent_role>
-Main agent is ORCHESTRATOR ONLY. Do NOT perform any codebase discovery, file analysis, or documentation planning. All discovery work is delegated to the taxonomist agent.
-
-Main agent responsibilities:
-1. Parse arguments (paths, flags, context)
-2. Verify clean git state
-3. Delegate to taxonomist with raw inputs
-4. Orchestrate writers based on taxonomist output
-5. Handle merging, validation, and PR creation
-</main_agent_role>
-
-<process>
-<step name="parse_arguments">
-Parse $ARGUMENTS:
-- `--diff` flag: pass to taxonomist for git-based discovery
-- Paths: pass to taxonomist as scope
-- Context: pass to taxonomist as user guidance
-
-Do NOT run discovery commands - pass raw inputs to taxonomist.
-</step>
-
-<step name="ensure_committed_state">
-Before delegating to taxonomist, verify clean git state:
-
-1. Check for uncommitted changes:
-   ```bash
-   git status --porcelain
-   ```
-
-2. If changes exist:
-   - Use AskUserQuestion: "Uncommitted changes detected. Documentation requires committed state for valid reference hashes."
-   - Options:
-     - "Commit now" - propose message, gate for approval
-     - "Stash and continue" - `git stash`
-     - "Cancel" - abort workflow
-
-3. If "Commit now":
-   - Run `git diff --cached --stat` for context
-   - Propose commit message based on staged changes
-   - Gate for user approval
-   - Execute: `git add -A && git commit -m "<approved message>"`
-
-4. If "Stash and continue":
-   - Execute: `git stash push -m "pre-docs stash"`
-   - Note: remind user to `git stash pop` after docs complete
-
-5. Verify clean state before proceeding:
-   ```bash
-   git status --porcelain
-   ```
-   Must return empty.
-</step>
-
-<step name="delegate_to_taxonomist">
-Delegate to **documentation-taxonomist agent** with adjust-workflow.
-
-Taxonomist handles ALL discovery: analyzing codebase, checking existing docs, identifying affected domains, creating directory structure.
-
-**INPUTS:**
-```yaml
-mode: "adjust"
-use_diff: true | false  # from --diff flag
-scope_paths: [<paths from arguments, if any>]
-user_request: "<optional context from user>"
-feature_branch: "<current_branch>"
-```
-
-**OUTPUTS:**
-```yaml
-success: true
-segments:
-  - domain: "<domain-name>"
-    files: ["<glob-patterns>"]
-    output_path: "docs/<domain>/"
-    depth: "overview" | "detailed" | "comprehensive"
-    notes: "<guidance>"
-    action: "create" | "update"
-```
-</step>
-
-<step name="parallel_writers">
-If multiple segments, delegate to **documentation-writer agents** in parallel.
-
-If single segment, delegate to single writer.
-
-**INPUTS (per writer):**
-```yaml
-mode: "write"
-domain: "<segment.domain>"
-files: <segment.files>
-output_path: "<segment.output_path>"
-depth: "<segment.depth>"
-notes: "<segment.notes>"
-```
-
-**OUTPUTS:**
-```yaml
-success: true
-```
-
-Writers work directly on the branch. Taxonomist ensures non-overlapping output directories, so no conflicts occur.
-</step>
-
-<step name="validate_and_report">
-Run validation: `envoy docs validate`
-
-If stale/invalid refs found:
-- Present findings to user
-- Delegate single writer with fix-workflow if user approves
-</step>
-
-<step name="commit_documentation">
-Commit any uncommitted documentation changes (e.g., validation fixes):
-
-1. Check for uncommitted changes in docs/:
-   ```bash
-   git status --porcelain docs/
-   ```
-
-2. If changes exist:
-   ```bash
-   git add docs/
-   git commit -m "docs: update documentation"
-   ```
-
-3. Track documentation files for reindex:
-   - Get list of doc files created/modified since branch diverged from base:
-   ```bash
-   git diff --name-only $(git merge-base HEAD <base_branch>)..HEAD -- docs/
-   ```
-   - Store this list for the reindex step
-</step>
-
-<step name="reindex_knowledge">
-Update semantic search index with changed documentation:
-
-1. Build file changes JSON from tracked doc files:
-   ```json
-   [
-     {"path": "docs/domain/index.md", "added": true},
-     {"path": "docs/domain/subdomain/index.md", "modified": true}
-   ]
-   ```
-   - Use `added: true` for new files
-   - Use `modified: true` for updated files
-   - Use `deleted: true` for removed files
-
-2. Call reindex:
-   ```bash
-   envoy knowledge reindex-from-changes docs --files '<json_array>'
-   ```
-
-3. If reindex reports missing references:
-   - Log warning but continue (docs may reference code not yet indexed)
-</step>
-
-<step name="finalize">
-If in workflow context (called from /continue):
-- Return success without creating PR
-- Let parent workflow handle PR
-
-If standalone:
-- Create PR if changes made
-- Report completion
-</step>
-</process>
-
-<workflow_integration>
-When called from `/continue` or implementation workflow:
-- Skip PR creation
-- Return `{ success: true }` for workflow to continue
-- Validation warnings go to workflow orchestrator
-
-When called standalone:
-- Create PR with changes
-- Present validation results to user
-</workflow_integration>
-
-<success_criteria>
-- Changed files identified (if --diff)
-- Taxonomist created targeted segments with non-overlapping output directories
-- Writers updated relevant docs
-- Validation run
-- Documentation committed
-- Knowledge index updated
-- PR created (if standalone)
-</success_criteria>
-
-<constraints>
-- MUST NOT perform codebase discovery - delegate ALL discovery to taxonomist
-- MUST NOT run envoy docs tree, envoy docs complexity, or envoy knowledge search
-- MUST verify clean git state before documentation (ensure_committed_state step)
-- MUST delegate to taxonomist for all segmentation and discovery
-- MUST pass --diff flag to taxonomist (not process it directly)
-- MUST work both standalone and in workflow context
-- MUST validate after documentation
-- MUST commit documentation changes before reindex (reindex reads from disk)
-- MUST reindex knowledge base after documentation committed
-- All delegations MUST follow INPUTS/OUTPUTS format
-</constraints>