Initial commit

2025-11-29 18:20:31 +08:00
commit 6bee51f8ec
20 changed files with 4266 additions and 0 deletions
--- a/commands/plugin-scaffold/complete-scaffold.md
+++ b/commands/plugin-scaffold/complete-scaffold.md
@@ -0,0 +1,445 @@
+---
+description: Generate complete plugin structure with all necessary files in one operation
+---
+
+# Complete Plugin Scaffolding
+
+## Parameters
+
+**Required**:
+- `name`: Plugin name in lowercase-hyphen format
+- `description`: Brief description (50-200 characters)
+- `author`: Author name or "name:email" format
+- `license`: License type (MIT|Apache-2.0|GPL-3.0|BSD-3-Clause)
+
+**Optional**:
+- `category`: OpenPlugins category (default: "development")
+- `keywords`: Comma-separated keywords (default: auto-generated)
+- `version`: Initial version (default: "1.0.0")
+- `with_agent`: Include agent template (format: true|false, default: false)
+- `with_hooks`: Include hooks template (format: true|false, default: false)
+
+## Workflow
+
+### Step 1: Validate Parameters
+
+**Plugin Name Validation**:
+- Must match pattern: `^[a-z][a-z0-9-]*$`
+- Must be lowercase with hyphens only
+- Cannot start with numbers
+- Should be descriptive and memorable
+
+Execute validation script:
+```bash
+.scripts/validate-name.sh "{name}"
+```
+
+**Description Validation**:
+- Length: 50-200 characters
+- Must be specific and actionable
+- Should answer "What does this do?"
+
+**Author Format**:
+- Simple: "John Doe"
+- With email: "John Doe <john@example.com>"
+- Object format: handled automatically
+
+### Step 2: Create Directory Structure
+
+**Base Structure**:
+```bash
+mkdir -p {name}/.claude-plugin
+mkdir -p {name}/commands
+mkdir -p {name}/agents     # if with_agent:true
+mkdir -p {name}/hooks      # if with_hooks:true
+```
+
+**Subdirectories Based on Pattern**:
+- Simple plugin: No subdirectories needed
+- Moderate plugin: May create command namespace directories
+- Complex plugin: Create skill directories with .scripts/
+
+### Step 3: Generate plugin.json
+
+Create `plugin.json` at the plugin root with complete metadata:
+
+```json
+{
+  "name": "{name}",
+  "version": "{version}",
+  "description": "{description}",
+  "author": {
+    "name": "{author_name}",
+    "email": "{author_email}"
+  },
+  "license": "{license}",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/{username}/{name}"
+  },
+  "homepage": "https://github.com/{username}/{name}",
+  "keywords": [{keywords}],
+  "category": "{category}"
+}
+```
+
+Execute metadata generation script:
+```bash
+.scripts/generate-metadata.py --name "{name}" --author "{author}" --description "{description}" --license "{license}" --category "{category}"
+```
+
+### Step 4: Create README.md
+
+Generate comprehensive README with sections:
+
+1. **Title and Badge**
+2. **Description** (expanded from metadata)
+3. **Features** (bullet list)
+4. **Installation** (multiple methods)
+5. **Usage** (with examples)
+6. **Configuration** (if applicable)
+7. **Commands** (document each command)
+8. **Agents** (if with_agent:true)
+9. **Hooks** (if with_hooks:true)
+10. **Examples** (multiple real scenarios)
+11. **Troubleshooting**
+12. **Development** (testing, contributing)
+13. **Changelog** (link to CHANGELOG.md)
+14. **License**
+15. **Resources**
+
+### Step 5: Add LICENSE File
+
+Based on license parameter, add appropriate LICENSE file:
+
+**MIT**:
+```
+MIT License
+
+Copyright (c) {year} {author}
+
+Permission is hereby granted, free of charge, to any person obtaining a copy...
+```
+
+**Apache-2.0**:
+```
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+...
+```
+
+**GPL-3.0**:
+```
+GNU GENERAL PUBLIC LICENSE
+Version 3, 29 June 2007
+...
+```
+
+**BSD-3-Clause**:
+```
+BSD 3-Clause License
+
+Copyright (c) {year}, {author}
+...
+```
+
+### Step 6: Create CHANGELOG.md
+
+Initialize changelog with version 1.0.0:
+
+```markdown
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - {date}
+
+### Added
+- Initial release
+- {feature 1}
+- {feature 2}
+```
+
+### Step 7: Create .gitignore
+
+Add plugin development .gitignore:
+
+```
+# OS files
+.DS_Store
+Thumbs.db
+
+# Editor directories
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Logs
+*.log
+npm-debug.log*
+
+# Environment
+.env
+.env.local
+
+# Dependencies
+node_modules/
+__pycache__/
+*.pyc
+
+# Build outputs
+dist/
+build/
+*.egg-info/
+
+# Test coverage
+coverage/
+.coverage
+.nyc_output
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+```
+
+### Step 8: Create Template Files
+
+**If with_agent:true**, create `agents/specialist.md`:
+```markdown
+---
+name: {name}-specialist
+description: Expert in {domain}. Use when users need guidance with {functionality}.
+capabilities: [capability1, capability2, capability3]
+tools: Read, Write, Bash, Grep, Glob
+model: inherit
+---
+
+# {Name} Specialist Agent
+
+You are an expert in {domain}. Your role is to provide guidance and automation for {functionality}.
+
+## When to Invoke
+
+This agent is automatically invoked when users:
+- {trigger condition 1}
+- {trigger condition 2}
+
+## Approach
+
+{Agent's methodology and best practices}
+```
+
+**If with_hooks:true**, create `hooks/hooks.json`:
+```json
+{
+  "PostToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "echo 'Hook triggered after file modification'"
+        }
+      ]
+    }
+  ]
+}
+```
+
+**Create sample command** in `commands/example.md`:
+```markdown
+---
+description: Example command demonstrating plugin functionality
+---
+
+# Example Command
+
+This is a sample command. Replace with your actual implementation.
+
+## Usage
+
+/{name} [arguments]
+
+## Parameters
+
+- `arg1`: Description
+- `arg2`: Description (optional)
+
+## Implementation
+
+{Implementation instructions}
+```
+
+### Step 9: Verify Structure
+
+Run structure validation:
+```bash
+# Check all required files exist
+test -f {name}/plugin.json && echo "✅ plugin.json" || echo "❌ plugin.json missing"
+test -f {name}/README.md && echo "✅ README.md" || echo "✅ README.md" || echo "❌ README.md missing"
+test -f {name}/LICENSE && echo "✅ LICENSE" || echo "❌ LICENSE missing"
+test -f {name}/CHANGELOG.md && echo "✅ CHANGELOG.md" || echo "❌ CHANGELOG.md missing"
+test -d {name}/commands && echo "✅ commands/" || echo "❌ commands/ missing"
+```
+
+### Step 10: Generate Success Report
+
+Provide comprehensive report with:
+- Structure created confirmation
+- Files generated list
+- Next steps for development
+- Testing instructions
+- Marketplace submission readiness checklist
+
+## Output Format
+
+```markdown
+## ✅ Plugin Scaffolding Complete
+
+### Generated Structure
+
+```
+{name}/
+├── .claude-plugin/
+│   └── plugin.json ✅
+├── .gitignore ✅
+├── CHANGELOG.md ✅
+├── LICENSE ({license}) ✅
+├── README.md ✅
+├── commands/
+│   └── example.md ✅
+├── agents/ {if applicable}
+│   └── specialist.md ✅
+└── hooks/ {if applicable}
+    └── hooks.json ✅
+```
+
+### Files Created
+
+- ✅ **plugin.json**: Complete metadata with all required fields
+- ✅ **README.md**: Comprehensive documentation template
+- ✅ **LICENSE**: {license} license file
+- ✅ **CHANGELOG.md**: Initialized with version 1.0.0
+- ✅ **.gitignore**: Plugin development exclusions
+- ✅ **commands/example.md**: Sample command template
+{Additional files if created}
+
+### Metadata Summary
+
+**Name**: {name}
+**Version**: {version}
+**Description**: {description}
+**Author**: {author}
+**License**: {license}
+**Category**: {category}
+**Keywords**: {keywords}
+
+### Next Steps
+
+1. **Implement Functionality**
+   - Edit `commands/example.md` with your actual implementation
+   - Add more commands as needed
+   - Implement agent logic if included
+
+2. **Update Documentation**
+   - Customize README.md with real examples
+   - Document all parameters and usage
+   - Add troubleshooting section
+
+3. **Local Testing**
+   ```bash
+   # Create test marketplace
+   mkdir -p test-marketplace/.claude-plugin
+   # Add marketplace.json
+   # Install and test plugin
+   ```
+
+4. **Prepare for Release**
+   - Update CHANGELOG.md with features
+   - Verify all documentation is complete
+   - Run quality checks
+   - Test all functionality
+
+5. **Submit to OpenPlugins**
+   - Fork OpenPlugins repository
+   - Add plugin entry to marketplace.json
+   - Create pull request
+
+### Quality Checklist
+
+Before submission, ensure:
+- ✅ Plugin name follows lowercase-hyphen format
+- ✅ Description is 50-200 characters
+- ✅ All required metadata fields present
+- ✅ README has real content (no placeholders)
+- ✅ LICENSE file included
+- ✅ At least one functional command
+- ✅ No hardcoded secrets
+- ✅ Examples are concrete and realistic
+
+### Testing Commands
+
+```bash
+# Navigate to plugin directory
+cd {name}
+
+# Validate plugin.json
+python3 -m json.tool plugin.json
+
+# Check file structure
+ls -la
+
+# Initialize git repository
+git init
+git add .
+git commit -m "Initial plugin structure"
+```
+
+### Resources
+
+- Plugin Documentation: https://docs.claude.com/en/docs/claude-code/plugins
+- OpenPlugins Guide: https://github.com/dhofheinz/open-plugins
+- Submit Plugin: Fork repository and add to marketplace.json
+
+---
+
+**Plugin scaffolding complete!** Your plugin is ready for implementation.
+```
+
+## Error Handling
+
+- **Invalid plugin name** → Show valid pattern and suggest correction
+- **Directory exists** → Ask for confirmation to overwrite or use different name
+- **Invalid license type** → List supported licenses: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause
+- **Missing required parameter** → Request parameter with expected format
+- **Git not available** → Skip git initialization, provide manual instructions
+- **File creation fails** → Report specific file and error, provide recovery steps
+
+## Examples
+
+### Example 1: Simple Plugin
+
+**Input**:
+```
+/plugin-scaffold complete name:hello-world author:"Jane Smith" license:MIT description:"Simple greeting plugin for Claude Code"
+```
+
+**Output**: Complete plugin structure with all files
+
+### Example 2: Plugin with Agent
+
+**Input**:
+```
+/plugin-scaffold complete name:code-reviewer author:"John Doe <john@example.com>" license:Apache-2.0 description:"Automated code review with security analysis" with_agent:true category:quality
+```
+
+**Output**: Plugin structure including agent template
+
+**Request**: $ARGUMENTS