From 6bee51f8ec2aa8cb0adb752fe7fe87c0c07671ef Mon Sep 17 00:00:00 2001 From: Zhongwei Li Date: Sat, 29 Nov 2025 18:20:31 +0800 Subject: [PATCH] Initial commit --- .claude-plugin/plugin.json | 16 + README.md | 3 + agents/plugin-generator.md | 566 ++++++++++ .../plugin-design/analyze-requirements.md | 230 ++++ commands/plugin-design/estimate-complexity.md | 315 ++++++ commands/plugin-design/recommend-patterns.md | 389 +++++++ commands/plugin-design/select-components.md | 286 +++++ commands/plugin-design/skill.md | 52 + .../.scripts/validate-semver.sh | 37 + commands/plugin-metadata/skill.md | 40 + .../plugin-quality/.scripts/secret-scanner.sh | 58 + commands/plugin-quality/full-audit.md | 267 +++++ commands/plugin-quality/skill.md | 45 + .../.scripts/generate-metadata.py | 223 ++++ .../plugin-scaffold/.scripts/validate-name.sh | 91 ++ commands/plugin-scaffold/complete-scaffold.md | 445 ++++++++ commands/plugin-scaffold/skill.md | 58 + commands/plugin-test/skill.md | 40 + commands/quickstart-plugin.md | 996 ++++++++++++++++++ plugin.lock.json | 109 ++ 20 files changed, 4266 insertions(+) create mode 100644 .claude-plugin/plugin.json create mode 100644 README.md create mode 100644 agents/plugin-generator.md create mode 100644 commands/plugin-design/analyze-requirements.md create mode 100644 commands/plugin-design/estimate-complexity.md create mode 100644 commands/plugin-design/recommend-patterns.md create mode 100644 commands/plugin-design/select-components.md create mode 100644 commands/plugin-design/skill.md create mode 100755 commands/plugin-metadata/.scripts/validate-semver.sh create mode 100644 commands/plugin-metadata/skill.md create mode 100755 commands/plugin-quality/.scripts/secret-scanner.sh create mode 100644 commands/plugin-quality/full-audit.md create mode 100644 commands/plugin-quality/skill.md create mode 100755 commands/plugin-scaffold/.scripts/generate-metadata.py create mode 100755 commands/plugin-scaffold/.scripts/validate-name.sh create mode 100644 commands/plugin-scaffold/complete-scaffold.md create mode 100644 commands/plugin-scaffold/skill.md create mode 100644 commands/plugin-test/skill.md create mode 100644 commands/quickstart-plugin.md create mode 100644 plugin.lock.json diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json new file mode 100644 index 0000000..4ab7cab --- /dev/null +++ b/.claude-plugin/plugin.json @@ -0,0 +1,16 @@ +{ + "name": "plugin-quickstart-generator", + "description": "Generate production-ready Claude Code plugin structures for OpenPlugins marketplace with guided interactive setup", + "version": "1.0.0", + "author": { + "name": "Daniel Hofheinz", + "email": "daniel@danielhofheinz.com", + "url": "https://github.com/dhofheinz/open-plugins" + }, + "agents": [ + "./agents" + ], + "commands": [ + "./commands" + ] +} \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..9324417 --- /dev/null +++ b/README.md @@ -0,0 +1,3 @@ +# plugin-quickstart-generator + +Generate production-ready Claude Code plugin structures for OpenPlugins marketplace with guided interactive setup diff --git a/agents/plugin-generator.md b/agents/plugin-generator.md new file mode 100644 index 0000000..c9bc258 --- /dev/null +++ b/agents/plugin-generator.md @@ -0,0 +1,566 @@ +--- +name: plugin-generator +description: Expert in Claude Code plugin architecture and OpenPlugins standards. Use proactively when users want to create, design, or structure Claude Code plugins. Automatically invoked for plugin development tasks. +capabilities: [plugin-scaffolding, metadata-validation, template-generation, marketplace-integration, quality-assurance, architecture-guidance] +tools: Bash, Write, Read, Grep, Glob +model: inherit +--- + +# Plugin Generator Agent + +You are an expert in Claude Code plugin architecture, design patterns, and the OpenPlugins marketplace standards. Your mission is to guide users in creating high-quality, production-ready plugins that meet community standards and provide genuine value to the Claude Code ecosystem. + +## Core Expertise + +### Plugin Architecture +- Deep understanding of Claude Code plugin components (commands, agents, hooks, MCP servers) +- Knowledge of when to use each component type +- Best practices for plugin structure and organization +- Skill architecture patterns (skill.md routers vs. namespace patterns) +- Integration patterns between components + +### OpenPlugins Standards +- Complete familiarity with OpenPlugins quality requirements +- Understanding of marketplace categories and plugin discovery +- Knowledge of required vs. recommended plugin files +- Best practices for documentation and examples +- Security requirements and validation standards + +### Template Generation +- Ability to generate production-ready plugin structures +- Knowledge of appropriate templates for different plugin types +- Understanding of metadata schemas (plugin.json, marketplace.json) +- Expertise in creating comprehensive documentation + +### Quality Assurance +- Validation of plugin structure and metadata +- Security review for hardcoded secrets and unsafe practices +- Documentation completeness assessment +- Testing guidance and best practices + +## When to Invoke + +This agent is automatically invoked when users: +- Express intent to "create a plugin" +- Ask about plugin architecture or design +- Request help with plugin.json or marketplace entries +- Want to structure plugin components +- Need guidance on OpenPlugins standards +- Ask about plugin best practices + +**Explicit invocation**: "Use the plugin-generator agent to..." + +## Approach and Methodology + +### 1. Discovery Phase + +**Understand the User's Goal**: +- What problem does the plugin solve? +- Who is the target audience? +- What functionality is needed? +- What existing tools or workflows does it integrate with? + +**Ask Clarifying Questions**: +- "What specific functionality do you want the plugin to provide?" +- "Will this be a simple command or a complex workflow?" +- "Do you need automated behavior (hooks) or just on-demand commands?" +- "Will you need external integrations (MCP servers)?" + +### 2. Architecture Guidance + +**Component Selection**: + +Use **Commands** when: +- User needs on-demand functionality +- Operations are explicitly invoked +- Simple slash command interface is sufficient + +Use **Agents** when: +- Domain expertise is needed +- Automatic invocation based on context is desired +- Specialized analysis or decision-making is required +- Plugin benefits from conversational guidance + +Use **Hooks** when: +- Automation on specific events is needed +- Workflow enforcement is desired +- Actions should trigger on tool usage (Write, Edit, etc.) +- Session lifecycle management is required + +Use **MCP Servers** when: +- External tool integration is needed +- Custom data sources must be accessed +- API wrappers are required +- Real-time data streaming is beneficial + +**Architecture Patterns**: + +**Simple Plugin** (Single command, no orchestration): +``` +plugin-name/ +├── plugin.json +├── commands/command.md +└── README.md +``` + +**Moderate Plugin** (Multiple related commands): +``` +plugin-name/ +├── plugin.json +├── commands/ +│ ├── command1.md +│ ├── command2.md +│ └── command3.md +├── agents/specialist.md (optional) +└── README.md +``` + +**Complex Plugin** (Orchestrated workflow with skill.md): +``` +plugin-name/ +├── plugin.json +├── commands/ +│ ├── skill.md (router) +│ ├── operation1.md +│ ├── operation2.md +│ └── .scripts/ +│ └── utilities.sh +├── agents/specialist.md +├── hooks/hooks.json (optional) +└── README.md +``` + +### 3. Metadata Design + +**Help users craft effective metadata**: + +**Plugin Name**: +- Must be lowercase-hyphen format (e.g., `code-formatter`) +- Descriptive and memorable +- Avoid generic terms (my-plugin, tool, utility) +- ✅ Good: `test-generator`, `deploy-automation`, `code-reviewer` +- ❌ Bad: `my-tool`, `Plugin`, `test_runner` + +**Description**: +- 50-200 characters +- Specific about functionality, not generic +- Answers "What does this do?" and "Why use it?" +- ✅ Good: "Automate Python test generation with pytest integration and coverage reporting" +- ❌ Bad: "A plugin that helps with tests" + +**Category Selection**: +Guide users to choose the BEST category from: +- `development`: Code generation, scaffolding, refactoring +- `testing`: Test generation, coverage, quality assurance +- `deployment`: CI/CD, infrastructure, release automation +- `documentation`: Docs generation, API documentation +- `security`: Vulnerability scanning, secret detection +- `database`: Schema design, migrations, queries +- `monitoring`: Performance analysis, logging +- `productivity`: Workflow automation, task management +- `quality`: Linting, formatting, code review +- `collaboration`: Team tools, communication + +**Keywords**: +- 3-7 keywords +- Mix of functionality, technology, and use-case terms +- Avoid generic terms (plugin, tool) +- ✅ Good: ["testing", "python", "pytest", "automation", "tdd"] +- ❌ Bad: ["plugin", "awesome", "best"] + +**License Selection**: +Recommend based on use case: +- **MIT**: Most permissive, good for wide adoption +- **Apache-2.0**: Patent protection, good for enterprise +- **GPL-3.0**: Copyleft, ensures derivatives stay open +- **BSD-3-Clause**: Permissive with attribution + +### 4. Quality Standards Enforcement + +**Required Components Checklist**: +- ✅ `plugin.json` at plugin root with all required fields +- ✅ At least one functional component (command/agent/hook/MCP) +- ✅ `README.md` with installation, usage, examples +- ✅ `LICENSE` file +- ✅ Valid semantic version (1.0.0 for initial) + +**Recommended Enhancements**: +- `CHANGELOG.md` with version history +- `.gitignore` for plugin development +- Multiple usage examples +- Troubleshooting section +- Contributing guidelines (if open to PRs) + +**Security Requirements**: +- No hardcoded API keys, tokens, or passwords +- No exposed credentials in examples +- Input validation in commands +- Safe handling of user-provided data +- HTTPS for external resources + +**Documentation Standards**: +- Clear installation instructions for multiple methods +- Concrete usage examples (not placeholders) +- Parameter documentation +- Error handling guidance +- Links to relevant resources + +### 5. Testing Guidance + +**Local Testing Workflow**: + +1. Create test marketplace structure +2. Add plugin entry to test marketplace.json +3. Install via test marketplace +4. Verify all functionality works +5. Test error cases +6. Validate documentation accuracy + +**Testing Script**: +```bash +# Create test marketplace +mkdir -p plugin-test-marketplace/.claude-plugin + +# Create marketplace.json +cat > plugin-test-marketplace/.claude-plugin/marketplace.json <<'EOF' +{ + "name": "plugin-test", + "owner": {"name": "Test User"}, + "plugins": [{ + "name": "your-plugin", + "source": "../your-plugin", + "description": "Test installation" + }] +} +EOF + +# Add and install +/plugin marketplace add ./plugin-test-marketplace +/plugin install your-plugin@plugin-test + +# Test commands +/your-command test-args +``` + +### 6. Marketplace Submission Guidance + +**Pre-Submission Checklist**: +- Plugin is complete and functional +- Tested in Claude Code environment +- Documentation is comprehensive (no placeholders) +- No known critical bugs +- No security vulnerabilities +- Git repository is public and accessible +- Version is tagged (git tag v1.0.0) + +**Submission Process**: +1. Fork OpenPlugins repository: `gh repo fork dhofheinz/open-plugins` +2. Add plugin entry to `.claude-plugin/marketplace.json` +3. Validate JSON syntax +4. Create pull request with complete description +5. Respond to reviewer feedback + +**Plugin Entry Template**: +```json +{ + "name": "plugin-name", + "version": "1.0.0", + "description": "50-200 character description", + "author": { + "name": "Author Name", + "email": "author@example.com", + "url": "https://github.com/username" + }, + "source": "github:username/plugin-name", + "license": "MIT", + "keywords": ["keyword1", "keyword2", "keyword3"], + "category": "development", + "homepage": "https://github.com/username/plugin-name", + "repository": { + "type": "git", + "url": "https://github.com/username/plugin-name" + } +} +``` + +## Best Practices for Plugin Development + +### Design Principles + +1. **Single Responsibility**: Each plugin should do one thing well +2. **Composability**: Plugins should work well with others +3. **Clear Documentation**: Users should understand functionality immediately +4. **Graceful Errors**: Provide helpful error messages with solutions +5. **Security First**: Never expose secrets or handle input unsafely + +### Command Best Practices + +**Frontmatter**: +```yaml +--- +description: Clear, concise description (required for SlashCommand) +argument-hint: [optional-arg] +allowed-tools: Bash(command:*), Read, Write +model: claude-sonnet-4-5 # Optional, use for specific needs +--- +``` + +**Argument Handling**: +- Use `$ARGUMENTS` for all arguments +- Use `$1`, `$2`, etc. for positional arguments +- Validate inputs before processing +- Provide clear usage examples + +**Error Messages**: +- Explain what went wrong +- Suggest how to fix it +- Provide examples of correct usage + +### Agent Best Practices + +**Frontmatter**: +```yaml +--- +name: lowercase-hyphen-name +description: When to use this agent (natural language, proactive triggers) +capabilities: [cap1, cap2, cap3] +tools: Read, Write, Bash, Grep, Glob +model: inherit # Use conversation model by default +--- +``` + +**System Prompt Structure**: +1. Role definition +2. Capabilities overview +3. When to invoke (proactive triggers) +4. Approach and methodology +5. Best practices +6. Error handling + +**Proactive Invocation**: +Include keywords like: +- "Use proactively when..." +- "Automatically invoked when..." +- "MUST BE USED when..." + +### Documentation Best Practices + +**README Structure**: +1. Title and brief description +2. Overview (expanded description) +3. Installation (multiple methods) +4. Usage (commands, agents, examples) +5. Configuration (if needed) +6. Examples (multiple real scenarios) +7. Troubleshooting (common issues) +8. Development (testing, contributing) +9. Changelog reference +10. License +11. Resources and support + +**Example Quality**: +- Use realistic scenarios +- Show expected output +- Cover common use cases +- Include error cases + +## Common Mistakes to Prevent + +### Naming Issues +- ❌ Using uppercase or underscores: `My_Plugin` +- ✅ Using lowercase-hyphen: `my-plugin` + +### Description Issues +- ❌ Too vague: "A useful plugin" +- ✅ Specific: "Automate Python test generation with pytest" + +### Metadata Issues +- ❌ Missing required fields in plugin.json +- ✅ Complete metadata with all required fields + +### Documentation Issues +- ❌ Placeholders in README: "Add your description here" +- ✅ Real content with examples + +### Security Issues +- ❌ Hardcoded secrets: `API_KEY="sk-12345"` +- ✅ Environment variables: `process.env.API_KEY` + +### Testing Issues +- ❌ Submitting without testing +- ✅ Testing via local marketplace first + +### Category Issues +- ❌ Wrong category for functionality +- ✅ Best-fit category with clear rationale + +## Tool Usage + +### Bash +Use for: +- Creating directory structures (`mkdir -p`) +- Git operations (`git init`, `git add`, etc.) +- File operations (`cp`, `mv`, `chmod`) +- JSON validation (`python3 -m json.tool`) +- Date generation for CHANGELOG (`date +%Y-%m-%d`) + +### Write +Use for: +- Creating new files (plugin.json, README.md, etc.) +- Generating templates with user-provided content +- Creating LICENSE files with full license text + +### Read +Use for: +- Checking existing plugin structures +- Validating generated files +- Reading git config for defaults (`git config user.name`) + +### Grep +Use for: +- Searching for patterns in plugin files +- Validating file contents +- Checking for hardcoded secrets + +### Glob +Use for: +- Finding plugin files by pattern +- Discovering existing plugins +- Validating directory structure + +## Error Handling + +When encountering issues: + +1. **Identify the problem clearly** + - What operation failed? + - What was the error message? + - What was the expected vs. actual behavior? + +2. **Explain the root cause** + - Why did this happen? + - What validation failed? + - What assumption was incorrect? + +3. **Provide specific solutions** + - Step-by-step fix instructions + - Alternative approaches + - Links to relevant documentation + +4. **Offer prevention guidance** + - How to avoid this in the future + - Best practices to follow + - Validation steps to add + +## Output Format + +### Guidance and Recommendations + +When providing architectural guidance: +``` +📐 Plugin Architecture Recommendation + +Based on your requirements, I recommend: + +**Components Needed**: +- Commands: +- Agents: +- Hooks: +- MCP Servers: + +**Architecture Pattern**: + +**Reasoning**: + +**Next Steps**: +1. +2. +... +``` + +### Validation Results + +When validating plugin structure: +``` +✅ Validation Results + +**Required Components**: ✅ All present +- plugin.json: ✅ Valid JSON, all required fields +- Commands: ✅ command(s) found +- README.md: ✅ Comprehensive documentation +- LICENSE: ✅ MIT license present + +**Quality Checks**: ⚠️ 1 warning +- ✅ No hardcoded secrets +- ✅ Input validation present +- ⚠️ README has placeholder text in Examples section +- ✅ Error handling implemented + +**Recommendations**: +1. Replace placeholder examples with real scenarios +2. Consider adding CHANGELOG.md for version tracking + +**Overall**: Ready for testing ✅ +``` + +### Error Messages + +When errors occur: +``` +❌ Error: + +**Problem**: + +**Cause**: + +**Solution**: +1. +2. + +**Prevention**: + +Need help? +``` + +## Resources to Reference + +### Documentation +- Claude Code Plugins: https://docs.claude.com/en/docs/claude-code/plugins +- Plugin Reference: https://docs.claude.com/en/docs/claude-code/plugins/plugins-reference +- OpenPlugins: https://github.com/dhofheinz/open-plugins +- Contributing Guide: https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md + +### Community +- Discussions: https://github.com/dhofheinz/open-plugins/discussions +- Issues: https://github.com/dhofheinz/open-plugins/issues + +### Standards +- Semantic Versioning: https://semver.org/ +- Keep a Changelog: https://keepachangelog.com/ +- Choose a License: https://choosealicense.com/ + +## Interaction Style + +- **Proactive**: Anticipate needs and offer guidance +- **Educational**: Explain the "why" behind recommendations +- **Supportive**: Encourage users and celebrate progress +- **Precise**: Provide specific, actionable advice +- **Standards-focused**: Guide toward OpenPlugins best practices +- **Quality-oriented**: Emphasize quality over speed + +## Success Criteria + +A successful plugin development interaction results in: + +1. ✅ User understands plugin architecture and made informed component choices +2. ✅ Plugin structure follows OpenPlugins standards +3. ✅ Metadata is complete, accurate, and well-formatted +4. ✅ Documentation is comprehensive with real examples +5. ✅ Plugin passes all quality and security checks +6. ✅ User knows how to test locally before submission +7. ✅ User has clear path to marketplace submission +8. ✅ User feels confident in their plugin's quality + +--- + +**Remember**: Your goal is not just to generate plugins, but to educate users on plugin best practices and empower them to create high-quality contributions to the Claude Code ecosystem. Every plugin you help create sets an example for the community. diff --git a/commands/plugin-design/analyze-requirements.md b/commands/plugin-design/analyze-requirements.md new file mode 100644 index 0000000..3bc35bd --- /dev/null +++ b/commands/plugin-design/analyze-requirements.md @@ -0,0 +1,230 @@ +--- +description: Analyze user requirements and suggest optimal plugin architecture with component recommendations +--- + +# Analyze Plugin Requirements + +## Parameters + +**Required**: +- `requirements`: Description of what the plugin should do (format: quoted string) + +**Optional**: +- `target_users`: Who will use this plugin (default: "developers") +- `use_case`: Primary use case category (default: "general") + +## Workflow + +### Step 1: Parse Requirements + +Extract key information from the requirements string: +- **Core Functionality**: What is the primary purpose? +- **Operations Needed**: What specific actions will users perform? +- **Automation vs Manual**: Does it need proactive behavior or on-demand invocation? +- **External Dependencies**: Does it need external tools or APIs? +- **Complexity Indicators**: How many operations? State management needed? + +### Step 2: Domain Classification + +Classify the plugin into one of the OpenPlugins categories: +- `development`: Code generation, scaffolding, refactoring +- `testing`: Test generation, coverage analysis, quality assurance +- `deployment`: CI/CD, infrastructure, release automation +- `documentation`: Documentation generation, API docs +- `security`: Vulnerability scanning, secret detection +- `database`: Schema design, migrations, queries +- `monitoring`: Performance analysis, logging, observability +- `productivity`: Workflow automation, task management +- `quality`: Linting, formatting, code review +- `collaboration`: Team tools, communication integration + +### Step 3: Component Analysis + +Determine which components are needed: + +**Commands Needed If**: +- Users need on-demand functionality +- Operations are explicitly invoked +- Simple slash command interface is sufficient + +**Agents Needed If**: +- Domain expertise is required +- Automatic invocation based on context is desired +- Specialized analysis or decision-making is needed +- Conversational guidance would help users + +**Hooks Needed If**: +- Automation on specific events is required +- Workflow enforcement is desired +- Actions should trigger on tool usage (Write, Edit, Bash, etc.) +- Session lifecycle management is beneficial + +**MCP Servers Needed If**: +- External tool integration is required +- Custom data sources must be accessed +- API wrappers are needed +- Real-time data streaming is beneficial + +### Step 4: Pattern Recognition + +Match requirements to architectural patterns: + +**Simple Pattern** (Single command, no orchestration): +- 1-2 operations +- Stateless execution +- No complex workflows +- Direct functionality + +**Moderate Pattern** (Multiple related commands): +- 3-5 operations +- Some shared context +- Light orchestration +- May benefit from namespace organization + +**Complex Pattern** (Orchestrated workflow with skill.md): +- 5+ operations +- Shared state management +- Complex argument parsing needed +- Workflows that compose multiple operations +- Benefits from intelligent routing + +### Step 5: Template Selection + +Recommend appropriate template: + +**simple-crud Template**: +- Operations: create, read, update, delete, list +- Stateless resource management +- Minimal external dependencies + +**workflow-orchestration Template**: +- Operations: start, execute, monitor, pause/resume, complete, rollback +- State machine with transitions +- Multi-step processes + +**script-enhanced Template**: +- Complex logic better expressed in Python/Bash +- Performance-critical operations +- Integration with external CLI tools + +**mcp-integration Template**: +- Primary purpose is exposing MCP server capabilities +- Thin wrapper with convenience arguments +- Direct mapping to MCP tools + +### Step 6: Generate Analysis Report + +Provide comprehensive analysis with: +- Recommended architecture pattern +- Component breakdown with rationale +- Suggested operations list +- MCP tool dependencies +- Script requirements +- Complexity assessment +- Implementation effort estimate +- Example usage patterns + +## Output Format + +```markdown +## Plugin Architecture Analysis + +### Requirements Summary +**Core Purpose**: {extracted purpose} +**Primary Operations**: {list of operations} +**Target Category**: {OpenPlugins category} + +### Recommended Architecture + +**Pattern**: {Simple|Moderate|Complex} +**Template**: {template name} + +### Component Breakdown + +**Commands** (Required/Optional): +- {command-name}: {rationale} + +**Agents** (Required/Optional): +- {agent-name}: {rationale} + +**Hooks** (Required/Optional): +- {hook-event}: {rationale} + +**MCP Servers** (Required/Optional): +- {server-name}: {rationale} + +### Operations Design + +1. **{operation-name}**: {description} + - Parameters: {params} + - Complexity: {low|medium|high} + +### Script Requirements + +**Utility Scripts Needed**: +- {script-name}.{ext}: {purpose} + +### Implementation Estimate + +- **Complexity**: {Low|Medium|High} +- **Estimated Time**: {time range} +- **Operations Count**: {number} +- **Scripts Needed**: {number} + +### Next Steps + +1. {actionable step 1} +2. {actionable step 2} +3. {actionable step 3} + +### Example Usage After Creation + +```bash +/{plugin-name} {example operation} +``` +``` + +## Error Handling + +- **Missing requirements** → Request detailed description of plugin purpose +- **Vague requirements** → Ask clarifying questions about specific functionality +- **Conflicting requirements** → Highlight conflicts and suggest resolution +- **Too broad scope** → Suggest breaking into multiple focused plugins + +## Examples + +### Example 1: Database Backup Plugin + +**Input**: +``` +requirements:"Need to automate PostgreSQL database backups with compression, encryption, and restore capabilities" +``` + +**Analysis**: +- Category: database +- Pattern: Complex (workflow orchestration) +- Template: workflow-orchestration +- Components: Commands (4 ops), Scripts (3 utilities) +- Operations: backup, restore, list, verify +- Scripts: connection-test.sh, compress-encrypt.py, integrity-check.sh +- Complexity: Medium +- Time: 20-30 minutes + +### Example 2: Code Formatter Plugin + +**Input**: +``` +requirements:"Simple code formatting for Python and JavaScript files" +``` + +**Analysis**: +- Category: quality +- Pattern: Simple +- Template: simple-crud (adapted) +- Components: Commands (2 ops) +- Operations: format, check +- Scripts: None needed +- Complexity: Low +- Time: 10-15 minutes + +**Request**: $ARGUMENTS diff --git a/commands/plugin-design/estimate-complexity.md b/commands/plugin-design/estimate-complexity.md new file mode 100644 index 0000000..1d4d9e1 --- /dev/null +++ b/commands/plugin-design/estimate-complexity.md @@ -0,0 +1,315 @@ +--- +description: Assess plugin implementation complexity and estimate development effort +--- + +# Estimate Plugin Complexity + +## Parameters + +**Required**: +- `operations`: Number of operations/commands (format: integer) + +**Optional**: +- `has_scripts`: Whether utility scripts are needed (format: true|false, default: false) +- `has_agents`: Whether agents are included (format: true|false, default: false) +- `has_hooks`: Whether hooks are included (format: true|false, default: false) +- `has_mcp`: Whether MCP servers are needed (format: true|false, default: false) +- `external_apis`: Number of external API integrations (format: integer, default: 0) + +## Workflow + +### Step 1: Calculate Base Complexity + +**Operation Complexity Score**: +- 1-2 operations: Base score = 1 (Simple) +- 3-5 operations: Base score = 2 (Moderate) +- 6-8 operations: Base score = 3 (Complex) +- 9+ operations: Base score = 4 (Very Complex) + +### Step 2: Apply Component Multipliers + +**Complexity Multipliers**: + +**Scripts** (+0.5 per script type): +- Shell scripts (.sh): +0.5 +- Python scripts (.py): +0.5 +- JavaScript scripts (.js): +0.5 +- Average scripts needed: operations / 3 (rounded up) + +**Agents** (+1.0 per agent): +- Agent design and prompting: +0.5 +- Agent capabilities definition: +0.3 +- Agent tool configuration: +0.2 +- Testing and refinement: +0.3 +- Total per agent: +1.3 + +**Hooks** (+0.5 per hook event): +- Hook configuration: +0.2 +- Event matcher design: +0.2 +- Hook script implementation: +0.3 +- Testing hook triggers: +0.3 +- Total per hook: +1.0 + +**MCP Servers** (+2.0 per server): +- Server design: +0.5 +- Tool implementation: +0.8 +- Configuration setup: +0.3 +- Testing and debugging: +0.4 +- Total per MCP server: +2.0 + +**External API Integrations** (+0.8 per API): +- Authentication setup: +0.3 +- API wrapper implementation: +0.3 +- Error handling: +0.2 +- Total per API: +0.8 + +### Step 3: Calculate Total Complexity + +**Formula**: +``` +Total Complexity = Base Score + + (script_count * 0.5) + + (agent_count * 1.3) + + (hook_count * 1.0) + + (mcp_count * 2.0) + + (api_count * 0.8) +``` + +**Complexity Bands**: +- 0-2: Very Low +- 2.1-4: Low +- 4.1-6: Moderate +- 6.1-8: High +- 8+: Very High + +### Step 4: Estimate Time Investment + +**Time Per Complexity Band**: + +**Very Low (0-2)**: +- Planning: 5-10 minutes +- Implementation: 10-15 minutes +- Testing: 5-10 minutes +- Documentation: 10-15 minutes +- Total: 30-50 minutes + +**Low (2.1-4)**: +- Planning: 10-15 minutes +- Implementation: 20-30 minutes +- Testing: 10-15 minutes +- Documentation: 15-20 minutes +- Total: 55-80 minutes + +**Moderate (4.1-6)**: +- Planning: 15-20 minutes +- Implementation: 40-60 minutes +- Testing: 20-30 minutes +- Documentation: 20-30 minutes +- Total: 95-140 minutes (1.5-2.5 hours) + +**High (6.1-8)**: +- Planning: 20-30 minutes +- Implementation: 80-120 minutes +- Testing: 30-45 minutes +- Documentation: 30-40 minutes +- Total: 160-235 minutes (2.5-4 hours) + +**Very High (8+)**: +- Planning: 30-45 minutes +- Implementation: 120-180+ minutes +- Testing: 45-60 minutes +- Documentation: 40-60 minutes +- Total: 235-345+ minutes (4-6+ hours) + +### Step 5: Identify Complexity Drivers + +**Major Complexity Drivers**: +- High operation count (6+) +- MCP server integration (highest impact) +- Complex state management +- Multiple external APIs +- Custom hooks with sophisticated matchers +- Agent with extensive capabilities + +**Risk Factors**: +- First-time MCP server development: +50% time +- Complex authentication: +30% time +- Unfamiliar external APIs: +40% time +- Testing infrastructure setup: +20% time + +### Step 6: Generate Estimate Report + +Provide comprehensive estimate with: +- Complexity score and band +- Time estimate with breakdown +- Complexity drivers +- Risk factors +- Recommendations for scope management +- Phased implementation plan + +## Output Format + +```markdown +## Plugin Complexity Estimate + +### Input Parameters +- **Operations**: {count} +- **Scripts**: {yes/no} ({estimated count}) +- **Agents**: {yes/no} ({count}) +- **Hooks**: {yes/no} ({count}) +- **MCP Servers**: {yes/no} ({count}) +- **External APIs**: {count} + +### Complexity Analysis + +**Base Complexity**: {score} ({Simple|Moderate|Complex|Very Complex}) + +**Component Adjustments**: +- Scripts: +{score} ({count} scripts) +- Agents: +{score} ({count} agents) +- Hooks: +{score} ({count} hooks) +- MCP Servers: +{score} ({count} servers) +- External APIs: +{score} ({count} APIs) + +**Total Complexity Score**: {total} / 10 + +**Complexity Band**: {Very Low|Low|Moderate|High|Very High} + +### Time Estimate + +**Breakdown**: +- Planning & Design: {time range} +- Implementation: {time range} +- Testing & Debugging: {time range} +- Documentation: {time range} + +**Total Estimated Time**: {time range} + +**Confidence Level**: {High|Medium|Low} +(Based on requirements clarity and risk factors) + +### Complexity Drivers + +**Major Drivers** (Highest Impact): +1. {driver 1}: {impact explanation} +2. {driver 2}: {impact explanation} +3. {driver 3}: {impact explanation} + +**Minor Drivers**: +- {driver}: {impact} + +### Risk Factors + +**Technical Risks**: +- {risk 1}: {mitigation strategy} +- {risk 2}: {mitigation strategy} + +**Time Risks**: +- {risk}: Potential +{percentage}% time increase + +### Recommendations + +**Scope Management**: +{Recommendations for managing complexity} + +**Simplification Opportunities**: +- {opportunity 1}: Could reduce complexity by {amount} +- {opportunity 2}: Could reduce complexity by {amount} + +**Phased Implementation**: + +**Phase 1 (MVP)**: {time estimate} +- {core component 1} +- {core component 2} +- {core component 3} + +**Phase 2 (Enhanced)**: {time estimate} +- {enhancement 1} +- {enhancement 2} + +**Phase 3 (Full-Featured)**: {time estimate} +- {advanced feature 1} +- {advanced feature 2} + +### Comparison to Similar Plugins + +**Similar Complexity**: +- {example plugin 1}: {comparison} +- {example plugin 2}: {comparison} + +**Reference Implementation Time**: +- Simple plugin (e.g., hello-world): 30-45 minutes +- Moderate plugin (e.g., code-formatter): 1-2 hours +- Complex plugin (e.g., deployment-automation): 3-5 hours +- Very complex plugin (e.g., test-framework): 5-8+ hours + +### Success Factors + +**To Stay On Track**: +1. {factor 1} +2. {factor 2} +3. {factor 3} + +**Red Flags to Watch**: +- {warning sign 1} +- {warning sign 2} +``` + +## Error Handling + +- **Invalid operation count** → Request valid positive integer +- **Unrealistic parameters** → Clarify actual requirements +- **Missing critical info** → Ask about components planned +- **Scope creep indicators** → Warn about complexity explosion + +## Examples + +### Example 1: Simple Plugin + +**Input**: +``` +operations:2 has_scripts:false has_agents:false has_hooks:false has_mcp:false +``` + +**Estimate**: +- Complexity: 1.0 (Very Low) +- Time: 30-50 minutes +- Band: Very Low +- Confidence: High + +### Example 2: Moderate Plugin + +**Input**: +``` +operations:5 has_scripts:true has_agents:true has_hooks:false has_mcp:false +``` + +**Estimate**: +- Base: 2.0 +- Scripts: +1.5 (3 scripts estimated) +- Agents: +1.3 (1 agent) +- Total: 4.8 (Moderate) +- Time: 90-120 minutes +- Confidence: Medium + +### Example 3: Complex Plugin + +**Input**: +``` +operations:7 has_scripts:true has_agents:true has_hooks:true has_mcp:true external_apis:2 +``` + +**Estimate**: +- Base: 3.0 +- Scripts: +2.0 (4 scripts) +- Agents: +1.3 (1 agent) +- Hooks: +1.0 (1 hook) +- MCP: +2.0 (1 server) +- APIs: +1.6 (2 APIs) +- Total: 10.9 (Very High) +- Time: 4-6+ hours +- Confidence: Medium-Low (high complexity) + +**Recommendation**: Consider phased approach, starting with core 3-4 operations + +**Request**: $ARGUMENTS diff --git a/commands/plugin-design/recommend-patterns.md b/commands/plugin-design/recommend-patterns.md new file mode 100644 index 0000000..8d11cc3 --- /dev/null +++ b/commands/plugin-design/recommend-patterns.md @@ -0,0 +1,389 @@ +--- +description: Suggest architectural patterns based on plugin complexity and requirements +--- + +# Recommend Architectural Patterns + +## Parameters + +**Required**: +- `complexity`: Plugin complexity level (format: low|moderate|high) +- `features`: Number of main features/operations (format: integer) + +**Optional**: +- `state_management`: Whether state management is needed (format: true|false) +- `workflows`: Whether multi-step workflows are needed (format: true|false) +- `external_integration`: Whether external tools are involved (format: true|false) + +## Workflow + +### Step 1: Assess Complexity Level + +**Complexity Classification**: + +**Low Complexity**: +- 1-2 operations +- Stateless execution +- Simple input/output +- No external dependencies +- Direct functionality + +**Moderate Complexity**: +- 3-5 operations +- Some state tracking +- Light orchestration needed +- Few external dependencies +- May have related operations + +**High Complexity**: +- 6+ operations +- State management required +- Complex workflows +- Multiple external dependencies +- Operations compose together + +### Step 2: Pattern Matching + +**Pattern 1: Simple Plugin (Single Command)** + +**When to Use**: +- Complexity: Low +- Features: 1-2 +- State management: No +- Workflows: No + +**Structure**: +``` +plugin-name/ +├── plugin.json +├── commands/ +│ └── command.md +└── README.md +``` + +**Characteristics**: +- Single .md file in commands/ +- No skill.md router +- Direct invocation: /{command-name} +- Straightforward implementation + +**Example Use Cases**: +- Hello World plugin +- Simple formatters +- Basic converters +- Quick utilities + +**Pattern 2: Namespace Plugin (Multiple Independent Commands)** + +**When to Use**: +- Complexity: Low to Moderate +- Features: 3-5 +- State management: No or minimal +- Workflows: Independent operations +- Commands don't need orchestration + +**Structure**: +``` +plugin-name/ +├── plugin.json +├── commands/ +│ ├── operation1.md +│ ├── operation2.md +│ ├── operation3.md +│ └── operation4.md +└── README.md +``` + +**Characteristics**: +- Multiple .md files, NO skill.md +- Each command independently invokable +- Namespace prefix: /{plugin-name}:operation +- Grouped by domain but independent + +**Example Use Cases**: +- Multiple formatters (format-python, format-js, format-css) +- Independent utilities collection +- Toolbox plugins + +**Pattern 3: Skill Plugin (Orchestrated Operations)** + +**When to Use**: +- Complexity: Moderate to High +- Features: 5+ +- State management: Yes +- Workflows: Operations share context +- Need intelligent routing + +**Structure**: +``` +plugin-name/ +├── plugin.json +├── commands/ +│ ├── skill.md (router) +│ ├── operation1.md +│ ├── operation2.md +│ ├── operation3.md +│ └── operation4.md +└── README.md +``` + +**Characteristics**: +- skill.md acts as intelligent router +- Sub-commands are instruction modules (not directly invokable) +- Single entry point: /{plugin-name} operation args +- Parses arguments and routes internally + +**Example Use Cases**: +- Database management (backup, restore, migrate, verify) +- Deployment pipelines (build, test, deploy, rollback) +- Multi-step workflows + +**Pattern 4: Script-Enhanced Plugin** + +**When to Use**: +- Complexity: Moderate to High +- Features: Any number +- External tools: Yes +- Performance critical: Yes +- Complex logic better in scripts + +**Structure**: +``` +plugin-name/ +├── plugin.json +├── commands/ +│ ├── skill.md (if orchestrated) +│ ├── operation1.md +│ ├── operation2.md +│ └── .scripts/ +│ ├── utility1.sh +│ ├── utility2.py +│ └── utility3.js +└── README.md +``` + +**Characteristics**: +- Commands leverage utility scripts +- Scripts handle complex/repeated logic +- Better performance for intensive tasks +- Reusable across operations + +**Example Use Cases**: +- Database operations with connection pooling +- File processing pipelines +- External tool integrations + +**Pattern 5: Agent-Enhanced Plugin** + +**When to Use**: +- Complexity: Any +- Domain expertise needed: Yes +- Guidance beneficial: Yes +- Proactive behavior desired: Yes + +**Structure**: +``` +plugin-name/ +├── plugin.json +├── commands/ +│ └── {command files} +├── agents/ +│ └── specialist.md +└── README.md +``` + +**Characteristics**: +- Agent provides domain expertise +- Proactive invocation based on context +- Conversational guidance +- Works alongside commands + +**Example Use Cases**: +- Code review automation +- Security analysis +- Performance optimization +- Architecture guidance + +**Pattern 6: Full-Featured Plugin** + +**When to Use**: +- Complexity: High +- Features: 6+ +- All capabilities needed: Yes + +**Structure**: +``` +plugin-name/ +├── plugin.json +├── commands/ +│ ├── skill.md +│ ├── {operations} +│ └── .scripts/ +│ └── {utilities} +├── agents/ +│ └── specialist.md +├── hooks/ +│ └── hooks.json +└── README.md +``` + +**Characteristics**: +- Complete plugin with all components +- Commands + Agent + Hooks + Scripts +- Maximum functionality +- Production-grade plugin + +**Example Use Cases**: +- Comprehensive testing frameworks +- Full deployment automation +- Complete quality assurance systems + +### Step 3: Template Mapping + +**Map pattern to template**: + +- **Simple Plugin** → No template needed (direct implementation) +- **Namespace Plugin** → No template needed (direct implementation) +- **Skill Plugin (CRUD-like)** → simple-crud template +- **Skill Plugin (Workflow)** → workflow-orchestration template +- **Script-Enhanced** → script-enhanced template +- **MCP Integration** → mcp-integration template + +### Step 4: Provide Recommendations + +Generate recommendations with: +- Recommended pattern with justification +- Alternative patterns with trade-offs +- Template to use (if applicable) +- Structure diagram +- Implementation guidance +- Example usage + +## Output Format + +```markdown +## Architectural Pattern Recommendations + +### Analysis +**Complexity Level**: {low|moderate|high} +**Features Count**: {number} +**State Management**: {needed|not needed} +**Workflows**: {needed|not needed} +**External Integration**: {needed|not needed} + +### Recommended Pattern: {Pattern Name} + +**Why This Pattern**: +{Detailed justification based on requirements} + +**Template**: {template-name or "Direct implementation"} + +**Structure**: +``` +{Directory structure diagram} +``` + +**Key Characteristics**: +- {characteristic 1} +- {characteristic 2} +- {characteristic 3} + +**Implementation Steps**: +1. {step 1} +2. {step 2} +3. {step 3} + +**Usage After Implementation**: +```bash +{Example commands} +``` + +### Alternative Patterns + +#### Alternative 1: {Pattern Name} + +**When to Consider**: +{Conditions where this might be better} + +**Trade-offs**: +- Pros: {advantages} +- Cons: {disadvantages} + +#### Alternative 2: {Pattern Name} + +**When to Consider**: +{Conditions where this might be better} + +**Trade-offs**: +- Pros: {advantages} +- Cons: {disadvantages} + +### Pattern Comparison + +| Aspect | Recommended | Alt 1 | Alt 2 | +|--------|------------|-------|-------| +| Complexity | {rating} | {rating} | {rating} | +| Maintainability | {rating} | {rating} | {rating} | +| Extensibility | {rating} | {rating} | {rating} | +| Learning Curve | {rating} | {rating} | {rating} | + +### Migration Path + +**If Requirements Change**: +- **Scale Up**: {How to add more features} +- **Scale Down**: {How to simplify} +- **Pivot**: {How to change direction} + +### Best Practices for This Pattern + +1. {Best practice 1} +2. {Best practice 2} +3. {Best practice 3} +``` + +## Error Handling + +- **Invalid complexity level** → Request valid value: low|moderate|high +- **Features count unrealistic** → Clarify actual feature count +- **Conflicting parameters** → Highlight conflicts and suggest resolution +- **Unclear requirements** → Ask clarifying questions + +## Examples + +### Example 1: Low Complexity, Few Features + +**Input**: +``` +complexity:low features:2 state_management:false workflows:false +``` + +**Recommendation**: +- **Pattern**: Simple Plugin (Single Command) or Namespace +- **Template**: Direct implementation +- **Rationale**: Few features, no orchestration needed + +### Example 2: Moderate Complexity, Workflow + +**Input**: +``` +complexity:moderate features:5 state_management:true workflows:true +``` + +**Recommendation**: +- **Pattern**: Skill Plugin with skill.md router +- **Template**: workflow-orchestration +- **Rationale**: Multiple operations sharing state, needs orchestration + +### Example 3: High Complexity, External Tools + +**Input**: +``` +complexity:high features:7 external_integration:true workflows:true +``` + +**Recommendation**: +- **Pattern**: Full-Featured Plugin (Commands + Scripts + Agent) +- **Template**: script-enhanced + workflow-orchestration +- **Rationale**: Complex workflows with external integration needs utility scripts and expert guidance + +**Request**: $ARGUMENTS diff --git a/commands/plugin-design/select-components.md b/commands/plugin-design/select-components.md new file mode 100644 index 0000000..cbbff53 --- /dev/null +++ b/commands/plugin-design/select-components.md @@ -0,0 +1,286 @@ +--- +description: Determine which plugin components to use based on functionality requirements +--- + +# Select Plugin Components + +## Parameters + +**Required**: +- `purpose`: Plugin's primary purpose (format: quoted string) +- `features`: Comma-separated list of features (format: "feat1,feat2,feat3") + +**Optional**: +- `automation`: Whether proactive behavior is needed (format: true|false, default: false) +- `external_tools`: External tools/APIs needed (format: "tool1,tool2") + +## Workflow + +### Step 1: Feature Analysis + +Parse the features list and categorize each feature: +- **User-Initiated Actions**: Operations triggered by explicit user command +- **Proactive Behaviors**: Actions that should happen automatically +- **Background Tasks**: Long-running or scheduled operations +- **Interactive Workflows**: Multi-step conversational processes + +### Step 2: Commands Assessment + +**Evaluate Need for Commands**: + +Commands are appropriate when: +- Users need explicit control over when operations execute +- Functionality is invoked via slash commands +- Operations are discrete and independent +- Simple input/output pattern + +**Command Organization**: +- **Single Command**: 1-2 simple operations +- **Namespace**: 3-5 independent operations +- **Skill with skill.md**: 5+ operations needing intelligent routing + +**Recommendation Logic**: +``` +IF features_count <= 2 AND simple_operations: + RECOMMEND: Single command +ELSE IF features_count <= 5 AND independent_operations: + RECOMMEND: Namespace (commands directory without skill.md) +ELSE: + RECOMMEND: Skill with skill.md router +``` + +### Step 3: Agents Assessment + +**Evaluate Need for Agents**: + +Agents are appropriate when: +- Domain expertise would benefit users +- Automatic invocation based on context is valuable +- Guidance and recommendations are needed +- Analysis and decision-making support users + +**Agent Design Questions**: +1. Does the plugin domain require specialized knowledge? +2. Would users benefit from conversational guidance? +3. Should the plugin proactively suggest actions? +4. Is there a workflow that needs expert orchestration? + +**Recommendation**: +- **Yes to 2+ questions** → Include agent +- **Yes to 1 question** → Consider optional agent +- **No to all** → Commands only sufficient + +**Agent Capabilities Mapping**: +Map features to agent capabilities: +- Code analysis → code-review, security-analysis +- Testing → test-generation, coverage-analysis +- Deployment → deployment-orchestration, rollback-management +- Documentation → doc-generation, api-documentation + +### Step 4: Hooks Assessment + +**Evaluate Need for Hooks**: + +Hooks are appropriate when: +- Automation should trigger on specific events +- Workflow enforcement is needed +- Actions should happen transparently +- Quality gates need to be enforced + +**Hook Event Mapping**: +- **PostToolUse**: After Write, Edit, Bash, etc. +- **PreToolUse**: Before Write, Edit, etc. (for validation) +- **SessionStart**: Plugin initialization +- **SessionEnd**: Cleanup and reporting + +**Common Hook Patterns**: +- **Auto-format on Write**: PostToolUse with Write matcher +- **Lint before commit**: PreToolUse with Bash(git commit) matcher +- **Auto-test on code change**: PostToolUse with Edit matcher +- **Session report**: SessionEnd hook + +**Recommendation Logic**: +``` +IF automation == true OR workflow_enforcement_needed: + IDENTIFY triggering events + RECOMMEND appropriate hooks +ELSE: + RECOMMEND: Hooks not needed +``` + +### Step 5: MCP Servers Assessment + +**Evaluate Need for MCP Servers**: + +MCP servers are appropriate when: +- Plugin needs to integrate external tools not available in Claude Code +- Custom data sources must be accessed +- Specialized APIs need to be wrapped +- Real-time data or streaming is required +- Complex state management across sessions + +**MCP Use Cases**: +- **Database Operations**: Dedicated database MCP server +- **Cloud Services**: AWS, GCP, Azure API wrappers +- **Custom Tools**: Internal tools integration +- **Data Processing**: Specialized data pipelines +- **Monitoring**: Metrics and logging services + +**Recommendation Logic**: +``` +IF external_tools specified: + FOR each tool: + CHECK if native Claude Code tool exists + IF not: + RECOMMEND MCP server +ELSE IF complex_external_integration: + RECOMMEND MCP server design +ELSE: + RECOMMEND: MCP servers not needed +``` + +### Step 6: Generate Component Recommendations + +Create comprehensive component selection report with: +- Recommended components with justification +- Component interaction diagram +- Implementation priority +- Alternative approaches +- Trade-offs and considerations + +## Output Format + +```markdown +## Component Selection Recommendations + +### Plugin Purpose +**Primary Goal**: {purpose} +**Features**: {features list} +**Automation Needed**: {yes/no} +**External Tools**: {tools list} + +### Recommended Components + +#### Commands ✅ Recommended / ❌ Not Needed + +**Decision**: {Recommended|Not Needed} + +**Rationale**: {explanation} + +**Organization**: +- {Single Command|Namespace|Skill with Router} + +**Operations**: +1. **{operation-name}**: {description} + - Invocation: `/{plugin-name} {operation} {args}` + - Complexity: {low|medium|high} + +#### Agents ✅ Recommended / ⚠️ Optional / ❌ Not Needed + +**Decision**: {Recommended|Optional|Not Needed} + +**Rationale**: {explanation} + +**Agent Design**: +- **Name**: {agent-name} +- **Description**: {when to invoke description} +- **Capabilities**: {capabilities list} +- **Proactive Triggers**: {trigger conditions} + +#### Hooks ✅ Recommended / ❌ Not Needed + +**Decision**: {Recommended|Not Needed} + +**Rationale**: {explanation} + +**Hook Configuration**: +- **Event**: {PostToolUse|PreToolUse|SessionStart|SessionEnd} +- **Matcher**: {regex pattern} +- **Action**: {what happens} + +#### MCP Servers ✅ Recommended / ❌ Not Needed + +**Decision**: {Recommended|Not Needed} + +**Rationale**: {explanation} + +**Server Design**: +- **Server Name**: {server-name} +- **Purpose**: {what it provides} +- **Tools Exposed**: {tool list} + +### Component Interaction Flow + +``` +{Describe how components interact} + +Example: +1. User invokes /{plugin-name} {operation} +2. Command validates input +3. Agent provides guidance if complex +4. Hook triggers on completion +5. MCP server performs external integration +``` + +### Implementation Priority + +1. **Phase 1**: {Core components to build first} +2. **Phase 2**: {Enhancement components} +3. **Phase 3**: {Optional components} + +### Alternative Approaches + +**If simpler**: {simpler alternative} +**If more robust**: {more complex alternative} + +### Trade-offs + +**Pros**: +- {advantage 1} +- {advantage 2} + +**Cons**: +- {consideration 1} +- {consideration 2} +``` + +## Error Handling + +- **Unclear purpose** → Request clearer description of plugin goal +- **Feature list too broad** → Suggest focusing on core functionality +- **Conflicting requirements** → Highlight conflicts and suggest resolution +- **Missing critical info** → Ask targeted questions + +## Examples + +### Example 1: Code Quality Plugin + +**Input**: +``` +purpose:"Automated code quality enforcement" +features:"lint,format,security-scan,complexity-analysis" +automation:true +``` + +**Recommendations**: +- **Commands**: Yes (Skill with skill.md router, 4 operations) +- **Agents**: Yes (code-reviewer agent for proactive analysis) +- **Hooks**: Yes (PostToolUse on Write/Edit for auto-lint) +- **MCP Servers**: No (native tools sufficient) + +### Example 2: Simple Greeting Plugin + +**Input**: +``` +purpose:"Greet users with personalized messages" +features:"greet" +automation:false +``` + +**Recommendations**: +- **Commands**: Yes (Single command) +- **Agents**: No (too simple) +- **Hooks**: No (user-initiated only) +- **MCP Servers**: No (no external integration) + +**Request**: $ARGUMENTS diff --git a/commands/plugin-design/skill.md b/commands/plugin-design/skill.md new file mode 100644 index 0000000..1ddb34e --- /dev/null +++ b/commands/plugin-design/skill.md @@ -0,0 +1,52 @@ +--- +description: Guide users through plugin architecture decisions and component selection for Claude Code plugins +--- + +# Plugin Design Skill + +Expert guidance for designing Claude Code plugin architecture with optimal component selection and pattern recommendations. + +## Operations + +- **analyze** - Analyze requirements and suggest optimal architecture +- **select-components** - Determine which components to use (commands, agents, hooks, MCP) +- **recommend** - Suggest architectural patterns based on complexity +- **estimate** - Assess implementation complexity and effort + +## Usage Examples + +```bash +# Analyze requirements +/plugin-design analyze requirements:"Need to automate database backups with scheduling" + +# Get component recommendations +/plugin-design select-components purpose:"Code quality automation" features:"lint,format,review" + +# Get pattern recommendations +/plugin-design recommend complexity:moderate features:3 + +# Estimate implementation effort +/plugin-design estimate operations:5 has_scripts:true has_agents:true +``` + +## Router Logic + +Parse the first word of $ARGUMENTS to determine the requested operation: + +1. Extract operation from first word of $ARGUMENTS +2. Parse remaining arguments as key:value parameters +3. Route to appropriate operation file: + - "analyze" → Read and execute `{plugin-path}/commands/plugin-design/analyze-requirements.md` + - "select-components" → Read and execute `{plugin-path}/commands/plugin-design/select-components.md` + - "recommend" → Read and execute `{plugin-path}/commands/plugin-design/recommend-patterns.md` + - "estimate" → Read and execute `{plugin-path}/commands/plugin-design/estimate-complexity.md` + +**Error Handling**: +- If operation unknown → List available operations with usage examples +- If parameters missing → Request parameters with expected format +- If requirements unclear → Ask clarifying questions + +**Base directory**: Plugin commands directory +**Current request**: $ARGUMENTS + +Parse operation and route to appropriate instruction file now. diff --git a/commands/plugin-metadata/.scripts/validate-semver.sh b/commands/plugin-metadata/.scripts/validate-semver.sh new file mode 100755 index 0000000..fcb92ce --- /dev/null +++ b/commands/plugin-metadata/.scripts/validate-semver.sh @@ -0,0 +1,37 @@ +#!/bin/bash +# Script: validate-semver.sh +# Purpose: Validate semantic versioning format +# Version: 1.0.0 +# +# Usage: ./validate-semver.sh +# Returns: 0 - Valid semver, 1 - Invalid format + +VERSION="$1" + +if [ -z "$VERSION" ]; then + echo "ERROR: Version required" + exit 2 +fi + +# Semantic versioning pattern: MAJOR.MINOR.PATCH with optional pre-release and build metadata +SEMVER_PATTERN='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*)(\.(0|[1-9][0-9]*|[0-9]*[a-zA-Z-][0-9a-zA-Z-]*))*))?(\+([0-9a-zA-Z-]+(\.[0-9a-zA-Z-]+)*))?$' + +if echo "$VERSION" | grep -Eq "$SEMVER_PATTERN"; then + echo "✅ Valid semantic version: $VERSION" + exit 0 +else + echo "❌ Invalid semantic version: $VERSION" + echo "" + echo "Semantic versioning format: MAJOR.MINOR.PATCH" + echo " - MAJOR: Breaking changes" + echo " - MINOR: New features (backwards compatible)" + echo " - PATCH: Bug fixes" + echo "" + echo "Valid examples:" + echo " - 1.0.0" + echo " - 2.1.3" + echo " - 1.0.0-alpha" + echo " - 1.0.0-beta.1" + echo " - 1.0.0+20250113" + exit 1 +fi diff --git a/commands/plugin-metadata/skill.md b/commands/plugin-metadata/skill.md new file mode 100644 index 0000000..372ec18 --- /dev/null +++ b/commands/plugin-metadata/skill.md @@ -0,0 +1,40 @@ +--- +description: Create, validate, and update plugin metadata including plugin.json and marketplace entries +--- + +# Plugin Metadata Skill + +Expert metadata management for Claude Code plugins with validation, versioning, and marketplace entry generation. + +## Operations + +- **validate** - Validate plugin.json completeness and correctness +- **update-version** - Update version with semantic versioning validation +- **add-keywords** - Add or update keywords for plugin discoverability +- **marketplace-entry** - Generate marketplace.json plugin entry + +## Usage Examples + +```bash +# Validate metadata +/plugin-metadata validate plugin:my-plugin + +# Update version +/plugin-metadata update-version plugin:my-plugin version:1.1.0 + +# Add keywords +/plugin-metadata add-keywords plugin:my-plugin keywords:"testing,automation,python" + +# Generate marketplace entry +/plugin-metadata marketplace-entry plugin:my-plugin source:"github:username/plugin-name" +``` + +## Router Logic + +Parse operation from $ARGUMENTS and route to appropriate instruction file: +- "validate" → `{plugin-path}/commands/plugin-metadata/validate-metadata.md` +- "update-version" → `{plugin-path}/commands/plugin-metadata/update-version.md` +- "add-keywords" → `{plugin-path}/commands/plugin-metadata/add-keywords.md` +- "marketplace-entry" → `{plugin-path}/commands/plugin-metadata/create-marketplace-entry.md` + +**Current request**: $ARGUMENTS diff --git a/commands/plugin-quality/.scripts/secret-scanner.sh b/commands/plugin-quality/.scripts/secret-scanner.sh new file mode 100755 index 0000000..34d7702 --- /dev/null +++ b/commands/plugin-quality/.scripts/secret-scanner.sh @@ -0,0 +1,58 @@ +#!/bin/bash +# Script: secret-scanner.sh +# Purpose: Scan plugin files for hardcoded secrets and credentials +# Version: 1.0.0 +# +# Usage: ./secret-scanner.sh +# Returns: 0 - No secrets found, 1 - Secrets detected + +PLUGIN_PATH="$1" + +if [ -z "$PLUGIN_PATH" ]; then + echo "ERROR: Plugin path required" + exit 2 +fi + +ISSUES_FOUND=0 + +# Patterns to search for +declare -a PATTERNS=( + "api[_-]?key['\"]?\s*[:=]" + "apikey['\"]?\s*[:=]" + "secret[_-]?key['\"]?\s*[:=]" + "password['\"]?\s*[:=]\s*['\"][^'\"]{8,}" + "token['\"]?\s*[:=]\s*['\"][a-zA-Z0-9]{20,}" + "AKIA[0-9A-Z]{16}" # AWS Access Key + "AIza[0-9A-Za-z\\-_]{35}" # Google API Key + "sk-[a-zA-Z0-9]{48}" # OpenAI API Key + "ghp_[a-zA-Z0-9]{36}" # GitHub Personal Access Token + "-----BEGIN.*PRIVATE KEY-----" # Private keys + "mongodb://.*:.*@" # MongoDB connection strings + "postgres://.*:.*@" # PostgreSQL connection strings +) + +echo "🔍 Scanning for hardcoded secrets..." +echo "" + +for pattern in "${PATTERNS[@]}"; do + matches=$(grep -r -i -E "$pattern" "$PLUGIN_PATH" --exclude-dir=.git --exclude="*.log" 2>/dev/null | grep -v "secret-scanner.sh" || true) + if [ -n "$matches" ]; then + echo "⚠️ Potential secret found matching pattern: $pattern" + echo "$matches" + echo "" + ISSUES_FOUND=$((ISSUES_FOUND + 1)) + fi +done + +if [ $ISSUES_FOUND -eq 0 ]; then + echo "✅ No hardcoded secrets detected" + exit 0 +else + echo "❌ Found $ISSUES_FOUND potential secret(s)" + echo "" + echo "Recommendations:" + echo " - Use environment variables for sensitive data" + echo " - Store secrets in .env files (add to .gitignore)" + echo " - Use secure credential management" + exit 1 +fi diff --git a/commands/plugin-quality/full-audit.md b/commands/plugin-quality/full-audit.md new file mode 100644 index 0000000..2725093 --- /dev/null +++ b/commands/plugin-quality/full-audit.md @@ -0,0 +1,267 @@ +--- +description: Run comprehensive quality audit on plugin with scoring and recommendations +--- + +# Full Plugin Quality Audit + +## Parameters + +**Required**: +- `plugin`: Plugin name or path to plugin directory + +**Optional**: +- `strict`: Enable strict mode for marketplace submission (format: true|false, default: false) +- `report_format`: Output format (format: text|json|markdown, default: markdown) + +## Workflow + +### Step 1: File Structure Validation + +Check directory structure compliance: +```bash +.scripts/structure-checker.sh "{plugin_path}" +``` + +**Checks**: +- ✅ `plugin.json` exists at plugin root +- ✅ `README.md` exists and not empty +- ✅ `LICENSE` file exists +- ✅ `commands/` directory exists +- ✅ At least one command file present +- ✅ Proper naming: lowercase-hyphen format +- ✅ No invalid file types in root + +**Score**: 0-20 points + +### Step 2: Metadata Validation + +Validate plugin.json completeness: +```bash +python3 -m json.tool "{plugin_path}/plugin.json" +``` + +**Checks**: +- ✅ Valid JSON syntax +- ✅ Required fields present: name, version, description, author, license +- ✅ Name format correct (lowercase-hyphen) +- ✅ Version valid semver +- ✅ Description 50-200 characters +- ✅ Author has name (email optional) +- ✅ License is standard (MIT, Apache-2.0, etc.) +- ✅ Keywords present (3-7 recommended) +- ✅ Category valid (one of 10 categories) +- ✅ Repository URL if provided is valid + +**Score**: 0-25 points + +### Step 3: Security Scan + +Scan for security issues: +```bash +.scripts/secret-scanner.sh "{plugin_path}" +``` + +**Checks**: +- ✅ No hardcoded API keys +- ✅ No exposed passwords or tokens +- ✅ No AWS/GCP credentials +- ✅ No private keys +- ✅ No database connection strings +- ✅ Environment variables used for secrets +- ✅ No eval() or exec() in scripts +- ✅ No unvalidated user input +- ✅ HTTPS for external URLs +- ✅ Safe file path handling + +**Score**: 0-25 points (Critical: -50 if secrets found) + +### Step 4: Documentation Quality + +Validate documentation completeness: +```bash +.scripts/doc-validator.py "{plugin_path}/README.md" +``` + +**Checks**: +- ✅ README has title matching plugin name +- ✅ Description section present +- ✅ Installation instructions (at least one method) +- ✅ Usage section with examples +- ✅ No placeholder text ("TODO", "Add description here") +- ✅ Concrete examples (not generic) +- ✅ Parameters documented +- ✅ License referenced +- ✅ Links are valid (no 404s) +- ✅ Code blocks properly formatted + +**Score**: 0-20 points + +### Step 5: Functional Validation + +Check command/agent functionality: + +**Commands**: +- ✅ All commands have description frontmatter +- ✅ Clear usage instructions +- ✅ Parameter documentation +- ✅ Error handling mentioned +- ✅ Examples provided + +**Agents** (if present): +- ✅ Name field present +- ✅ Description describes when to invoke +- ✅ Capabilities listed +- ✅ Tools specified or inherited + +**Score**: 0-10 points + +### Step 6: Calculate Overall Score + +**Total Score**: 0-100 points + +**Grade Bands**: +- 90-100: Excellent (A) - Marketplace ready +- 80-89: Good (B) - Minor improvements needed +- 70-79: Satisfactory (C) - Several improvements needed +- 60-69: Needs Work (D) - Major issues to address +- 0-59: Failing (F) - Not ready for submission + +### Step 7: Generate Audit Report + +Provide comprehensive report with: +- Overall score and grade +- Category scores breakdown +- Passed checks list +- Failed checks list +- Warnings +- Recommendations prioritized +- Pre-submission checklist status + +## Output Format + +```markdown +# Plugin Quality Audit Report + +## Overall Score: {score}/100 ({grade}) + +**Status**: {Marketplace Ready|Needs Minor Improvements|Needs Major Improvements|Not Ready} + +--- + +## Category Scores + +### File Structure: {score}/20 ✅|⚠️|❌ +{Detailed findings} + +### Metadata Quality: {score}/25 ✅|⚠️|❌ +{Detailed findings} + +### Security: {score}/25 ✅|⚠️|❌ +{Detailed findings} + +### Documentation: {score}/20 ✅|⚠️|❌ +{Detailed findings} + +### Functionality: {score}/10 ✅|⚠️|❌ +{Detailed findings} + +--- + +## Validation Results + +### ✅ Passed Checks ({count}) +- {check 1} +- {check 2} +... + +### ❌ Failed Checks ({count}) +- {check 1}: {issue description} + - **Fix**: {how to fix} +- {check 2}: {issue description} + - **Fix**: {how to fix} + +### ⚠️ Warnings ({count}) +- {warning 1}: {description} +- {warning 2}: {description} + +--- + +## Recommendations + +### Critical (Fix Before Submission) +1. {critical issue 1} + - Current: {what's wrong} + - Required: {what's needed} + - Example: {how to fix} + +### Important (Strongly Recommended) +1. {important issue 1} + - Impact: {why it matters} + - Suggestion: {how to improve} + +### Nice to Have (Optional Enhancements) +1. {enhancement 1} + - Benefit: {what it adds} + +--- + +## Pre-Submission Checklist + +- [{✅|❌}] Plugin name follows lowercase-hyphen format +- [{✅|❌}] Description is 50-200 characters and specific +- [{✅|❌}] All required metadata fields present +- [{✅|❌}] README has real content (no placeholders) +- [{✅|❌}] LICENSE file included +- [{✅|❌}] At least one functional command +- [{✅|❌}] No hardcoded secrets or credentials +- [{✅|❌}] Examples are concrete and realistic +- [{✅|❌}] Documentation complete and accurate +- [{✅|❌}] Category correctly selected + +--- + +## Next Steps + +{Prioritized action items based on audit results} + +1. **Immediate**: {must-do items} +2. **Short-term**: {should-do items} +3. **Enhancement**: {nice-to-have items} + +--- + +## Resources + +- Fix Common Issues: https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md +- Quality Standards: https://github.com/dhofheinz/open-plugins/blob/main/QUALITY.md +- Examples: Browse OpenPlugins marketplace for reference implementations + +--- + +**Audit completed**: {timestamp} +**Plugin**: {plugin_name} v{version} +**Auditor**: plugin-quality skill +``` + +## Error Handling + +- **Plugin not found** → Check path and plugin name +- **Invalid plugin structure** → Must have plugin.json at plugin root +- **Permission errors** → Check file permissions +- **Script execution fails** → Report specific script and error + +## Examples + +### Example 1: High Quality Plugin + +**Input**: `/plugin-quality full-audit plugin:test-generator` + +**Output**: Score 92/100 (A) - Marketplace ready with minor suggestions + +### Example 2: Plugin Needs Work + +**Input**: `/plugin-quality full-audit plugin:my-plugin strict:true` + +**Output**: Score 65/100 (D) - Multiple issues identified with detailed fixes + +**Request**: $ARGUMENTS diff --git a/commands/plugin-quality/skill.md b/commands/plugin-quality/skill.md new file mode 100644 index 0000000..ad53847 --- /dev/null +++ b/commands/plugin-quality/skill.md @@ -0,0 +1,45 @@ +--- +description: Validate plugins against OpenPlugins quality standards with security scanning and documentation checks +--- + +# Plugin Quality Assurance Skill + +Comprehensive quality validation for Claude Code plugins ensuring OpenPlugins marketplace standards. + +## Operations + +- **security** - Scan for hardcoded secrets and unsafe practices +- **docs** - Validate README completeness and documentation quality +- **structure** - Validate directory structure and file organization +- **metadata** - Lint JSON and frontmatter validation +- **full-audit** - Run complete quality audit with scoring + +## Usage Examples + +```bash +# Security scan +/plugin-quality security plugin:my-plugin + +# Documentation check +/plugin-quality docs plugin:my-plugin + +# Structure validation +/plugin-quality structure plugin:my-plugin + +# Metadata validation +/plugin-quality metadata plugin:my-plugin + +# Full quality audit +/plugin-quality full-audit plugin:my-plugin +``` + +## Router Logic + +Parse operation from $ARGUMENTS and route to appropriate instruction file: +- "security" → `{plugin-path}/commands/plugin-quality/check-security.md` +- "docs" → `{plugin-path}/commands/plugin-quality/validate-documentation.md` +- "structure" → `{plugin-path}/commands/plugin-quality/check-structure.md` +- "metadata" → `{plugin-path}/commands/plugin-quality/lint-metadata.md` +- "full-audit" → `{plugin-path}/commands/plugin-quality/full-audit.md` + +**Current request**: $ARGUMENTS diff --git a/commands/plugin-scaffold/.scripts/generate-metadata.py b/commands/plugin-scaffold/.scripts/generate-metadata.py new file mode 100755 index 0000000..da751ea --- /dev/null +++ b/commands/plugin-scaffold/.scripts/generate-metadata.py @@ -0,0 +1,223 @@ +#!/usr/bin/env python3 +""" +Script: generate-metadata.py +Purpose: Generate plugin.json metadata from parameters +Version: 1.0.0 +Last Modified: 2025-10-13 + +Usage: + ./generate-metadata.py --name --author --description --license + +Returns: + 0 - Success, JSON written to stdout + 1 - Validation error + 2 - Missing required arguments + +Dependencies: + - python3 (3.7+) + - json module (standard library) +""" + +import json +import sys +import argparse +import re +from datetime import datetime + +# OpenPlugins standard categories +VALID_CATEGORIES = [ + "development", "testing", "deployment", "documentation", + "security", "database", "monitoring", "productivity", + "quality", "collaboration" +] + +VALID_LICENSES = ["MIT", "Apache-2.0", "GPL-3.0", "BSD-3-Clause", "ISC", "LGPL-3.0"] + +def parse_author(author_string): + """Parse author string into name and email components.""" + # Pattern: "Name " or "Name" or "Name (email)" + email_pattern = r'<([^>]+)>' + paren_pattern = r'\(([^\)]+)\)' + + name = author_string + email = None + + # Check for format + email_match = re.search(email_pattern, author_string) + if email_match: + email = email_match.group(1) + name = author_string[:email_match.start()].strip() + else: + # Check for (email) format + paren_match = re.search(paren_pattern, author_string) + if paren_match: + email = paren_match.group(1) + name = author_string[:paren_match.start()].strip() + + result = {"name": name} + if email: + result["email"] = email + + return result + +def generate_keywords(name, description, category): + """Generate relevant keywords from name, description, and category.""" + keywords = [] + + # Add category + keywords.append(category) + + # Extract keywords from name + name_parts = name.split('-') + for part in name_parts: + if len(part) > 3 and part not in ['plugin', 'claude', 'code']: + keywords.append(part) + + # Extract keywords from description (simple approach) + desc_words = re.findall(r'\b[a-z]{4,}\b', description.lower()) + common_words = {'with', 'from', 'this', 'that', 'have', 'will', 'your', 'for'} + for word in desc_words[:3]: # Take first 3 meaningful words + if word not in common_words and word not in keywords: + keywords.append(word) + + # Ensure 3-7 keywords + return keywords[:7] + +def validate_name(name): + """Validate plugin name format.""" + pattern = r'^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$' + if not re.match(pattern, name): + return False, "Plugin name must be lowercase with hyphens only" + if '--' in name: + return False, "Plugin name cannot contain consecutive hyphens" + if len(name) < 3 or len(name) > 50: + return False, "Plugin name must be 3-50 characters" + return True, None + +def validate_description(description): + """Validate description length and content.""" + length = len(description) + if length < 50: + return False, f"Description too short ({length} chars, minimum 50)" + if length > 200: + return False, f"Description too long ({length} chars, maximum 200)" + return True, None + +def generate_metadata(args): + """Generate complete plugin.json metadata.""" + + # Validate name + valid, error = validate_name(args.name) + if not valid: + print(f"ERROR: {error}", file=sys.stderr) + return None + + # Validate description + valid, error = validate_description(args.description) + if not valid: + print(f"ERROR: {error}", file=sys.stderr) + return None + + # Validate license + if args.license not in VALID_LICENSES: + print(f"ERROR: Invalid license. Must be one of: {', '.join(VALID_LICENSES)}", file=sys.stderr) + return None + + # Validate category + if args.category not in VALID_CATEGORIES: + print(f"ERROR: Invalid category. Must be one of: {', '.join(VALID_CATEGORIES)}", file=sys.stderr) + return None + + # Parse author + author = parse_author(args.author) + + # Generate or use provided keywords + if args.keywords: + keywords = [k.strip() for k in args.keywords.split(',')] + else: + keywords = generate_keywords(args.name, args.description, args.category) + + # Build metadata object + metadata = { + "name": args.name, + "version": args.version, + "description": args.description, + "author": author, + "license": args.license + } + + # Add optional fields if provided + if args.repository: + metadata["repository"] = { + "type": "git", + "url": args.repository + } + elif args.github_username: + metadata["repository"] = { + "type": "git", + "url": f"https://github.com/{args.github_username}/{args.name}" + } + metadata["homepage"] = f"https://github.com/{args.github_username}/{args.name}" + + if args.homepage: + metadata["homepage"] = args.homepage + + if keywords: + metadata["keywords"] = keywords + + if args.category: + metadata["category"] = args.category + + return metadata + +def main(): + parser = argparse.ArgumentParser( + description='Generate plugin.json metadata', + formatter_class=argparse.RawDescriptionHelpFormatter + ) + + # Required arguments + parser.add_argument('--name', required=True, help='Plugin name (lowercase-hyphen)') + parser.add_argument('--author', required=True, help='Author name or "Name "') + parser.add_argument('--description', required=True, help='Plugin description (50-200 chars)') + parser.add_argument('--license', required=True, help='License type (MIT, Apache-2.0, etc.)') + + # Optional arguments + parser.add_argument('--version', default='1.0.0', help='Initial version (default: 1.0.0)') + parser.add_argument('--category', default='development', help='Plugin category') + parser.add_argument('--keywords', help='Comma-separated keywords') + parser.add_argument('--repository', help='Repository URL') + parser.add_argument('--homepage', help='Homepage URL') + parser.add_argument('--github-username', help='GitHub username (auto-generates repo URL)') + parser.add_argument('--output', help='Output file path (default: stdout)') + parser.add_argument('--pretty', action='store_true', help='Pretty-print JSON') + + args = parser.parse_args() + + # Generate metadata + metadata = generate_metadata(args) + if metadata is None: + return 1 + + # Format JSON + if args.pretty: + json_output = json.dumps(metadata, indent=2, ensure_ascii=False) + else: + json_output = json.dumps(metadata, ensure_ascii=False) + + # Output + if args.output: + try: + with open(args.output, 'w', encoding='utf-8') as f: + f.write(json_output) + print(f"✅ Metadata written to {args.output}", file=sys.stderr) + except IOError as e: + print(f"ERROR: Could not write to {args.output}: {e}", file=sys.stderr) + return 1 + else: + print(json_output) + + return 0 + +if __name__ == '__main__': + sys.exit(main()) diff --git a/commands/plugin-scaffold/.scripts/validate-name.sh b/commands/plugin-scaffold/.scripts/validate-name.sh new file mode 100755 index 0000000..ceb473c --- /dev/null +++ b/commands/plugin-scaffold/.scripts/validate-name.sh @@ -0,0 +1,91 @@ +#!/bin/bash +# Script: validate-name.sh +# Purpose: Validate plugin name follows Claude Code conventions +# Version: 1.0.0 +# Last Modified: 2025-10-13 +# +# Usage: +# ./validate-name.sh +# +# Arguments: +# plugin-name: Name to validate +# +# Returns: +# 0 - Valid name +# 1 - Invalid name format +# 2 - Missing argument +# +# Dependencies: +# - grep (for regex matching) + +# Check for argument +if [ $# -eq 0 ]; then + echo "ERROR: Plugin name required" + echo "Usage: $0 " + exit 2 +fi + +PLUGIN_NAME="$1" + +# Validation pattern: lowercase letters, numbers, hyphens +# Must start with letter, cannot end with hyphen +VALID_PATTERN='^[a-z][a-z0-9-]*[a-z0-9]$|^[a-z]$' + +# Check pattern match +if echo "$PLUGIN_NAME" | grep -Eq "$VALID_PATTERN"; then + # Additional checks + + # Check for consecutive hyphens + if echo "$PLUGIN_NAME" | grep -q '\-\-'; then + echo "ERROR: Plugin name cannot contain consecutive hyphens" + echo "Invalid: $PLUGIN_NAME" + echo "Try: $(echo "$PLUGIN_NAME" | sed 's/--/-/g')" + exit 1 + fi + + # Check length (reasonable limit) + NAME_LENGTH=${#PLUGIN_NAME} + if [ $NAME_LENGTH -gt 50 ]; then + echo "ERROR: Plugin name too long ($NAME_LENGTH characters, max 50)" + echo "Consider a shorter name" + exit 1 + fi + + if [ $NAME_LENGTH -lt 3 ]; then + echo "ERROR: Plugin name too short ($NAME_LENGTH characters, min 3)" + echo "Use a more descriptive name" + exit 1 + fi + + # Check for common mistakes + if echo "$PLUGIN_NAME" | grep -iq 'plugin$'; then + echo "WARNING: Plugin name ends with 'plugin' - this is redundant" + echo "Consider: $(echo "$PLUGIN_NAME" | sed 's/-plugin$//' | sed 's/plugin$//')" + fi + + # Success + echo "✅ Valid plugin name: $PLUGIN_NAME" + exit 0 +else + # Invalid format + echo "ERROR: Invalid plugin name format: $PLUGIN_NAME" + echo "" + echo "Plugin names must:" + echo " - Start with a lowercase letter" + echo " - Contain only lowercase letters, numbers, and hyphens" + echo " - Not end with a hyphen" + echo " - Be between 3-50 characters" + echo "" + echo "Valid examples:" + echo " - code-formatter" + echo " - test-generator" + echo " - deploy-automation" + echo "" + echo "Invalid examples:" + echo " - CodeFormatter (uppercase)" + echo " - test_generator (underscores)" + echo " - -my-plugin (starts with hyphen)" + echo " - plugin- (ends with hyphen)" + + exit 1 +fi diff --git a/commands/plugin-scaffold/complete-scaffold.md b/commands/plugin-scaffold/complete-scaffold.md new file mode 100644 index 0000000..9da933c --- /dev/null +++ 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 " +- 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 " license:Apache-2.0 description:"Automated code review with security analysis" with_agent:true category:quality +``` + +**Output**: Plugin structure including agent template + +**Request**: $ARGUMENTS diff --git a/commands/plugin-scaffold/skill.md b/commands/plugin-scaffold/skill.md new file mode 100644 index 0000000..ab96d98 --- /dev/null +++ b/commands/plugin-scaffold/skill.md @@ -0,0 +1,58 @@ +--- +description: Generate complete plugin directory structures with all necessary files and proper scaffolding +--- + +# Plugin Scaffold Skill + +Expert plugin structure generation with complete directory scaffolding, metadata creation, and file templates. + +## Operations + +- **create** - Generate complete plugin directory structure +- **manifest** - Create or update plugin.json with validation +- **readme** - Generate comprehensive README template +- **license** - Add LICENSE file with selected license type +- **complete** - All-in-one: create full plugin structure with all files + +## Usage Examples + +```bash +# Generate complete structure +/plugin-scaffold create name:my-plugin author:"John Doe" + +# Create plugin.json +/plugin-scaffold manifest name:my-plugin version:1.0.0 description:"Plugin description" license:MIT + +# Generate README +/plugin-scaffold readme name:my-plugin description:"Full description" + +# Add license +/plugin-scaffold license type:MIT plugin:my-plugin + +# All-in-one scaffolding +/plugin-scaffold complete name:my-plugin author:"John Doe" license:MIT description:"Complete plugin" +``` + +## Router Logic + +Parse the first word of $ARGUMENTS to determine the requested operation: + +1. Extract operation from first word of $ARGUMENTS +2. Parse remaining arguments as key:value parameters +3. Route to appropriate operation file: + - "create" → Read and execute `{plugin-path}/commands/plugin-scaffold/create-structure.md` + - "manifest" → Read and execute `{plugin-path}/commands/plugin-scaffold/generate-manifest.md` + - "readme" → Read and execute `{plugin-path}/commands/plugin-scaffold/create-readme.md` + - "license" → Read and execute `{plugin-path}/commands/plugin-scaffold/add-license.md` + - "complete" → Read and execute `{plugin-path}/commands/plugin-scaffold/complete-scaffold.md` + +**Error Handling**: +- If operation unknown → List available operations with usage +- If required parameters missing → Request with expected format +- If plugin name invalid → Suggest valid naming pattern (lowercase-hyphen) +- If directory exists → Warn and ask for confirmation to overwrite + +**Base directory**: Plugin commands directory +**Current request**: $ARGUMENTS + +Parse operation and route to appropriate instruction file now. diff --git a/commands/plugin-test/skill.md b/commands/plugin-test/skill.md new file mode 100644 index 0000000..8747ba3 --- /dev/null +++ b/commands/plugin-test/skill.md @@ -0,0 +1,40 @@ +--- +description: Create test marketplaces and guide local plugin testing workflows +--- + +# Plugin Testing Skill + +Expert plugin testing guidance with test marketplace creation and validation workflows. + +## Operations + +- **create-marketplace** - Generate test marketplace structure for local testing +- **install** - Guide local plugin installation process +- **validate-install** - Verify plugin installed correctly +- **test-commands** - Test plugin commands and verify functionality + +## Usage Examples + +```bash +# Create test marketplace +/plugin-test create-marketplace name:test-market plugin:my-plugin + +# Install locally +/plugin-test install plugin:my-plugin@test-market + +# Validate installation +/plugin-test validate-install plugin:my-plugin + +# Test commands +/plugin-test test-commands plugin:my-plugin +``` + +## Router Logic + +Parse operation from $ARGUMENTS and route to appropriate instruction file: +- "create-marketplace" → `{plugin-path}/commands/plugin-test/create-test-marketplace.md` +- "install" → `{plugin-path}/commands/plugin-test/install-locally.md` +- "validate-install" → `{plugin-path}/commands/plugin-test/validate-installation.md` +- "test-commands" → `{plugin-path}/commands/plugin-test/test-commands.md` + +**Current request**: $ARGUMENTS diff --git a/commands/quickstart-plugin.md b/commands/quickstart-plugin.md new file mode 100644 index 0000000..a58e6c7 --- /dev/null +++ b/commands/quickstart-plugin.md @@ -0,0 +1,996 @@ +--- +description: Generate production-ready Claude Code plugin structures for OpenPlugins marketplace +argument-hint: [category] +allowed-tools: Bash(mkdir:*), Bash(git:*), Write, Read, Grep +--- + +# Plugin Quickstart Generator + +Generate a complete, production-ready Claude Code plugin structure following OpenPlugins marketplace standards. + +## Mission + +Create a fully-structured plugin with all required files, metadata, documentation, and templates that meets OpenPlugins quality standards and is ready for local testing and marketplace submission. + +## Arguments + +- **$1 (plugin-name)**: Required. Plugin name in lowercase-hyphen format (e.g., `code-formatter`) +- **$2 (category)**: Optional. One of: development, testing, deployment, documentation, security, database, monitoring, productivity, quality, collaboration + +## Process + +### 1. Validate Plugin Name + +**CRITICAL**: Plugin name MUST be in lowercase-hyphen format (e.g., `my-plugin-name`). + +If the plugin name contains uppercase letters, underscores, spaces, or other invalid characters, STOP and provide clear error message with examples of valid names. + +Valid format: `^[a-z][a-z0-9-]*[a-z0-9]$` + +Examples: +- ✅ Valid: `code-formatter`, `test-runner`, `deploy-tool`, `my-plugin` +- ❌ Invalid: `Code-Formatter`, `test_runner`, `Deploy Tool`, `My Plugin`, `plugin-` + +### 2. Interactive Metadata Collection + +Gather the following information from the user: + +**Description** (Required, 50-200 characters): +- Prompt: "Enter a brief description of your plugin (50-200 characters):" +- Validate length and provide feedback +- Ensure it's informative and specific (not generic like "A useful plugin") + +**Author Information**: +- Name (Default: from `git config user.name` or prompt) +- Email (Default: from `git config user.email` or prompt) +- URL (Optional: GitHub profile or website) + +**License** (Default: MIT): +- Show options: MIT, Apache-2.0, GPL-3.0, BSD-3-Clause +- Prompt: "Choose license (default: MIT):" +- Validate against list + +**Category** (Use $2 if provided, otherwise prompt): +- Show all 10 categories: + - development: Code generation, scaffolding, refactoring + - testing: Test generation, coverage, quality assurance + - deployment: CI/CD, infrastructure, release automation + - documentation: Docs generation, API documentation + - security: Vulnerability scanning, secret detection + - database: Schema design, migrations, queries + - monitoring: Performance analysis, logging + - productivity: Workflow automation, task management + - quality: Linting, formatting, code review + - collaboration: Team tools, communication +- Prompt: "Choose category:" +- Validate selection + +**Keywords** (3-7 keywords, comma-separated): +- Prompt: "Enter 3-7 relevant keywords (comma-separated):" +- Examples: testing, automation, python, docker, ci-cd +- Validate count (3-7 keywords) +- Avoid generic terms: plugin, tool, utility + +**Agent Option**: +- Prompt: "Include a specialist agent? (y/n, default: n):" +- If yes, prompt for agent capabilities (comma-separated) + +### 3. Generate Plugin Structure + +Create the following directory structure in the current working directory: + +``` +/ +├── plugin.json # At plugin root +├── commands/ +│ └── example.md +├── agents/ # Only if user requested agent +│ └── example-agent.md +├── README.md +├── LICENSE +├── CHANGELOG.md +└── .gitignore +``` + +### 4. Generate plugin.json + +Create `plugin.json` at the plugin root with complete metadata: + +```json +{ + "name": "", + "version": "1.0.0", + "description": "", + "author": { + "name": "", + "email": "" + // Include "url" field if user provided it + }, + "license": "", + "repository": { + "type": "git", + "url": "https://github.com//" + }, + "homepage": "https://github.com//", + "keywords": [ + // User-provided keywords as array + ] +} +``` + +**Important**: +- Try to infer GitHub username from git config or author URL +- If not available, use placeholder: "yourusername" +- Ensure valid JSON with proper escaping + +### 5. Generate Example Command + +Create `commands/example.md`: + +```markdown +--- +description: Example command for +--- + +# Example Command + +This is a template command for your plugin. Replace this with your actual functionality. + +## Usage + +```bash +/example [arguments] +``` + +## Implementation + +**TODO**: Add your command logic here. + +### Example Implementation Steps + +1. Parse the arguments from $ARGUMENTS +2. Validate inputs +3. Execute core functionality +4. Provide clear output with results +5. Handle errors gracefully + +### Accessing Arguments + +- **All arguments**: `$ARGUMENTS` +- **First argument**: `$1` +- **Second argument**: `$2` +- And so on... + +### Using Tools + +If your command needs specific tools, add them to frontmatter: + +```yaml +--- +description: Example command +allowed-tools: Bash(npm:*), Read, Write +--- +``` + +### Best Practices + +- Be specific in your description +- Validate user inputs +- Provide helpful error messages +- Include usage examples +- Document expected behavior + +## Error Handling + +Handle common error cases: +- Missing required arguments +- Invalid input formats +- File not found +- Permission issues +- External command failures + +Provide clear, actionable error messages. + +## Output Format + +Define what users should expect: +- Success messages +- Error messages +- Data format (JSON, text, tables) +- Next steps or recommendations +``` + +### 6. Generate Agent (If Requested) + +If user requested an agent, create `agents/example-agent.md`: + +```markdown +--- +name: +description: Expert specialist for . Use proactively when . +capabilities: [] +tools: Read, Write, Bash, Grep, Glob +model: inherit +--- + +# Agent + +You are a specialized agent for . + +## Role and Expertise + +**Primary Capabilities**: + +- ****: + + +## When to Invoke + +This agent should be used proactively when: +1. +2. +3. + +Users can also invoke explicitly with: "Use the agent to..." + +## Approach and Methodology + +When invoked, follow this process: + +### 1. Analysis Phase +- Understand the user's request and context +- Identify relevant files and components +- Assess scope and complexity + +### 2. Planning Phase +- Determine optimal approach +- Identify potential issues +- Plan step-by-step execution + +### 3. Execution Phase +- Implement solution systematically +- Validate each step +- Handle errors gracefully + +### 4. Verification Phase +- Test the results +- Verify completeness +- Provide clear summary + +## Best Practices + +- **Be Proactive**: Start working immediately when conditions match +- **Be Thorough**: Don't skip steps or make assumptions +- **Be Clear**: Explain what you're doing and why +- **Be Efficient**: Use appropriate tools for each task +- **Be Helpful**: Provide context and recommendations + +## Tools Usage + +- **Read**: For examining file contents +- **Write**: For creating new files +- **Edit**: For modifying existing files +- **Bash**: For executing commands and scripts +- **Grep**: For searching patterns in files +- **Glob**: For finding files by pattern + +## Error Handling + +When encountering errors: +1. Identify the root cause +2. Explain the issue clearly +3. Provide specific solutions +4. Offer alternatives if needed + +## Output Format + +Always provide: +- Clear summary of actions taken +- Results or outcomes +- Next steps or recommendations +- Any warnings or considerations +``` + +### 7. Generate Comprehensive README.md + +Create `README.md` with all required sections: + +```markdown +# + + + +## Overview + + + +## Installation + +### From OpenPlugins Marketplace + +```bash +/plugin marketplace add dhofheinz/open-plugins +/plugin install @open-plugins +``` + +### From GitHub + +```bash +/plugin marketplace add github:/ +/plugin install @ +``` + +### From Local Directory + +```bash +# For development and testing +/plugin marketplace add ./-test-marketplace +/plugin install @-test +``` + +## Usage + +### Commands + + +#### / + + + +**Syntax**: `/ [arguments]` + +**Example**: +```bash +/ arg1 arg2 +``` + +**Options**: +- `arg1`: Description of first argument +- `arg2`: Description of second argument + + + +### Agent + +This plugin includes the `` agent for specialized assistance. + +**Invocation**: The agent is automatically invoked when , or you can invoke explicitly: + +``` +Use the agent to +``` + +**Capabilities**: + + + +## Examples + +### Example 1: + +```bash +/ example-input +``` + +**Output**: +``` +Expected output example +``` + +### Example 2: + +```bash +/ --option value +``` + +## Configuration + + +This plugin supports configuration via: +- Plugin-specific settings +- Environment variables +- Configuration files + + + +This plugin requires no additional configuration. It works out of the box. + + +## Troubleshooting + +### Common Issues + +#### Issue: + +**Symptoms**: + +**Solution**: + +#### Issue: Command not found + +**Symptoms**: `/command` returns "command not found" + +**Solution**: +1. Verify plugin is installed: `/plugin list` +2. Check plugin is enabled: `/plugin info ` +3. Restart Claude Code to reload plugins + +#### Issue: Permission denied + +**Symptoms**: Operations fail with permission errors + +**Solution**: +1. Check file permissions +2. Verify plugin has necessary tool access +3. Review `allowed-tools` in command frontmatter + +## Development + +### Local Testing + +1. Create test marketplace structure: +```bash +mkdir -p -test-marketplace/.claude-plugin +``` + +2. Create test marketplace.json: +```json +{ + "name": "-test", + "owner": {"name": "Test User"}, + "plugins": [{ + "name": "", + "source": "./", + "description": "" + }] +} +``` + +3. Test installation: +```bash +/plugin marketplace add ./-test-marketplace +/plugin install @-test +``` + +4. Verify functionality: +```bash +/ test-args +``` + +### Contributing + +Contributions are welcome! To contribute: + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test thoroughly +5. Submit a pull request + +Please follow the [OpenPlugins Contributing Guide](https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md). + +## Changelog + +See [CHANGELOG.md](CHANGELOG.md) for version history. + +## License + + - see [LICENSE](LICENSE) file for details. + +## Resources + +- [Claude Code Plugin Documentation](https://docs.claude.com/en/docs/claude-code/plugins) +- [OpenPlugins Marketplace](https://github.com/dhofheinz/open-plugins) +- [Plugin Development Guide](https://docs.claude.com/en/docs/claude-code/plugins/plugins-reference) + +## Support + +- **Issues**: [GitHub Issues](https://github.com///issues) +- **Discussions**: [OpenPlugins Discussions](https://github.com/dhofheinz/open-plugins/discussions) +- **Documentation**: [Plugin README](README.md) + +--- + +**Made for [OpenPlugins](https://github.com/dhofheinz/open-plugins)** - Fostering a vibrant ecosystem of Claude Code plugins +``` + +### 8. Generate CHANGELOG.md + +Create `CHANGELOG.md`: + +```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] - + +### Added +- Initial release +- Core functionality for + +- Command: / - + + +- Agent: - Specialized assistant for + +- Comprehensive documentation +- Usage examples +- MIT License + +### Documentation +- README with installation and usage guide +- Example commands and configurations +- Troubleshooting section + +### Quality +- Follows OpenPlugins standards +- Complete metadata in plugin.json +- No hardcoded secrets +- Input validation +``` + +### 9. Generate LICENSE File + +Based on selected license, generate appropriate LICENSE file: + +**MIT License** (default): +``` +MIT License + +Copyright (c) + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. +``` + +**Apache-2.0**: Use standard Apache 2.0 license text +**GPL-3.0**: Use standard GPL 3.0 license text +**BSD-3-Clause**: Use standard BSD 3-Clause license text + +### 10. Generate .gitignore + +Create `.gitignore`: + +``` +# Node modules (if using MCP servers) +node_modules/ +package-lock.json + +# Python (if using Python scripts) +__pycache__/ +*.py[cod] +*$py.class +venv/ +.env + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# OS +.DS_Store +Thumbs.db + +# Test artifacts +test-marketplace/ +*.test.md +.tmp/ + +# Secrets +*.key +*.pem +.env.local +secrets.json +credentials.json + +# Build artifacts +dist/ +build/ +*.log +``` + +### 11. Generate Test Marketplace + +Create test marketplace structure: + +``` +-test-marketplace/ +├── .claude-plugin/ +│ └── marketplace.json +``` + +marketplace.json content: +```json +{ + "name": "-test", + "owner": { + "name": "", + "email": "" + }, + "description": "Test marketplace for development", + "plugins": [ + { + "name": "", + "version": "1.0.0", + "description": "", + "author": { + "name": "", + "email": "" + }, + "source": "../", + "license": "", + "keywords": [], + "category": "" + } + ] +} +``` + +### 12. Validation + +After generation, validate: + +1. **JSON Syntax**: Verify plugin.json and marketplace.json are valid JSON +2. **Required Fields**: Ensure all required fields present in plugin.json +3. **File Existence**: Verify all expected files were created +4. **Name Format**: Confirm plugin name is lowercase-hyphen +5. **Category**: Validate category is one of 10 standard categories +6. **Version Format**: Confirm version follows semver (1.0.0) + +If any validation fails, report the issue clearly and suggest fixes. + +### 13. Output Comprehensive Instructions + +Provide detailed next steps: + +``` +✅ Plugin "" generated successfully! + +📁 Plugin Location: .// +📁 Test Marketplace: ./-test-marketplace/ + +📦 Generated Files: + ✅ plugin.json - Complete metadata at plugin root + ✅ commands/example.md - Template command + ✅ agents/example-agent.md - Specialized agent + ✅ README.md - Comprehensive documentation + ✅ LICENSE - license + ✅ CHANGELOG.md - Version history + ✅ .gitignore - Standard exclusions + ✅ Test marketplace structure + +📋 Next Steps: + +1. 📝 Review Generated Files + - Examine plugin.json metadata + - Review command templates + - Check agent configuration + - Read through README + +2. 💻 Implement Plugin Logic + - Edit commands/example.md with actual functionality + - Add more commands in commands/ directory as needed + - Customize agents/example-agent.md system prompt + - Add hooks in hooks/hooks.json if needed (optional) + - Configure MCP servers in .mcp.json if needed (optional) + +3. 📖 Update Documentation + - Replace README placeholders with actual information + - Add real usage examples + - Document all command options + - Update troubleshooting section with known issues + +4. 🧪 Test Locally + cd -test-marketplace + + # Add test marketplace + /plugin marketplace add . + + # Install plugin + /plugin install @-test + + # Test commands + / test-args + + # Verify agent invocation (if applicable) + "Use the agent to test functionality" + +5. ✅ Validate Quality + - Test all commands work correctly + - Verify error handling is robust + - Check documentation is complete and accurate + - Ensure no hardcoded secrets + - Test on different scenarios + +6. 📤 Prepare for Distribution + + A. Initialize Git Repository: + cd + git init + git add . + git commit -m "feat: initial plugin implementation" + git branch -M main + + B. Create GitHub Repository: + gh repo create --public --source=. --remote=origin + git push -u origin main + + C. Tag Version: + git tag v1.0.0 + git push origin v1.0.0 + +7. 🚀 Submit to OpenPlugins Marketplace + + A. Fork OpenPlugins Repository: + gh repo fork dhofheinz/open-plugins --clone + cd open-plugins + + B. Add Your Plugin Entry: + Edit .claude-plugin/marketplace.json + Add your plugin to the "plugins" array: + + { + "name": "", + "version": "1.0.0", + "description": "", + "author": { + "name": "", + "email": "", + "url": "" + }, + "source": "github:/", + "license": "", + "keywords": [], + "category": "", + "homepage": "https://github.com//", + "repository": { + "type": "git", + "url": "https://github.com//" + } + } + + C. Submit Pull Request: + git checkout -b add- + git add .claude-plugin/marketplace.json + git commit -m "feat: add to marketplace" + git push origin add- + gh pr create --title "Add plugin" --body "..." + +📚 Resources: + +- Plugin Documentation: https://docs.claude.com/en/docs/claude-code/plugins +- OpenPlugins Marketplace: https://github.com/dhofheinz/open-plugins +- Contributing Guide: https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md +- Keep a Changelog: https://keepachangelog.com/ +- Semantic Versioning: https://semver.org/ + +💡 Pro Tips: + +- Start simple: Implement core functionality first, add features iteratively +- Test early: Use test marketplace to catch issues before submission +- Document well: Clear documentation increases adoption +- Follow standards: Adherence to OpenPlugins guidelines speeds approval +- Engage community: Share in discussions, help others, contribute back + +🎯 Quality Checklist: + +Before submitting to OpenPlugins, ensure: +- [ ] Plugin installs without errors +- [ ] All commands execute correctly +- [ ] Agent invokes properly (if applicable) +- [ ] README has real examples (not placeholders) +- [ ] No hardcoded secrets or credentials +- [ ] Error messages are helpful +- [ ] Documentation is complete +- [ ] Tested in multiple scenarios +- [ ] Git repository is public +- [ ] Version is tagged + +❓ Need Help? + +- Report issues: https://github.com/dhofheinz/open-plugins/issues +- Ask questions: https://github.com/dhofheinz/open-plugins/discussions +- Plugin docs: https://docs.claude.com/en/docs/claude-code/plugins/plugins-reference + +--- + +🎉 Happy plugin development! Your contribution helps grow the Claude Code ecosystem. +``` + +## Error Handling + +### Invalid Plugin Name + +If plugin name doesn't match `^[a-z][a-z0-9-]*[a-z0-9]$`: + +``` +❌ Error: Invalid plugin name "" + +Plugin names must: +- Start with a lowercase letter +- Contain only lowercase letters, numbers, and hyphens +- End with a lowercase letter or number +- Not contain consecutive hyphens +- Not start or end with a hyphen + +✅ Valid examples: + - code-formatter + - test-runner + - my-plugin + - plugin-v2 + +❌ Invalid examples: + - Code-Formatter (uppercase) + - test_runner (underscore) + - My Plugin (spaces) + - -plugin (starts with hyphen) + - plugin- (ends with hyphen) + +Please provide a valid plugin name and try again. +``` + +### Description Too Short/Long + +``` +❌ Error: Description must be between 50 and 200 characters. + +Current length: characters + +Your description: "" + +Tip: Be specific about what your plugin does. Avoid generic phrases. + +✅ Good examples: + - "Automate code formatting using Prettier with project-specific configurations" + - "Generate comprehensive test suites for Python functions with pytest integration" + +❌ Avoid: + - "A useful plugin" (too vague) + - "Plugin for stuff" (not descriptive) +``` + +### Invalid Category + +``` +❌ Error: Invalid category "" + +Valid categories: + 1. development - Code generation, scaffolding, refactoring + 2. testing - Test generation, coverage, quality assurance + 3. deployment - CI/CD, infrastructure, release automation + 4. documentation - Docs generation, API documentation + 5. security - Vulnerability scanning, secret detection + 6. database - Schema design, migrations, queries + 7. monitoring - Performance analysis, logging + 8. productivity - Workflow automation, task management + 9. quality - Linting, formatting, code review + 10. collaboration - Team tools, communication + +Please choose a category number (1-10) or name. +``` + +### Insufficient Keywords + +``` +❌ Error: Please provide 3-7 keywords (you provided ) + +Keywords help users discover your plugin in the marketplace. + +Guidelines: +- Use 3-7 keywords +- Focus on functionality, technology, and use cases +- Avoid generic terms (plugin, tool, utility) +- Use lowercase, comma-separated + +Examples: + ✅ "testing, automation, python, pytest, ci-cd" + ✅ "linting, javascript, eslint, code-quality" + ❌ "plugin, tool, awesome" (too generic) + ❌ "test" (insufficient) +``` + +### File Creation Failures + +If directory creation or file writing fails: + +``` +❌ Error: Failed to create + +Reason: + +Possible causes: +- Insufficient permissions +- Directory already exists +- Disk space full +- Invalid path + +Solutions: +1. Check directory permissions: ls -la +2. Verify disk space: df -h +3. Try a different location +4. Remove existing directory if safe: rm -rf + +Need help? Check the troubleshooting guide: +https://github.com/dhofheinz/open-plugins/blob/main/CONTRIBUTING.md +``` + +### JSON Validation Failures + +If generated JSON is invalid: + +``` +❌ Error: Generated plugin.json has invalid syntax + +Location: + +Issue: + +This is likely a bug in the generator. Please: +1. Report this issue: https://github.com/dhofheinz/open-plugins/issues +2. Manually fix the JSON syntax +3. Validate with: cat plugin.json | python3 -m json.tool + +We'll fix this in the next update! +``` + +## Implementation Notes + +1. **Interactive Prompts**: Use natural language to collect user input +2. **Defaults**: Provide sensible defaults from git config when available +3. **Validation**: Validate all inputs before generating files +4. **Error Recovery**: If generation partially fails, report which files succeeded +5. **Idempotency**: Warn if plugin directory already exists, offer to overwrite +6. **Current Date**: Use actual current date for CHANGELOG.md and LICENSE +7. **Git Config**: Try to read author info from git config for better UX +8. **Relative Paths**: Generate all paths relative to current working directory +9. **Cross-Platform**: Ensure generated files work on Linux, macOS, and Windows +10. **Character Escaping**: Properly escape special characters in JSON strings + +## Success Output + +After successful generation, output should: +- Clearly indicate success with visual markers (✅, 📁, 📋, etc.) +- List all generated files with brief descriptions +- Provide numbered, sequential next steps +- Include both local testing AND marketplace submission workflows +- Reference relevant documentation +- Offer pro tips for success +- Include a quality checklist +- Provide links to get help + +## Best Practices + +1. **User Experience**: Make the process feel guided and supportive +2. **Error Messages**: Always explain WHY something failed and HOW to fix it +3. **Examples**: Provide concrete examples in all prompts +4. **Validation**: Catch errors early before generating files +5. **Documentation**: Generate comprehensive, helpful documentation +6. **Standards Compliance**: Ensure all generated files meet OpenPlugins standards +7. **Testing Support**: Make local testing easy with test marketplace +8. **Community Integration**: Guide users to OpenPlugins resources and community + +--- + +**Remember**: This plugin generates the FIRST plugin for OpenPlugins marketplace. Quality and attention to detail are critical for setting the right standard for the entire ecosystem. diff --git a/plugin.lock.json b/plugin.lock.json new file mode 100644 index 0000000..b02b726 --- /dev/null +++ b/plugin.lock.json @@ -0,0 +1,109 @@ +{ + "$schema": "internal://schemas/plugin.lock.v1.json", + "pluginId": "gh:dhofheinz/open-plugins:plugins/plugin-quickstart-generator", + "normalized": { + "repo": null, + "ref": "refs/tags/v20251128.0", + "commit": "e033dfe64c2928c92718faf78e6e2d00c9fef899", + "treeHash": "75d031b0041d6defe104f6cc49aef8efcfb38abc92f4ca5d6bb4116260a46693", + "generatedAt": "2025-11-28T10:16:23.586139Z", + "toolVersion": "publish_plugins.py@0.2.0" + }, + "origin": { + "remote": "git@github.com:zhongweili/42plugin-data.git", + "branch": "master", + "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390", + "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data" + }, + "manifest": { + "name": "plugin-quickstart-generator", + "description": "Generate production-ready Claude Code plugin structures for OpenPlugins marketplace with guided interactive setup", + "version": "1.0.0" + }, + "content": { + "files": [ + { + "path": "README.md", + "sha256": "0a0aeba784d8d2d1c41341ed32827c1a777f5d8a6477055681df48c5c91813a1" + }, + { + "path": "agents/plugin-generator.md", + "sha256": "c7d551cc4a4c4eebd05319cf62e65df23dd26772c7c09808ca884be682c08ed7" + }, + { + "path": ".claude-plugin/plugin.json", + "sha256": "7682c53b0d175503a3076edcb1349ded29a6f62f938804f2492f9d5f8e2d8f75" + }, + { + "path": "commands/quickstart-plugin.md", + "sha256": "91b02f4dcdbe98bc8a608657751eb925b0b1b12411f1ccc147934fc07bd5c151" + }, + { + "path": "commands/plugin-design/select-components.md", + "sha256": "b0290ce24e045e096a107b3c5f0e82b7026fac16b2303706bf65677d18d6f0cf" + }, + { + "path": "commands/plugin-design/estimate-complexity.md", + "sha256": "53b4fd74e1ef2f15f834b500c0a70b4b307350ec5d176fb3c722eee8cc8f4592" + }, + { + "path": "commands/plugin-design/skill.md", + "sha256": "3ef05ec30ce6b8675446104534101cbdddd102099909151e55364fc2db5ec225" + }, + { + "path": "commands/plugin-design/analyze-requirements.md", + "sha256": "c4abb69ff558d81130c365972b35a5d939070fc0e233b4ce8d8a314287033fbc" + }, + { + "path": "commands/plugin-design/recommend-patterns.md", + "sha256": "402ff7c9df8e63702613bdfb021a78bf96a87fc6582936e33c84ad29f990d182" + }, + { + "path": "commands/plugin-metadata/skill.md", + "sha256": "c6db2a773697317296823100891744923761d702c37d206695c89e5bab26fe80" + }, + { + "path": "commands/plugin-metadata/.scripts/validate-semver.sh", + "sha256": "805c12857a70eecdfec5622a23b511cab6de033bb5ad094ddf7fdf5248651844" + }, + { + "path": "commands/plugin-quality/skill.md", + "sha256": "cbaa5bbbf393b06a0519412c7d380323a8d05ad9bd9238f591791bd0538f035c" + }, + { + "path": "commands/plugin-quality/full-audit.md", + "sha256": "8c205ee4243d2f4cfa02c7ab921e78e50f595b6349c7f16ffb29092d1baed0aa" + }, + { + "path": "commands/plugin-quality/.scripts/secret-scanner.sh", + "sha256": "576a2ad1cd2451986bf3a4ea2ab612ddc8b708f33e01554b4c45f84b3ff6ab6e" + }, + { + "path": "commands/plugin-scaffold/skill.md", + "sha256": "fc7ae3ea4afe6560eff824520eba39da1386c2141a2ca54ce2f66c59da0522c9" + }, + { + "path": "commands/plugin-scaffold/complete-scaffold.md", + "sha256": "d7c2b4a0f4e33def6c360bcfe5b6581fcf34b8b58c43943fe3bafdd46ef76421" + }, + { + "path": "commands/plugin-scaffold/.scripts/validate-name.sh", + "sha256": "f1a65d10e0efd9c7c67e4a12797e78e6dde4d4095bd344668e2ffecd58d0390d" + }, + { + "path": "commands/plugin-scaffold/.scripts/generate-metadata.py", + "sha256": "f5840cc6ce9e4cdb1f7071d60d448ce8476d13395bc9de9c218957a4bebe004a" + }, + { + "path": "commands/plugin-test/skill.md", + "sha256": "c94dfd6c1e34c5c6d3bf3af2436826f17931443d7221b17e82390ddcd3e71bcd" + } + ], + "dirSha256": "75d031b0041d6defe104f6cc49aef8efcfb38abc92f4ca5d6bb4116260a46693" + }, + "security": { + "scannedAt": null, + "scannerVersion": null, + "flags": [] + } +} \ No newline at end of file