claude-all-hands 1.0.1 → 1.0.3

package/.claude/skills/commands-development/references/tool-restrictions.md

@@ -0,0 +1,376 @@
+# Tool Restrictions Reference
+
+Official documentation on restricting tool access in slash commands.
+
+## Why Restrict Tools
+
+Tool restrictions provide:
+- **Security**: Prevent accidental destructive operations
+- **Focus**: Limit scope for specialized commands
+- **Safety**: Ensure commands only perform intended operations
+
+## allowed-tools Field
+
+**Location**: YAML frontmatter
+
+**Format**: Array of tool names or patterns
+
+**Default**: If omitted, all tools available
+
+## Basic Patterns
+
+### Array Format
+
+```yaml
+---
+description: My command
+allowed-tools: [Read, Edit, Write]
+---
+```
+
+### Single Tool
+
+```yaml
+---
+description: Thinking command
+allowed-tools: SequentialThinking
+---
+```
+
+## Bash Command Restrictions
+
+**Source**: Official Claude Code documentation
+
+Restrict bash commands to specific patterns using wildcards.
+
+### Git-Only Commands
+
+```yaml
+---
+description: Create a git commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+```
+
+**Allows**:
+- `git add <anything>`
+- `git status <anything>`
+- `git commit <anything>`
+
+**Prevents**:
+- `rm -rf`
+- `curl <url>`
+- Any non-git bash commands
+
+### NPM Script Restrictions
+
+```yaml
+---
+description: Run tests and lint
+allowed-tools: Bash(npm test:*), Bash(npm run lint:*)
+---
+```
+
+**Allows**:
+- `npm test`
+- `npm test -- --watch`
+- `npm run lint`
+- `npm run lint:fix`
+
+**Prevents**:
+- `npm install malicious-package`
+- `npm run deploy`
+- Other npm commands
+
+### Multiple Bash Patterns
+
+```yaml
+---
+description: Development workflow
+allowed-tools: Bash(git status:*), Bash(npm test:*), Bash(npm run build:*)
+---
+```
+
+Combines multiple bash command patterns.
+
+## Common Tool Restriction Patterns
+
+### Pattern 1: Git Workflows
+
+**Use case**: Commands that create commits, check status, etc.
+
+```yaml
+---
+description: Create a git commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
+---
+
+Current status: ! `git status`
+Changes: ! `git diff HEAD`
+
+Create a commit for these changes.
+```
+
+**Security benefit**: Cannot accidentally run destructive commands like `rm -rf` or `curl malicious-site.com`
+
+### Pattern 2: Read-Only Analysis
+
+**Use case**: Commands that analyze code without modifying it
+
+```yaml
+---
+description: Analyze codebase for pattern
+allowed-tools: [Read, Grep, Glob]
+---
+
+Search codebase for: $ARGUMENTS
+```
+
+**Security benefit**: Cannot write files or execute code
+
+### Pattern 3: Thinking-Only Commands
+
+**Use case**: Deep analysis or planning without file operations
+
+```yaml
+---
+description: Analyze problem from first principles
+allowed-tools: SequentialThinking
+---
+
+Analyze the current problem from first principles.
+```
+
+**Focus benefit**: Claude focuses purely on reasoning, no file operations
+
+### Pattern 4: Controlled File Operations
+
+**Use case**: Commands that should only read/edit specific types
+
+```yaml
+---
+description: Update documentation
+allowed-tools: [Read, Edit(*.md)]
+---
+
+Update documentation in @ $ARGUMENTS
+```
+
+**Note**: File pattern restrictions may not be supported in all versions.
+
+## Real Examples from Official Docs
+
+### Example 1: Git Commit Command
+
+**Source**: Official Claude Code documentation
+
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+description: Create a git commit
+---
+
+## Context
+
+- Current git status: ! `git status`
+- Current git diff (staged and unstaged changes): ! `git diff HEAD`
+- Current branch: ! `git branch --show-current`
+- Recent commits: ! `git log --oneline -10`
+
+## Your task
+
+Based on the above changes, create a single git commit.
+```
+
+**Allowed bash commands**:
+- `git add .`
+- `git add file.js`
+- `git status`
+- `git status --short`
+- `git commit -m "message"`
+- `git commit --amend`
+
+**Blocked commands**:
+- `rm file.js`
+- `curl https://malicious.com`
+- `npm install`
+- Any non-git commands
+
+### Example 2: Code Review (No Restrictions)
+
+```markdown
+---
+description: Review this code for security vulnerabilities
+---
+
+Review this code for security vulnerabilities:
+```
+
+**No allowed-tools field** = All tools available
+
+Claude can:
+- Read files
+- Write files
+- Execute bash commands
+- Use any tool
+
+**Use when**: Command needs full flexibility
+
+## When to Restrict Tools
+
+### ✅ Restrict when:
+
+1. **Security-sensitive operations**
+   ```yaml
+   # Git operations only
+   allowed-tools: Bash(git add:*), Bash(git status:*)
+   ```
+
+2. **Focused tasks**
+   ```yaml
+   # Deep thinking only
+   allowed-tools: SequentialThinking
+   ```
+
+3. **Read-only analysis**
+   ```yaml
+   # No modifications
+   allowed-tools: [Read, Grep, Glob]
+   ```
+
+4. **Specific bash commands**
+   ```yaml
+   # Only npm scripts
+   allowed-tools: Bash(npm run test:*), Bash(npm run build:*)
+   ```
+
+### ❌ Don't restrict when:
+
+1. **Command needs flexibility**
+   - Complex workflows
+   - Exploratory tasks
+   - Multi-step operations
+
+2. **Tool needs are unpredictable**
+   - General problem-solving
+   - Debugging unknown issues
+
+3. **Already in safe environment**
+   - Sandboxed execution
+   - Non-production systems
+
+## Best Practices
+
+### 1. Use Wildcards for Command Families
+
+```yaml
+# Good - allows all git commands
+allowed-tools: Bash(git *)
+
+# Better - specific git operations
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+
+# Best - minimal necessary permissions
+allowed-tools: Bash(git status:*), Bash(git diff:*)
+```
+
+### 2. Combine Tool Types Appropriately
+
+```yaml
+# Analysis with optional git context
+allowed-tools: [Read, Grep, Bash(git status:*)]
+```
+
+### 3. Test Restrictions
+
+Create command and verify:
+- Allowed operations work
+- Blocked operations are prevented
+- Error messages are clear
+
+### 4. Document Why
+
+```yaml
+---
+description: Create git commit (restricted to git commands only for security)
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+```
+
+## Tool Types
+
+### File Operations
+- `Read` - Read files
+- `Write` - Write new files
+- `Edit` - Modify existing files
+- `Grep` - Search file contents
+- `Glob` - Find files by pattern
+
+### Execution
+- `Bash(pattern:*)` - Execute bash commands matching pattern
+- `SequentialThinking` - Reasoning tool
+
+### Other
+- `Task` - Invoke subagents
+- `WebSearch` - Search the web
+- `WebFetch` - Fetch web pages
+
+## Security Patterns
+
+### Pattern: Prevent Data Exfiltration
+
+```yaml
+---
+description: Analyze code locally
+allowed-tools: [Read, Grep, Glob, SequentialThinking]
+# No Bash, WebFetch - cannot send data externally
+---
+```
+
+### Pattern: Prevent Destructive Operations
+
+```yaml
+---
+description: Review changes
+allowed-tools: [Read, Bash(git diff:*), Bash(git log:*)]
+# No Write, Edit, git reset, git push --force
+---
+```
+
+### Pattern: Controlled Deployment
+
+```yaml
+---
+description: Deploy to staging
+allowed-tools: Bash(npm run deploy:staging), Bash(git push origin:staging)
+# Cannot deploy to production accidentally
+---
+```
+
+## Limitations
+
+1. **Wildcard patterns** may vary by version
+2. **File-specific restrictions** (like `Edit(*.md)`) may not be supported
+3. **Cannot blacklist** - only whitelist
+4. **All or nothing** for tool types - can't partially restrict
+
+## Testing Tool Restrictions
+
+### Verify Restrictions Work
+
+1. Create command with restrictions
+2. Try to use restricted tool
+3. Confirm operation is blocked
+4. Check error message
+
+Example test:
+```markdown
+---
+description: Test restrictions
+allowed-tools: [Read]
+---
+
+Try to write a file - this should fail.
+```
+
+Expected: Write operations blocked with error message.

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

