feat: Add delegate, setperms, and spawn commands

- Add /delegate command for task delegation workflows
- Add /setperms command for permission management
- Add /spawn command for agent spawning
- Add delegate.yaml template for delegation configuration

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

commands/delegate.md

@@ -0,0 +1,665 @@
+---
+description: Delegate tasks to external LLM CLIs (Gemini, OpenAI Codex, Perplexity). Use Gemini's 2M context for large codebases, OpenAI's deep reasoning, Perplexity's web search with citations, or get consensus from multiple models.
+---
+
+# Delegate - Multi-LLM Task Dispatch
+
+> Delegate tasks to external LLMs. Use each model's strengths: Gemini's massive context, OpenAI's reasoning depth, Perplexity's web-grounded answers, or combine them for consensus.
+
+```
+/delegate [provider] [target] [--flags]
+    |
+    +-> Step 1: Detect Provider
+    |     +- gemini (default) -> Gemini CLI
+    |     +- openai / codex   -> OpenAI Codex CLI
+    |     +- perplexity / pplx -> Perplexity CLI (web search)
+    |     +- conclave         -> Multiple providers (consensus mode)
+    |
+    +-> Step 2: Select Mode
+    |     +- analyze (default) -> Codebase analysis
+    |     +- ask "<question>"  -> Direct question
+    |     +- verify "<stmt>"   -> Yes/no verification
+    |     +- compare <a> <b>   -> Diff analysis
+    |
+    +-> Step 3: Configure Autonomy
+    |     +- --auto            -> Enable autonomous mode
+    |     +- --thinking        -> Extended reasoning (where supported)
+    |     +- --quiet           -> Non-interactive, parseable output
+    |
+    +-> Step 4: Execute & Distill
+          +- Run delegated command
+          +- Parse structured output
+          +- Return distilled results to Claude
+```
+
+---
+
+## Quick Start
+
+```bash
+# Basic usage (Gemini, analyze current directory)
+/delegate .
+
+# Ask Gemini a question about the codebase
+/delegate ask "Where is authentication implemented?"
+
+# Use OpenAI Codex for deep reasoning
+/delegate openai . --thinking
+
+# Use Perplexity for web-grounded research
+/delegate perplexity "What are the latest React 19 breaking changes?"
+
+# Get consensus from multiple models
+/delegate conclave "Is this code secure?"
+```
+
+---
+
+## Arguments
+
+```
+$ARGUMENTS
+
+Providers:
+- (none) / gemini    -> Gemini CLI (default, 2M context)
+- openai / codex     -> OpenAI Codex CLI (deep reasoning)
+- perplexity / pplx  -> Perplexity CLI (web search + citations)
+- conclave           -> Multiple providers (consensus mode)
+
+Modes:
+- <path>             -> Analyze target (default mode)
+- ask "<question>"   -> Direct question about codebase
+- verify "<stmt>"    -> Yes/no verification with evidence
+- compare <a> <b>    -> Compare two paths/branches
+
+Flags:
+- --auto             -> Enable autonomous mode (no prompts)
+- --thinking         -> Extended reasoning mode
+- --quiet            -> Non-interactive output (JSON where supported)
+- --model <name>     -> Override default model
+- --save <file>      -> Save output to file
+- --raw              -> Return unprocessed output
+- --brief            -> ~500 char summary
+- --detailed         -> ~5000 char comprehensive breakdown
+- --setup            -> Interactive configuration wizard
+
+Focus flags:
+- --arch             -> Architecture, patterns, structure
+- --security         -> Vulnerabilities, auth, injection
+- --perf             -> Performance bottlenecks
+- --quality          -> Code quality, tech debt
+- --test             -> Test coverage, gaps
+```
+
+---
+
+## Configuration
+
+### Configuration File (Preferred)
+
+Create `~/.claude/delegate.yaml` for all settings including API keys:
+
+```yaml
+# ~/.claude/delegate.yaml
+
+# API Keys (preferred storage method)
+# These take precedence over environment variables
+api_keys:
+  gemini: "your-gemini-api-key-here"
+  openai: "your-openai-api-key-here"
+  perplexity: "your-perplexity-api-key-here"
+
+# Provider Configuration
+providers:
+  gemini:
+    model: gemini-2.5-pro       # Strongest: gemini-2.5-pro
+    default_flags:              # Flash: gemini-2.5-flash (faster, cheaper)
+      - --output-format
+      - json
+
+  openai:
+    model: gpt-5.2               # Strongest (requires ChatGPT login)
+    default_flags:               # Alternatives: gpt-5.1-codex-max, gpt-4o
+      - --quiet
+
+  perplexity:
+    model: sonar-pro             # Best balance: complex queries, more citations
+    default_flags:               # Alternatives: sonar, sonar-reasoning, sonar-reasoning-pro
+      - --citations
+    # Unique: returns web citations with every response
+
+# Conclave (Multi-Model) Settings
+conclave:
+  providers: [gemini, openai]    # Which providers participate
+  require_consensus: true        # All must agree for YES/NO verdicts
+```
+
+### Default Models (Tested \& Working)
+
+| Provider | Default Model | Context | Strengths |
+|----------|---------------|---------|-----------|
+| **Gemini** | `gemini-2.5-pro` | 1M tokens | **Agentic coding assistant** - best for code analysis (refuses non-code tasks) |
+| **Gemini** | `gemini-2.5-flash` | 1M tokens | General-purpose, fast, answers any question |
+| **Gemini** | `gemini-3-pro` | 1M tokens | Most intelligent (requires [Ultra subscription](https://ai.google.dev/gemini-api/docs/models)) |
+| **OpenAI** | gpt-5.2 | 128K tokens | Deep reasoning, best knowledge (ChatGPT login) |
+| **Perplexity** | `sonar-pro` | 200K tokens | **Real-time web search** - best for research, current info, fact-checking |
+
+> **Notes:**
+> - `gemini-2.5-pro` is tuned as a "CLI agent for software engineering" - it deliberately refuses non-coding questions. Perfect for `/delegate` code analysis.
+> - `gemini-2.5-flash` answers general questions but is less capable for complex code tasks.
+> - Gemini 3 Pro requires Google AI Ultra subscription. Free tier users can [join the waitlist](https://developers.googleblog.com/en/5-things-to-try-with-gemini-3-pro-in-gemini-cli/).
+
+### API Key Resolution Order
+
+Keys are resolved in this priority order:
+
+1. **Config file** - `~/.claude/delegate.yaml` (recommended)
+2. **Environment variables** - `GEMINI_API_KEY`, `OPENAI_API_KEY`
+3. **Interactive prompt** - If missing, prompt user in interactive mode
+
+```
+Key Resolution:
+    ~/.claude/delegate.yaml (api_keys.gemini)
+        ↓ (not found)
+    Environment: GEMINI_API_KEY
+        ↓ (not found)
+    Interactive: "Enter Gemini API key: ___"
+        ↓ (entered)
+    Save to config? [y/N]
+```
+
+### First-Time Setup
+
+When `/delegate` is run without configuration:
+
+1. Check for `~/.claude/delegate.yaml`
+2. If missing or incomplete, prompt:
+   ```
+   Gemini API key not found.
+   Enter key (or press Enter to skip Gemini): ___
+
+   OpenAI API key not found.
+   Enter key (or press Enter to skip OpenAI): ___
+
+   Save to ~/.claude/delegate.yaml? [Y/n]
+   ```
+3. Create config file with entered keys
+4. Inform user: "Config saved. Future runs will use stored keys."
+
+### Environment Variables (Fallback)
+
+If you prefer environment variables over config file:
+
+| Variable | Purpose |
+|----------|---------|
+| `GEMINI_API_KEY` | Gemini CLI authentication |
+| `OPENAI_API_KEY` | OpenAI Codex authentication |
+| `PERPLEXITY_API_KEY` | Perplexity CLI authentication |
+
+```bash
+# Add to ~/.bashrc or ~/.zshrc
+export GEMINI_API_KEY="your-key-here"
+export OPENAI_API_KEY="your-key-here"
+export PERPLEXITY_API_KEY="your-key-here"
+```
+
+### Security Notes
+
+- Config file is stored in user's `.claude/` directory (not in project)
+- Never commit API keys to git
+- The `delegate.yaml` should be in `.gitignore` by default
+- Keys in config file take precedence over environment variables
+
+---
+
+## Provider-Specific Flags
+
+### Gemini CLI
+
+| Flag | Mapped From | Effect |
+|------|-------------|--------|
+| `-p "<prompt>"` | (default) | One-off prompt execution |
+| `--yolo` / `-y` | `--auto` | Auto-approve all operations |
+| `--output-format json` | `--quiet` | Structured JSON output |
+| `--output-format text` | (default) | Plain text output |
+| `-m <model>` | `--model` | Specify model |
+
+**Gemini Command Template:**
+```bash
+# Pipe file content via stdin and use positional prompt arg
+cat file.md | gemini -m gemini-2.5-pro "Analyze this code" [--output-format json]
+
+# Or for simple prompts without file content
+gemini -m gemini-2.5-pro "Your prompt here"
+```
+
+> **⚠️ Important Notes:**
+> - Always specify model: `-m gemini-2.5-pro` (recommended) or `-m gemini-2.5-flash` (faster)
+> - Use stdin piping for file content: `cat file.md | gemini -m gemini-2.5-pro "prompt"`
+> - The `-p` flag is deprecated - use positional argument for prompts
+> - DO NOT use `@file.md` syntax - it requires GCP auth (`GOOGLE_CLOUD_PROJECT` env var)
+
+### OpenAI Codex CLI
+
+**Authentication Modes:**
+
+| Auth Method | Command | Default Model | Billing |
+|-------------|---------|---------------|---------|
+| **ChatGPT Login** | `codex login --device-auth` | `gpt-5.2` | Subscription |
+| **API Key** | `codex login --with-api-key` | `gpt-4o` | Pay per token |
+
+> **Recommended:** Use ChatGPT login for subscription-based access. API key mode doesn't support `gpt-5.x-codex` models.
+
+**Available Models (ChatGPT Login):**
+
+| Model | Capability |
+|-------|------------|
+| `gpt-5.2` | Latest frontier - best knowledge, reasoning, coding |
+| `gpt-5.1-codex-max` | Default - flagship for deep/fast reasoning |
+| `gpt-5.1-codex` | Optimized for codex |
+| `gpt-5.1-codex-mini` | Cheaper, faster, less capable |
+| `gpt-5.1` | Broad world knowledge, general reasoning |
+
+| Flag | Mapped From | Effect |
+|------|-------------|--------|
+| `--full-auto` | `--auto` | Autonomous sandboxed execution |
+| `--json` | `--quiet` | JSONL output for parsing |
+| `-m <model>` | `--model` | Specify model |
+| `codex exec` | (CI mode) | Non-interactive runs |
+| `-s read-only` | (default) | Read-only sandbox |
+
+**Codex Command Template:**
+```bash
+codex exec "<prompt>" [--full-auto] [--json] [-m <model>] --skip-git-repo-check
+```
+
+### Perplexity CLI
+
+**Authentication:**
+
+| Auth Method | Setup | Notes |
+|-------------|-------|-------|
+| **Environment Variable** | `export PERPLEXITY_API_KEY="key"` | Standard approach |
+| **Config File** | Add to `~/.claude/delegate.yaml` | Preferred for persistence |
+
+> Get your API key at [perplexity.ai/settings/api](https://www.perplexity.ai/settings/api)
+
+**Available Models:**
+
+| Model | Use Case |
+|-------|----------|
+| `sonar` | Fast, cost-effective for quick facts |
+| `sonar-pro` | Complex queries, more citations (default) |
+| `sonar-reasoning` | Multi-step problem solving |
+| `sonar-reasoning-pro` | Deep reasoning (DeepSeek-R1 based) |
+
+| Flag | Mapped From | Effect |
+|------|-------------|--------|
+| `-m <model>` | `--model` | Specify model |
+| `--no-citations` | (n/a) | Disable citation output |
+| `--json` | `--quiet` | Output raw JSON response |
+| `-s <prompt>` | (n/a) | System prompt |
+
+**Perplexity Command Template:**
+```bash
+# Direct question with citations
+perplexity "What are the latest React 19 breaking changes?"
+
+# Pipe content and analyze
+cat code.py | perplexity -m sonar-pro "Review this code for security issues"
+
+# Use reasoning model for complex analysis
+perplexity -m sonar-reasoning "Explain the tradeoffs of microservices vs monolith"
+```
+
+**Unique Capability:** Every response includes web citations. Use Perplexity when you need:
+- Current information (not in Claude/Gemini training data)
+- Verification with sources
+- Research questions requiring web search
+- Fact-checking claims with citations
+
+---
+
+## Conclave Mode
+
+Conclave mode dispatches tasks to multiple LLMs and has **Claude arbitrate** the results.
+
+```
+/delegate conclave "<query>"
+    │
+    ├─→ Step 1: Dispatch (parallel)
+    │     ├─ Gemini: detailed analysis request
+    │     └─ Codex:  detailed analysis request
+    │
+    ├─→ Step 2: Collect Raw Responses
+    │     ├─ Gemini returns: analysis, evidence, reasoning
+    │     └─ Codex returns:  analysis, evidence, reasoning
+    │
+    └─→ Step 3: Claude Arbitrates
+          ├─ Parse both full responses
+          ├─ Identify agreements & disagreements
+          ├─ Evaluate reasoning quality
+          ├─ Weigh evidence strength
+          └─ Synthesize final verdict
+```
+
+### Claude's Arbitration Role
+
+Claude doesn't just pattern-match YES/NO. Claude:
+
+1. **Reads both full responses** - understands reasoning, not just conclusions
+2. **Identifies agreements** - shared facts, common ground
+3. **Identifies disagreements** - conflicting claims, different interpretations
+4. **Evaluates argument quality** - which reasoning is more sound? more evidence-backed?
+5. **Synthesizes a verdict** - may agree with one, take parts from both, or note uncertainty
+
+### Expert Prompt Template
+
+Request rich, detailed output from each model:
+
+```markdown
+Analyze the following and provide a detailed response:
+
+<query>
+
+Structure your response:
+1. **Assessment** - Your conclusion/finding
+2. **Evidence** - Specific facts, code references, documentation
+3. **Reasoning** - How you reached this conclusion
+4. **Confidence** - How certain (high/medium/low) and why
+5. **Caveats** - What could change this assessment
+```
+
+### Conclave Output Format
+
+```markdown
+## Conclave Analysis: <query>
+
+### Expert Responses
+
+**Gemini's Analysis:**
+<full response with assessment, evidence, reasoning>
+
+**OpenAI's Analysis:**
+<full response with assessment, evidence, reasoning>
+
+---
+
+### Claude's Arbitration
+
+**Agreements:**
+- Both models concur that...
+- Shared evidence: ...
+
+**Disagreements:**
+- Gemini argues: ... (because...)
+- OpenAI argues: ... (because...)
+
+**Evaluation of Reasoning:**
+- Gemini's strength: ...
+- Gemini's weakness: ...
+- OpenAI's strength: ...
+- OpenAI's weakness: ...
+
+---
+
+### Verdict
+
+<Claude's synthesized conclusion drawing on strongest arguments from both>
+
+**Confidence:** HIGH / MEDIUM / LOW
+**Primary basis:** <which reasoning was most convincing>
+**Caveat:** <remaining uncertainty, if any>
+```
+
+### Usage Examples
+
+```bash
+# Security review with arbitration
+/delegate conclave "Is this authentication implementation secure?"
+
+# Architecture decision
+/delegate conclave "Should we use microservices or monolith for this project?"
+
+# Code quality assessment
+/delegate conclave . --quality "Evaluate the test coverage and error handling"
+
+# Verify a claim with multiple perspectives
+/delegate conclave verify "All database queries are properly parameterized"
+```
+
+### When to Use Conclave
+
+| Scenario | Use Conclave? |
+|----------|---------------|
+| High-stakes security review | ✅ Yes |
+| Architecture decisions | ✅ Yes |
+| Resolving ambiguous requirements | ✅ Yes |
+| Routine code analysis | ❌ Single model sufficient |
+| Simple questions | ❌ Overkill |
+
+---
+
+## Execution Protocol
+
+### Step 1: Verify CLI Availability
+
+```bash
+# Check Gemini
+which gemini || echo "Install: https://github.com/google-gemini/gemini-cli"
+
+# Check OpenAI Codex
+which codex || echo "Install: https://github.com/openai/codex"
+
+# Check Perplexity (included in claude-mods toolkit)
+which perplexity || echo "Install: Run tools/install-*.sh from claude-mods"
+```
+
+### Step 2: Parse Provider & Mode
+
+| Input Pattern | Provider | Mode |
+|---------------|----------|------|
+| `/delegate .` | gemini | analyze |
+| `/delegate openai .` | openai | analyze |
+| `/delegate perplexity "..."` | perplexity | ask |
+| `/delegate ask "..."` | gemini | ask |
+| `/delegate codex ask "..."` | openai | ask |
+| `/delegate pplx ask "..."` | perplexity | ask |
+| `/delegate conclave .` | configured | analyze |
+| `/delegate verify "..."` | gemini | verify |
+
+### Step 3: Construct Command
+
+**Always add read-only instruction:**
+> "IMPORTANT: This is a read-only analysis. Do not execute code or modify files."
+
+**Map flags to provider-specific equivalents:**
+
+| Generic Flag | Gemini | OpenAI Codex | Perplexity |
+|--------------|--------|--------------|------------|
+| `--auto` | `--yolo` | `--full-auto` | (n/a) |
+| `--quiet` | `--output-format json` | `--json` | `--json` |
+| `--thinking` | (n/a) | (use default `gpt-5.2`) | `-m sonar-reasoning-pro` |
+| `--model X` | `-m X` | `-m X` | `-m X` |
+
+> **Safety note:** Default mode is read-only analysis. `--auto` explicitly opts into tool execution - use with caution.
+
+### Step 4: Execute
+
+**Important:** Claude reads files using Read tool, then passes content via stdin.
+
+```bash
+# Gemini example: pipe content via stdin
+cat src/main.ts | gemini -m gemini-2.5-pro "IMPORTANT: Read-only analysis. Analyze architecture and patterns."
+
+# OpenAI example (ChatGPT subscription)
+codex exec "Analyze @src/ - architecture and patterns. Read-only, no modifications." --skip-git-repo-check
+
+# Perplexity example: web-grounded research
+perplexity -m sonar-pro "What are the security best practices for JWT tokens in 2025?"
+```
+
+> **Notes:**
+> - For Gemini: Use stdin piping with explicit model (`-m gemini-2.5-pro`)
+> - For Codex: The `@` syntax works (Codex handles file references internally)
+> - Claude should use Read tool to fetch file content for Gemini, pass via stdin
+
+### Step 5: Distill Results
+
+**Brief (~500 chars):** Executive summary only
+**Default (~2000 chars):** Architecture, patterns, issues, recommendations
+**Detailed (~5000 chars):** Full breakdown with file references
+
+---
+
+## Usage Examples
+
+### Basic Analysis
+
+```bash
+# Analyze with Gemini (default)
+/delegate src/
+
+# Analyze with OpenAI Codex
+/delegate openai src/
+
+# Quick architecture overview
+/delegate . --arch --brief
+```
+
+### Questions & Verification
+
+```bash
+# Ask a question (Gemini)
+/delegate ask "How does the authentication flow work?"
+
+# Ask with deep reasoning (OpenAI)
+/delegate openai ask "What are the security implications of this design?" --thinking
+
+# Ask with web-grounded research (Perplexity)
+/delegate perplexity "What are the latest OWASP Top 10 vulnerabilities for 2025?"
+
+# Verify a claim
+/delegate verify "All database queries use parameterized statements"
+```
+
+### Research & Current Info (Perplexity)
+
+```bash
+# Get current information with sources
+/delegate pplx "Is this npm package actively maintained?"
+
+# Research best practices with citations
+/delegate perplexity "What are the recommended JWT token expiration times in 2025?"
+
+# Fact-check a claim
+/delegate pplx "Does React 19 remove support for class components?"
+```
+
+### Autonomous Mode
+
+```bash
+# Let Gemini run without prompts
+/delegate . --auto --security
+
+# Full autonomous with OpenAI
+/delegate openai . --auto --detailed
+```
+
+### Conclave (Multi-Model)
+
+```bash
+# Get consensus on architecture
+/delegate conclave . --arch
+
+# Security verification with multiple opinions
+/delegate conclave verify "This code is safe from SQL injection"
+
+# Compare complex analysis
+/delegate conclave ask "What's the biggest technical debt in this codebase?"
+```
+
+### Saving Output
+
+```bash
+# Save analysis to file
+/delegate . --detailed --save analysis.md
+
+# Save conclave results
+/delegate conclave . --security --save security-audit.md
+```
+
+---
+
+## Error Handling
+
+| Error | Action |
+|-------|--------|
+| CLI not found | Provide install instructions with links |
+| API key missing (interactive) | Prompt for key, offer to save to config |
+| API key missing (non-interactive) | Error with config setup instructions |
+| Rate limited | Suggest waiting or reducing scope |
+| Timeout | Suggest narrower target or `--brief` |
+| Provider unavailable | Fall back to available provider |
+| Config file invalid | Show YAML parse error, suggest fix |
+
+### Missing API Key Flow
+
+**Interactive Mode:**
+```
+Gemini API key not found.
+
+Options:
+  1. Enter key now (will save to ~/.claude/delegate.yaml)
+  2. Set env: export GEMINI_API_KEY="your-key"
+  3. Edit config: ~/.claude/delegate.yaml
+
+Enter key (or 'skip' for OpenAI only): ___
+```
+
+**Non-Interactive Mode (--quiet, CI):**
+```
+ERROR: Gemini API key not found.
+
+Configure in ~/.claude/delegate.yaml:
+  api_keys:
+    gemini: "your-key"
+
+Or set: export GEMINI_API_KEY="your-key"
+```
+
+---
+
+## Migration from /g-slave
+
+The `/delegate` command is the successor to `/g-slave` with expanded capabilities:
+
+| Old | New | Notes |
+|-----|-----|-------|
+| `/g-slave .` | `/delegate .` | Same behavior |
+| `/g-slave ask "..."` | `/delegate ask "..."` | Same behavior |
+| `/g-slave --raw` | `/delegate --raw` | Same behavior |
+| (n/a) | `/delegate openai .` | NEW: OpenAI support |
+| (n/a) | `/delegate conclave .` | NEW: Multi-model consensus |
+| (n/a) | `/delegate --thinking` | NEW: Extended reasoning |
+
+---
+
+## Remember
+
+1. **Claude commands, LLMs execute.** You delegate heavy lifting, receive distilled intel.
+2. **Read-only always.** Never let delegates modify files (unless explicitly autonomous).
+3. **Default to strongest.** Use best available model unless user specifies otherwise.
+4. **Distill by default.** Only pass raw output when requested.
+5. **Conclave for confidence.** When stakes are high, get multiple opinions.
+
+---
+
+## Sources
+
+- [Gemini CLI Headless Mode](https://geminicli.com/docs/cli/headless/)
+- [Gemini CLI GitHub](https://github.com/google-gemini/gemini-cli)
+- [OpenAI Codex CLI Reference](https://developers.openai.com/codex/cli/reference)
+- [OpenAI Codex GitHub](https://github.com/openai/codex)
+- [Perplexity API Docs](https://docs.perplexity.ai/)
+- [Perplexity Model Cards](https://docs.perplexity.ai/guides/model-cards)

commands/setperms.md

@@ -0,0 +1,227 @@
+---
+name: setperms
+description: "Set tool permissions for Claude Code. Configures allowed commands, rules, and preferences in .claude/ directory."
+---
+
+# /init-tools
+
+Initialize Claude Code with modern dev-shell-tools for a comfortable development experience.
+
+## What This Does
+
+**Installs complete dev environment setup:**
+
+1. **Permissions** (`.claude/settings.local.json`) - Pre-approved CLI tools
+2. **Rules** (`.claude/rules/cli-tools.md`) - Instructions to prefer modern tools
+
+Tools from [dev-shell-tools](https://github.com/0xDarkMatter/dev-shell-tools):
+
+**Core Tools:**
+- **Git**: Full git access, lazygit, gh (GitHub CLI)
+- **File ops**: ls, mkdir, cat, wc, tree, eza, bat
+- **Search**: rg (ripgrep), fd, fzf, ast-grep/sg
+- **Navigation**: zoxide/z, broot/br
+- **Data processing**: jq, yq, sd
+- **Diff tools**: delta, difft (difftastic)
+- **Analysis**: tokei, procs, hyperfine
+
+**Dev Tools:**
+- **Package managers**: npm, node, python, uv, pip
+- **Task runners**: just
+- **Network**: curl, http (httpie)
+- **Windows**: powershell
+
+## Execution Flow
+
+```
+/init-tools
+    |
+    +-- Check for existing .claude/ files
+    |     +-- If exists: Ask to overwrite or skip
+    |     +-- If not: Proceed
+    |
+    +-- Create .claude directory
+    +-- Create .claude/rules directory
+    |
+    +-- Write settings.local.json (permissions)
+    +-- Write rules/cli-tools.md (tool preferences)
+```
+
+## Instructions
+
+### Step 1: Check for existing settings
+
+```bash
+ls -la .claude/settings.local.json 2>/dev/null
+ls -la .claude/rules/cli-tools.md 2>/dev/null
+```
+
+If files exist, ask user:
+- **Overwrite**: Replace entirely
+- **Skip**: Keep existing, do nothing
+
+### Step 2: Create directories
+
+```bash
+mkdir -p .claude/rules
+```
+
+### Step 3: Write permissions file
+
+Write to `.claude/settings.local.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(git:*)",
+      "Bash(ls:*)",
+      "Bash(mkdir:*)",
+      "Bash(cat:*)",
+      "Bash(wc:*)",
+      "Bash(tree:*)",
+      "Bash(curl:*)",
+      "Bash(rg:*)",
+      "Bash(fd:*)",
+      "Bash(fzf:*)",
+      "Bash(z:*)",
+      "Bash(zoxide:*)",
+      "Bash(br:*)",
+      "Bash(broot:*)",
+      "Bash(ast-grep:*)",
+      "Bash(sg:*)",
+      "Bash(bat:*)",
+      "Bash(eza:*)",
+      "Bash(delta:*)",
+      "Bash(difft:*)",
+      "Bash(jq:*)",
+      "Bash(yq:*)",
+      "Bash(sd:*)",
+      "Bash(lazygit:*)",
+      "Bash(gh:*)",
+      "Bash(tokei:*)",
+      "Bash(uv:*)",
+      "Bash(just:*)",
+      "Bash(http:*)",
+      "Bash(procs:*)",
+      "Bash(hyperfine:*)",
+      "Bash(npm:*)",
+      "Bash(node:*)",
+      "Bash(python:*)",
+      "Bash(pip:*)",
+      "Bash(powershell -Command:*)",
+      "Bash(powershell.exe:*)"
+    ],
+    "deny": [],
+    "ask": []
+  },
+  "hooks": {}
+}
+```
+
+### Step 4: Write rules file
+
+Write to `.claude/rules/cli-tools.md`:
+
+```markdown
+# CLI Tool Preferences (dev-shell-tools)
+
+ALWAYS prefer modern CLI tools over traditional alternatives.
+
+## File Search & Navigation
+
+| Instead of | Use | Why |
+|------------|-----|-----|
+| `find` | `fd` | 5x faster, respects .gitignore |
+| `grep` | `rg` (ripgrep) | 10x faster, respects .gitignore |
+| `ls` | `eza` | Git status, tree view |
+| `cat` | `bat` | Syntax highlighting |
+| `cd` + manual | `z`/`zoxide` | Frecent directories |
+| `tree` | `eza --tree` | Interactive |
+
+## Data Processing
+
+| Instead of | Use |
+|------------|-----|
+| `sed` | `sd` |
+| Manual JSON | `jq` |
+| Manual YAML | `yq` |
+
+## Git Operations
+
+| Instead of | Use |
+|------------|-----|
+| `git diff` | `delta` or `difft` |
+| Manual git | `lazygit` |
+| GitHub web | `gh` |
+
+## Code Analysis
+
+- Line counts: `tokei`
+- AST search: `ast-grep` / `sg`
+- Benchmarks: `hyperfine`
+
+## Python
+
+| Instead of | Use |
+|------------|-----|
+| `pip` | `uv` |
+| `python -m venv` | `uv venv` |
+
+## Task Running
+
+Prefer `just` over Makefiles.
+
+Reference: https://github.com/0xDarkMatter/dev-shell-tools
+```
+
+### Step 5: Confirm
+
+Report to user:
+```
+Initialized Claude Code with dev-shell-tools:
+
+Created:
+  .claude/settings.local.json  (37 tool permissions)
+  .claude/rules/cli-tools.md   (modern tool preferences)
+
+Claude will now:
+  - Auto-approve dev-shell-tools commands
+  - Prefer fd over find, rg over grep, bat over cat, etc.
+
+To customize: edit files in .claude/
+To add to git: git add .claude/
+```
+
+## Options
+
+| Flag | Effect |
+|------|--------|
+| `--force` | Overwrite existing without asking |
+| `--perms-only` | Only install permissions, skip rules |
+| `--rules-only` | Only install rules, skip permissions |
+| `--minimal` | Minimal permissions (git, ls, cat, mkdir only) |
+| `--full` | Add cloud/container tools (docker, kubectl, terraform, etc.) |
+
+### Full Template (--full)
+
+Adds to permissions:
+```json
+"Bash(docker:*)",
+"Bash(docker-compose:*)",
+"Bash(kubectl:*)",
+"Bash(helm:*)",
+"Bash(terraform:*)",
+"Bash(aws:*)",
+"Bash(gcloud:*)",
+"Bash(az:*)",
+"Bash(wrangler:*)"
+```
+
+## Notes
+
+- Permissions are project-local (don't affect other projects)
+- Rules instruct Claude to prefer modern tools
+- Global settings in `~/.claude/` still apply
+- Restart Claude Code session for changes to take effect
+- Tools from: https://github.com/0xDarkMatter/dev-shell-tools

commands/spawn.md

@@ -0,0 +1,315 @@
+---
+description: Generate PhD-level expert agent prompts for Claude Code. Creates comprehensive 500-1000 line agents with detailed patterns, code examples, and best practices.
+---
+
+# Spawn - Expert Agent Generator
+
+Generate world-class, comprehensive expert agent prompts for Claude Code. Each agent should be a definitive reference for its domain—the kind of guide a PhD-level practitioner would create.
+
+**Target quality:** 500-1000 lines per agent with real code examples, complete configs, and detailed patterns.
+
+**Benchmark agents:** `python-expert.md` (1600 lines), `claude-architect.md` (1242 lines), `react-expert.md` (440 lines)
+
+## Usage Modes
+
+### Mode 1: Single Agent Generation
+Generate one expert agent prompt for a specific technology platform.
+
+**Prompt for:**
+- Technology platform/framework name
+- Scope (project-level or global/user-level)
+- Focus areas (optional: specific features, patterns, use cases)
+- Output format (markdown file or clipboard-ready text)
+
+### Mode 2: Batch Agent Generation
+Create multiple agent prompts from a list of technology platforms.
+
+**Accept:**
+- Multi-line list of technology platforms
+- Scope (project-level or global/user-level)
+- Common focus areas (optional)
+- Output format (individual .md files or consolidated text)
+
+### Mode 3: Architecture Analysis
+Analyze a tech stack or architecture description and suggest relevant agents.
+
+**Process:**
+1. Read architecture description (from user input or file)
+2. Identify all technology platforms/services
+3. Ask for scope (project or global)
+4. Present checkbox selector for agent creation
+5. Generate selected agents
+
+## Agent File Format
+
+All agents MUST be created as Markdown files with **YAML frontmatter**:
+- **Project-level**: `.claude/agents/` (current project only)
+- **Global/User-level**: `~/.claude/agents/` or `C:\Users\[username]\.claude\agents\` (all projects)
+
+**File Structure:**
+```markdown
+---
+name: technology-name-expert
+description: When this agent should be used. Can include examples and use cases. No strict length limit - be clear and specific. Include "use PROACTIVELY" for automatic invocation.
+model: inherit
+color: blue
+---
+
+[Agent system prompt content here]
+```
+
+**YAML Frontmatter Fields:**
+- `name` (required): Unique identifier, lowercase-with-hyphens (e.g., "asus-router-expert")
+- `description` (required): Clear, specific description of when to use this agent
+  - No strict length limit - prioritize clarity over brevity
+  - Can include examples, use cases, and context
+  - Use "use PROACTIVELY" or "MUST BE USED" to encourage automatic invocation
+  - Multi-line YAML string format is fine for lengthy descriptions
+- `tools` (optional): Comma-separated list of allowed tools (e.g., "Read, Grep, Glob, Bash")
+  - If omitted, agent inherits all tools from main session
+  - **Best practice**: Only grant tools necessary for the agent's purpose (improves security and focus)
+- `model` (optional): Specify model ("sonnet", "opus", "haiku", or "inherit" to use main session model)
+- `color` (optional): Visual identifier in UI ("blue", "green", "purple", etc.)
+
+**File Creation:**
+Agents can be created programmatically using the Write tool:
+```
+Project-level: .claude/agents/[platform]-expert.md
+Global/User-level: ~/.claude/agents/[platform]-expert.md (or C:\Users\[username]\.claude\agents\ on Windows)
+```
+
+**Choosing Scope:**
+- **Project Agent** (`.claude/agents/`): Specific to the current project, can be version controlled and shared with team
+- **Global Agent** (`~/.claude/agents/`): Available across all projects on your machine
+
+After creation, the agent is immediately available for use with the Task tool.
+
+## Claude Code Agent Documentation
+
+**Essential Reading:**
+- **Subagents Overview**: https://docs.claude.com/en/docs/claude-code/sub-agents
+- **Subagents in SDK**: https://docs.claude.com/en/api/agent-sdk/subagents
+- **Agent SDK Overview**: https://docs.claude.com/en/api/agent-sdk/overview
+- **Agent Skills Guide**: https://docs.claude.com/en/docs/claude-code/skills
+- **Agent Skills in SDK**: https://docs.claude.com/en/api/agent-sdk/skills
+- **Skill Authoring Best Practices**: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices
+- **Using Agent Skills with API**: https://docs.claude.com/en/api/skills-guide
+- **Agent Skills Quickstart**: https://docs.claude.com/en/docs/agents-and-tools/agent-skills/quickstart
+- **Claude Code Settings**: https://docs.claude.com/en/docs/claude-code/settings
+- **Common Workflows**: https://docs.claude.com/en/docs/claude-code/common-workflows
+- **Claude Code Overview**: https://docs.claude.com/en/docs/claude-code/overview
+- **Plugins Reference**: https://docs.claude.com/en/docs/claude-code/plugins-reference
+
+**Key Concepts from Documentation:**
+- Subagents operate in separate context windows with customized system prompts
+- Each subagent can have restricted tool access for focused capabilities
+- Multiple subagents can run concurrently for parallel processing
+- User-level agents (`~/.claude/agents/`) are available across all projects
+- Project-level agents (`.claude/agents/`) are project-specific and shareable
+- Use `/agents` command for the recommended UI to manage agents
+- Start with Claude-generated agents, then customize for best results
+- Version control project-level subagents for team collaboration
+
+## Generation Requirements
+
+For each agent, create a comprehensive expert prompt with:
+
+**Agent Content Structure (10-Part Template):**
+
+Every generated agent MUST follow this comprehensive 10-part structure:
+
+
+1. **Part 1: Core Concepts** - Fundamental principles, mental model, architecture overview
+2. **Part 2: Essential Patterns** (5-10 patterns) - Each with: when to use, full implementation (20-50 lines), variations, common mistakes
+3. **Part 3: Advanced Techniques** (3-5 techniques) - Deep dives with complete examples
+4. **Part 4: Configuration** - Complete dev config, complete prod config, environment variables table
+5. **Part 5: Integration Patterns** - Integration code for 2-3 common technologies
+6. **Part 6: Testing Strategies** - Unit tests with mocks, integration tests, test configuration
+7. **Part 7: Error Handling** - Custom exception hierarchy, retry/circuit breaker patterns, structured logging
+8. **Part 8: Performance Optimization** - Profiling techniques, optimization table, caching strategies
+9. **Part 9: Security Considerations** - Common vulnerabilities, security hardening checklist
+10. **Part 10: Quick Reference** - Common operations cheat sheet (20-30 snippets), CLI commands, troubleshooting table
+
+Plus: Quality Checklist, Anti-Patterns (5-10 with bad/good code), Canonical Resources (10-15 URLs)
+
+See `python-expert.md` and `react-expert.md` in agents/ for reference implementations.
+
+**Requirements:**
+- YAML frontmatter at top with required fields (name, description)
+- Concise, actionable system prompt (not verbose)
+- Minimum 10 official/authoritative URLs
+- Include real, production-ready code examples (10+ code blocks)
+- Include complete configuration files (dev + prod)
+- Include testing patterns with actual test code
+- Focus on patterns, best practices, architecture
+- Include canonical references for expansion
+- Markdown formatted for direct use
+- Description field can be lengthy with examples if needed for clarity
+
+## Output Options
+
+**Ask user to choose scope:**
+1. **Project Agent** - Save to `.claude/agents/` (project-specific, version controlled)
+2. **Global Agent** - Save to `~/.claude/agents/` or `C:\Users\[username]\.claude\agents\` (all projects)
+
+**Ask user to choose format:**
+1. **Clipboard-ready** - Output complete markdown (with YAML frontmatter) in code block
+2. **File creation** - Use Write tool to save to appropriate agents directory based on scope
+3. **Both** - Create file using Write tool AND show complete content in chat for review
+
+**File Creation Process:**
+When creating files programmatically:
+1. Generate complete agent content with YAML frontmatter
+2. Determine path based on scope selection:
+   - Project: `.claude/agents/[platform-name]-expert.md`
+   - Global: `~/.claude/agents/[platform-name]-expert.md` (or Windows equivalent)
+3. Use Write tool with appropriate path
+4. Verify file was created successfully
+5. Agent is immediately available for use
+
+## Examples
+
+### Example 1: Single Agent
+```
+User: /agent-genesis
+Agent: [Shows multi-tab AskUserQuestion with 5 tabs]
+  Tab 1 (Mode): Single Agent / Batch Generation / Architecture Analysis
+  Tab 2 (Scope): Project Agent / Global Agent
+  Tab 3 (Output): Create File / Show in Chat / Both
+  Tab 4 (Platform): Custom Platform / [or popular options]
+  Tab 5 (Focus): [Multi-select] General Coverage / Caching Patterns / Pub/Sub / etc.
+User: [Selects all answers and submits once]
+  Mode: Single Agent
+  Scope: Global Agent
+  Output: Both
+  Platform: Redis (via Other field)
+  Focus: General Coverage, Caching Patterns, Pub/Sub
+Agent: [Generates Redis expert prompt and saves to ~/.claude/agents/redis-expert.md]
+```
+
+### Example 2: Batch Generation
+```
+User: /agent-genesis
+Agent: [Shows multi-tab AskUserQuestion with 3 tabs]
+  Tab 1 (Mode): Single Agent / Batch Generation / Architecture Analysis
+  Tab 2 (Scope): Project Agent / Global Agent
+  Tab 3 (Output): Create Files / Show in Chat / Both
+User: [Submits]
+  Mode: Batch Generation
+  Scope: Project Agent
+  Output: Create Files
+Agent: Please provide platforms (one per line):
+User: PostgreSQL
+Redis
+RabbitMQ
+
+Agent: [Creates 3 .md files in .claude/agents/ (project directory)]
+```
+
+### Example 3: Architecture Analysis
+```
+User: /agent-genesis
+Agent: [Shows multi-tab AskUserQuestion with 3 tabs]
+  Tab 1 (Mode): Single Agent / Batch Generation / Architecture Analysis
+  Tab 2 (Scope): Project Agent / Global Agent
+  Tab 3 (Output): Create Files / Show in Chat / Both
+User: [Submits]
+  Mode: Architecture Analysis
+  Scope: Global Agent
+  Output: Both
+Agent: Describe your architecture or provide file path:
+User: E-commerce platform: Next.js frontend, Node.js API, PostgreSQL, Redis cache, Stripe payments, AWS S3 storage, SendGrid emails
+Agent: Found platforms: Next.js, Node.js, PostgreSQL, Redis, Stripe, AWS S3, SendGrid
+[Shows multi-select AskUserQuestion]
+User: [Selects: nextjs-expert, postgres-expert, redis-expert, stripe-expert]
+Agent: [Generates 4 selected agents in ~/.claude/agents/]
+```
+
+## Implementation Steps
+
+1. **Ask All Questions at Once** using a single multi-question AskUserQuestion call:
+   - **Question 1** (header: "Mode"): Single Agent / Batch Generation / Architecture Analysis
+   - **Question 2** (header: "Scope"): Project Agent (this project only) / Global Agent (all projects)
+   - **Question 3** (header: "Output"): Create File / Show in Chat / Both
+
+   For Single Mode, also ask in the same call:
+   - **Question 4** (header: "Platform"): Offer "Custom Platform" option (user types in Other field)
+   - **Question 5** (header: "Focus", multiSelect: true): General Coverage / [2-3 common focus areas for that tech]
+
+2. **For Single Mode:**
+   - If user selected "Custom Platform", prompt for the platform name in chat
+   - Generate comprehensive prompt based on answers
+   - Create file and/or display based on output preference
+
+3. **For Batch Mode:**
+   - Ask user to provide multi-line platform list in chat
+   - For each platform:
+     - Generate expert prompt
+     - Save to `.claude/agents/[platform]-expert.md`
+   - Report completion with file paths
+
+4. **For Architecture Analysis:**
+   - Ask user for architecture description in chat
+   - Parse and identify technologies
+   - Present checkbox selector using AskUserQuestion (multiSelect: true)
+   - Generate selected agents
+   - Save to files based on output preference
+
+5. **Generate Each Agent Prompt:**
+   - Research official docs (WebSearch or WebFetch)
+   - Find 10+ authoritative URLs
+   - Structure according to template above
+   - Focus on patterns and best practices
+   - Target 500-1000 lines with comprehensive patterns
+   - Markdown formatted
+
+6. **Output:**
+   - Determine file path based on Scope selection:
+     - **Project Agent**: `.claude/agents/[platform]-expert.md`
+     - **Global Agent**: `~/.claude/agents/[platform]-expert.md` (Unix/Mac) or `C:\Users\[username]\.claude\agents\[platform]-expert.md` (Windows)
+   - If "Create File" or "Both": Use Write tool with appropriate path and complete YAML frontmatter + system prompt
+   - If "Show in Chat" or "Both": Display complete markdown (including frontmatter) in code block
+   - Confirm creation with full file path
+   - Remind user agent is immediately available via Task tool
+
+**Important**: Always use a single AskUserQuestion call with multiple questions (2-4) to create the multi-tab interface. Never ask questions sequentially one at a time.
+
+## Quality Checklist
+
+Before outputting each agent prompt, verify:
+- ✅ YAML frontmatter present with required fields (name, description)
+- ✅ Name uses lowercase-with-hyphens format
+- ✅ Description is clear and specific (length is flexible)
+- ✅ Tools field specified if restricting access (best practice: limit to necessary tools)
+- ✅ 10+ authoritative URLs included in system prompt
+- ✅ 10+ production-ready code examples included
+- ✅ Complete dev and prod configuration files
+- ✅ Testing patterns with actual test code
+- ✅ Error handling patterns and exception hierarchy
+- ✅ 5+ anti-patterns with bad/good code comparison
+- ✅ Concise and scannable system prompt
+- ✅ Clear use cases defined
+- ✅ Integration points identified
+- ✅ Common patterns referenced
+- ✅ Anti-patterns listed
+- ✅ Proper markdown formatting throughout
+- ✅ Filename matches name field: `[name].md`
+- ✅ Follows Claude Code subagent best practices (see documentation links above)
+
+## Post-Generation
+
+After creating agents, remind user:
+1. Review generated prompts
+2. Test agent with sample questions
+3. Refine based on actual usage
+4. Add to version control if satisfied
+5. Consult Claude Code documentation links above for advanced features and best practices
+
+**Additional Resources:**
+- Use `/agents` command to view and manage all available agents
+- Refer to https://docs.claude.com/en/docs/claude-code/sub-agents for detailed subagent documentation
+- Check https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices for authoring guidelines
+
+---
+
+**Execute this command to generate expert agent prompts on demand!**

templates/delegate.yaml

@@ -0,0 +1,50 @@
+# ~/.claude/delegate.yaml
+# Configuration for /delegate command - Multi-LLM task dispatch
+
+# API Keys (preferred over environment variables)
+# Uncomment and add your keys:
+# api_keys:
+#   gemini: "your-gemini-api-key"
+#   openai: "your-openai-api-key"
+#   perplexity: "your-perplexity-api-key"
+
+# Provider Configuration
+providers:
+  gemini:
+    model: gemini-2.5-pro        # Recommended: 1M context, best for code analysis
+    # model: gemini-2.5-flash    # Faster, still 1M context
+    # model: gemini-3-pro        # Requires Ultra subscription (waitlist for free tier)
+    default_flags:
+      - --output-format
+      - text
+    # IMPORTANT: Use stdin piping for file content, not @file.md syntax
+    # Example: cat file.md | gemini -m gemini-2.5-pro "prompt"
+
+  openai:
+    model: gpt-5.2          # Strongest (requires ChatGPT login)
+    # model: gpt-5.1-codex-max   # Default for Pro subscription
+    # model: gpt-4o              # API key only (pay per token)
+    auth: chatgpt                 # chatgpt (subscription) or api-key
+    default_flags:
+      - --json
+
+  perplexity:
+    model: sonar-pro             # Best balance: complex queries, more citations
+    # model: sonar               # Fast, cost-effective for quick facts
+    # model: sonar-reasoning     # Multi-step problem solving
+    # model: sonar-reasoning-pro # Deep reasoning (DeepSeek-R1 based)
+    default_flags: []
+    # Unique: returns web citations with every response
+    # Get API key at: https://www.perplexity.ai/settings/api
+
+# Conclave (Multi-Model) Settings
+conclave:
+  providers: [gemini, openai]     # Which providers participate
+  # providers: [gemini, openai, perplexity]  # Include Perplexity for web-grounded consensus
+  require_consensus: true         # All must agree for YES/NO verdicts
+
+# Default behavior
+defaults:
+  provider: gemini                # Default provider when none specified
+  output: text                    # text or json
+  verbosity: default              # brief, default, or detailed