claude-all-hands 1.0.1 → 1.0.3

package/.claude/skills/implementation-mode/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: implementation-mode
+description: Prompt execution lifecycle for implementing plan tasks. Handles prompt reading, implementation, history tracking, and review iteration.
+---
+
+<objective>
+Execute individual prompts from an active plan. Read prompt → implement → track history → get review feedback → iterate until complete.
+</objective>
+
+<quick_start>
+```bash
+# 1. Get prompt to implement
+envoy plans get-prompt <task-number>
+
+# 2. Implement using Glob, Grep, Read for context
+
+# 3. Track progress
+envoy plans append-history <task> --summary "Added auth middleware" --files '["src/auth.ts"]'
+
+# 4. Get review
+envoy plans review-prompt <task>
+
+# 5. Commit when review passes
+git commit -m "task-<N>: <summary>"
+```
+</quick_start>
+
+<workflow>
+### 1. Get Prompt
+```bash
+envoy plans get-prompt <task-number>
+```
+Returns: prompt content + existing history
+
+### 2. Setup (if variant)
+If implementing a variant prompt:
+```bash
+git worktree add .worktrees/task-N-V <branch>
+```
+
+### 3. Implement
+- Use Glob, Grep, Read for context gathering
+- Make code changes per prompt instructions
+- Follow existing codebase patterns
+
+### 4. Track History
+After each significant change:
+```bash
+envoy plans append-history <task> \
+  --summary "Brief description of change" \
+  --files '["path/to/changed.ts", "path/to/other.ts"]'
+```
+
+### 5. Get Review
+```bash
+envoy plans review-prompt <task>
+```
+If changes needed → fix → append-history → review again
+
+### 6. Commit
+When review passes:
+```bash
+git commit -m "task-<N>: <summary>"
+```
+
+### 7. Return Status
+```yaml
+status: completed | needs_attention
+summary: "one line"
+files_changed: [list]
+history_entries: N
+```
+</workflow>
+
+<constraints>
+- **Append history after changes** - maintains audit trail
+- **Review before commit** - ensure implementation matches prompt
+- **Worktree cleanup** - handled by git checkout hooks
+</constraints>
+
+<modes>
+### NORMAL Mode (default)
+Full workflow: get-prompt → implement → history → review → commit
+
+### FEEDBACK Mode
+Called when specialist returns to address review issues from /complete.
+
+**Trigger**: Main agent delegates with "FEEDBACK MODE" context
+</modes>
+
+<feedback_mode>
+Comprehensive workflow for addressing review feedback after /complete.
+
+<trigger>
+Main agent delegates with FEEDBACK MODE flag and review feedback content.
+</trigger>
+
+<input_format>
+Main agent provides:
+- `FEEDBACK MODE` marker
+- Review feedback (issues array from vertex review)
+- Optional: file paths mentioned in feedback
+</input_format>
+
+<workflow>
+### 1. Parse Feedback
+Extract actionable items from review feedback:
+- Specific issues to fix
+- File locations mentioned
+- Severity/priority if indicated
+
+DO NOT read prompt files - feedback IS the task.
+
+### 2. Implement Fixes
+For each issue:
+1. Locate relevant code (use Grep/Read)
+2. Make targeted fix
+3. Keep changes minimal - only what's needed for the issue
+
+### 3. Review Changes
+```bash
+envoy vertex review --last-commit
+```
+
+| Response | Action |
+|----------|--------|
+| verdict: approved | Continue to Step 4 |
+| verdict: needs_work | Extract new issues, return to Step 2 |
+| verdict: off_track | Return to main agent with failure report |
+
+### 4. Commit
+When review passes:
+```bash
+git add -A && git commit -m "fix: address review feedback"
+```
+
+### 5. Return to Main Agent
+```yaml
+status: completed
+mode: feedback
+fixes_applied: [list of issues addressed]
+review_verdict: approved
+commit_id: <sha>
+```
+</workflow>
+
+<constraints>
+- **NO prompt reading** - feedback is your only input
+- **Minimal changes** - fix only what's flagged
+- **Max 3 iterations** - if still failing after 3 review cycles, return with failure
+- **No history tracking** - not a prompt implementation
+</constraints>
+
+<failure_handling>
+If review fails 3 times or returns "off_track":
+```yaml
+status: needs_attention
+mode: feedback
+reason: "Review failed after N iterations"
+remaining_issues: [unresolved items]
+```
+Main agent will escalate to user.
+</failure_handling>
+</feedback_mode>
+
+<success_criteria>
+- Prompt requirements implemented (NORMAL) OR feedback addressed (FEEDBACK)
+- History entries recorded (NORMAL only)
+- Review passes
+- Clean commit created
+</success_criteria>

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/.claude/skills/research-tools/SKILL.md

