📦 deps(thirdparty): update snapshots

2026-05-29 08:33:53 +00:00
parent fdb52f1e96
commit 06e0d13d57
1615 changed files with 232858 additions and 0 deletions
@@ -0,0 +1,364 @@
+# Argument Handling Reference
+
+Complete guide to handling arguments in Claude Code slash commands.
+
+## Overview
+
+Commands can accept arguments from users and use them in the prompt content.
+
+```
+/fix-issue 123 high
+         |   |
+         $1  $2
+```
+
+---
+
+## Syntax
+
+### Positional Arguments (`$1`, `$2`, `$3`, ...)
+
+Access individual arguments by position:
+
+```markdown
+Process file $1 with config $2 and output to $3
+```
+
+**Usage**:
+
+```
+/process data.csv config.json output.txt
+```
+
+**Result**:
+
+```
+Process file data.csv with config config.json and output to output.txt
+```
+
+### All Arguments (`$ARGUMENTS`)
+
+Access all arguments as a single string:
+
+```markdown
+Fix the following issues: $ARGUMENTS
+```
+
+**Usage**:
+
+```
+/fix memory leak in auth module slow query in search
+```
+
+**Result**:
+
+```
+Fix the following issues: memory leak in auth module slow query in search
+```
+
+---
+
+## Parsing Rules
+
+### Whitespace Separation
+
+Arguments are separated by whitespace:
+
+```
+/cmd foo bar baz
+     |   |   |
+     $1  $2  $3
+```
+
+### Quoted Strings
+
+Preserve spaces with quotes:
+
+```
+/cmd "foo bar" baz
+     |         |
+     $1        $2
+     (foo bar)  (baz)
+```
+
+### Missing Arguments
+
+Missing arguments resolve to empty string:
+
+```
+/deploy staging
+        |       |
+        $1      $2
+     (staging) ("")
+```
+
+---
+
+## Patterns
+
+### Required Arguments
+
+Use `<brackets>` in `argument-hint`:
+
+```yaml
+---
+description: Create feature branch
+argument-hint: <branch-name>
+---
+
+Create branch: feature/$1
+```
+
+### Optional Arguments
+
+Use `[brackets]` in `argument-hint`:
+
+```yaml
+---
+description: Deploy to environment
+argument-hint: <environment> [--skip-tests]
+---
+
+Deploy to $1
+Options: $2
+```
+
+### Default Values
+
+Handle defaults in command content:
+
+```markdown
+---
+description: Deploy (defaults to staging)
+argument-hint: [environment]
+---
+
+# Deployment
+
+Target: ${1:-staging}
+
+Deploy to ${1:-staging} environment.
+If no environment specified, staging is used.
+```
+
+**Note**: This is contextual interpretation, not shell expansion.
+
+### Multiple Arguments
+
+```yaml
+---
+description: Compare two files
+argument-hint: <file1> <file2>
+---
+
+Compare these files:
+- First: $1
+- Second: $2
+
+Provide detailed comparison.
+```
+
+### Variadic Arguments
+
+Use `$ARGUMENTS` for any number:
+
+```yaml
+---
+description: Review multiple files
+argument-hint: <files...>
+---
+
+Review these files: $ARGUMENTS
+
+For each file, check:
+1. Code quality
+2. Security issues
+3. Performance
+```
+
+**Usage**: `/review src/a.ts src/b.ts src/c.ts`
+
+---
+
+## Combining with Features
+
+### Arguments + File References
+
+Include file contents using argument value:
+
+```yaml
+---
+description: Explain a file
+argument-hint: <file-path>
+---
+
+# File Analysis
+
+**File**: @$1
+
+Provide detailed explanation of this file.
+```
+
+**Usage**: `/explain src/auth/login.ts`
+
+### Arguments + Bash Execution
+
+Use arguments in shell commands:
+
+```yaml
+---
+description: Show git history for file
+argument-hint: <file-path>
+---
+
+## Git History
+
+!`git log --oneline -10 -- $1`
+
+## Recent Changes
+
+!`git diff HEAD~5 -- $1`
+```
+
+**Usage**: `/history src/main.ts`
+
+### Arguments in Conditional Logic
+
+```yaml
+---
+description: Deploy to environment
+argument-hint: <environment>
+---
+
+# Deployment
+
+Target: $1
+
+## Validation
+!`case "$1" in
+  production)
+    echo "PRODUCTION - requires approval"
+    ;;
+  staging)
+    echo "Staging - auto-approved"
+    ;;
+  *)
+    echo "Unknown environment: $1"
+    ;;
+esac`
+
+Based on validation, proceed appropriately.
+```
+
+---
+
+## Validation
+
+### Check Required Arguments
+
+```markdown
+## Validation
+
+Environment: $1
+
+**First**, verify the environment argument is provided and valid.
+If missing or invalid, explain the error and valid options.
+
+**Valid environments**: staging, production
+```
+
+### Validate Argument Format
+
+```markdown
+## Issue Validation
+
+Issue number: $1
+
+Verify issue #$1:
+- Must be a number
+- Must exist in the repository
+- Must not be closed
+
+!`gh issue view $1 --json state,title 2>&1 || echo "Issue not found"`
+```
+
+---
+
+## Edge Cases
+
+### Empty Arguments
+
+```markdown
+# Handler for missing arguments
+
+Target: $1
+
+If no target specified above, prompt user for required information.
+```
+
+### Quoted Arguments with Spaces
+
+```
+/search "error message with spaces"
+```
+
+`$1` = `error message with spaces` (quotes stripped)
+
+### Special Characters
+
+Arguments may contain special characters:
+
+```
+/fix "issue: TypeError"
+```
+
+`$1` = `issue: TypeError`
+
+### Mixed Positional and ARGUMENTS
+
+Use both when needed:
+
+```yaml
+---
+description: Run command on files
+argument-hint: <command> <files...>
+---
+
+Command: $1
+Files: $ARGUMENTS
+
+# Note: $ARGUMENTS includes ALL arguments including $1
+# For just remaining args, parse manually:
+
+Run $1 on the following files (everything after first argument).
+```
+
+---
+
+## Best Practices
+
+1. **Document expected arguments** in command content
+2. **Validate early** before proceeding
+3. **Provide defaults** for optional arguments
+4. **Quote in bash** when arguments might have spaces
+5. **Handle missing arguments** gracefully
+
+```yaml
+---
+description: Complete workflow
+argument-hint: <branch-name> [--skip-tests]
+---
+
+# Workflow
+
+Branch: $1
+Skip tests: $2
+
+## Validation
+
+1. Verify branch name provided (required)
+2. Check if branch exists
+3. Validate optional flags
+
+If validation fails, explain what's missing.
+```
@@ -0,0 +1,377 @@
+# Bash Execution Reference
+
+Complete guide to executing shell commands within Claude Code slash commands.
+
+## Overview
+
+The `!` prefix executes bash commands and includes their output in the command context before Claude processes it.
+
+```markdown
+Current branch: !`git branch --show-current`
+```
+
+---
+
+## Syntax
+
+### Basic Execution
+
+```markdown
+!`command here`
+```
+
+The command runs, and output replaces the `!`backtick block.
+
+### Examples
+
+```markdown
+## Git Context
+Branch: !`git branch --show-current`
+Status: !`git status --short`
+User: !`git config user.email`
+```
+
+**Output** (example):
+
+```markdown
+## Git Context
+Branch: main
+Status: M  src/app.ts
+?? new-file.ts
+User: developer@example.com
+```
+
+---
+
+## Command Types
+
+### Simple Commands
+
+```markdown
+Current directory: !`pwd`
+Node version: !`node --version`
+Current user: !`whoami`
+Date: !`date +%Y-%m-%d`
+```
+
+### Pipelines
+
+```markdown
+Recent authors:
+!`git log --format='%an' -20 | sort | uniq -c | sort -rn`
+
+TypeScript files:
+!`find src -name '*.ts' | wc -l`
+
+Large files:
+!`find . -type f -size +1M | head -10`
+```
+
+### Complex Commands
+
+```markdown
+Test results:
+!`bun test --reporter=json 2>&1 | jq '.summary'`
+
+Open PRs:
+!`gh pr list --limit 5 --json number,title,author | jq '.[] | "\(.number): \(.title) by \(.author.login)"'`
+
+Code stats:
+!`git diff --stat HEAD~10..HEAD | tail -3`
+```
+
+### Multi-line Commands
+
+```markdown
+Environment check:
+!`echo "Node: $(node --version)"
+echo "npm: $(npm --version)"
+echo "bun: $(bun --version 2>/dev/null || echo 'not installed')"`
+```
+
+---
+
+## Output Handling
+
+### Character Budget
+
+**Default limit**: 15,000 characters per command
+
+**Configure via environment variable**:
+
+```bash
+export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000
+```
+
+**Exceeding budget**:
+- Output truncated with warning
+- Command still executes
+- Consider limiting output in command
+
+### Limiting Output
+
+```markdown
+# Limit lines
+Recent commits: !`git log --oneline -10`
+
+# Truncate with head
+Large output: !`cat big-file.txt | head -50`
+
+# Filter relevant lines
+Errors only: !`bun test 2>&1 | grep -E "FAIL|Error"`
+
+# Summary instead of full
+Stats only: !`git diff --stat | tail -1`
+```
+
+### Error Handling
+
+**Stderr is captured**:
+
+```markdown
+Result: !`some-command 2>&1`
+```
+
+**Conditional execution**:
+
+```markdown
+Status: !`git status 2>&1 || echo "Not a git repository"`
+
+File check: !`[ -f config.json ] && cat config.json || echo "No config found"`
+```
+
+**Exit codes**:
+
+```markdown
+Test result:
+!`bun test && echo "All tests passed" || echo "Tests failed"`
+```
+
+---
+
+## Patterns
+
+### Git Workflows
+
+```markdown
+## Repository State
+
+Branch: !`git branch --show-current`
+Commits ahead: !`git rev-list --count origin/main..HEAD`
+Last commit: !`git log -1 --format='%h %s (%ar)'`
+
+## Changes
+
+Staged: !`git diff --staged --stat`
+Unstaged: !`git diff --stat`
+Untracked: !`git ls-files --others --exclude-standard`
+```
+
+### Project Analysis
+
+```markdown
+## Project Structure
+
+!`tree -L 2 -I 'node_modules|.git' 2>/dev/null || find . -maxdepth 2 -type d | head -20`
+
+## Dependencies
+
+!`cat package.json | jq '.dependencies | keys | length'` dependencies
+!`cat package.json | jq '.devDependencies | keys | length'` dev dependencies
+
+## Scripts
+
+!`cat package.json | jq -r '.scripts | to_entries[] | "- \(.key): \(.value)"'`
+```
+
+### GitHub Integration
+
+```markdown
+## Issue Details
+
+!`gh issue view $1 --json title,body,labels,assignees | jq -r '
+  "Title: \(.title)\n" +
+  "Labels: \(.labels | map(.name) | join(", "))\n" +
+  "Assignees: \(.assignees | map(.login) | join(", "))\n\n" +
+  "Body:\n\(.body)"
+'`
+
+## Recent PRs
+
+!`gh pr list --limit 5 --json number,title,state | jq -r '.[] | "#\(.number) [\(.state)] \(.title)"'`
+```
+
+### Environment Validation
+
+```markdown
+## Prerequisites
+
+Node: !`node --version 2>&1 || echo "NOT INSTALLED"`
+Docker: !`docker --version 2>&1 || echo "NOT INSTALLED"`
+kubectl: !`kubectl version --client --short 2>&1 || echo "NOT INSTALLED"`
+
+## Configuration
+
+AWS: !`aws sts get-caller-identity --query Account 2>&1 || echo "Not configured"`
+```
+
+---
+
+## Arguments in Bash
+
+Use command arguments in shell commands:
+
+```markdown
+---
+argument-hint: <file-path>
+---
+
+## File Info
+
+Path: $1
+Size: !`ls -lh "$1" | awk '{print $5}'`
+Lines: !`wc -l < "$1"`
+Type: !`file "$1"`
+
+## Content Preview
+
+!`head -20 "$1"`
+```
+
+**Important**: Quote arguments to handle spaces:
+
+```markdown
+!`cat "$1"`      # Correct
+!`cat $1`        # Breaks with spaces in path
+```
+
+---
+
+## Conditional Logic
+
+### If/Else
+
+```markdown
+## Environment Check
+
+!`if [ "$1" = "production" ]; then
+  echo "WARNING: Production deployment"
+  echo "Requires additional approval"
+else
+  echo "Environment: $1"
+  echo "Ready to proceed"
+fi`
+```
+
+### Case Statements
+
+```markdown
+## Action Selection
+
+!`case "$1" in
+  deploy)
+    echo "Deploying..."
+    ;;
+  rollback)
+    echo "Rolling back..."
+    ;;
+  status)
+    echo "Checking status..."
+    ;;
+  *)
+    echo "Unknown action: $1"
+    echo "Valid: deploy, rollback, status"
+    ;;
+esac`
+```
+
+---
+
+## Security Considerations
+
+### Avoid Command Injection
+
+```markdown
+# Dangerous - user input directly in command
+!`cat $1`
+
+# Safer - validate input first
+!`[[ "$1" =~ ^[a-zA-Z0-9_/-]+\.ts$ ]] && cat "$1" || echo "Invalid file path"`
+```
+
+### Read-Only Commands
+
+Use `allowed-tools` to restrict capabilities:
+
+```yaml
+---
+allowed-tools: Bash(git show:*), Bash(git diff:*), Bash(git log:*), Read
+---
+```
+
+### Limit Destructive Operations
+
+```yaml
+---
+description: Safe code review
+allowed-tools: Read, Grep, Glob
+---
+
+# No bash execution - read-only review
+```
+
+---
+
+## Common Errors
+
+### Missing Backticks
+
+```markdown
+# Wrong
+!git status
+
+# Correct
+!`git status`
+```
+
+### Broken Quotes
+
+```markdown
+# Wrong (unbalanced quotes)
+!`echo "Hello`
+
+# Correct
+!`echo "Hello"`
+```
+
+### Unsafe Variable Expansion
+
+```markdown
+# Wrong (no quotes)
+!`cat $1`
+
+# Correct (quoted)
+!`cat "$1"`
+```
+
+### Exceeding Output Limit
+
+```markdown
+# Wrong (huge output)
+!`cat very-large-file.log`
+
+# Correct (limited)
+!`tail -100 very-large-file.log`
+```
+
+---
+
+## Best Practices
+
+1. **Test commands in terminal first**
+2. **Quote all variables** for safety
+3. **Limit output** to relevant portions
+4. **Handle errors** with `2>&1` or `||`
+5. **Use `allowed-tools`** to restrict access
+6. **Validate arguments** before using in commands
+7. **Provide context** about what commands do
@@ -0,0 +1,297 @@
+# Community Resources
+
+Curated collection of community-created slash commands, patterns, and resources.
+
+## Popular Command Collections
+
+### Production-Ready Collections
+
+**[wshobson/commands](https://github.com/wshobson/commands)**
+57 production-ready commands organized into workflows and tools:
+- 15 workflow commands (feature development, TDD, modernization)
+- 42 tool commands (testing, security, infrastructure)
+- Invocation: `/workflows:command-name` or `/tools:command-name`
+
+**[Claude Command Suite](https://github.com/qdhenry/Claude-Command-Suite)**
+Enterprise-scale development toolkit:
+- 148+ slash commands
+- 54 AI agents
+- Namespace organization: `/dev:*`, `/test:*`, `/security:*`, `/deploy:*`
+- Business scenario modeling and GitHub-Linear sync
+
+**[awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code)**
+Curated list of commands, CLAUDE.md files, and workflows:
+- Git workflows: `/commit`, `/create-pr`, `/fix-github-issue`
+- Code quality: `/check`, `/optimize`, `/tdd`
+- Documentation: `/create-docs`, `/update-docs`
+- Project management: `/create-prd`, `/todo`
+
+### Starter Collections
+
+**[claude-code-showcase](https://github.com/ChrisWiles/claude-code-showcase)**
+Comprehensive project configuration example:
+- Hooks, skills, agents, commands
+- GitHub Actions workflows
+- Best practices demonstration
+
+**[claude-code-guide](https://github.com/zebbern/claude-code-guide)**
+Setup guide with:
+- SKILL.md files
+- Agents and commands
+- Workflow examples
+
+---
+
+## Standout Commands
+
+### Git Workflows
+
+**`/commit` (steadycursor)**
+Automates git commit with conventional format:
+
+```yaml
+---
+description: Create conventional commit from staged changes
+allowed-tools: Bash(git *)
+---
+```
+
+**`/create-pr` (toyamarinyon)**
+Full PR workflow: branch, commit, format, submit.
+
+**`/catchup`**
+Reload work-in-progress after `/clear`:
+
+```yaml
+---
+description: Load uncommitted changes into context
+---
+!`git diff`
+!`git status`
+Continue with the above context.
+```
+
+### Code Quality
+
+**`/commit-fast`**
+Selects first commit suggestion automatically:
+
+```yaml
+---
+description: Fast commit - auto-select first suggestion
+disable-model-invocation: true
+---
+```
+
+**`/security-scan`**
+Vulnerability assessment with OWASP patterns.
+
+**`/tdd-cycle`**
+Test-driven development orchestration:
+- Red: Write failing tests
+- Green: Implement to pass
+- Refactor: Clean up
+
+### Context Management
+
+**`/context-prime`**
+Initialize project understanding:
+
+```yaml
+---
+description: Prime context with project structure and goals
+---
+!`tree -L 2 -I node_modules`
+@README.md
+@package.json
+```
+
+**`/prime`**
+Lightweight context setup via directory visualization.
+
+---
+
+## Command Patterns from Community
+
+### Workflow Orchestration
+
+**Sequential Pipeline**:
+
+```
+/feature-development implement OAuth
+  -> Backend scaffolding
+  -> Frontend integration
+  -> Testing
+  -> Documentation
+```
+
+**Parallel Tools**:
+
+```
+/review-suite
+  -> /security-scan (parallel)
+  -> /performance-check (parallel)
+  -> /code-quality (parallel)
+```
+
+### Smart Routing
+
+**Dynamic Agent Selection** (from Claude Command Suite):
+
+```yaml
+---
+description: Intelligent problem resolution
+---
+Based on the issue type, delegate to:
+- Security issues -> security agent
+- Performance -> optimization agent
+- Tests failing -> debugging agent
+```
+
+### Resume Capability
+
+**Interruptible Workflows**:
+
+```yaml
+---
+description: Save and resume complex tasks
+---
+## State
+!`cat .claude/workflow-state.json 2>/dev/null || echo "No state"`
+
+## Resume or Start
+If state exists, continue. Otherwise, begin fresh.
+```
+
+---
+
+## Community Best Practices
+
+### From Production Users
+
+1. **Namespace by domain** (`/git:*`, `/test:*`, `/deploy:*`)
+2. **Include validation** in deployment commands
+3. **Use `disable-model-invocation`** for destructive operations
+4. **Add context sections** before task instructions
+5. **Limit bash output** to prevent truncation
+
+### Common Pitfalls
+
+1. Commands too broad (do one thing well)
+2. Missing `allowed-tools` for safety
+3. No validation for required arguments
+4. Excessive bash output hitting char limits
+5. Forgetting to quote arguments with spaces
+
+---
+
+## Integration Examples
+
+### GitHub Integration
+
+```yaml
+---
+description: Review PR with full context
+argument-hint: <pr-number>
+allowed-tools: Bash(gh *), Read, Grep
+---
+## PR Details
+!`gh pr view $1 --json title,body,files`
+
+## Changes
+!`gh pr diff $1`
+
+## Checks
+!`gh pr checks $1`
+
+Review comprehensively.
+```
+
+### Linear Integration
+
+```yaml
+---
+description: Create issue from current context
+allowed-tools: Bash(linear *), Read
+---
+!`git diff --stat`
+!`git status`
+
+Create Linear issue based on current changes.
+```
+
+### Slack Notifications
+
+```yaml
+---
+description: Deploy with Slack notification
+argument-hint: <environment>
+allowed-tools: Bash(*)
+---
+!`curl -X POST $SLACK_WEBHOOK -d '{"text":"Deploying to $1"}'`
+
+## Deploy
+!`./deploy.sh $1`
+
+!`curl -X POST $SLACK_WEBHOOK -d '{"text":"Deployed to $1 successfully"}'`
+```
+
+---
+
+## Learning Resources
+
+### Official Documentation
+
+- [Claude Code Docs - Slash Commands](https://code.claude.com/docs/en/slash-commands)
+- [Claude Agent SDK - Commands](https://platform.claude.com/docs/en/agent-sdk/slash-commands)
+- [Best Practices Guide](https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices)
+
+### Tutorials
+
+- [How I use Claude Code](https://www.builder.io/blog/claude-code) - Practical tips from Builder.io
+- [Custom Commands Guide](https://en.bioerrorlog.work/entry/claude-code-custom-slash-command) - Step-by-step tutorial
+- [Claude Code Cheatsheet](https://shipyard.build/blog/claude-code-cheat-sheet/) - Configuration and commands
+
+### Community Discussions
+
+- [GitHub Issues](https://github.com/anthropics/claude-code/issues) - Bug reports and feature requests
+- [Discord Community](https://discord.gg/anthropic) - Real-time discussions
+
+---
+
+## Contributing Commands
+
+### Share Your Commands
+
+1. Create a GitHub repository with your commands
+2. Include clear README with examples
+3. Add to awesome-claude-code list via PR
+4. Tag with `claude-code-commands` topic
+
+### Quality Checklist
+
+Before sharing:
+- [ ] Commands have clear descriptions
+- [ ] Arguments are documented with `argument-hint`
+- [ ] `allowed-tools` specified for safety
+- [ ] Tested in real projects
+- [ ] README with usage examples
+- [ ] License included
+
+---
+
+## Staying Updated
+
+### Follow Changes
+
+- Watch [anthropics/claude-code](https://github.com/anthropics/claude-code) for updates
+- Monitor [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) for new entries
+- Check [platform.claude.com](https://platform.claude.com/docs) for documentation updates
+
+### Version Compatibility
+
+Commands may need updates when:
+- Frontmatter schema changes
+- New features added (new fields)
+- Tool names modified
+- SDK breaking changes
@@ -0,0 +1,391 @@
+# File References Reference
+
+Complete guide to including file contents in Claude Code slash commands.
+
+## Overview
+
+The `@` prefix includes file contents directly in the command context.
+
+```markdown
+Review this configuration: @package.json
+```
+
+---
+
+## Syntax
+
+### Basic Reference
+
+```markdown
+@path/to/file
+```
+
+**Example**:
+
+```markdown
+Analyze this file:
+@src/main.ts
+```
+
+The entire contents of `src/main.ts` are included where `@src/main.ts` appears.
+
+### With Arguments
+
+Combine with command arguments:
+
+```markdown
+---
+argument-hint: <file-path>
+---
+
+Explain this file: @$1
+```
+
+**Usage**: `/explain src/auth/login.ts`
+
+---
+
+## Path Resolution
+
+### Relative Paths
+
+Paths are relative to project root:
+
+```markdown
+@src/components/Button.tsx
+@package.json
+@.env.example
+```
+
+### Nested Paths
+
+```markdown
+@src/features/auth/middleware/validate.ts
+```
+
+### Current Directory
+
+For commands in specific contexts:
+
+```markdown
+# If command is about current file
+@$1
+```
+
+---
+
+## Patterns
+
+### Single File Analysis
+
+```yaml
+---
+description: Explain a file in detail
+argument-hint: <file-path>
+---
+
+# File Analysis
+
+**File**: @$1
+
+Provide detailed explanation:
+1. Purpose and responsibility
+2. Key functions and methods
+3. Dependencies and imports
+4. Potential improvements
+```
+
+### Multiple Files
+
+```yaml
+---
+description: Compare implementations
+argument-hint: <file1> <file2>
+---
+
+# Comparison
+
+## File 1
+@$1
+
+## File 2
+@$2
+
+Compare these implementations:
+- Architecture differences
+- Performance implications
+- Maintainability
+```
+
+### Configuration Review
+
+```markdown
+---
+description: Review project configuration
+---
+
+# Configuration Review
+
+## Package
+@package.json
+
+## TypeScript
+@tsconfig.json
+
+## Linter
+@.eslintrc.json
+
+Review configuration for:
+- Consistency
+- Best practices
+- Potential issues
+```
+
+### Code + Tests
+
+```yaml
+---
+description: Review implementation with tests
+argument-hint: <source-file>
+---
+
+# Code Review
+
+## Implementation
+@$1
+
+## Tests
+@$1.test.ts
+
+Review:
+1. Does the implementation meet requirements?
+2. Are tests comprehensive?
+3. Edge cases covered?
+```
+
+---
+
+## Limitations
+
+### No Glob Patterns
+
+File references don't support wildcards:
+
+```markdown
+# Not supported
+@src/**/*.ts
+@*.json
+```
+
+**Workaround**: Use bash to list files, then reference individually:
+
+```markdown
+Files to review:
+!`find src -name '*.ts' -type f`
+
+Review each file listed above.
+```
+
+Or prompt Claude to read files:
+
+```markdown
+Find all TypeScript files in src/auth/ and review them.
+```
+
+### Binary Files
+
+Binary files produce unreadable output:
+
+```markdown
+# Don't do this
+@image.png
+@compiled.wasm
+```
+
+**Workaround**: Get file info instead:
+
+```markdown
+Image info: !`file assets/logo.png`
+Image size: !`ls -lh assets/logo.png`
+```
+
+### Large Files
+
+Very large files may be truncated. Claude will inform you if this happens.
+
+**Best practice**: Reference specific portions when possible:
+
+```markdown
+Instead of the full log, show last 100 lines:
+!`tail -100 app.log`
+```
+
+### Non-existent Files
+
+Referencing missing files produces an error message in that location:
+
+```markdown
+Configuration: @config.json
+
+# If config.json doesn't exist, shows error
+```
+
+---
+
+## Combining with Other Features
+
+### File + Bash
+
+```yaml
+---
+description: Analyze file with git history
+argument-hint: <file-path>
+---
+
+# File Analysis
+
+## Current Content
+@$1
+
+## Git History
+!`git log --oneline -10 -- $1`
+
+## Recent Changes
+!`git diff HEAD~5 -- $1`
+```
+
+### File + Arguments
+
+```yaml
+---
+description: Compare file versions
+argument-hint: <file-path> <commit-hash>
+---
+
+# Version Comparison
+
+## Current Version
+@$1
+
+## Previous Version (at $2)
+!`git show $2:$1`
+
+Explain what changed between versions.
+```
+
+### Multiple Dynamic Files
+
+```yaml
+---
+description: Review component and styles
+argument-hint: <component-name>
+---
+
+# Component Review
+
+## Component
+@src/components/$1.tsx
+
+## Styles
+@src/components/$1.module.css
+
+## Tests
+@src/components/$1.test.tsx
+
+Review the complete component implementation.
+```
+
+---
+
+## Best Practices
+
+### 1. Validate File Exists
+
+```markdown
+First, verify the file exists:
+!`[ -f "$1" ] && echo "File found" || echo "File not found: $1"`
+
+If file exists:
+@$1
+```
+
+### 2. Provide Context
+
+```markdown
+# Configuration Review
+
+**Purpose**: Review the TypeScript configuration for best practices.
+
+## File: tsconfig.json
+@tsconfig.json
+
+## Analysis
+
+Focus on:
+- Strict mode settings
+- Path mappings
+- Module resolution
+```
+
+### 3. Handle Missing Files
+
+```markdown
+Review these configurations (skip if not found):
+
+## TypeScript
+@tsconfig.json
+
+## ESLint (if present)
+!`[ -f .eslintrc.json ] && cat .eslintrc.json || echo "No ESLint config"`
+```
+
+### 4. Combine Related Files
+
+```markdown
+# Review Authentication Module
+
+## Types
+@src/auth/types.ts
+
+## Implementation
+@src/auth/service.ts
+
+## Tests
+@src/auth/service.test.ts
+
+Review the complete auth module.
+```
+
+---
+
+## Common Errors
+
+### Wrong Path
+
+```markdown
+# Wrong (from user home)
+@~/project/file.ts
+
+# Correct (from project root)
+@src/file.ts
+```
+
+### Spaces in Path
+
+```markdown
+# Problematic
+@path/to/my file.ts
+
+# Better (use quotes in instructions)
+Analyze the file at: @"path/to/my file.ts"
+```
+
+### Variable Syntax
+
+```markdown
+# Wrong (shell syntax)
+@${FILE_PATH}
+
+# Correct (command argument)
+@$1
+```
@@ -0,0 +1,337 @@
+# Command Frontmatter Reference
+
+Complete reference for all frontmatter fields in Claude Code slash commands.
+
+## Overview
+
+Frontmatter is optional YAML metadata at the start of command files. It configures how the command appears in `/help`, what tools it can use, and how it behaves.
+
+```yaml
+---
+description: Brief description for /help
+argument-hint: <required> [optional]
+allowed-tools: Read, Grep, Glob
+model: haiku
+disable-model-invocation: true
+---
+```
+
+---
+
+## Fields
+
+### `description`
+
+**Type**: string
+**Default**: First line of command content
+**Purpose**: Brief explanation shown in `/help` list
+
+```yaml
+description: Deploy application to target environment with health checks
+```
+
+**Best practices**:
+- Keep under 80 characters
+- Action-oriented (start with verb)
+- Specific about what it does
+- Avoid vague terms like "helps with" or "stuff"
+
+**Examples**:
+
+```yaml
+# Good
+description: Create git commit from staged changes with conventional format
+description: Review PR for security vulnerabilities and best practices
+description: Generate API documentation from TypeScript source files
+
+# Bad
+description: Deploy stuff
+description: Helps with git
+description: Command for reviewing things
+```
+
+---
+
+### `argument-hint`
+
+**Type**: string
+**Default**: none
+**Purpose**: Show expected arguments in autocomplete
+
+```yaml
+argument-hint: <environment> [--skip-tests] [--no-notify]
+```
+
+**Conventions**:
+- `<required>` - Required arguments (angle brackets)
+- `[optional]` - Optional arguments (square brackets)
+- `--flag` - Boolean flags
+- `<arg1|arg2>` - Alternatives (pipe-separated)
+
+**Examples**:
+
+```yaml
+# Single required argument
+argument-hint: <issue-number>
+
+# Multiple arguments
+argument-hint: <file1> <file2>
+
+# Optional with defaults
+argument-hint: [environment=staging]
+
+# Flags
+argument-hint: <branch> [--force] [--no-verify]
+
+# Alternatives
+argument-hint: <staging|production>
+```
+
+---
+
+### `allowed-tools`
+
+**Type**: string (comma-separated)
+**Default**: Inherits from conversation
+**Purpose**: Restrict which tools Claude can use
+
+```yaml
+allowed-tools: Read, Grep, Glob, Bash(git *)
+```
+
+**Tool names** (case-sensitive):
+
+**File Operations**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `Read` | Read file contents, images, PDFs, Jupyter notebooks | File content with line numbers |
+| `Write` | Create new files or overwrite existing files | Confirmation |
+| `Edit` | Make targeted string replacements in existing files | Updated file snippet |
+| `MultiEdit` | Multiple edits to a single file in one atomic operation | Updated file |
+| `NotebookEdit` | Edit, insert, or delete Jupyter notebook cells | Updated notebook |
+| `LS` | List directory contents | Directory listing |
+
+**Search & Discovery**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `Grep` | Search file contents using regex patterns | Matching lines, file paths, or counts |
+| `Glob` | Find files by name/path glob patterns (e.g., `**/*.ts`) | List of matching file paths |
+
+**Execution**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `Bash` | Execute shell commands with optional timeout | Command stdout/stderr |
+| `Task` | Launch subagents for complex, parallel, or specialized work | Agent result or task ID (if background) |
+| `TaskOutput` | Retrieve output from background tasks | Task output and status |
+| `KillShell` | Terminate a running background shell process | Confirmation |
+
+**Context & Skills**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `Skill` | Load a skill's instructions into context | Skill content |
+| `TaskCreate` | Create tasks for tracking progress | Task ID |
+| `TaskUpdate` | Update task status (in_progress, completed) | Confirmation |
+| `TaskList` | List all tasks | Task summaries |
+| `TaskGet` | Get full task details | Task details |
+
+**Planning**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `EnterPlanMode` | Transition to plan mode for complex implementation tasks | User approval prompt |
+| `ExitPlanMode` | Signal plan completion and request user approval | Plan review prompt |
+
+**User Interaction**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `AskUserQuestion` | Present choices or gather input with structured options | User's selection(s) or custom input |
+| `SlashCommand` | Invoke slash commands programmatically (controlled via `disable-model-invocation`) | Command result |
+
+**Web**
+
+| Tool | Purpose | Returns |
+|------|---------|---------|
+| `WebSearch` | Search the web for current information | Search results with URLs |
+| `WebFetch` | Fetch URL content and process with AI | Processed/summarized content |
+
+**MCP Tools**
+
+MCP (Model Context Protocol) tools follow the naming pattern `mcp__<server>__<tool>`. Examples:
+- `mcp__github__create_issue` - GitHub MCP server
+- `mcp__memory__search` - Memory MCP server
+- `mcp__filesystem__read` - Filesystem MCP server
+
+Use regex patterns to match MCP tools: `mcp__.*__.*` matches all MCP tools.
+
+**Bash patterns**:
+
+```yaml
+# All bash commands
+allowed-tools: Bash(*)
+
+# All git commands
+allowed-tools: Bash(git *)
+
+# Specific git commands only
+allowed-tools: Bash(git add:*), Bash(git commit:*), Bash(git status:*)
+
+# Multiple command types
+allowed-tools: Bash(git *), Bash(npm *), Bash(bun *)
+```
+
+**Common patterns**:
+
+```yaml
+# Read-only analysis
+allowed-tools: Read, Grep, Glob
+
+# Git workflow
+allowed-tools: Read, Write, Edit, Bash(git *)
+
+# Safe code review
+allowed-tools: Read, Grep, Glob, Bash(git diff:*), Bash(git show:*)
+
+# Full development
+allowed-tools: Read, Write, Edit, Bash(*), Grep, Glob
+```
+
+**Behavior**:
+- Without `allowed-tools`: inherits conversation permissions
+- With `allowed-tools`: only listed tools allowed without asking
+- Other tools blocked or require explicit permission
+
+---
+
+### `model`
+
+**Type**: string
+**Default**: Inherits from conversation
+**Purpose**: Override model for this command
+
+```yaml
+model: haiku
+```
+
+**Available models**:
+
+```yaml
+# Fast, low-cost (simple tasks)
+model: haiku
+
+# Balanced (default for most)
+model: sonnet
+
+# Most capable (complex analysis)
+model: opus
+```
+
+**Use cases**:
+- Simple commands (formatting, simple lookups) -> haiku
+- Standard development tasks -> sonnet (default)
+- Complex analysis, security review -> opus
+
+---
+
+### `disable-model-invocation`
+
+**Type**: boolean
+**Default**: false
+**Purpose**: Prevent SlashCommand tool from invoking this command automatically
+
+```yaml
+disable-model-invocation: true
+```
+
+**When to use**:
+- Interactive commands requiring user input
+- Destructive operations (delete, deploy to production)
+- Commands with side effects that shouldn't be automated
+- Testing or debugging commands
+
+**Behavior**:
+- When `true`: Command can only be invoked explicitly by user
+- When `false` (default): Claude can invoke via SlashCommand tool
+
+---
+
+## Complete Example
+
+```yaml
+---
+description: Deploy application with full validation pipeline
+argument-hint: <environment> [--skip-tests] [--force]
+allowed-tools: Read, Bash(kubectl *), Bash(docker *), Bash(git *)
+model: sonnet
+disable-model-invocation: true
+---
+
+# Deployment Pipeline
+
+Environment: $1
+Options: $ARGUMENTS
+
+## Pre-flight Checks
+...
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Frontmatter opens with `---` on line 1
+- [ ] Frontmatter closes with `---` before content
+- [ ] Uses spaces, not tabs
+- [ ] Special characters in strings are quoted
+- [ ] Field names are lowercase with hyphens
+- [ ] Tool names in `allowed-tools` are case-sensitive
+- [ ] Model identifier is valid if specified
+- [ ] Description is action-oriented and specific
+
+---
+
+## Common Errors
+
+**Tab characters**:
+
+```yaml
+# Bad (tabs)
+description: Deploy to staging
+
+# Good (spaces)
+description: Deploy to staging
+```
+
+**Unquoted special characters**:
+
+```yaml
+# Bad (colon in value)
+description: Review: code quality check
+
+# Good (quoted)
+description: "Review: code quality check"
+```
+
+**Wrong tool names**:
+
+```yaml
+# Bad (lowercase)
+allowed-tools: read, grep, glob
+
+# Good (proper case)
+allowed-tools: Read, Grep, Glob
+```
+
+**Invalid model**:
+
+```yaml
+# Bad (non-existent)
+model: gpt-4
+
+# Good (valid Claude model)
+model: haiku
+```
@@ -0,0 +1,369 @@
+# Command Namespacing Reference
+
+Complete guide to organizing slash commands with directories and namespaces.
+
+## Overview
+
+Commands can be organized in subdirectories to group related functionality. The directory structure becomes the namespace.
+
+```
+.claude/commands/
+-- frontend/
+|   +-- component.md    # /component (project:frontend)
+|   +-- styling.md      # /styling (project:frontend)
+-- backend/
+|   +-- api.md          # /api (project:backend)
+-- review.md           # /review (project)
+```
+
+---
+
+## How Namespacing Works
+
+### Display in /help
+
+Commands show their namespace in parentheses:
+
+```
+Available commands:
+  /component    Create React component (project:frontend)
+  /styling      Check styling guidelines (project:frontend)
+  /api          Create API endpoint (project:backend)
+  /review       Review code changes (project)
+```
+
+### Invocation
+
+Commands can be invoked with or without namespace:
+
+```bash
+# Direct (command name only)
+/component Button
+
+# With namespace
+/frontend/component Button
+```
+
+Both work. Use direct for brevity, namespace for clarity when names overlap.
+
+---
+
+## Directory Structure
+
+### Single Level
+
+```
+.claude/commands/
+-- git/
+|   +-- commit.md       # /commit (project:git)
+|   +-- branch.md       # /branch (project:git)
+|   +-- sync.md         # /sync (project:git)
+```
+
+### Multiple Namespaces
+
+```
+.claude/commands/
+-- frontend/
+|   +-- component.md
+|   +-- test.md
+-- backend/
+|   +-- endpoint.md
+|   +-- test.md         # Different from frontend/test.md
+-- deploy/
+|   +-- staging.md
+|   +-- production.md
+```
+
+### Mixed (Root + Namespaced)
+
+```
+.claude/commands/
+-- review.md           # Root level: /review
+-- commit.md           # Root level: /commit
+-- git/
+|   +-- sync.md         # Namespaced: /sync (project:git)
+-- test/
+|   +-- unit.md         # Namespaced: /unit (project:test)
+|   +-- e2e.md          # Namespaced: /e2e (project:test)
+```
+
+---
+
+## Naming Collisions
+
+### Same Name in Different Namespaces
+
+When multiple commands have the same name:
+
+```
+.claude/commands/
+-- frontend/
+|   +-- build.md        # /build (project:frontend)
+-- backend/
+|   +-- build.md        # /build (project:backend)
+```
+
+**Invocation**:
+- `/build` - Ambiguous, may prompt for clarification
+- `/frontend/build` - Explicit
+- `/backend/build` - Explicit
+
+### Resolution Priority
+
+1. Root commands (`.claude/commands/name.md`)
+2. First alphabetically by namespace
+3. User prompted if ambiguous
+
+**Best practice**: Use unique names or explicit namespaces to avoid ambiguity.
+
+---
+
+## Organizational Patterns
+
+### By Domain
+
+Group by functional area:
+
+```
+.claude/commands/
+-- auth/
+|   +-- login.md
+|   +-- session.md
+|   +-- permissions.md
+-- data/
+|   +-- migrate.md
+|   +-- seed.md
+|   +-- backup.md
+-- api/
+|   +-- endpoint.md
+|   +-- client.md
+```
+
+### By Workflow
+
+Group by development stage:
+
+```
+.claude/commands/
+-- setup/
+|   +-- init.md
+|   +-- config.md
+-- develop/
+|   +-- feature.md
+|   +-- fix.md
+-- review/
+|   +-- pr.md
+|   +-- security.md
+-- deploy/
+|   +-- staging.md
+|   +-- production.md
+```
+
+### By Team
+
+Group by team ownership:
+
+```
+.claude/commands/
+-- platform/
+|   +-- infra.md
+|   +-- deploy.md
+-- frontend/
+|   +-- component.md
+|   +-- story.md
+-- backend/
+|   +-- api.md
+|   +-- migration.md
+```
+
+### By Command Type
+
+Group by command category:
+
+```
+.claude/commands/
+-- tools/
+|   +-- lint.md
+|   +-- format.md
+|   +-- test.md
+-- workflows/
+|   +-- feature.md
+|   +-- release.md
+-- analysis/
+|   +-- review.md
+|   +-- audit.md
+```
+
+---
+
+## Scope Interaction
+
+### Project Namespaces
+
+Project commands (`.claude/commands/`) show:
+
+```
+/command (project:namespace)
+```
+
+### Personal Namespaces
+
+Personal commands (`~/.claude/commands/`) show:
+
+```
+/command (user:namespace)
+```
+
+### Plugin Namespaces
+
+Plugin commands show:
+
+```
+/command (plugin-name:namespace)
+```
+
+### Priority
+
+When same-named commands exist:
+1. Plugin commands
+2. Project commands (override personal)
+3. Personal commands (fallback)
+
+---
+
+## Best Practices
+
+### 1. Consistent Structure
+
+Choose one organizational pattern and stick with it:
+
+```
+# Good: Consistent by domain
+frontend/
+backend/
+deploy/
+
+# Bad: Mixed patterns
+frontend/
+deploy-staging/
+api-commands/
+```
+
+### 2. Shallow Nesting
+
+Keep to one level of directories:
+
+```
+# Good
+.claude/commands/frontend/component.md
+
+# Avoid
+.claude/commands/frontend/react/components/button.md
+```
+
+### 3. Descriptive Names
+
+Make namespaces self-explanatory:
+
+```
+# Good
+git/
+test/
+deploy/
+
+# Avoid
+g/
+t/
+d/
+```
+
+### 4. README in Directories
+
+Document namespace purpose:
+
+```
+.claude/commands/
+-- frontend/
+|   +-- README.md       # Explains frontend commands
+|   +-- component.md
+|   +-- styling.md
+```
+
+### 5. Group Related Commands
+
+Keep tightly related commands together:
+
+```
+# Good: Git operations together
+git/
+  +-- commit.md
+  +-- branch.md
+  +-- sync.md
+
+# Avoid: Scattered
+commands/
+  +-- git-commit.md
+  +-- git-branch.md
+  +-- other-stuff.md
+  +-- git-sync.md
+```
+
+---
+
+## Examples
+
+### Monorepo Structure
+
+```
+.claude/commands/
+-- packages/
+|   +-- core/
+|   |   +-- build.md
+|   |   +-- test.md
+|   +-- web/
+|   |   +-- build.md
+|   |   +-- dev.md
+|   +-- api/
+|       +-- build.md
+|       +-- deploy.md
+-- shared/
+    +-- lint.md
+    +-- format.md
+```
+
+### Full-Stack App
+
+```
+.claude/commands/
+-- client/
+|   +-- component.md
+|   +-- page.md
+|   +-- story.md
+-- server/
+|   +-- endpoint.md
+|   +-- middleware.md
+|   +-- migration.md
+-- ops/
+|   +-- deploy.md
+|   +-- rollback.md
+|   +-- monitor.md
+-- review.md
+-- test.md
+```
+
+### Open Source Project
+
+```
+.claude/commands/
+-- contribute/
+|   +-- setup.md
+|   +-- pr.md
+|   +-- issue.md
+-- maintain/
+|   +-- release.md
+|   +-- changelog.md
+-- docs/
+|   +-- api.md
+|   +-- readme.md
+```
@@ -0,0 +1,354 @@
+# Tool Permissions Reference
+
+Complete guide to restricting tool access in Claude Code slash commands.
+
+## Overview
+
+The `allowed-tools` frontmatter field restricts which tools Claude can use when executing a command. This provides safety boundaries for automated workflows.
+
+```yaml
+---
+allowed-tools: Read, Grep, Glob, Bash(git *)
+---
+```
+
+---
+
+## How It Works
+
+### Without `allowed-tools`
+
+Commands inherit tool permissions from the conversation:
+- Claude may ask for permission to use new tools
+- User can approve/deny as normal
+- No automatic restrictions
+
+### With `allowed-tools`
+
+Only listed tools are available without asking:
+- Tools in the list work immediately
+- Unlisted tools are blocked or require permission
+- Overrides conversation settings for this command
+
+---
+
+## Tool Names
+
+Tools are case-sensitive. Use exact names:
+
+| Tool | Purpose |
+|------|---------|
+| `Read` | Read file contents |
+| `Write` | Create/overwrite files |
+| `Edit` | Modify existing files |
+| `Grep` | Search file contents |
+| `Glob` | Find files by pattern |
+| `Bash` | Execute shell commands |
+| `Task` | Create subagent tasks |
+| `Skill` | Invoke skills |
+| `TaskCreate` | Create tasks |
+| `TaskUpdate` | Update task status |
+| `TaskList` | List tasks |
+| `TaskGet` | Get task details |
+| `WebSearch` | Search the web |
+| `WebFetch` | Fetch web content |
+| `SlashCommand` | Invoke other commands |
+
+---
+
+## Bash Patterns
+
+Bash requires special pattern syntax to restrict which commands can run.
+
+### All Bash Commands
+
+```yaml
+allowed-tools: Bash(*)
+```
+
+### Command Family
+
+```yaml
+# All git commands
+allowed-tools: Bash(git *)
+
+# All npm commands
+allowed-tools: Bash(npm *)
+
+# All bun commands
+allowed-tools: Bash(bun *)
+```
+
+### Specific Commands
+
+```yaml
+# Only git status, diff, log
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)
+
+# Only read operations
+allowed-tools: Bash(cat:*), Bash(ls:*), Bash(find:*)
+```
+
+### Multiple Command Families
+
+```yaml
+allowed-tools: Bash(git *), Bash(npm *), Bash(docker *)
+```
+
+---
+
+## Common Patterns
+
+### Read-Only Analysis
+
+Safe for code review and analysis:
+
+```yaml
+allowed-tools: Read, Grep, Glob
+```
+
+**Use cases**: Code review, security audit, documentation analysis
+
+### Read-Only with Git
+
+Add git read commands for version control context:
+
+```yaml
+allowed-tools: Read, Grep, Glob, Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git show:*)
+```
+
+**Use cases**: PR review, change analysis
+
+### Git Workflow
+
+Full git access for commit/branch operations:
+
+```yaml
+allowed-tools: Read, Write, Edit, Bash(git *)
+```
+
+**Use cases**: Commit creation, branch management, rebasing
+
+### Development Workflow
+
+Standard development with restricted bash:
+
+```yaml
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(bun *), Bash(npm *)
+```
+
+**Use cases**: Feature development, testing, building
+
+### Full Access
+
+When no restrictions needed:
+
+```yaml
+# Option 1: Explicit full access
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash(*), Task, Skill, TaskCreate, TaskUpdate, TaskList, TaskGet
+
+# Option 2: Omit field entirely (inherits all)
+# (no allowed-tools field)
+```
+
+### Research Commands
+
+Web access for documentation lookup:
+
+```yaml
+allowed-tools: Read, Grep, Glob, WebSearch, WebFetch
+```
+
+**Use cases**: API research, documentation lookup
+
+---
+
+## Safety Patterns
+
+### Prevent File Modifications
+
+```yaml
+# No Write or Edit
+allowed-tools: Read, Grep, Glob, Bash(git diff:*)
+```
+
+### Prevent Bash Execution
+
+```yaml
+# No Bash at all
+allowed-tools: Read, Write, Edit, Grep, Glob
+```
+
+### Prevent Destructive Git
+
+```yaml
+# No push, force, reset
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*), Bash(git add:*), Bash(git commit:*)
+```
+
+### Restrict to Specific Scripts
+
+```yaml
+# Only run specific scripts
+allowed-tools: Bash(bun run test:*), Bash(bun run lint:*), Bash(bun run build:*)
+```
+
+---
+
+## Permission Hierarchy
+
+### Command vs Conversation
+
+1. Command's `allowed-tools` takes precedence
+2. Tools not in list require explicit permission
+3. User can still deny even allowed tools
+
+### Command vs Skill
+
+If command invokes a skill:
+- Skill's tool restrictions may also apply
+- Most restrictive wins
+
+### Subagent Permissions
+
+If using `Task` tool:
+- Subagent inherits command's permissions
+- Unless subagent has its own restrictions
+
+---
+
+## Testing Permissions
+
+### Verify Restrictions
+
+```bash
+# Create test command
+cat > .claude/commands/test-perms.md << 'EOF'
+---
+description: Test permissions
+allowed-tools: Read, Grep
+---
+Try to write a file. This should fail or ask permission.
+EOF
+
+# Test
+/test-perms
+```
+
+### Debug Mode
+
+```bash
+claude --debug
+```
+
+Shows tool permission checks in output.
+
+---
+
+## Common Errors
+
+### Case Sensitivity
+
+```yaml
+# Wrong
+allowed-tools: read, grep, glob
+
+# Correct
+allowed-tools: Read, Grep, Glob
+```
+
+### Missing Comma Separator
+
+```yaml
+# Wrong
+allowed-tools: Read Grep Glob
+
+# Correct
+allowed-tools: Read, Grep, Glob
+```
+
+### Invalid Bash Pattern
+
+```yaml
+# Wrong (missing colon)
+allowed-tools: Bash(git status*)
+
+# Correct
+allowed-tools: Bash(git status:*)
+
+# Also correct (space pattern)
+allowed-tools: Bash(git *)
+```
+
+### Incomplete Tool List
+
+```yaml
+# Problem: Can read but not find files
+allowed-tools: Read
+
+# Better: Include discovery tools
+allowed-tools: Read, Grep, Glob
+```
+
+---
+
+## Best Practices
+
+### 1. Principle of Least Privilege
+
+Only grant tools needed for the specific task:
+
+```yaml
+# Good: Minimal for code review
+allowed-tools: Read, Grep, Glob
+
+# Avoid: Everything for code review
+allowed-tools: Read, Write, Edit, Bash(*), ...
+```
+
+### 2. Document Restrictions
+
+Explain why tools are restricted:
+
+```markdown
+---
+description: Safe security audit (read-only)
+allowed-tools: Read, Grep, Glob
+---
+
+# Security Audit
+
+This command performs read-only analysis.
+No modifications will be made.
+```
+
+### 3. Test Thoroughly
+
+Before sharing with team:
+- Test with expected inputs
+- Verify blocked operations fail gracefully
+- Check edge cases
+
+### 4. Combine with disable-model-invocation
+
+For dangerous operations:
+
+```yaml
+---
+description: Deploy to production
+allowed-tools: Bash(kubectl *), Bash(docker *)
+disable-model-invocation: true
+---
+```
+
+### 5. Include Baseline Tools
+
+When restricting, include common needs:
+
+```yaml
+# Baseline for most commands
+allowed-tools: Grep, Glob, Read
+
+# Add what's specifically needed
+allowed-tools: Grep, Glob, Read, Bash(git *)
+```
@@ -0,0 +1,436 @@
+# SDK Integration Reference
+
+Guide to using slash commands with the Claude Agent SDK.
+
+## Overview
+
+Custom slash commands are fully accessible through the Claude Agent SDK, enabling programmatic invocation and integration into automated workflows.
+
+---
+
+## Discovering Commands
+
+Commands are listed in the system initialization message:
+
+### TypeScript
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Hello",
+  options: { maxTurns: 1 }
+})) {
+  if (message.type === "system" && message.subtype === "init") {
+    console.log("Available commands:", message.slash_commands);
+    // Example: ["/compact", "/clear", "/help", "/review", "/deploy"]
+  }
+}
+```
+
+### Python
+
+```python
+import asyncio
+from claude_agent_sdk import query
+
+async def main():
+    async for message in query(
+        prompt="Hello",
+        options={"max_turns": 1}
+    ):
+        if message.type == "system" and message.subtype == "init":
+            print("Available commands:", message.slash_commands)
+
+asyncio.run(main())
+```
+
+---
+
+## Invoking Commands
+
+Send commands as prompt strings:
+
+### TypeScript
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+// Basic invocation
+for await (const message of query({
+  prompt: "/review",
+  options: { maxTurns: 3 }
+})) {
+  if (message.type === "assistant") {
+    console.log("Review:", message.message);
+  }
+}
+
+// With arguments
+for await (const message of query({
+  prompt: "/fix-issue 123",
+  options: { maxTurns: 5 }
+})) {
+  if (message.type === "result") {
+    console.log("Fixed:", message.result);
+  }
+}
+```
+
+### Python
+
+```python
+async def main():
+    # Basic invocation
+    async for message in query(
+        prompt="/review",
+        options={"max_turns": 3}
+    ):
+        if message.type == "assistant":
+            print("Review:", message.message)
+
+    # With arguments
+    async for message in query(
+        prompt="/fix-issue 123",
+        options={"max_turns": 5}
+    ):
+        if message.type == "result":
+            print("Fixed:", message.result)
+```
+
+---
+
+## Enabling Filesystem Settings
+
+By default, the SDK doesn't read filesystem settings. Enable them explicitly:
+
+### TypeScript
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "/my-custom-command",
+  options: {
+    maxTurns: 3,
+    settingSources: ['user', 'project', 'local']  // Enable filesystem
+  }
+})) {
+  // Process results
+}
+```
+
+### Python
+
+```python
+async for message in query(
+    prompt="/my-custom-command",
+    options={
+        "max_turns": 3,
+        "setting_sources": ["user", "project", "local"]
+    }
+):
+    # Process results
+```
+
+**Setting Sources**:
+- `user` - Personal settings (`~/.claude/`)
+- `project` - Project settings (`.claude/`)
+- `local` - Local overrides
+
+---
+
+## Built-in Commands
+
+### /compact
+
+Summarize conversation history to reduce context:
+
+```typescript
+for await (const message of query({
+  prompt: "/compact",
+  options: { maxTurns: 1 }
+})) {
+  if (message.type === "system" && message.subtype === "compact_boundary") {
+    console.log("Compacted");
+    console.log("Pre-tokens:", message.compact_metadata.pre_tokens);
+  }
+}
+```
+
+### /clear
+
+Start fresh conversation:
+
+```typescript
+for await (const message of query({
+  prompt: "/clear",
+  options: { maxTurns: 1 }
+})) {
+  if (message.type === "system" && message.subtype === "init") {
+    console.log("Cleared, new session:", message.session_id);
+  }
+}
+```
+
+---
+
+## Workflow Automation
+
+### Sequential Commands
+
+Chain commands for multi-step workflows:
+
+```typescript
+async function developmentWorkflow(featureName: string) {
+  // Step 1: Create branch
+  for await (const msg of query({
+    prompt: `/create-branch ${featureName}`,
+    options: { maxTurns: 3 }
+  })) {
+    // Handle branch creation
+  }
+
+  // Step 2: Implement feature
+  for await (const msg of query({
+    prompt: `/implement ${featureName}`,
+    options: { maxTurns: 10 }
+  })) {
+    // Handle implementation
+  }
+
+  // Step 3: Create PR
+  for await (const msg of query({
+    prompt: "/create-pr",
+    options: { maxTurns: 3 }
+  })) {
+    // Handle PR creation
+  }
+}
+```
+
+### Conditional Execution
+
+Execute commands based on results:
+
+```typescript
+async function deployIfTestsPass() {
+  let testsPass = false;
+
+  for await (const msg of query({
+    prompt: "/run-tests",
+    options: { maxTurns: 5 }
+  })) {
+    if (msg.type === "result" && msg.result.includes("All tests passed")) {
+      testsPass = true;
+    }
+  }
+
+  if (testsPass) {
+    for await (const msg of query({
+      prompt: "/deploy staging",
+      options: { maxTurns: 5 }
+    })) {
+      // Handle deployment
+    }
+  }
+}
+```
+
+---
+
+## Error Handling
+
+### Command Not Found
+
+```typescript
+for await (const msg of query({
+  prompt: "/nonexistent-command",
+  options: { maxTurns: 1 }
+})) {
+  if (msg.type === "error") {
+    console.error("Command error:", msg.error);
+  }
+}
+```
+
+### Timeout Handling
+
+```typescript
+import { query } from "@anthropic-ai/claude-agent-sdk";
+
+const controller = new AbortController();
+const timeout = setTimeout(() => controller.abort(), 60000);
+
+try {
+  for await (const msg of query({
+    prompt: "/long-running-command",
+    options: { maxTurns: 10 },
+    signal: controller.signal
+  })) {
+    // Process messages
+  }
+} finally {
+  clearTimeout(timeout);
+}
+```
+
+---
+
+## SlashCommand Tool
+
+Claude can programmatically invoke commands via the SlashCommand tool:
+
+### Enabling
+
+Commands with `description` are automatically available to the SlashCommand tool.
+
+### Disabling
+
+Prevent automatic invocation:
+
+```yaml
+---
+description: Interactive deployment (manual only)
+disable-model-invocation: true
+---
+```
+
+### Character Budget
+
+Control how many command descriptions fit in context:
+
+```bash
+export SLASH_COMMAND_TOOL_CHAR_BUDGET=30000  # Default: 15000
+```
+
+---
+
+## Integration Patterns
+
+### CI/CD Pipeline
+
+```typescript
+// GitHub Actions integration
+async function runCodeQuality() {
+  const results = [];
+
+  for await (const msg of query({
+    prompt: "/lint && /test && /security-check",
+    options: { maxTurns: 10 }
+  })) {
+    if (msg.type === "result") {
+      results.push(msg.result);
+    }
+  }
+
+  return results;
+}
+```
+
+### Chatbot Integration
+
+```typescript
+// Slack/Discord bot
+async function handleUserCommand(userMessage: string) {
+  if (userMessage.startsWith("/")) {
+    for await (const msg of query({
+      prompt: userMessage,
+      options: { maxTurns: 5 }
+    })) {
+      if (msg.type === "assistant") {
+        await sendToChannel(msg.message);
+      }
+    }
+  }
+}
+```
+
+### Batch Processing
+
+```typescript
+// Process multiple items
+async function batchReview(files: string[]) {
+  for (const file of files) {
+    for await (const msg of query({
+      prompt: `/review-file ${file}`,
+      options: { maxTurns: 3 }
+    })) {
+      if (msg.type === "result") {
+        await saveReview(file, msg.result);
+      }
+    }
+  }
+}
+```
+
+---
+
+## Best Practices
+
+### 1. Enable Settings Explicitly
+
+Always specify which settings to load:
+
+```typescript
+options: {
+  settingSources: ['user', 'project', 'local']
+}
+```
+
+### 2. Handle All Message Types
+
+Check for various response types:
+
+```typescript
+for await (const msg of query({ prompt: "/command" })) {
+  switch (msg.type) {
+    case "assistant":
+      // Claude's response
+      break;
+    case "result":
+      // Command result
+      break;
+    case "error":
+      // Error occurred
+      break;
+    case "system":
+      // System message
+      break;
+  }
+}
+```
+
+### 3. Set Appropriate Timeouts
+
+Long-running commands need timeout handling:
+
+```typescript
+options: {
+  maxTurns: 10,
+  timeout: 120000  // 2 minutes
+}
+```
+
+### 4. Use maxTurns Appropriately
+
+Simple commands need fewer turns:
+
+```typescript
+// Simple lookup
+options: { maxTurns: 1 }
+
+// Standard operation
+options: { maxTurns: 3 }
+
+// Complex workflow
+options: { maxTurns: 10 }
+```
+
+---
+
+## Resources
+
+- [Claude Agent SDK Documentation](https://platform.claude.com/docs/en/agent-sdk/overview)
+- [TypeScript SDK Reference](https://platform.claude.com/docs/en/agent-sdk/typescript)
+- [Python SDK Reference](https://platform.claude.com/docs/en/agent-sdk/python)