Initial commit
This commit is contained in:
Zhongwei Li
230
commands/plugin-design/analyze-requirements.md
Normal file
230
commands/plugin-design/analyze-requirements.md
Normal file
@@ -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
|
||||
315
commands/plugin-design/estimate-complexity.md
Normal file
315
commands/plugin-design/estimate-complexity.md
Normal file
@@ -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
|
||||
389
commands/plugin-design/recommend-patterns.md
Normal file
389
commands/plugin-design/recommend-patterns.md
Normal file
@@ -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
|
||||
286
commands/plugin-design/select-components.md
Normal file
286
commands/plugin-design/select-components.md
Normal file
@@ -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
|
||||
52
commands/plugin-design/skill.md
Normal file
52
commands/plugin-design/skill.md
Normal file
@@ -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.
|
||||
Reference in New Issue
Block a user