@@ -1,10 +1,10 @@
 ---
 name: research-tools
-description: Use when need to "search the web", "research [topic]", "extract URL content", or "find sources". Provides web search (Tavily), deep research (Perplexity), and X/Twitter insights (Grok). Only for curator/researcher agents.
+description: External research via envoy commands. Use for "search the web", "research [topic]", "extract URL content", "find sources". Provides Tavily (search/extract), Perplexity (deep research), Grok (X/Twitter). Curator/researcher agents only.
 ---
 
 <objective>
-External research capability for curator and researcher agents. Provides web search, deep research with citations, and real-time social signals via envoy commands.
+External research capability for curator/researcher agents. Web search, deep research with citations, and real-time social signals via envoy commands.
 </objective>
 
 <quick_start>
@@ -20,71 +20,66 @@ envoy tavily extract "url1" "url2"
 ```
 </quick_start>
 
-<success_criteria>
-- JSON response with `status: success` and `data` containing findings
-- Sources/citations included for synthesis queries
-- Content extracted for known URLs
-</success_criteria>
-
 <constraints>
 - Only curator/researcher agents may use these tools
 - GitHub content: use `gh` CLI instead of extract
 - All commands return JSON - parse `data.content` or `data.results`
+- Use TODAY's date for time-sensitive queries: `date +%Y-%m-%d`
 </constraints>
 
 <workflow>
-### 1. Scope the Query
-- What specifically needs to be learned?
-- What will the findings be used for?
-- What level of depth is needed?
-
-### 2. Choose Approach
+<step name="scope">
+Clarify: What to learn? What for? Depth needed?
+</step>
 
+<step name="choose_tool">
 | Need | Tool | Cost |
 |------|------|------|
-| Broad question, need synthesis | `perplexity research` | High |
+| Broad question, synthesis | `perplexity research` | High |
 | Synthesis + real-time validation | `perplexity research --grok-challenge` | Higher |
 | X/Twitter community insights | `xai search` | Medium |
 | Find sources, discover URLs | `tavily search` | Medium |
-| Get full content from known URL | `tavily extract` | Low |
+| Full content from known URL | `tavily extract` | Low |
+</step>
 
-### 3. Process Results
+<step name="process_results">
 All tools return JSON. Parse `data.content` or `data.results` for findings.
+</step>
 </workflow>
 
 <examples>
-### Command Reference
+<command_reference>
 ```bash
-# Deep research with citations (Perplexity)
+# Perplexity (deep research)
 envoy perplexity research "query"
-envoy perplexity research "query" --grok-challenge  # validate via X search
+envoy perplexity research "query" --grok-challenge
 
-# X/Twitter search (Grok)
+# Grok (X/Twitter)
 envoy xai search "query"
-envoy xai search "query" --results-to-challenge "findings"  # challenger mode
+envoy xai search "query" --results-to-challenge "findings"
 
-# Web search (Tavily)
+# Tavily (web search/extract)
 envoy tavily search "query"
 envoy tavily search "query" --max-results 10
-
-# Extract content from URLs (Tavily)
 envoy tavily extract "url1" "url2"
 
-# GitHub content (use gh CLI)
+# GitHub (use gh CLI)
 gh api repos/{owner}/{repo}/contents/{path}
 gh issue view {number} --repo {owner}/{repo}
 ```
+</command_reference>
 
-### Decision Tree
+<decision_tree>
 ```
 Need information?
