npm - claude-all-hands - Versions diffs - 1.0.2 → 1.0.3 - Mend

claude-all-hands 1.0.2 → 1.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/.claude/agents/curator.md +1 -5
package/.claude/agents/documentation-taxonomist.md +255 -0
package/.claude/agents/documentation-writer.md +366 -0
package/.claude/agents/surveyor.md +1 -1
package/.claude/commands/continue.md +12 -10
package/.claude/commands/create-skill.md +2 -2
package/.claude/commands/create-specialist.md +3 -3
package/.claude/commands/debug.md +5 -5
package/.claude/commands/docs-adjust.md +214 -0
package/.claude/commands/docs-audit.md +172 -0
package/.claude/commands/docs-init.md +210 -0
package/.claude/commands/plan.md +6 -6
package/.claude/commands/whats-next.md +2 -2
package/.claude/envoy/README.md +5 -5
package/.claude/envoy/package-lock.json +216 -10
package/.claude/envoy/package.json +9 -0
package/.claude/envoy/src/commands/docs.ts +881 -0
package/.claude/envoy/src/commands/knowledge.ts +33 -42
package/.claude/envoy/src/lib/ast-queries.ts +261 -0
package/.claude/envoy/src/lib/knowledge.ts +176 -124
package/.claude/envoy/src/lib/tree-sitter-utils.ts +301 -0
package/.claude/envoy/src/types/tree-sitter.d.ts +76 -0
package/.claude/hooks/scripts/enforce_research_fetch.py +1 -1
package/.claude/protocols/bug-discovery.yaml +1 -1
package/.claude/protocols/discovery.yaml +1 -1
package/.claude/settings.json +4 -3
package/.claude/skills/discovery-mode/SKILL.md +7 -7
package/.claude/skills/documentation-taxonomy/SKILL.md +287 -0
package/.claude/skills/implementation-mode/SKILL.md +7 -7
package/.claude/skills/knowledge-discovery/SKILL.md +178 -0
package/bin/cli.js +41 -1
package/package.json +1 -1
package/.claude/agents/documentor.md +0 -147
package/.claude/commands/audit-docs.md +0 -94
package/.claude/commands/create-docs.md +0 -100

package/.claude/commands/continue.md CHANGED Viewed

@@ -7,12 +7,12 @@ Loop through plan prompts, delegate to specialists for implementation, extract d
 </objective>
 <context>
-Plan status: !`.claude/envoy/envoy plan check`
+Plan status: !`envoy plan check`
 </context>
 <process>
 <step name="get_next_prompts">
-Call `.claude/envoy/envoy plan next [-n <count>]`
+Call `envoy plan next [-n <count>]`
 Returns next available prompts respecting dependencies:
 - If count > 1: returns independent prompts that can run in parallel
@@ -45,9 +45,10 @@ For each prompt from next:
 <step name="extract_documentation">
 After each specialist returns (prompt merged):
-Delegate to **documentor agent**:
-* "Run the extract-workflow. INPUTS: `{ mode: 'extract', prompt_num: <N>, variant: <V>, feature_branch: <current_branch> }`"
-* OUTPUTS: `{ success: true }`
+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">
@@ -57,7 +58,7 @@ Repeat steps 1-3 until:
 </step>
 <step name="full_review">
-Call `.claude/envoy/envoy gemini review --full`
+Call `envoy gemini review --full`
 Returns: `{ verdict, thoughts?, answered_questions?, suggested_fixes? }`
@@ -80,13 +81,14 @@ If verdict = "failed" OR suggested_fixes exist:
 </step>
 <step name="mandatory_doc_audit">
