@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/extensions/plugin-dev/skills/command-development/references/plugin-features-reference.md

@@ -0,0 +1,637 @@
+# Plugin-Specific Command Features Reference
+
+This reference covers features and patterns specific to commands bundled in Claude Code plugins.
+
+## Table of Contents
+
+- [Plugin Command Discovery](#plugin-command-discovery)
+- [CLAUDE_PLUGIN_ROOT Environment Variable](#claude_plugin_root-environment-variable)
+- [Plugin Command Patterns](#plugin-command-patterns)
+- [Integration with Plugin Components](#integration-with-plugin-components)
+- [Validation Patterns](#validation-patterns)
+
+## Plugin Command Discovery
+
+### Auto-Discovery
+
+Claude Code automatically discovers commands in plugins using the following locations:
+
+```
+plugin-name/
+├── commands/              # Auto-discovered commands
+│   ├── foo.md            # /foo (plugin:plugin-name)
+│   └── bar.md            # /bar (plugin:plugin-name)
+└── plugin.json           # Plugin manifest
+```
+
+**Key points:**
+
+- Commands are discovered at plugin load time
+- No manual registration required
+- Commands appear in `/help` with "(plugin:plugin-name)" label
+- Subdirectories create namespaces
+
+### Namespaced Plugin Commands
+
+Organize commands in subdirectories for logical grouping:
+
+```
+plugin-name/
+└── commands/
+    ├── review/
+    │   ├── security.md    # /security (plugin:plugin-name:review)
+    │   └── style.md       # /style (plugin:plugin-name:review)
+    └── deploy/
+        ├── staging.md     # /staging (plugin:plugin-name:deploy)
+        └── prod.md        # /prod (plugin:plugin-name:deploy)
+```
+
+**Namespace behavior:**
+
+- Subdirectory name becomes namespace
+- Shown as "(plugin:plugin-name:namespace)" in `/help`
+- Helps organize related commands
+- Use when plugin has 5+ commands
+
+### Command Naming Conventions
+
+**Plugin command names should:**
+
+1. Be descriptive and action-oriented
+2. Avoid conflicts with common command names
+3. Use hyphens for multi-word names
+4. Consider prefixing with plugin name for uniqueness
+
+**Examples:**
+
+```
+Good:
+- /mylyn-sync          (plugin-specific prefix)
+- /analyze-performance (descriptive action)
+- /docker-compose-up   (clear purpose)
+
+Avoid:
+- /test               (conflicts with common name)
+- /run                (too generic)
+- /do-stuff           (not descriptive)
+```
+
+## CLAUDE_PLUGIN_ROOT Environment Variable
+
+### Purpose
+
+`${CLAUDE_PLUGIN_ROOT}` is a special environment variable available in plugin commands that resolves to the absolute path of the plugin directory.
+
+**Why it matters:**
+
+- Enables portable paths within plugin
+- Allows referencing plugin files and scripts
+- Works across different installations
+- Essential for multi-file plugin operations
+
+### Basic Usage
+
+Reference files within your plugin:
+
+```markdown
+---
+description: Analyze using plugin script
+allowed-tools: Bash(node:*), Read
+---
+
+Run analysis: [BANG]`node ${CLAUDE_PLUGIN_ROOT}/scripts/analyze.js`
+
+Read template: @${CLAUDE_PLUGIN_ROOT}/templates/report.md
+```
+
+**Expands to:**
+
+```markdown
+Run analysis: [actual output from analyze.js]
+
+Read template: @/path/to/plugins/plugin-name/templates/report.md
+```
+
+### Common Patterns
+
+#### 1. Executing Plugin Scripts
+
+```markdown
+---
+description: Run custom linter from plugin
+allowed-tools: Bash(node:*)
+---
+
+Lint results: [BANG]`node ${CLAUDE_PLUGIN_ROOT}/bin/lint.js $1`
+
+Review the linting output and suggest fixes.
+```
+
+#### 2. Loading Configuration Files
+
+```markdown
+---
+description: Deploy using plugin configuration
+allowed-tools: Read, Bash(*)
+---
+
+Configuration: @${CLAUDE_PLUGIN_ROOT}/config/deploy-config.json
+
+Deploy application using the configuration above for $1 environment.
+```
+
+#### 3. Accessing Plugin Resources
+
+```markdown
+---
+description: Generate report from template
+---
+
+Use this template: @${CLAUDE_PLUGIN_ROOT}/templates/api-report.md
+
+Generate a report for @$1 following the template format.
+```
+
+#### 4. Multi-Step Plugin Workflows
+
+```markdown
+---
+description: Complete plugin workflow
+allowed-tools: Bash(*), Read
+---
+
+Step 1 - Prepare: [BANG]`bash ${CLAUDE_PLUGIN_ROOT}/scripts/prepare.sh $1`
+Step 2 - Config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
+Step 3 - Execute: [BANG]`${CLAUDE_PLUGIN_ROOT}/bin/execute $1`
+
+Review results and report status.
+```
+
+### Best Practices
+
+1. **Always use for plugin-internal paths:**
+
+   ```markdown
+   # Good
+
+   @${CLAUDE_PLUGIN_ROOT}/templates/foo.md
+
+   # Bad
+
+   @./templates/foo.md # Relative to current directory, not plugin
+   ```
+
+2. **Validate file existence:**
+
+   ```markdown
+   ---
+   description: Use plugin config if exists
+   allowed-tools: Bash(test:*), Read
+   ---
+
+   [BANG]`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "exists" || echo "missing"`
+
+   If config exists, load it: @${CLAUDE_PLUGIN_ROOT}/config.json
+   Otherwise, use defaults...
+   ```
+
+3. **Document plugin file structure:**
+
+   ```markdown
+   <!--
+   Plugin structure:
+   ${CLAUDE_PLUGIN_ROOT}/
+   ├── scripts/analyze.js  (analysis script)
+   ├── templates/          (report templates)
+   └── config/             (configuration files)
+   -->
+   ```
+
+4. **Combine with arguments:**
+   ```markdown
+   Run: [BANG]`${CLAUDE_PLUGIN_ROOT}/bin/process.sh $1 $2`
+   ```
+
+### Troubleshooting
+
+**Variable not expanding:**
+
+- Ensure command is loaded from plugin
+- Check bash execution is allowed
+- Verify syntax is exact: `${CLAUDE_PLUGIN_ROOT}`
+
+**File not found errors:**
+
+- Verify file exists in plugin directory
+- Check file path is correct relative to plugin root
+- Ensure file permissions allow reading/execution
+
+**Path with spaces:**
+
+- Bash commands automatically handle spaces
+- File references work with spaces in paths
+- No special quoting needed
+
+## Plugin Command Patterns
+
+### Pattern 1: Configuration-Based Commands
+
+Commands that load plugin-specific configuration:
+
+```markdown
+---
+description: Deploy using plugin settings
+allowed-tools: Read, Bash(*)
+---
+
+Load configuration: @${CLAUDE_PLUGIN_ROOT}/deploy-config.json
+
+Deploy to $1 environment using:
+
+1. Configuration settings above
+2. Current git branch: [BANG]`git branch --show-current`
+3. Application version: [BANG]`cat package.json | grep version`
+
+Execute deployment and monitor progress.
+```
+
+**When to use:** Commands that need consistent settings across invocations
+
+### Pattern 2: Template-Based Generation
+
+Commands that use plugin templates:
+
+```markdown
+---
+description: Generate documentation from template
+argument-hint: [component-name]
+---
+
+Template: @${CLAUDE_PLUGIN_ROOT}/templates/component-docs.md
+
+Generate documentation for $1 component following the template structure.
+Include:
+
+- Component purpose and usage
+- API reference
+- Examples
+- Testing guidelines
+```
+
+**When to use:** Standardized output generation
+
+### Pattern 3: Multi-Script Workflow
+
+Commands that orchestrate multiple plugin scripts:
+
+```markdown
+---
+description: Complete build and test workflow
+allowed-tools: Bash(*)
+---
+
+Build: [BANG]`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
+Validate: [BANG]`bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh`
+Test: [BANG]`bash ${CLAUDE_PLUGIN_ROOT}/scripts/test.sh`
+
+Review all outputs and report:
+
+1. Build status
+2. Validation results
+3. Test results
+4. Recommended next steps
+```
+
+**When to use:** Complex plugin workflows with multiple steps
+
+### Pattern 4: Environment-Aware Commands
+
+Commands that adapt to environment:
+
+```markdown
+---
+description: Deploy based on environment
+argument-hint: [dev|staging|prod]
+---
+
+Environment config: @${CLAUDE_PLUGIN_ROOT}/config/$1.json
+
+Environment check: [BANG]`echo "Deploying to: $1"`
+
+Deploy application using $1 environment configuration.
+Verify deployment and run smoke tests.
+```
+
+**When to use:** Commands that behave differently per environment
+
+### Pattern 5: Plugin Data Management
+
+Commands that manage plugin-specific data:
+
+```markdown
+---
+description: Save analysis results to plugin cache
+allowed-tools: Bash(*), Read, Write
+---
+
+Cache directory: ${CLAUDE_PLUGIN_ROOT}/cache/
+
+Analyze @$1 and save results to cache:
+[BANG]`mkdir -p ${CLAUDE_PLUGIN_ROOT}/cache && date > ${CLAUDE_PLUGIN_ROOT}/cache/last-run.txt`
+
+Store analysis for future reference and comparison.
+```
+
+**When to use:** Commands that need persistent data storage
+
+## Integration with Plugin Components
+
+### Invoking Plugin Agents
+
+Commands can trigger plugin agents using the Task tool:
+
+```markdown
+---
+description: Deep analysis using plugin agent
+argument-hint: [file-path]
+---
+
+Initiate deep code analysis of @$1 using the code-analyzer agent.
+
+The agent will:
+
+1. Analyze code structure
+2. Identify patterns
+3. Suggest improvements
+4. Generate detailed report
+
+Note: This uses the Task tool to launch the plugin's code-analyzer agent.
+```
+
+**Key points:**
+
+- Agent must be defined in plugin's `agents/` directory
+- Claude will automatically use Task tool to launch agent
+- Agent has access to same plugin resources
+
+### Invoking Plugin Skills
+
+Commands can reference plugin skills for specialized knowledge:
+
+```markdown
+---
+description: API documentation with best practices
+argument-hint: [api-file]
+---
+
+Document the API in @$1 following our API documentation standards.
+
+Use the api-docs-standards skill to ensure documentation includes:
+
+- Endpoint descriptions
+- Parameter specifications
+- Response formats
+- Error codes
+- Usage examples
+
+Note: This leverages the plugin's api-docs-standards skill for consistency.
+```
+
+**Key points:**
+
+- Skill must be defined in plugin's `skills/` directory
+- Mention skill by name to hint Claude should invoke it
+- Skills provide specialized domain knowledge
+
+### Coordinating with Plugin Hooks
+
+Commands can be designed to work with plugin hooks:
+
+```markdown
+---
+description: Commit with pre-commit validation
+allowed-tools: Bash(git:*)
+---
+
+Stage changes: [BANG]`git add $1`
+
+Commit changes: [BANG]`git commit -m "$2"`
+
+Note: This commit will trigger the plugin's pre-commit hook for validation.
+Review hook output for any issues.
+```
+
+**Key points:**
+
+- Hooks execute automatically on events
+- Commands can prepare state for hooks
+- Document hook interaction in command
+
+### Multi-Component Plugin Commands
+
+Commands that coordinate multiple plugin components:
+
+```markdown
+---
+description: Comprehensive code review workflow
+argument-hint: [file-path]
+---
+
+File to review: @$1
+
+Execute comprehensive review:
+
+1. **Static Analysis** (via plugin scripts)
+   [BANG]`node ${CLAUDE_PLUGIN_ROOT}/scripts/lint.js $1`
+
+2. **Deep Review** (via plugin agent)
+   Launch the code-reviewer agent for detailed analysis.
+
+3. **Best Practices** (via plugin skill)
+   Use the code-standards skill to ensure compliance.
+
+4. **Documentation** (via plugin template)
+   Template: @${CLAUDE_PLUGIN_ROOT}/templates/review-report.md
+
+Generate final report combining all outputs.
+```
+
+**When to use:** Complex workflows leveraging multiple plugin capabilities
+
+## Validation Patterns
+
+### Input Validation
+
+Commands should validate inputs before processing:
+
+```markdown
+---
+description: Deploy to environment with validation
+argument-hint: [environment]
+---
+
+Validate environment: [BANG]`echo "$1" | grep -E "^(dev|staging|prod)$" || echo "INVALID"`
+
+$IF($1 in [dev, staging, prod],
+Deploy to $1 environment using validated configuration,
+ERROR: Invalid environment '$1'. Must be one of: dev, staging, prod
+)
+```
+
+**Validation approaches:**
+
+1. Bash validation using grep/test
+2. Inline validation in prompt
+3. Script-based validation
+
+### File Existence Checks
+
+Verify required files exist:
+
+```markdown
+---
+description: Process configuration file
+argument-hint: [config-file]
+---
+
+Check file: [BANG]`test -f $1 && echo "EXISTS" || echo "MISSING"`
+
+Process configuration if file exists: @$1
+
+If file doesn't exist, explain:
+
+- Expected location
+- Required format
+- How to create it
+```
+
+### Required Arguments
+
+Validate required arguments provided:
+
+```markdown
+---
+description: Create deployment with version
+argument-hint: [environment] [version]
+---
+
+Validate inputs: [BANG]`test -n "$1" -a -n "$2" && echo "OK" || echo "MISSING"`
+
+$IF($1 AND $2,
+Deploy version $2 to $1 environment,
+ERROR: Both environment and version required. Usage: /deploy [env] [version]
+)
+```
+
+### Plugin Resource Validation
+
+Verify plugin resources available:
+
+```markdown
+---
+description: Run analysis with plugin tools
+allowed-tools: Bash(test:*)
+---
+
+Validate plugin setup:
+
+- Config exists: [BANG]`test -f ${CLAUDE_PLUGIN_ROOT}/config.json && echo "✓" || echo "✗"`
+- Scripts exist: [BANG]`test -d ${CLAUDE_PLUGIN_ROOT}/scripts && echo "✓" || echo "✗"`
+- Tools available: [BANG]`test -x ${CLAUDE_PLUGIN_ROOT}/bin/analyze && echo "✓" || echo "✗"`
+
+If all checks pass, proceed with analysis.
+Otherwise, report missing components and installation steps.
+```
+
+### Output Validation
+
+Validate command execution results:
+
+```markdown
+---
+description: Build and validate output
+allowed-tools: Bash(*)
+---
+
+Build: [BANG]`bash ${CLAUDE_PLUGIN_ROOT}/scripts/build.sh`
+
+Validate output:
+
+- Exit code: [BANG]`echo $?`
+- Output exists: [BANG]`test -d dist && echo "✓" || echo "✗"`
+- File count: [BANG]`find dist -type f | wc -l`
+
+Report build status and any validation failures.
+```
+
+### Graceful Error Handling
+
+Handle errors gracefully with helpful messages:
+
+```markdown
+---
+description: Process file with error handling
+argument-hint: [file-path]
+---
+
+Try processing: [BANG]`node ${CLAUDE_PLUGIN_ROOT}/scripts/process.js $1 2>&1 || echo "ERROR: $?"`
+
+If processing succeeded:
+
+- Report results
+- Suggest next steps
+
+If processing failed:
+
+- Explain likely causes
+- Provide troubleshooting steps
+- Suggest alternative approaches
+```
+
+## Best Practices Summary
+
+### Plugin Commands Should
+
+1. **Use ${CLAUDE_PLUGIN_ROOT} for all plugin-internal paths**
+   - Scripts, templates, configuration, resources
+
+2. **Validate inputs early**
+   - Check required arguments
+   - Verify file existence
+   - Validate argument formats
+
+3. **Document plugin structure**
+   - Explain required files
+   - Document script purposes
+   - Clarify dependencies
+
+4. **Integrate with plugin components**
+   - Reference agents for complex tasks
+   - Use skills for specialized knowledge
+   - Coordinate with hooks when relevant
+
+5. **Provide helpful error messages**
+   - Explain what went wrong
+   - Suggest how to fix
+   - Offer alternatives
+
+6. **Handle edge cases**
+   - Missing files
+   - Invalid arguments
+   - Failed script execution
+   - Missing dependencies
+
+7. **Keep commands focused**
+   - One clear purpose per command
+   - Delegate complex logic to scripts
+   - Use agents for multi-step workflows
+
+8. **Test across installations**
+   - Verify paths work everywhere
+   - Test with different arguments
+   - Validate error cases
+
+---
+
+For general command development, see main SKILL.md.
+For command examples, see examples/ directory.