aiblueprint-cli 1.4.11 → 1.4.13

package/claude-code-config/skills/create-slash-commands/references/patterns.md

@@ -0,0 +1,947 @@
+# Command Patterns Reference
+
+Verified patterns from official Claude Code documentation.
+
+## Git Workflow Patterns
+
+### Pattern: Commit with Full Context
+
+**Source**: Official Claude Code documentation
+
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+description: Create a git commit
+---
+
+<objective>
+Create a git commit for current changes following repository conventions.
+</objective>
+
+<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`
+</context>
+
+<process>
+1. Review staged and unstaged changes
+2. Stage relevant files with git add
+3. Write commit message following recent commit style
+4. Create commit
+</process>
+
+<success_criteria>
+
+- All relevant changes staged
+- Commit message follows repository conventions
+- Commit created successfully
+  </success_criteria>
+```
+
+**Key features**:
+
+- Tool restrictions prevent running arbitrary bash commands
+- Dynamic context loaded via the exclamation mark prefix before backticks
+- Git state injected before prompt execution
+
+### Pattern: Simple Git Commit
+
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+description: Create a git commit
+---
+
+<objective>
+Create a commit for current changes.
+</objective>
+
+<context>
+Current changes: ! `git status`
+</context>
+
+<process>
+1. Review changes
+2. Stage files
+3. Create commit
+</process>
+
+<success_criteria>
+
+- Changes committed successfully
+  </success_criteria>
+```
+
+## Code Analysis Patterns
+
+### Pattern: Performance Optimization
+
+**Source**: Official Claude Code documentation
+
+**File**: `.claude/commands/optimize.md`
+
+```markdown
+---
+description: Analyze the performance of this code and suggest three specific optimizations
+---
+
+<objective>
+Analyze code performance and suggest three specific optimizations.
+
+This helps improve application performance through targeted improvements.
+</objective>
+
+<process>
+1. Review code in current conversation context
+2. Identify bottlenecks and inefficiencies
+3. Suggest three specific optimizations with rationale
+4. Estimate performance impact of each
+</process>
+
+<success_criteria>
+
+- Performance issues clearly identified
+- Three concrete optimizations suggested
+- Implementation guidance provided
+- Performance impact estimated
+  </success_criteria>
+```
+
+**Usage**: `/optimize`
+
+Claude analyzes code in the current conversation context.
+
+### Pattern: Security Review
+
+**File**: `.claude/commands/security-review.md`
+
+```markdown
+---
+description: Review this code for security vulnerabilities
+---
+
+<objective>
+Review code for security vulnerabilities and suggest fixes.
+</objective>
+
+<process>
+1. Scan code for common vulnerabilities (XSS, SQL injection, CSRF, etc.)
+2. Identify specific issues with line numbers
+3. Assess severity of each vulnerability
+4. Suggest remediation for each issue
+</process>
+
+<success_criteria>
+
+- All major vulnerability types checked
+- Specific issues identified with locations
+- Severity levels assigned
+- Actionable fixes provided
+  </success_criteria>
+```
+
+**Usage**: `/security-review`
+
+### Pattern: File-Specific Analysis
+
+```markdown
+---
+description: Optimize specific file
+argument-hint: [file-path]
+---
+
+<objective>
+Analyze performance of @ #$ARGUMENTS and suggest three specific optimizations.
+
+This helps improve application performance through targeted file improvements.
+</objective>
+
+<process>
+1. Review code in @ #$ARGUMENTS for performance issues
+2. Identify bottlenecks and inefficiencies
+3. Suggest three specific optimizations with rationale
+4. Estimate performance impact of each
+</process>
+
+<success_criteria>
+
+- File analyzed thoroughly
+- Performance issues identified
+- Three concrete optimizations suggested
+- Implementation guidance provided
+  </success_criteria>
+```
+
+**Usage**: `/optimize src/utils/helpers.js`
+
+References the specified file.
+
+## Issue Tracking Patterns
+
+### Pattern: Fix Issue with Workflow
+
+**Source**: Official Claude Code documentation
+
+```markdown
+---
+description: Find and fix issue following workflow
+argument-hint: [issue-number]
+---
+
+<objective>
+Find and fix issue #$ARGUMENTS following project workflow.
+
+This ensures bugs are resolved systematically with proper testing and documentation.
+</objective>
+
+<process>
+1. Understand the issue described in ticket #$ARGUMENTS
+2. Locate the relevant code in codebase
+3. Implement a solution that addresses the root cause
+4. Add appropriate tests
+5. Prepare a concise PR description
+</process>
+
+<success_criteria>
+
+- Issue fully understood and addressed
+- Solution addresses root cause
+- Tests added and passing
+- PR description clearly explains fix
+  </success_criteria>
+```
+
+**Usage**: `/fix-issue 123`
+
+### Pattern: PR Review with Context
+
+```markdown
+---
+description: Review PR with priority and assignment
+argument-hint: <pr-number> <priority> <assignee>
+---
+
+<objective>
+Review PR #$1 with priority $2 and assign to $3.
+
+This ensures PRs are reviewed systematically with proper prioritization and assignment.
+</objective>
+
+<process>
+1. Fetch PR #$1 details
+2. Review code changes
+3. Assess based on priority $2
+4. Provide feedback
+5. Assign to $3
+</process>
+
+<success_criteria>
+
+- PR reviewed thoroughly
+- Priority considered in review depth
+- Constructive feedback provided
+- Assigned to correct person
+  </success_criteria>
+```
+
+**Usage**: `/review-pr 456 high alice`
+
+Uses positional arguments for structured input.
+
+## File Operation Patterns
+
+### Pattern: File Reference
+
+**Source**: Official Claude Code documentation
+
+```markdown
+---
+description: Review implementation
+---
+
+<objective>
+Review the implementation in @ src/utils/helpers.js.
+
+This ensures code quality and identifies potential improvements.
+</objective>
+
+<process>
+1. Read @ src/utils/helpers.js
+2. Analyze code structure and patterns
+3. Check for best practices
+4. Identify potential improvements
+5. Suggest specific changes
+</process>
+
+<success_criteria>
+
+- File reviewed thoroughly
+- Code quality assessed
+- Specific improvements identified
+- Actionable suggestions provided
+  </success_criteria>
+```
+
+Uses `@` prefix to reference specific files.
+
+### Pattern: Dynamic File Reference
+
+```markdown
+---
+description: Review specific file
+argument-hint: [file-path]
+---
+
+<objective>
+Review the implementation in @ #$ARGUMENTS.
+
+This allows flexible file review based on user specification.
+</objective>
+
+<process>
+1. Read @ #$ARGUMENTS
+2. Analyze code structure and patterns
+3. Check for best practices
+4. Identify potential improvements
+5. Suggest specific changes
+</process>
+
+<success_criteria>
+
+- File reviewed thoroughly
+- Code quality assessed
+- Specific improvements identified
+- Actionable suggestions provided
+  </success_criteria>
+```
+
+**Usage**: `/review src/app.js`
+
+File path comes from argument.
+
+### Pattern: Multi-File Analysis
+
+```markdown
+---
+description: Compare two files
+argument-hint: <file1> <file2>
+---
+
+<objective>
+Compare @ $1 with @ $2 and highlight key differences.
+
+This helps understand changes and identify important variations between files.
+</objective>
+
+<process>
+1. Read @ $1 and @ $2
+2. Identify structural differences
+3. Compare functionality and logic
+4. Highlight key changes
+5. Assess impact of differences
+</process>
+
+<success_criteria>
+
+- Both files analyzed
+- Key differences identified
+- Impact of changes assessed
+- Clear comparison provided
+  </success_criteria>
+```
+
+**Usage**: `/compare src/old.js src/new.js`
+
+## Thinking-Only Patterns
+
+### Pattern: Deep Analysis
+
+```markdown
+---
+description: Analyze problem from first principles
+allowed-tools: SequentialThinking
+---
+
+<objective>
+Analyze the current problem from first principles.
+
+This helps discover optimal solutions by stripping away assumptions and rebuilding from fundamental truths.
+</objective>
+
+<process>
+1. Identify the core problem
+2. Strip away all assumptions
+3. Identify fundamental truths and constraints
+4. Rebuild solution from first principles
+5. Compare with current approach
+</process>
+
+<success_criteria>
+
+- Problem analyzed from ground up
+- Assumptions identified and questioned
+- Solution rebuilt from fundamentals
+- Novel insights discovered
+  </success_criteria>
+```
+
+Tool restriction ensures Claude only uses SequentialThinking.
+
+### Pattern: Strategic Planning
+
+```markdown
+---
+description: Plan implementation strategy
+allowed-tools: SequentialThinking
+argument-hint: [task description]
+---
+
+<objective>
+Create a detailed implementation strategy for: #$ARGUMENTS
+
+This ensures complex tasks are approached systematically with proper planning.
+</objective>
+
+<process>
+1. Break down task into phases
+2. Identify dependencies between phases
+3. Estimate complexity for each phase
+4. Suggest optimal approach
+5. Identify potential risks
+</process>
+
+<success_criteria>
+
+- Task broken into clear phases
+- Dependencies mapped
+- Complexity estimated
+- Optimal approach identified
+- Risks and mitigations outlined
+  </success_criteria>
+```
+
+## Bash Execution Patterns
+
+### Pattern: Dynamic Environment Loading
+
+```markdown
+---
+description: Check project status
+---
+
+<objective>
+Provide a comprehensive project health summary.
+
+This helps understand current project state across git, dependencies, and tests.
+</objective>
+
+<context>
+- Git: ! `git status --short`
+- Node: ! `npm list --depth=0 2>/dev/null | head -20`
+- Tests: ! `npm test -- --listTests 2>/dev/null | wc -l`
+</context>
+
+<process>
+1. Analyze git status for uncommitted changes
+2. Review npm dependencies for issues
+3. Check test coverage
+4. Identify potential problems
+5. Provide actionable recommendations
+</process>
+
+<success_criteria>
+
+- All metrics checked
+- Current state clearly described
+- Issues identified
+- Recommendations provided
+  </success_criteria>
+```
+
+Multiple bash commands load environment state.
+
+### Pattern: Conditional Execution
+
+```markdown
+---
+description: Deploy if tests pass
+allowed-tools: Bash(npm test:*), Bash(npm run deploy:*)
+---
+
+<objective>
+Deploy to production only if all tests pass.
+
+This ensures deployment safety through automated testing gates.
+</objective>
+
+<context>
+Test results: ! `npm test`
+</context>
+
+<process>
+1. Review test results
+2. If all tests passed, proceed to deployment
+3. If any tests failed, report failures and abort
+4. Monitor deployment process
+5. Confirm successful deployment
+</process>
+
+<success_criteria>
+
+- All tests verified passing
+- Deployment executed only on test success
+- Deployment confirmed successful
+- Or deployment aborted with clear failure reasons
+  </success_criteria>
+```
+
+## Multi-Step Workflow Patterns
+
+### Pattern: Structured Workflow
+
+```markdown
+---
+description: Complete feature development workflow
+argument-hint: [feature description]
+---
+
+<objective>
+Complete full feature development workflow for: #$ARGUMENTS
+
+This ensures features are developed systematically with proper planning, implementation, testing, and documentation.
+</objective>
+
+<process>
+1. **Planning**
+   - Review requirements
+   - Design approach
+   - Identify files to modify
+
+2. **Implementation**
+   - Write code
+   - Add tests
+   - Update documentation
+
+3. **Review**
+   - Run tests: ! `npm test`
+   - Check lint: ! `npm run lint`
+   - Verify changes: ! `git diff`
+
+4. **Completion**
+   - Create commit
+   - Write PR description
+     </process>
+
+<testing>
+- Run tests: ! `npm test`
+- Check lint: ! `npm run lint`
+</testing>
+
+<verification>
+Before completing:
+- All tests passing
+- No lint errors
+- Documentation updated
+- Changes verified with git diff
+</verification>
+
+<success_criteria>
+
+- Feature fully implemented
+- Tests added and passing
+- Code passes linting
+- Documentation updated
+- Commit created
+- PR description written
+  </success_criteria>
+```
+
+## Command Chaining Patterns
+
+### Pattern: Analysis → Action
+
+```markdown
+---
+description: Analyze and fix performance issues
+argument-hint: [file-path]
+---
+
+<objective>
+Analyze and fix performance issues in @ #$ARGUMENTS.
+
+This provides end-to-end performance improvement from analysis through verification.
+</objective>
+
+<process>
+1. Analyze @ #$ARGUMENTS for performance issues
+2. Identify top 3 most impactful optimizations
+3. Implement the optimizations
+4. Verify improvements with benchmarks
+</process>
+
+<verification>
+Before completing:
+- Benchmarks run showing performance improvement
+- No functionality regressions
+- Code quality maintained
+</verification>
+
+<success_criteria>
+
+- Performance issues identified and fixed
+- Measurable performance improvement
+- Benchmarks confirm gains
+- No regressions introduced
+  </success_criteria>
+```
+
+Sequential steps in single command.
+
+## Tool Restriction Patterns
+
+### Pattern: Git-Only Command
+
+```markdown
+---
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git diff:*), Bash(git commit:*)
+description: Git workflow command
+---
+
+<objective>
+Perform git operations safely with tool restrictions.
+
+This prevents running arbitrary bash commands while allowing necessary git operations.
+</objective>
+
+<context>
+Current git state: ! `git status`
+</context>
+
+<process>
+1. Review git status
+2. Perform git operations
+3. Verify changes
+</process>
+
+<success_criteria>
+
+- Git operations completed successfully
+- No arbitrary commands executed
+- Repository state as expected
+  </success_criteria>
+```
+
+Prevents running non-git bash commands.
+
+### Pattern: Read-Only Analysis
+
+```markdown
+---
+allowed-tools: [Read, Grep, Glob]
+description: Analyze codebase
+argument-hint: [search pattern]
+---
+
+<objective>
+Search codebase for pattern: #$ARGUMENTS
+
+This provides safe codebase analysis without modification or execution permissions.
+</objective>
+
+<process>
+1. Use Grep to search for pattern across codebase
+2. Analyze findings
+3. Identify relevant files and code sections
+4. Provide summary of results
+</process>
+
+<success_criteria>
+
+- Pattern search completed
+- All matches identified
+- Relevant context provided
+- No files modified
+  </success_criteria>
+```
+
+No write or execution permissions.
+
+### Pattern: Specific Bash Commands
+
+```markdown
+---
+allowed-tools: Bash(npm test:*), Bash(npm run lint:*)
+description: Run project checks
+---
+
+<objective>
+Run project quality checks (tests and linting).
+
+This ensures code quality while restricting to specific npm scripts.
+</objective>
+
+<testing>
+Tests: ! `npm test`
+Lint: ! `npm run lint`
+</testing>
+
+<process>
+1. Run tests and capture results
+2. Run linting and capture results
+3. Analyze both outputs
+4. Report on pass/fail status
+5. Provide specific failure details if any
+</process>
+
+<success_criteria>
+
+- All tests passing
+- No lint errors
+- Clear report of results
+- Or specific failures identified with details
+  </success_criteria>
+```
+
+Only allows specific npm scripts.
+
+## Best Practices
+
+### 1. Use Tool Restrictions for Safety
+
+```yaml
+# Git commands
+allowed-tools: Bash(git add:*), Bash(git status:*)
+
+# Analysis only
+allowed-tools: [Read, Grep, Glob]
+
+# Thinking only
+allowed-tools: SequentialThinking
+```
+
+### 2. Load Dynamic Context When Needed
+
+```markdown
+Current state: ! `git status`
+Recent activity: ! `git log --oneline -5`
+```
+
+### 3. Reference Files Explicitly
+
+```markdown
+Review @ package.json for dependencies
+Check @ src/config/\* for settings
+```
+
+### 4. Structure Complex Commands
+
+```markdown
+## Step 1: Analysis
+
+[analysis prompt]
+
+## Step 2: Implementation
+
+[implementation prompt]
+
+## Step 3: Verification
+
+[verification prompt]
+```
+
+### 5. Use Arguments for Flexibility
+
+```markdown
+# Simple
+
+Fix issue #$ARGUMENTS
+
+# Positional
+
+Review PR #$1 with priority $2
+
+# File reference
+
+Analyze @ #$ARGUMENTS
+```
+
+## Subagent Patterns
+
+Slash commands can instruct Claude to use the Task tool to launch subagents for specialized work. This is powerful for delegating complex tasks to focused agents.
+
+### Pattern: Launch Subagent for Analysis
+
+```markdown
+---
+description: Deep security analysis with subagent
+argument-hint: [file-path or directory]
+---
+
+<objective>
+Perform comprehensive security analysis on #$ARGUMENTS using specialized security subagent.
+</objective>
+
+<process>
+1. Use the Task tool to launch the `security-scanner` subagent
+2. Pass the target path #$ARGUMENTS to the subagent
+3. Wait for subagent to complete analysis
+4. Present findings to user with severity ratings
+</process>
+
+<success_criteria>
+- Security subagent completed analysis
+- All findings reported with severity
+- Remediation suggestions provided
+</success_criteria>
+```
+
+### Pattern: Parallel Subagents
+
+Launch multiple subagents in parallel for comprehensive analysis:
+
+```markdown
+---
+description: Comprehensive code review with multiple subagents
+---
+
+<objective>
+Perform multi-faceted code review using parallel subagents.
+</objective>
+
+<context>
+Changed files: ! `git diff --name-only HEAD~1`
+</context>
+
+<process>
+1. Launch these subagents IN PARALLEL using run_in_background: true
+   - `code-reviewer` for code quality
+   - `security-scanner` for security issues
+   - `test-analyzer` for test coverage
+2. Collect results from all subagents using TaskOutput
+3. Synthesize findings into unified report
+</process>
+
+<success_criteria>
+- All three subagents completed
+- Findings consolidated
+- Unified report provided
+</success_criteria>
+```
+
+### Pattern: Background Agent with Progress
+
+```markdown
+---
+description: Long-running documentation generation
+argument-hint: [module-name]
+---
+
+<objective>
+Generate comprehensive documentation for #$ARGUMENTS using background subagent.
+</objective>
+
+<process>
+1. Launch `doc-generator` subagent in background (run_in_background: true)
+2. Report to user that documentation generation started
+3. Use TaskOutput with block: false to periodically check status
+4. Present final documentation when complete
+</process>
+
+<output>
+Files created:
+- `docs/#$ARGUMENTS/README.md`
+- `docs/#$ARGUMENTS/api-reference.md`
+</output>
+
+<success_criteria>
+- Documentation generated for all public APIs
+- Examples included
+- Links verified
+</success_criteria>
+```
+
+### Best Practices for Subagent Commands
+
+**1. Specify the subagent type clearly**
+```markdown
+Use the Task tool to launch the `code-reviewer` subagent...
+```
+
+**2. Pass context to subagents**
+```markdown
+Pass these files to the subagent:
+- Current changes: ! `git diff --name-only`
+- Target path: #$ARGUMENTS
+```
+
+**3. Use background for long-running tasks**
+```markdown
+Launch with run_in_background: true for tasks > 30 seconds
+```
+
+**4. Collect and synthesize results**
+```markdown
+After all subagents complete, synthesize findings into a unified report
+```
+
+## Anti-Patterns to Avoid
+
+### ❌ No Description
+
+```yaml
+---
+# Missing description field
+---
+```
+
+### ❌ Overly Broad Tool Access
+
+```yaml
+# Git command with no restrictions
+---
+description: Create commit
+---
+```
+
+Better:
+
+```yaml
+---
+description: Create commit
+allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
+---
+```
+
+### ❌ Vague Instructions
+
+```markdown
+Do the thing for #$ARGUMENTS
+```
+
+Better:
+
+```markdown
+Fix issue #$ARGUMENTS by:
+
+1. Understanding the issue
+2. Locating relevant code
+3. Implementing solution
+4. Adding tests
+```
+
+### ❌ Missing Context for State-Dependent Tasks
+
+```markdown
+Create a git commit
+```
+
+Better:
+
+```markdown
+Current changes: ! `git status`
+Diff: ! `git diff`
+
+Create a git commit for these changes
+```