@@ -0,0 +1,108 @@
+---
+name: discovery-mode
+description: Read-only codebase analysis mode. Agents write findings via envoy commands, not direct file writes. Enables parallel specialist dispatch with explicit naming.
+---
+
+<objective>
+Enable agents to perform read-only codebase analysis during planning phase. Agents gather context, analyze patterns, and write findings via envoy commands. ALL specialists can propose options when alternatives exist.
+</objective>
+
+<quick_start>
+```bash
+# Write approach (required)
+envoy plans write-approach \
+  --specialist "<your-name>" \
+  --summary "2-3 sentence summary" \
+  --files '[{"path": "src/auth/service.ts", "purpose": "Core auth logic"}]' \
+  --content "Full analysis..."
+
+# Write options (when alternatives exist)
+envoy plans write-option \
+  --specialist "<your-name>" \
+  --id "1A" --group "Token storage" --name "httpOnly cookies" \
+  --summary "Store tokens in httpOnly cookies..." \
+  --trade-offs '{"pros": ["XSS protection"], "cons": ["CSRF required"]}' \
+  --recommendation "Best for same-origin apps" \
+  --content "Full implementation details..."
+```
+</quick_start>
+
+<constraints>
+- **Read-only mode** - NO file edits except via envoy findings commands
+- **Envoy-mediated writes** - use `write-approach` and `write-option` commands
+- **Use assigned specialist name** - main agent provides name for findings subdirectory
+</constraints>
+
+<workflow>
+### 1. Receive Context
+Main agent provides: target directories, questions, specialist name
+
+### 2. Analyze Codebase
+Use: Glob, Grep, Read
+
+### 3. Write Findings
+
+**Approach (required)**:
+```bash
+envoy plans write-approach \
+  --specialist "<name>" \
+  --summary "Brief summary for main agent" \
+  --files '[{"path": "...", "purpose": "..."}]' \
+  --related-options '["1A", "1B"]' \
+  --content "Full analysis"
+```
+
+**Options (only if alternatives exist that the approach file mentions)**:
+```bash
+envoy plans write-option \
+  --specialist "<name>" \
+  --id "1A" \
+  --group "Token storage" \
+  --name "httpOnly cookies" \
+  --summary "Brief summary" \
+  --trade-offs '{"pros": [...], "cons": [...]}' \
+  --recommendation "When to use this option" \
+  --content "Full details"
+```
+
+### 4. Return Confirmation
+Return path + 1-2 line summary. Do NOT return full analysis.
+</workflow>
+
+<option_schema>
+Options use simplified schema:
+- `--id`: Single identifier (e.g., "1A", "1B", "2A")
+- `--group`: Display grouping (options with same prefix are related)
+- `--status`: Defaults to "pending" (main agent sets to selected/rejected)
+
+Related options share group prefix: "1A" and "1B" are alternatives in group "1".
+</option_schema>
+
+<replace_mode>
+When re-invoked after user feedback (re-discovery loop):
+
+```bash
+# Check for existing findings
+envoy plans has-findings --specialist "<name>"
+
+# Read previous approach
+envoy plans read-finding --specialist "<name>" --type approach
+
+# Write new approach with --replace (clears existing options)
+envoy plans write-approach \
+  --specialist "<name>" \
+  --replace \
+  --summary "..." \
+  --files '[...]' \
+  --content "Combined previous + new analysis"
+```
+
+Replace mode: read previous → combine with new prompt → overwrite findings.
+</replace_mode>
+
+<success_criteria>
+- Approach file written via envoy
+- Options written when alternatives exist
+- Brief confirmation returned (not full analysis)
+- No direct file modifications
+</success_criteria>