@amsterdamdatalabs/enact-extensions 0.1.3 → 0.1.8

package/extensions/plugin-dev/skills/command-development/references/marketplace-considerations.md

@@ -1,943 +0,0 @@
-# Marketplace Considerations for Commands
-
-Guidelines for creating commands designed for distribution and marketplace success.
-
-## Overview
-
-Commands distributed through marketplaces need additional consideration beyond personal use commands. They must work across environments, handle diverse use cases, and provide excellent user experience for unknown users.
-
-## Design for Distribution
-
-### Universal Compatibility
-
-**Cross-platform considerations:**
-
-```markdown
----
-description: Cross-platform command
-allowed-tools: Bash(*)
----
-
-# Platform-Aware Command
-
-Detecting platform...
-
-case "$(uname)" in
-Darwin*) PLATFORM="macOS" ;;
-Linux*) PLATFORM="Linux" ;;
-MINGW*|MSYS*|CYGWIN*) PLATFORM="Windows" ;;
-*) PLATFORM="Unknown" ;;
-esac
-
-Platform: $PLATFORM
-
-<!-- Adjust behavior based on platform -->
-
-if [ "$PLATFORM" = "Windows" ]; then
-
-# Windows-specific handling
-
-PATH_SEP="\\"
-NULL_DEVICE="NUL"
-else
-
-# Unix-like handling
-
-PATH_SEP="/"
-NULL_DEVICE="/dev/null"
-fi
-
-[Platform-appropriate implementation...]
-```
-
-**Avoid platform-specific commands:**
-
-```markdown
-<!-- BAD: macOS-specific -->
-
-`pbcopy < file.txt`
-
-<!-- GOOD: Platform detection -->
-
-if command -v pbcopy > /dev/null; then
-pbcopy < file.txt
-elif command -v xclip > /dev/null; then
-xclip -selection clipboard < file.txt
-elif command -v clip.exe > /dev/null; then
-cat file.txt | clip.exe
-else
-echo "Clipboard not available on this platform"
-fi
-```
-
-### Minimal Dependencies
-
-**Check for required tools:**
-
-```markdown
----
-description: Dependency-aware command
-allowed-tools: Bash(*)
----
-
-# Check Dependencies
-
-Required tools:
-
-- git
-- jq
-- node
-
-Checking availability...
-
-MISSING_DEPS=""
-
-for tool in git jq node; do
-if ! command -v $tool > /dev/null; then
-    MISSING_DEPS="$MISSING_DEPS $tool"
-fi
-done
-
-if [ -n "$MISSING_DEPS" ]; then
-❌ ERROR: Missing required dependencies:$MISSING_DEPS
-
-INSTALLATION:
-
-- git: https://git-scm.com/downloads
-- jq: https://stedolan.github.io/jq/download/
-- node: https://nodejs.org/
-
-Install missing tools and try again.
-
-Exit.
-fi
-
-✓ All dependencies available
-
-[Continue with command...]
-```
-
-**Document optional dependencies:**
-
-```markdown
-<!--
-DEPENDENCIES:
-  Required:
-  - git 2.0+: Version control
-  - jq 1.6+: JSON processing
-
-  Optional:
-  - gh: GitHub CLI (for PR operations)
-  - docker: Container operations (for containerized tests)
-
-  Feature availability depends on installed tools.
--->
-```
-
-### Graceful Degradation
-
-**Handle missing features:**
-
-```markdown
----
-description: Feature-aware command
----
-
-# Feature Detection
-
-Detecting available features...
-
-FEATURES=""
-
-if command -v gh > /dev/null; then
-FEATURES="$FEATURES github"
-fi
-
-if command -v docker > /dev/null; then
-FEATURES="$FEATURES docker"
-fi
-
-Available features: $FEATURES
-
-if echo "$FEATURES" | grep -q "github"; then
-
-# Full functionality with GitHub integration
-
-echo "✓ GitHub integration available"
-else
-
-# Reduced functionality without GitHub
-
-echo "⚠ Limited functionality: GitHub CLI not installed"
-echo " Install 'gh' for full features"
-fi
-
-[Adapt behavior based on available features...]
-```
-
-## User Experience for Unknown Users
-
-### Clear Onboarding
-
-**First-run experience:**
-
-```markdown
----
-description: Command with onboarding
-allowed-tools: Read, Write
----
-
-# First Run Check
-
-if [ ! -f ".claude/command-initialized" ]; then
-**Welcome to Command Name!**
-
-This appears to be your first time using this command.
-
-WHAT THIS COMMAND DOES:
-[Brief explanation of purpose and benefits]
-
-QUICK START:
-
-1. Basic usage: /command [arg]
-2. For help: /command help
-3. Examples: /command examples
-
-SETUP:
-No additional setup required. You're ready to go!
-
-✓ Initialization complete
-
-[Create initialization marker]
-
-Ready to proceed with your request...
-fi
-
-[Normal command execution...]
-```
-
-**Progressive feature discovery:**
-
-```markdown
----
-description: Command with tips
----
-
-# Command Execution
-
-[Main functionality...]
-
----
-
-💡 TIP: Did you know?
-
-You can speed up this command with the --fast flag:
-/command --fast [args]
-
-For more tips: /command tips
-```
-
-### Comprehensive Error Handling
-
-**Anticipate user mistakes:**
-
-```markdown
----
-description: Forgiving command
----
-
-# User Input Handling
-
-Argument: "$1"
-
-<!-- Check for common typos -->
-
-if [ "$1" = "hlep" ] || [ "$1" = "hepl" ]; then
-Did you mean: help?
-
-Showing help instead...
-[Display help]
-
-Exit.
-fi
-
-<!-- Suggest similar commands if not found -->
-
-if [ "$1" != "valid-option1" ] && [ "$1" != "valid-option2" ]; then
-❌ Unknown option: $1
-
-Did you mean:
-
-- valid-option1 (most similar)
-- valid-option2
-
-For all options: /command help
-
-Exit.
-fi
-
-[Command continues...]
-```
-
-**Helpful diagnostics:**
-
-```markdown
----
-description: Diagnostic command
----
-
-# Operation Failed
-
-The operation could not complete.
-
-**Diagnostic Information:**
-
-Environment:
-
-- Platform: $(uname)
-- Shell: $SHELL
-- Working directory: $(pwd)
-- Command: /command $@
-
-Checking common issues:
-
-- Git repository: $(git rev-parse --git-dir 2>&1)
-- Write permissions: $(test -w . && echo "OK" || echo "DENIED")
-- Required files: $(test -f config.yml && echo "Found" || echo "Missing")
-
-This information helps debug the issue.
-
-For support, include the above diagnostics.
-```
-
-## Distribution Best Practices
-
-### Namespace Awareness
-
-**Avoid name collisions:**
-
-```markdown
----
-description: Namespaced command
----
-
-<!--
-COMMAND NAME: plugin-name-command
-
-This command is namespaced with the plugin name to avoid
-conflicts with commands from other plugins.
-
-Alternative naming approaches:
-- Use plugin prefix: /plugin-command
-- Use category: /category-command
-- Use verb-noun: /verb-noun
-
-Chosen approach: plugin-name prefix
-Reasoning: Clearest ownership, least likely to conflict
--->
-
-# Plugin Name Command
-
-[Implementation...]
-```
-
-**Document naming rationale:**
-
-```markdown
-<!--
-NAMING DECISION:
-
-Command name: /deploy-app
-
-Alternatives considered:
-- /deploy: Too generic, likely conflicts
-- /app-deploy: Less intuitive ordering
-- /my-plugin-deploy: Too verbose
-
-Final choice balances:
-- Discoverability (clear purpose)
-- Brevity (easy to type)
-- Uniqueness (unlikely conflicts)
--->
-```
-
-### Configurability
-
-**User preferences:**
-
-```markdown
----
-description: Configurable command
-allowed-tools: Read
----
-
-# Load User Configuration
-
-Default configuration:
-
-- verbose: false
-- color: true
-- max_results: 10
-
-Checking for user config: .claude/plugin-name.local.md
-
-if [ -f ".claude/plugin-name.local.md" ]; then
-
-# Parse YAML frontmatter for settings
-
-VERBOSE=$(grep "^verbose:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
-  COLOR=$(grep "^color:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
-MAX_RESULTS=$(grep "^max_results:" .claude/plugin-name.local.md | cut -d: -f2 | tr -d ' ')
-
-echo "✓ Using user configuration"
-else
-echo "Using default configuration"
-echo "Create .claude/plugin-name.local.md to customize"
-fi
-
-[Use configuration in command...]
-```
-
-**Sensible defaults:**
-
-```markdown
----
-description: Command with smart defaults
----
-
-# Smart Defaults
-
-Configuration:
-
-- Format: ${FORMAT:-json} # Defaults to json
-- Output: ${OUTPUT:-stdout} # Defaults to stdout
-- Verbose: ${VERBOSE:-false} # Defaults to false
-
-These defaults work for 80% of use cases.
-
-Override with arguments:
-/command --format yaml --output file.txt --verbose
-
-Or set in .claude/plugin-name.local.md:
-\`\`\`yaml
-
----
-
-format: yaml
-output: custom.txt
-verbose: true
-
----
-
-\`\`\`
-```
-
-### Version Compatibility
-
-**Version checking:**
-
-```markdown
----
-description: Version-aware command
----
-
-<!--
-COMMAND VERSION: 2.1.0
-
-COMPATIBILITY:
-- Requires plugin version: >= 2.0.0
-- Breaking changes from v1.x documented in MIGRATION.md
-
-VERSION HISTORY:
-- v2.1.0: Added --new-feature flag
-- v2.0.0: BREAKING: Changed argument order
-- v1.0.0: Initial release
--->
-
-# Version Check
-
-Command version: 2.1.0
-Plugin version: [detect from plugin.json]
-
-if [ "$PLUGIN_VERSION" < "2.0.0" ]; then
-❌ ERROR: Incompatible plugin version
-
-This command requires plugin version >= 2.0.0
-Current version: $PLUGIN_VERSION
-
-Update plugin:
-/plugin update plugin-name
-
-Exit.
-fi
-
-✓ Version compatible
-
-[Command continues...]
-```
-
-**Deprecation warnings:**
-
-```markdown
----
-description: Command with deprecation warnings
----
-
-# Deprecation Check
-
-if [ "$1" = "--old-flag" ]; then
-⚠️ DEPRECATION WARNING
-
-The --old-flag option is deprecated as of v2.0.0
-It will be removed in v3.0.0 (est. June 2025)
-
-Use instead: --new-flag
-
-Example:
-Old: /command --old-flag value
-New: /command --new-flag value
-
-See migration guide: /command migrate
-
-Continuing with deprecated behavior for now...
-fi
-
-[Handle both old and new flags during deprecation period...]
-```
-
-## Marketplace Presentation
-
-### Command Discovery
-
-**Descriptive naming:**
-
-```markdown
----
-description: Review pull request with security and quality checks
----
-
-<!-- GOOD: Descriptive name and description -->
-```
-
-```markdown
----
-description: Do the thing
----
-
-<!-- BAD: Vague description -->
-```
-
-**Searchable keywords:**
-
-```markdown
-<!--
-KEYWORDS: security, code-review, quality, validation, audit
-
-These keywords help users discover this command when searching
-for related functionality in the marketplace.
--->
-```
-
-### Showcase Examples
-
-**Compelling demonstrations:**
-
-```markdown
----
-description: Advanced code analysis command
----
-
-# Code Analysis Command
-
-This command performs deep code analysis with actionable insights.
-
-## Demo: Quick Security Audit
-
-Try it now:
-\`\`\`
-/analyze-code src/ --security
-\`\`\`
-
-**What you'll get:**
-
-- Security vulnerability detection
-- Code quality metrics
-- Performance bottleneck identification
-- Actionable recommendations
-
-**Sample output:**
-\`\`\`
-Security Analysis Results
-=========================
-
-🔴 Critical (2):
-
-- SQL injection risk in users.js:45
-- XSS vulnerability in display.js:23
-
-🟡 Warnings (5):
-
-- Unvalidated input in api.js:67
-  ...
-
-Recommendations:
-
-1. Fix critical issues immediately
-2. Review warnings before next release
-3. Run /analyze-code --fix for auto-fixes
-   \`\`\`
-
----
-
-Ready to analyze your code...
-
-[Command implementation...]
-```
-
-### User Reviews and Feedback
-
-**Feedback mechanism:**
-
-```markdown
----
-description: Command with feedback
----
-
-# Command Complete
-
-[Command results...]
-
----
-
-**How was your experience?**
-
-This helps improve the command for everyone.
-
-Rate this command:
-
-- 👍 Helpful
-- 👎 Not helpful
-- 🐛 Found a bug
-- 💡 Have a suggestion
-
-Reply with an emoji or:
-
-- /command feedback
-
-Your feedback matters!
-```
-
-**Usage analytics preparation:**
-
-```markdown
-<!--
-ANALYTICS NOTES:
-
-Track for improvement:
-- Most common arguments
-- Failure rates
-- Average execution time
-- User satisfaction scores
-
-Privacy-preserving:
-- No personally identifiable information
-- Aggregate statistics only
-- User opt-out respected
--->
-```
-
-## Quality Standards
-
-### Professional Polish
-
-**Consistent branding:**
-
-```markdown
----
-description: Branded command
----
-
-# ✨ Command Name
-
-Part of the [Plugin Name] suite
-
-[Command functionality...]
-
----
-
-**Need Help?**
-
-- Documentation: https://docs.example.com
-- Support: support@example.com
-- Community: https://community.example.com
-
-Powered by Plugin Name v2.1.0
-```
-
-**Attention to detail:**
-
-```markdown
-<!-- Details that matter -->
-
-✓ Use proper emoji/symbols consistently
-✓ Align output columns neatly
-✓ Format numbers with thousands separators
-✓ Use color/formatting appropriately
-✓ Provide progress indicators
-✓ Show estimated time remaining
-✓ Confirm successful operations
-```
-
-### Reliability
-
-**Idempotency:**
-
-```markdown
----
-description: Idempotent command
----
-
-# Safe Repeated Execution
-
-Checking if operation already completed...
-
-if [ -f ".claude/operation-completed.flag" ]; then
-ℹ️ Operation already completed
-
-Completed at: $(cat .claude/operation-completed.flag)
-
-To re-run:
-
-1. Remove flag: rm .claude/operation-completed.flag
-2. Run command again
-
-Otherwise, no action needed.
-
-Exit.
-fi
-
-Performing operation...
-
-[Safe, repeatable operation...]
-
-Marking complete...
-echo "$(date)" > .claude/operation-completed.flag
-```
-
-**Atomic operations:**
-
-```markdown
----
-description: Atomic command
----
-
-# Atomic Operation
-
-This operation is atomic - either fully succeeds or fully fails.
-
-Creating temporary workspace...
-TEMP_DIR=$(mktemp -d)
-
-Performing changes in isolated environment...
-[Make changes in $TEMP_DIR]
-
-if [ $? -eq 0 ]; then
-✓ Changes validated
-
-Applying changes atomically...
-mv $TEMP_DIR/\* ./target/
-
-✓ Operation complete
-else
-❌ Changes failed validation
-
-Rolling back...
-rm -rf $TEMP_DIR
-
-No changes applied. Safe to retry.
-fi
-```
-
-## Testing for Distribution
-
-### Pre-Release Checklist
-
-```markdown
-<!--
-PRE-RELEASE CHECKLIST:
-
-Functionality:
-- [ ] Works on macOS
-- [ ] Works on Linux
-- [ ] Works on Windows (WSL)
-- [ ] All arguments tested
-- [ ] Error cases handled
-- [ ] Edge cases covered
-
-User Experience:
-- [ ] Clear description
-- [ ] Helpful error messages
-- [ ] Examples provided
-- [ ] First-run experience good
-- [ ] Documentation complete
-
-Distribution:
-- [ ] No hardcoded paths
-- [ ] Dependencies documented
-- [ ] Configuration options clear
-- [ ] Version number set
-- [ ] Changelog updated
-
-Quality:
-- [ ] No TODO comments
-- [ ] No debug code
-- [ ] Performance acceptable
-- [ ] Security reviewed
-- [ ] Privacy considered
-
-Support:
-- [ ] README complete
-- [ ] Troubleshooting guide
-- [ ] Support contact provided
-- [ ] Feedback mechanism
-- [ ] License specified
--->
-```
-
-### Beta Testing
-
-**Beta release approach:**
-
-```markdown
----
-description: Beta command (v0.9.0)
----
-
-# 🧪 Beta Command
-
-**This is a beta release**
-
-Features may change based on feedback.
-
-BETA STATUS:
-
-- Version: 0.9.0
-- Stability: Experimental
-- Support: Limited
-- Feedback: Encouraged
-
-Known limitations:
-
-- Performance not optimized
-- Some edge cases not handled
-- Documentation incomplete
-
-Help improve this command:
-
-- Report issues: /command report-issue
-- Suggest features: /command suggest
-- Join beta testers: /command join-beta
-
----
-
-[Command implementation...]
-
----
-
-**Thank you for beta testing!**
-
-Your feedback helps make this command better.
-```
-
-## Maintenance and Updates
-
-### Update Strategy
-
-**Versioned commands:**
-
-```markdown
-<!--
-VERSION STRATEGY:
-
-Major (X.0.0): Breaking changes
-- Document all breaking changes
-- Provide migration guide
-- Support old version briefly
-
-Minor (x.Y.0): New features
-- Backward compatible
-- Announce new features
-- Update examples
-
-Patch (x.y.Z): Bug fixes
-- No user-facing changes
-- Update changelog
-- Security fixes prioritized
-
-Release schedule:
-- Patches: As needed
-- Minors: Monthly
-- Majors: Annually or as needed
--->
-```
-
-**Update notifications:**
-
-```markdown
----
-description: Update-aware command
----
-
-# Check for Updates
-
-Current version: 2.1.0
-Latest version: [check if available]
-
-if [ "$CURRENT_VERSION" != "$LATEST_VERSION" ]; then
-📢 UPDATE AVAILABLE
-
-New version: $LATEST_VERSION
-Current: $CURRENT_VERSION
-
-What's new:
-
-- Feature improvements
-- Bug fixes
-- Performance enhancements
-
-Update with:
-/plugin update plugin-name
-
-Release notes: https://releases.example.com/v$LATEST_VERSION
-fi
-
-[Command continues...]
-```
-
-## Best Practices Summary
-
-### Distribution Design
-
-1. **Universal**: Works across platforms and environments
-2. **Self-contained**: Minimal dependencies, clear requirements
-3. **Graceful**: Degrades gracefully when features unavailable
-4. **Forgiving**: Anticipates and handles user mistakes
-5. **Helpful**: Clear errors, good defaults, excellent docs
-
-### Marketplace Success
-
-1. **Discoverable**: Clear name, good description, searchable keywords
-2. **Professional**: Polished presentation, consistent branding
-3. **Reliable**: Tested thoroughly, handles edge cases
-4. **Maintainable**: Versioned, updated regularly, supported
-5. **User-focused**: Great UX, responsive to feedback
-
-### Quality Standards
-
-1. **Complete**: Fully documented, all features working
-2. **Tested**: Works in real environments, edge cases handled
-3. **Secure**: No vulnerabilities, safe operations
-4. **Performant**: Reasonable speed, resource-efficient
-5. **Ethical**: Privacy-respecting, user consent
-
-With these considerations, commands become marketplace-ready and delight users across diverse environments and use cases.