-├─ Know the exact URL? → tavily extract
+├─ Know exact URL? → tavily extract
 ├─ Need to find sources? → tavily search → extract promising URLs
 ├─ Tech research for planning? → perplexity research --grok-challenge
 └─ Quick answer, no validation? → perplexity research
 ```
+</decision_tree>
 
-### Output Format
+<output_format>
 ```markdown
 ## Research: [Topic]
 
@@ -92,16 +87,23 @@ Need information?
 - Finding with context
 
 ### Sources
-- [Source URL] - what was relevant
+- [URL] - relevance
 
 ### Recommendations
-What to do based on findings.
+Actions based on findings.
 ```
+</output_format>
 </examples>
 
 <anti_patterns>
-- Using extract for GitHub content (use `gh` CLI instead)
+- Using extract for GitHub content (use `gh` CLI)
 - Skipping scope clarification before research
 - Not parsing JSON response properly
-- Using research tools from non-curator/researcher agents
+- Using from non-curator/researcher agents
 </anti_patterns>
+
+<success_criteria>
+- JSON response: `status: success` with `data` containing findings
+- Sources/citations included for synthesis queries
+- Content extracted for known URLs
+</success_criteria>

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

@@ -0,0 +1,192 @@
+---
+name: skills-development
+description: Expert guidance for creating, refining, and auditing Claude Code Skills. Use when working with SKILL.md files, authoring new skills, improving/auditing existing skills, or understanding skill structure and best practices.
+---
+
+<essential_principles>
+## How Skills Work
+
+Skills are modular, filesystem-based capabilities that provide domain expertise on demand. This skill teaches how to create effective skills.
+
+### 1. Skills Are Prompts
+
+All prompting best practices apply. Be clear, be direct, use XML structure. Assume Claude is smart - only add context Claude doesn't have.
+
+### 2. SKILL.md Is Always Loaded
+
+When a skill is invoked, Claude reads SKILL.md. Use this guarantee:
+- Essential principles go in SKILL.md (can't be skipped)
+- Workflow-specific content goes in workflows/
+- Reusable knowledge goes in references/
+
+### 3. Router Pattern for Complex Skills
+
+```
+skill-name/
+├── SKILL.md              # Router + principles
+├── workflows/            # Step-by-step procedures (FOLLOW)
+├── references/           # Domain knowledge (READ)
+├── templates/            # Output structures (COPY + FILL)
+└── scripts/              # Reusable code (EXECUTE)
+```
+
+SKILL.md asks "what do you want to do?" → routes to workflow → workflow specifies which references to read.
+
+**When to use each folder:**
+- **workflows/** - Multi-step procedures Claude follows
+- **references/** - Domain knowledge Claude reads for context
+- **templates/** - Consistent output structures Claude copies and fills (plans, specs, configs)
+- **scripts/** - Executable code Claude runs as-is (deploy, setup, API calls)
+
+### 4. Pure XML Structure
+
+No markdown headings (#, ##, ###) in skill body. Use semantic XML tags:
+```xml
+<objective>...</objective>
+<process>...</process>
+<success_criteria>...</success_criteria>
+```
+
+Keep markdown formatting within content (bold, lists, code blocks).
+
+### 5. Progressive Disclosure
+
+SKILL.md under 500 lines. Split detailed content into reference files. Load only what's needed for the current workflow.
+</essential_principles>
+
+<intake>
+What would you like to do?
+
+1. Create new skill
+2. Audit/modify existing skill
+3. Add component (workflow/reference/template/script)
+4. Get guidance
+
+**Wait for response before proceeding.**
+</intake>
+
+<routing>
+| Response | Next Action | Workflow |
+|----------|-------------|----------|
+| 1, "create", "new", "build" | Ask: "Task-execution skill or domain expertise skill?" | Route to appropriate create workflow |
+| 2, "audit", "modify", "existing" | Ask: "Path to skill?" | Route to appropriate workflow |
+| 3, "add", "component" | Ask: "Add what? (workflow/reference/template/script)" | workflows/add-{type}.md |
+| 4, "guidance", "help" | General guidance | workflows/get-guidance.md |
+
+**Progressive disclosure for option 1 (create):**
+- If user selects "Task-execution skill" → workflows/create-new-skill.md
+- If user selects "Domain expertise skill" → workflows/create-domain-expertise-skill.md
+
+**Progressive disclosure for option 3 (add component):**
+- If user specifies workflow → workflows/add-workflow.md
+- If user specifies reference → workflows/add-reference.md
+- If user specifies template → workflows/add-template.md
+- If user specifies script → workflows/add-script.md
+
+**Intent-based routing (if user provides clear intent without selecting menu):**
+- "audit this skill", "check skill", "review" → workflows/audit-skill.md
+- "verify content", "check if current" → workflows/verify-skill.md
+- "create domain expertise", "exhaustive knowledge base" → workflows/create-domain-expertise-skill.md
+- "create skill for X", "build new skill" → workflows/create-new-skill.md
+- "add workflow", "add reference", etc. → workflows/add-{type}.md
+- "upgrade to router" → workflows/upgrade-to-router.md
+
+**After reading the workflow, follow it exactly.**
+</routing>
+
+<quick_reference>
+## Skill Structure Quick Reference
+
+**Simple skill (single file):**
+```yaml
+---
+name: skill-name
+description: What it does and when to use it.
+---
+
+<objective>What this skill does</objective>
+<quick_start>Immediate actionable guidance</quick_start>
+<process>Step-by-step procedure</process>
+<success_criteria>How to know it worked</success_criteria>
+```
+
+**Complex skill (router pattern):**
+```
+SKILL.md:
+  <essential_principles> - Always applies
+  <intake> - Question to ask
+  <routing> - Maps answers to workflows
+
+workflows/:
+  <required_reading> - Which refs to load
+  <process> - Steps
+  <success_criteria> - Done when...
+
+references/:
+  Domain knowledge, patterns, examples
+
+templates/:
+  Output structures Claude copies and fills
+  (plans, specs, configs, documents)
+
+scripts/:
+  Executable code Claude runs as-is
+  (deploy, setup, API calls, data processing)
+```
+</quick_reference>
+
+<reference_index>
+## Domain Knowledge
+
+All in `references/`:
+
+**Structure:** recommended-structure.md, skill-structure.md
+**Principles:** core-principles.md, be-clear-and-direct.md, use-xml-tags.md
+**Patterns:** common-patterns.md, workflows-and-validation.md
+**Assets:** using-templates.md, using-scripts.md
+**Advanced:** executable-code.md, api-security.md, iteration-and-testing.md
+</reference_index>
+
+<workflows_index>
+## Workflows
+
+All in `workflows/`:
+
+| Workflow | Purpose |
+|----------|---------|
+| create-new-skill.md | Build a skill from scratch |
+| create-domain-expertise-skill.md | Build exhaustive domain knowledge base for build/ |
+| audit-skill.md | Analyze skill against best practices |
+| verify-skill.md | Check if content is still accurate |
+| add-workflow.md | Add a workflow to existing skill |
+| add-reference.md | Add a reference to existing skill |
+| add-template.md | Add a template to existing skill |
+| add-script.md | Add a script to existing skill |
+| upgrade-to-router.md | Convert simple skill to router pattern |
+| get-guidance.md | Help decide what kind of skill to build |
+</workflows_index>
+
+<yaml_requirements>
+## YAML Frontmatter
+
+Required fields:
+```yaml
+---
+name: skill-name          # lowercase-with-hyphens, matches directory
+description: ...          # What it does AND when to use it (third person)
+---
+```
+
+Name conventions: `create-*`, `manage-*`, `setup-*`, `generate-*`, `build-*`
+</yaml_requirements>
+
+<success_criteria>
+A well-structured skill:
+- Has valid YAML frontmatter
+- Uses pure XML structure (no markdown headings in body)
+- Has essential principles inline in SKILL.md
+- Routes directly to appropriate workflows based on user intent
+- Keeps SKILL.md under 500 lines
+- Asks minimal clarifying questions only when truly needed
+- Has been tested with real usage
+</success_criteria>