claude-all-hands 1.0.1 → 1.0.3

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

@@ -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

@@ -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>

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

@@ -0,0 +1,210 @@
+---
+description: Initialize documentation for codebase (full documentation generation)
+argument-hint: [...optional paths] [optional context]
+---
+
+<objective>
+Create comprehensive documentation for the codebase from scratch. Uses taxonomy-based approach with parallel documentation writers. Taxonomist ensures non-overlapping output directories, so writers work directly on the branch without conflicts.
+</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. Setup branch (create docs branch if on base)
+2. Parse arguments (paths, context)
+3. Verify clean git state
+4. Delegate to taxonomist with raw inputs
+5. Orchestrate writers based on taxonomist output
+6. Handle merging, validation, and PR creation
+</main_agent_role>
+
+<process>
+<step name="setup_branch">
+Check if current branch equals base branch:
+
+**If on base branch:**
+1. Create docs branch: `docs/init-<timestamp>`
+2. Document from fresh docs branch
+
+**If on feature branch:**
+1. Stay on current branch
+2. Document from feature branch state (no branch switching)
+</step>
+
+<step name="parse_arguments">
+Parse $ARGUMENTS:
+- Extract paths (pass to taxonomist as scope)
+- Extract optional user context (pass to taxonomist)
+
+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 init-workflow.
+
+Taxonomist handles ALL discovery: analyzing codebase structure, checking existing docs, identifying products/features, creating directory structure, assigning writers.
+
+**INPUTS:**
+```yaml
+mode: "init"
+scope_paths: [<paths from arguments, or empty for full codebase>]
+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>"
+```
+</step>
+
+<step name="parallel_writers">
+For each segment from taxonomist, delegate to **documentation-writer agent** in parallel:
+
+**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_docs">
+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: finalize documentation"
+   ```
+
+3. Track documentation files for reindex:
+   - Get list of all 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 new documentation:
+
+1. Build file changes JSON from tracked doc files:
+   ```json
+   [
+     {"path": "docs/domain/index.md", "added": true},
+     {"path": "docs/domain/subdomain/index.md", "added": true}
+   ]
+   ```
+   - Use `added: true` for new files
+   - Use `modified: true` for updated 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)
+   - These will resolve on next full reindex
+</step>
+
+<step name="create_pr">
+Create PR:
+```bash
+envoy git create-pr --title "docs: initialize codebase documentation" --body "<summary>"
+```
+
+Report completion with PR link.
+</step>
+</process>
+
+<success_criteria>
+- Branch setup complete (docs branch from base OR stay on feature)
+- Taxonomist segmented codebase with non-overlapping output directories
+- Writers created docs in parallel
+- Validation passed
+- Documentation committed
+- Knowledge index updated
+- PR created
+</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 only create docs branch if already on base branch
+- MUST delegate to taxonomist for all segmentation and discovery
+- MUST run writers in parallel
+- MUST validate before PR
+- 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>