-Delegate to **documentor agent**:
-* "Run the audit-workflow. INPUTS: `{ mode: 'audit', feature_branch: <current_branch> }`"
-* OUTPUTS: `{ success: true }`
+Call `/docs audit` 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 }`
 </step>
 <step name="complete_plan">
-Call `.claude/envoy/envoy plan complete`
+Call `envoy plan complete`
 This:
 - Generates summary.md

package/.claude/commands/create-skill.md CHANGED Viewed

@@ -80,8 +80,8 @@ If "Need changes":
 Commit any final changes.
 Check branch status:
-- Call `.claude/envoy/envoy git is-base-branch` on parent branch
-- If parent is base branch: Create PR via `.claude/envoy/envoy git create-pr --title "<title>" --body "<body>"`
+- Call `envoy git is-base-branch` on parent branch
+- If parent is base branch: Create PR via `envoy git create-pr --title "<title>" --body "<body>"`
 - If parent has plan matter: Merge back to parent, add updates to curator.md
 Report completion with next steps.

package/.claude/commands/create-specialist.md CHANGED Viewed

@@ -9,7 +9,7 @@ Create a new specialist agent tailored to a specific domain. Gathers requirement
 <context>
 Current branch: !`git branch --show-current`
-Available envoy commands: !`.claude/envoy/envoy --help`
+Available envoy commands: !`envoy --help`
 Existing agents: !`ls -la .claude/agents/`
 </context>
@@ -84,8 +84,8 @@ If "Need changes":
 Commit any final changes.
 Check branch status:
-- Call `.claude/envoy/envoy git is-base-branch` on parent branch
-- If parent is base branch: Create PR via `.claude/envoy/envoy git create-pr --title "<title>" --body "<body>"`
+- Call `envoy git is-base-branch` on parent branch
+- If parent is base branch: Create PR via `envoy git create-pr --title "<title>" --body "<body>"`
 - If parent has plan matter: Merge back to parent, add updates to curator.md
 Report completion with next steps.

package/.claude/commands/debug.md CHANGED Viewed

@@ -13,7 +13,7 @@ Modes:
 </objective>
 <context>
-Plan status: !`.claude/envoy/envoy plan check`
+Plan status: !`envoy plan check`
 </context>
 <process>
@@ -30,7 +30,7 @@ Parse $ARGUMENTS for mode flags and bug description:
 1. Call `envoy plan check` to get status
 2. If no plan: Create branch from bug description (infer name)
-3. Append bug description: `.claude/envoy/envoy plan append-user-input "<bug_description>"`
+3. Append bug description: `envoy plan append-user-input "<bug_description>"`
 4. Delegate to **planner agent**:
    * "Run the planning-workflow. INPUTS: `{ mode: 'quick', workflow_type: 'debug', feature_branch: <current_branch>, plan_status: <status> }`"
    * OUTPUTS: `{ success: true }`
@@ -77,7 +77,7 @@ If user chooses "start fresh": create new branch off base, set mode = "create"
 <step name="write_user_input">
 Append all gathered context to user_input.md:
-`.claude/envoy/envoy plan append-user-input "<all_gathered_context>"`
+`envoy plan append-user-input "<all_gathered_context>"`
 </step>
 <step name="specialist_delegation">
@@ -93,7 +93,7 @@ Append all gathered context to user_input.md:
 </step>
 <step name="get_findings">
-Call `.claude/envoy/envoy plan get-findings` to get bug hypotheses/approaches
+Call `envoy plan get-findings` to get bug hypotheses/approaches
 </step>
 <step name="research_delegation">
@@ -107,7 +107,7 @@ For each research objective (known library issues, similar errors, anti-patterns
 1. Present all clarifying questions from approach documents (bug hypotheses) to user
 2. AskUserQuestion: "Want to redirect investigation with specific requirements? (clears all findings)"
    - If yes: clear findings, return to specialist_delegation step
-3. Call `.claude/envoy/envoy plan block-findings-gate`
+3. Call `envoy plan block-findings-gate`
    - Returns: `{ thoughts, affected_approaches: [{ specialist_name, approach_number }] }`
 4. If affected_approaches exist:
    - Re-delegate to affected specialists with thoughts context

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

@@ -0,0 +1,214 @@
+---
+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>

package/.claude/commands/docs-audit.md ADDED Viewed

@@ -0,0 +1,172 @@
+---
+description: Audit documentation for stale/invalid symbol references
+argument-hint: [--fix] [optional docs path]
+---
+<objective>
+Validate all documentation symbol references and fix stale/invalid references via documentation-writer agents. Main agent NEVER fixes documentation directly - writers must review source diffs to ensure prose accuracy.
+</objective>
+<context>
+Current branch: !`git branch --show-current`
+</context>
+<critical-constraint>
+**MAIN AGENT MUST NEVER EDIT DOCUMENTATION FILES DIRECTLY.**
+Even "simple" hash updates require documentation-writer review because:
+- Source file changed since doc was written
+- Writer must diff the source change to verify prose still accurate
+- Prose may need rewriting if implementation semantics changed
+- Only documentation-writer agents have the context and mandate to make doc changes
+</critical-constraint>
+<process>
+<step name="parse_arguments">
+Parse $ARGUMENTS:
+- `--fix` flag: automatically fix issues after presenting findings
+- Path: specific docs path to audit (default: docs/)
+</step>
+<step name="run_validation">
+Run validation:
+```bash
+envoy docs validate [--path <docs_path>]
+```
+Parse output - the `by_doc_file` field contains issues grouped by documentation file.
+</step>
+<step name="present_findings">
+Present findings **grouped by doc file** (matching delegation format):
+```markdown
+## Documentation Audit Results
+**Total references:** {total_refs}
+**Stale:** {stale_count} | **Invalid:** {invalid_count}
+**Doc files affected:** {affected_file_count}
+### By Documentation File
+**{doc_file_1}** ({issue_count} issues)
+| Type | Reference | Details |
+|------|-----------|---------|
+| stale | `file.ts` | cf5a964 → 6607b05 |
+| invalid | `removed.ts:fn` | file not found |
+**{doc_file_2}** ({issue_count} issues)
+...
+```
+If no issues:
+- Report "All references valid" and exit
+</step>
+<step name="user_decision">
+If issues found and `--fix` not provided:
+AskUserQuestion: "How should we handle these {issue_count} issues across {file_count} doc files?"
+Options:
+- "Fix all" - Delegate to documentation-writers for review and fixes
+- "Skip" - Don't fix, just report
+If `--fix` provided:
+- Proceed to delegation step automatically
+</step>
+<step name="batch_and_delegate">
+**Batching for parallel delegation (max 5 agents):**
+1. Count affected doc files from `by_doc_file`
+2. If ≤5 files: one agent per file
+3. If >5 files: distribute files across 5 agents
+   - Agent 1: files 1, 6, 11...
+   - Agent 2: files 2, 7, 12...
+   - etc.
+**Delegation format (per agent):**
+Each agent receives a `doc_files` array (1+ files per agent):
+```yaml
+mode: "audit-fix"
+doc_files:
+  - path: "<doc file path>"
+    stale_refs:
+      - reference: "[ref:path/file.ts:symbol:hash]"
+        ref_type: "symbol" | "file-only"
+        file_path: "path/file.ts"
+        symbol_name: "symbol" | null
+        stored_hash: "abc1234"
+        current_hash: "def5678"
+    invalid_refs:
+      - reference: "[ref:path/removed.ts:fn:hash]"
+        reason: "file not found" | "symbol not found"
+  - path: "<another doc file>"
+    stale_refs: [...]
+    invalid_refs: [...]
+```
+**Extract from reference string:**
+- `[ref:path/to/file.ts:symbolName:hash]` → file_path="path/to/file.ts", symbol_name="symbolName"
+- `[ref:path/to/file.yaml::hash]` → file_path="path/to/file.yaml", symbol_name=null
+**Launch all agents in parallel using single message with multiple Task tool calls.**
+**Expected output (per agent):**
+```yaml
+success: true
+doc_files_processed: ["path1", "path2"]
+changes:
+  - doc_file: "<path>"
+    ref: "<reference>"
+    action: "hash_update" | "prose_rewrite" | "ref_removed" | "ref_updated"
+    reason: "<why this action>"
+```
+</step>
+<step name="verify_and_report">
+After all agents complete:
+1. Run validation again:
+```bash
+envoy docs validate [--path <docs_path>]
+```
+2. If issues remain, report which failed and why
+3. Report completion:
+```markdown
+## Audit Complete
+**Agents dispatched:** {agent_count}
+**Files processed:** {file_count}
+**Changes made:**
+- Hash updates: {hash_update_count}
+- Prose rewrites: {prose_rewrite_count}
+- References removed: {ref_removed_count}
+- References updated: {ref_updated_count}
+**Validation:** {pass|fail with details}
+```
+</step>
+</process>
+<success_criteria>
+- Validation run on docs
+- Findings presented grouped by doc file
+- User decision collected (if not --fix)
+- Documentation-writer agents dispatched in parallel (max 5)
+- All agents complete successfully
+- Re-validation passes after fixes
+</success_criteria>
+<constraints>
+- **NEVER edit documentation files directly** - always delegate to documentation-writer
+- MUST present findings grouped by doc file (matches delegation format)
+- MUST batch files if >5 affected (max 5 parallel agents)
+- MUST launch agents in parallel (single message, multiple Task calls)
+- MUST re-validate after fixes complete
+- MUST report any remaining issues after fix attempt
+</constraints>