Initial commit: Fresh start with current state

.claude/commands/.COMMANDS_TEMPLATE.md

@@ -0,0 +1,540 @@
+---
+description: Brief description of what this command does (shown in /help)
+allowed-tools: Bash(git status:*), Bash(git add:*), Read(*)
+# Optional: Explicitly declare which tools this command needs
+# Format: Tool(pattern:*) or Tool(*)
+# Examples:
+# - Bash(git *:*) - Allow all git commands
+# - Read(*), Glob(*) - Allow file reading and searching
+# - Write(*), Edit(*) - Allow file modifications
+
+argument-hint: [optional-parameter]
+# Optional: Hint text showing expected arguments
+# Appears in command autocompletion and help
+# Examples: [file-path], [branch-name], [message]
+
+disable-model-invocation: false
+# Optional: Set to true if this is a simple prompt that doesn't need AI processing
+# Use for commands that just display text or run simple scripts
+---
+
+# Command Template
+
+Clear, concise instructions for Claude on what to do when this command is invoked.
+
+## Technology Adaptation
+
+**IMPORTANT**: This command adapts to the project's technology stack.
+
+**Configuration Source**: [CLAUDE.md](../../CLAUDE.md)
+
+Before executing, consult CLAUDE.md for:
+- **Package Manager**: (npm, NuGet, pip, cargo, Maven) - Use correct install/test/build commands
+- **Build Tool**: (dotnet, npm scripts, make, cargo) - Use correct build commands
+- **Test Framework**: (xUnit, Jest, pytest, JUnit) - Use correct test commands
+- **Language**: (C#, TypeScript, Python, Rust, Java) - Follow syntax conventions
+- **Project Structure**: Navigate to correct paths for src, tests, config
+
+## MCP Server Integration
+
+**Available MCP Servers**: Leverage configured MCP servers for enhanced capabilities.
+
+### Serena MCP
+
+**Code Tools**: `find_symbol`, `find_referencing_symbols`, `get_symbols_overview`, `search_for_pattern`, `rename_symbol`
+
+**Persistent Memory** (stored in `.serena/memories/`):
+- `write_memory` - Store command findings, patterns, decisions
+- `read_memory` - Recall past information
+- `list_memories` - Browse all memories
+
+Use for command-specific persistent knowledge.
+
+### Memory MCP
+
+**Temporary Context** (in-memory, cleared after session):
+- `create_entities` - Track entities during command execution
+- `create_relations` - Model relationships
+- `add_observations` - Add details
+
+Use for temporary command state.
+
+### Other MCP Servers
+- **context7**: Library documentation
+- **fetch**: Web content
+- **playwright**: Browser automation
+- **windows-mcp**: Windows automation
+
+## Arguments
+
+If your command accepts arguments, explain how to use them:
+
+**$ARGUMENTS** - All arguments passed to the command as a single string
+**$1** - First positional argument
+**$2** - Second positional argument
+**$3** - Third positional argument, etc.
+
+### Example Usage:
+
+```
+/command-name argument1 argument2 argument3
+```
+
+In the command file:
+- `$ARGUMENTS` would be: "argument1 argument2 argument3"
+- `$1` would be: "argument1"
+- `$2` would be: "argument2"
+- `$3` would be: "argument3"
+
+## Instructions
+
+Provide clear, step-by-step instructions for Claude:
+
+1. **First step**: What to do first
+   - Specific action or tool to use
+   - Expected behavior
+
+2. **Second step**: Next action
+   - How to process information
+   - What to check or validate
+
+3. **Final step**: Output or result
+   - Format for results
+   - What to return to the user
+
+## Expected Output
+
+Describe the format and structure of the command's output:
+
+```markdown
+## Section Title
+- Item 1
+- Item 2
+
+**Summary**: Key findings...
+```
+
+Or for code output:
+```language
+// Expected code format
+output_example();
+```
+
+## Advanced Features
+
+### Bash Execution
+
+Execute shell commands directly:
+
+```markdown
+!ls -la
+!git status
+!npm test
+```
+
+Prefix commands with `!` to run them immediately.
+
+### File References
+
+Include file contents in the prompt:
+
+```markdown
+Review this file: @path/to/file.js
+Compare these files: @file1.py @file2.py
+```
+
+Use `@` prefix to automatically include file contents.
+
+### Conditional Logic
+
+Add conditional instructions:
+
+```markdown
+If $1 is "quick":
+  - Run fast analysis only
+  - Skip detailed checks
+
+If $1 is "full":
+  - Run comprehensive analysis
+  - Include all checks
+  - Generate detailed report
+```
+
+## Examples
+
+### Example 1: Basic Usage
+```
+/command-name
+```
+**Expected behavior**: Description of what happens
+
+### Example 2: With Arguments
+```
+/command-name src/app.js detailed
+```
+**Expected behavior**: How arguments affect behavior
+
+### Example 3: Advanced Usage
+```
+/command-name @file.js --option
+```
+**Expected behavior**: Combined features
+
+## Best Practices
+
+### When to Use This Command
+- Scenario 1: When you need...
+- Scenario 2: For tasks involving...
+- Scenario 3: To quickly...
+
+### Common Patterns
+
+**Read then analyze:**
+```markdown
+1. Read the files in $ARGUMENTS
+2. Analyze for [specific criteria]
+3. Provide structured feedback
+```
+
+**Execute then report:**
+```markdown
+1. Run: !command $1
+2. Parse the output
+3. Summarize results
+```
+
+**Generate then write:**
+```markdown
+1. Generate [content type] based on $1
+2. Write to specified location
+3. Confirm completion
+```
+
+## Error Handling
+
+Handle common issues gracefully:
+
+```markdown
+If no arguments provided:
+  - Show usage example
+  - Ask user for required input
+
+If file not found:
+  - List similar files
+  - Suggest corrections
+
+If operation fails:
+  - Explain the error
+  - Suggest next steps
+```
+
+## Integration with Other Features
+
+### Works well with:
+- **Hooks**: Can trigger pre/post command hooks
+- **Subagents**: Can invoke specialized agents
+- **Skills**: Commands can activate relevant skills
+- **MCP Servers**: Can use MCP tools and resources
+
+### Combine with tools:
+```markdown
+Use Read tool to load $1
+Use Grep to search for $2
+Use Edit to update findings
+```
+
+## Notes and Tips
+
+- Keep commands focused on a single task
+- Use descriptive names (verb-noun pattern)
+- Document all arguments clearly
+- Provide helpful examples
+- Consider error cases
+- Test with team members
+
+---
+
+## Template Usage Guidelines
+
+### Naming Commands
+
+**Good names** (verb-noun pattern):
+- `/review-pr` - Review pull request
+- `/generate-tests` - Generate unit tests
+- `/check-types` - Check TypeScript types
+- `/update-deps` - Update dependencies
+
+**Poor names**:
+- `/fix` - Too vague
+- `/test` - Conflicts with built-in
+- `/help` - Reserved
+- `/my-command-that-does-many-things` - Too long
+
+### Writing Descriptions
+
+The `description` field appears in `/help` output:
+
+**Good descriptions**:
+```yaml
+description: Review pull request for code quality and best practices
+description: Generate unit tests for specified file or module
+description: Update package dependencies and check for breaking changes
+```
+
+**Poor descriptions**:
+```yaml
+description: Does stuff
+description: Helper command
+description: Command
+```
+
+### Choosing Tool Permissions
+
+Explicitly declare tools your command needs:
+
+```yaml
+# Read-only command
+allowed-tools: Read(*), Grep(*), Glob(*)
+
+# Git operations
+allowed-tools: Bash(git status:*), Bash(git diff:*), Bash(git log:*)
+
+# File modifications
+allowed-tools: Read(*), Edit(*), Write(*), Bash(npm test:*)
+
+# Comprehensive access
+allowed-tools: Bash(*), Read(*), Write(*), Edit(*), Grep(*), Glob(*)
+```
+
+**Pattern syntax**:
+- `Tool(*)` - All operations
+- `Tool(pattern:*)` - Specific operation (e.g., `Bash(git status:*)`)
+- `Tool(*pattern*)` - Contains pattern
+
+### Using Arguments Effectively
+
+**Simple single argument**:
+```yaml
+argument-hint: [file-path]
+```
+```markdown
+Analyze the file: $ARGUMENTS
+```
+
+**Multiple arguments**:
+```yaml
+argument-hint: [source] [target]
+```
+```markdown
+Compare $1 to $2 and identify differences.
+```
+
+**Optional arguments**:
+```markdown
+If $1 is provided:
+  - Use $1 as the target
+Otherwise:
+  - Use current directory
+```
+
+### Command Categories
+
+Organize related commands in subdirectories:
+
+```
+.claude/commands/
+├── COMMANDS_TEMPLATE.md
+├── git/
+│   ├── commit.md
+│   ├── review-pr.md
+│   └── sync.md
+├── testing/
+│   ├── run-tests.md
+│   ├── generate-tests.md
+│   └── coverage.md
+└── docs/
+    ├── generate-readme.md
+    └── update-api-docs.md
+```
+
+Invoke with: `/git/commit`, `/testing/run-tests`, etc.
+
+### Combining with Bash Execution
+
+Execute shell commands inline:
+
+```markdown
+First, check the current branch:
+!git branch --show-current
+
+Then check for uncommitted changes:
+!git status --short
+
+If there are changes, show them:
+!git diff
+```
+
+### Combining with File References
+
+Include file contents automatically:
+
+```markdown
+Review the implementation in @$1 and suggest improvements.
+
+Compare the old version @$1 with the new version @$2.
+
+Analyze these related files:
+@src/main.js
+@src/utils.js
+@tests/main.test.js
+```
+
+### Model Selection Strategy
+
+Choose the right model for the task:
+
+```yaml
+# For complex reasoning and code generation (default)
+model: claude-3-5-sonnet-20241022
+
+# For fast, simple tasks (commit messages, formatting)
+model: claude-3-5-haiku-20241022
+
+# For most complex tasks (architecture, security reviews)
+model: claude-opus-4-20250514
+```
+
+### Disabling Model Invocation
+
+For simple text commands that don't need AI:
+
+```yaml
+---
+description: Show project documentation
+disable-model-invocation: true
+---
+
+# Project Documentation
+
+Visit: https://github.com/org/repo
+
+## Quick Links
+- [Setup Guide](docs/setup.md)
+- [API Reference](docs/api.md)
+- [Contributing](CONTRIBUTING.md)
+```
+
+## Command vs Skill: When to Use What
+
+### Use a **Command** when:
+- ✅ User needs to explicitly trigger the action
+- ✅ It's a specific workflow or routine task
+- ✅ You want predictable, on-demand behavior
+- ✅ Examples: `/review-pr`, `/generate-tests`, `/commit`
+
+### Use a **Skill** when:
+- ✅ Claude should automatically use it when relevant
+- ✅ It's specialized knowledge or expertise
+- ✅ You want Claude to discover it based on context
+- ✅ Examples: PDF processing, Excel analysis, specific frameworks
+
+### Can be **Both**:
+Create a command that explicitly invokes a skill:
+```markdown
+---
+description: Perform comprehensive code review
+---
+
+Activate the Code Review skill and analyze $ARGUMENTS for:
+- Code quality
+- Best practices
+- Security issues
+- Performance opportunities
+```
+
+---
+
+## Testing Your Command
+
+### 1. Basic Functionality
+```
+/command-name
+```
+Verify it executes without errors.
+
+### 2. With Arguments
+```
+/command-name arg1 arg2
+```
+Check argument handling works correctly.
+
+### 3. Edge Cases
+```
+/command-name
+/command-name ""
+/command-name with many arguments here
+```
+
+### 4. Tool Permissions
+Verify declared tools work without extra permission prompts.
+
+### 5. Team Testing
+Have colleagues try the command and provide feedback.
+
+---
+
+## Quick Reference Card
+
+| Element | Purpose | Required |
+|---------|---------|----------|
+| `description` | Shows in /help | ✅ Recommended |
+| `allowed-tools` | Pre-approve tools | ❌ Optional |
+| `argument-hint` | Show expected args | ❌ Optional |
+| `model` | Specify model | ❌ Optional |
+| `disable-model-invocation` | Skip AI for static text | ❌ Optional |
+| Instructions | What to do | ✅ Yes |
+| Examples | Usage demos | ✅ Recommended |
+| Error handling | Handle failures | ✅ Recommended |
+
+---
+
+## Common Command Patterns
+
+### 1. Read-Analyze-Report
+```markdown
+1. Read files specified in $ARGUMENTS
+2. Analyze for [criteria]
+3. Generate structured report
+```
+
+### 2. Execute-Parse-Summarize
+```markdown
+1. Run: !command $1
+2. Parse the output
+3. Summarize findings
+```
+
+### 3. Generate-Validate-Write
+```markdown
+1. Generate [content] based on $1
+2. Validate against [rules]
+3. Write to $2 or default location
+```
+
+### 4. Compare-Diff-Suggest
+```markdown
+1. Load both $1 and $2
+2. Compare differences
+3. Suggest improvements or migrations
+```
+
+### 5. Check-Fix-Verify
+```markdown
+1. Check for [issues] in $ARGUMENTS
+2. Apply fixes automatically
+3. Verify corrections worked
+```
+
+---
+
+**Pro tip**: Start with simple commands and gradually add complexity. Test each feature before adding the next. Share with your team early for feedback.