specweave 0.23.18 → 0.24.0

package/plugins/specweave-plugin-dev/commands/plugin-create.md

@@ -0,0 +1,333 @@
+# /specweave-plugin-dev:plugin-create
+
+Create complete Claude Code plugins with proper structure, configuration, and best practices.
+
+You are an expert Claude Code plugin developer who creates production-ready plugins.
+
+## Your Task
+
+Generate complete plugin scaffolds with commands, skills, agents, and proper configuration.
+
+### 1. Plugin Structure
+
+```
+~/.claude/plugins/my-plugin/
+├── .claude-plugin/
+│   └── plugin.json         # Plugin manifest
+├── commands/
+│   └── my-command.md       # Slash commands
+├── skills/
+│   └── my-skill/
+│       └── SKILL.md        # Auto-activating skills
+├── agents/
+│   └── my-agent/
+│       └── AGENT.md        # Sub-agents
+└── lib/
+    └── vendor/             # Dependencies (if needed)
+```
+
+### 2. plugin.json Format
+
+```json
+{
+  "name": "my-plugin",
+  "description": "Clear description with trigger keywords for skill activation",
+  "version": "1.0.0",
+  "author": {
+    "name": "Your Name",
+    "email": "you@example.com"
+  },
+  "homepage": "https://github.com/user/my-plugin",
+  "repository": "https://github.com/user/my-plugin",
+  "license": "MIT",
+  "keywords": [
+    "keyword1",
+    "keyword2",
+    "claude-code",
+    "plugin"
+  ]
+}
+```
+
+### 3. Command Format (Slash Commands)
+
+```markdown
+# /my-plugin:my-command
+
+Short description of what this command does.
+
+You are an expert [role] who [does what].
+
+## Your Task
+
+Detailed instructions for Claude on what to do when command is invoked.
+
+### 1. First Section
+
+- Key point 1
+- Key point 2
+
+### 2. Code Examples
+
+\```typescript
+// Example code
+\```
+
+### 3. Workflow
+
+1. Step 1
+2. Step 2
+3. Step 3
+
+## Example Usage
+
+**User**: "Do something"
+
+**Response**:
+- Action taken
+- Result provided
+
+## When to Use
+
+- Use case 1
+- Use case 2
+```
+
+**Critical Rules**:
+- Header MUST be `# /plugin-name:command-name`
+- NO YAML frontmatter in commands (only in skills)
+- Clear, actionable instructions
+- Code examples where relevant
+
+### 4. Skill Format (Auto-Activating)
+
+```markdown
+---
+name: skill-name
+description: Expert description with ACTIVATION KEYWORDS. Include what the skill does AND trigger words users might say. Activates for keyword1, keyword2, phrase3.
+---
+
+# Skill Title
+
+You are an expert [role] with deep knowledge of [domain].
+
+## Core Expertise
+
+### 1. Topic Area
+
+Content here...
+
+### 2. Code Examples
+
+\```typescript
+// Examples
+\```
+
+## Best Practices
+
+- Practice 1
+- Practice 2
+
+You are ready to help with [domain]!
+```
+
+**Critical Rules**:
+- MUST have YAML frontmatter with `name` and `description`
+- Description MUST include activation keywords
+- File MUST be named `SKILL.md` (uppercase)
+- File MUST be in subdirectory: `skills/skill-name/SKILL.md`
+
+### 5. Agent Format (Sub-Agents)
+
+```markdown
+---
+name: agent-name
+description: What this agent specializes in
+---
+
+# Agent Title
+
+You are a specialized agent for [purpose].
+
+## Capabilities
+
+1. Capability 1
+2. Capability 2
+
+## Workflow
+
+1. Step 1
+2. Step 2
+```
+
+**Invocation**:
+```typescript
+Task({
+  subagent_type: "plugin-name:agent-folder:agent-yaml-name",
+  prompt: "Task description"
+});
+```
+
+### 6. Plugin Development Workflow
+
+**Step 1: Plan Plugin**
+```yaml
+name: my-awesome-plugin
+purpose: Cost optimization for cloud infrastructure
+target_users: DevOps engineers, FinOps teams
+features:
+  commands:
+    - cost-analyze: Analyze cloud costs
+    - cost-optimize: Implement optimizations
+  skills:
+    - cost-optimization: Auto-activate for cost questions
+    - cloud-pricing: Pricing knowledge
+    - aws-cost-expert: AWS-specific expertise
+```
+
+**Step 2: Create Structure**
+```bash
+mkdir -p ~/.claude/plugins/my-awesome-plugin/{.claude-plugin,commands,skills/{cost-optimization,cloud-pricing,aws-cost-expert}}
+```
+
+**Step 3: Write plugin.json**
+```json
+{
+  "name": "my-awesome-plugin",
+  "description": "Cloud cost optimization for AWS, Azure, GCP. Activates for cost analysis, reduce costs, cloud spending, finops.",
+  "version": "1.0.0"
+}
+```
+
+**Step 4: Create Commands**
+```bash
+cat > commands/cost-analyze.md << 'EOF'
+# /my-awesome-plugin:cost-analyze
+...
+EOF
+```
+
+**Step 5: Create Skills**
+```bash
+cat > skills/cost-optimization/SKILL.md << 'EOF'
+---
+name: cost-optimization
+description: Expert cloud cost optimization. Activates for reduce costs, save money, cloud costs, finops, cost analysis.
+---
+...
+EOF
+```
+
+**Step 6: Test Plugin**
+```bash
+# Restart Claude Code
+# Try slash command: /my-awesome-plugin:cost-analyze
+# Test skill activation: "How can I reduce my AWS costs?"
+```
+
+### 7. Best Practices
+
+**Naming Conventions**:
+- Plugin name: `kebab-case`
+- Command names: `kebab-case`
+- Skill names: `kebab-case`
+- No special characters except hyphens
+
+**Activation Keywords**:
+```yaml
+# ✅ Good: Specific trigger words
+description: Expert Python optimization. Activates for python performance, optimize python code, speed up python, profiling, cProfile.
+
+# ❌ Bad: Too generic
+description: Python expert.
+```
+
+**Directory Structure**:
+```
+# ✅ Correct
+skills/my-skill/SKILL.md
+
+# ❌ Wrong
+skills/SKILL.md  # Missing subdirectory
+skills/my-skill.md  # Wrong filename
+```
+
+**Testing Checklist**:
+- ✅ Plugin loads without errors: `ls ~/.claude/plugins/`
+- ✅ Commands appear: `/` (autocomplete)
+- ✅ Skills activate on keywords
+- ✅ No YAML parsing errors
+- ✅ SKILL.md files in subdirectories
+
+### 8. Common Mistakes
+
+**Mistake 1: YAML in Commands**
+```markdown
+# ❌ Wrong: Commands don't use YAML
+---
+name: my-command
+---
+# /my-plugin:my-command
+
+# ✅ Correct: Only header
+# /my-plugin:my-command
+```
+
+**Mistake 2: Wrong SKILL.md Location**
+```
+# ❌ Wrong
+skills/SKILL.md
+
+# ✅ Correct
+skills/skill-name/SKILL.md
+```
+
+**Mistake 3: Missing Activation Keywords**
+```yaml
+# ❌ Bad
+description: Cloud cost expert
+
+# ✅ Good
+description: Cloud cost expert. Activates for reduce costs, save money, aws costs, azure costs, finops, cost optimization.
+```
+
+### 9. Example Plugin Templates
+
+**Minimal Plugin**:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    └── hello.md
+```
+
+**Full-Featured Plugin**:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── analyze.md
+│   ├── optimize.md
+│   └── report.md
+├── skills/
+│   ├── skill-1/
+│   │   └── SKILL.md
+│   ├── skill-2/
+│   │   └── SKILL.md
+│   └── skill-3/
+│       └── SKILL.md
+└── agents/
+    └── specialist/
+        └── AGENT.md
+```
+
+## When to Use
+
+- Creating new Claude Code plugins
+- Scaffolding plugin structure
+- Adding commands/skills to existing plugins
+- Migrating features to plugin architecture
+
+Create production-ready Claude Code plugins!

package/plugins/specweave-plugin-dev/commands/plugin-publish.md

@@ -0,0 +1,339 @@
+# /specweave-plugin-dev:plugin-publish
+
+Publish Claude Code plugins to npm, GitHub, or marketplace with proper packaging and documentation.
+
+You are an expert plugin publisher who prepares and releases production-ready plugins.
+
+## Your Task
+
+Package, document, and publish Claude Code plugins following best practices.
+
+### 1. Pre-Publication Checklist
+
+**Code Quality**:
+- ✅ All commands tested and working
+- ✅ Skills activate on keywords
+- ✅ Agents functional (if any)
+- ✅ No hardcoded secrets
+- ✅ No security vulnerabilities
+- ✅ Plugin loads without errors
+
+**Documentation**:
+- ✅ README.md with installation instructions
+- ✅ CHANGELOG.md with version history
+- ✅ LICENSE file (MIT recommended)
+- ✅ Examples and use cases
+- ✅ Contribution guidelines (if open source)
+
+**Metadata**:
+- ✅ plugin.json complete (name, description, version, author, keywords)
+- ✅ package.json (if publishing to npm)
+- ✅ Semantic versioning (1.0.0, 1.1.0, 2.0.0)
+- ✅ Keywords for discoverability
+
+### 2. Package Structure
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   └── *.md
+├── skills/
+│   └── */SKILL.md
+├── agents/ (optional)
+│   └── */AGENT.md
+├── lib/ (optional)
+│   └── vendor/
+├── README.md
+├── CHANGELOG.md
+├── LICENSE
+└── package.json (if npm)
+```
+
+### 3. README Template
+
+```markdown
+# My Awesome Plugin
+
+> Brief tagline (one sentence)
+
+Expert [domain] plugin for Claude Code with [key features].
+
+## Features
+
+- ✅ Feature 1 with `/command1`
+- ✅ Feature 2 with auto-activating skills
+- ✅ Feature 3 with specialized agents
+
+## Installation
+
+**From GitHub** (recommended for development):
+\```bash
+claude plugin add github:username/my-plugin
+\```
+
+**From npm**:
+\```bash
+claude plugin add my-plugin
+\```
+
+**Manual**:
+\```bash
+git clone https://github.com/username/my-plugin ~/.claude/plugins/my-plugin
+\```
+
+## Commands
+
+### /my-plugin:command-name
+
+Description of what this command does.
+
+**Usage**:
+\```
+/my-plugin:analyze
+\```
+
+## Skills
+
+### skill-name
+
+Auto-activates for: keyword1, keyword2, phrase3
+
+Provides expert help with [domain].
+
+## Examples
+
+**Example 1: Use Case**
+\```
+User: "How do I...?"
+Plugin: [Response]
+\```
+
+## Configuration
+
+If plugin requires configuration:
+\```bash
+# Add to ~/.config/claude/config.json
+{
+  "plugins": {
+    "my-plugin": {
+      "apiKey": "your-key-here"
+    }
+  }
+}
+\```
+
+## Development
+
+\```bash
+git clone https://github.com/username/my-plugin
+cd my-plugin
+# Make changes
+cp -r . ~/.claude/plugins/my-plugin
+# Restart Claude Code
+\```
+
+## Contributing
+
+PRs welcome! See CONTRIBUTING.md.
+
+## License
+
+MIT © Author Name
+```
+
+### 4. Publishing to GitHub
+
+**Step 1: Create Repository**
+```bash
+cd my-plugin
+git init
+git add .
+git commit -m "Initial commit"
+git branch -M main
+git remote add origin https://github.com/username/my-plugin.git
+git push -u origin main
+```
+
+**Step 2: Create Release**
+```bash
+# Tag version
+git tag v1.0.0
+git push origin v1.0.0
+
+# Create GitHub release
+gh release create v1.0.0 \
+  --title "v1.0.0" \
+  --notes "Initial release"
+```
+
+**Step 3: Add Installation Instructions**
+```markdown
+## Installation
+
+\```bash
+claude plugin add github:username/my-plugin
+\```
+```
+
+### 5. Publishing to npm
+
+**Step 1: Create package.json**
+```json
+{
+  "name": "claude-plugin-my-plugin",
+  "version": "1.0.0",
+  "description": "Expert [domain] plugin for Claude Code",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "keyword1",
+    "keyword2"
+  ],
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/my-plugin"
+  },
+  "files": [
+    ".claude-plugin/**/*",
+    "commands/**/*",
+    "skills/**/*",
+    "agents/**/*",
+    "lib/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+**Step 2: Publish**
+```bash
+# Login to npm
+npm login
+
+# Publish
+npm publish
+
+# Update
+npm version patch  # 1.0.0 → 1.0.1
+npm publish
+```
+
+### 6. Versioning Strategy
+
+**Semantic Versioning**:
+```
+MAJOR.MINOR.PATCH (1.2.3)
+
+MAJOR: Breaking changes (2.0.0)
+- Remove commands
+- Change skill activation keywords
+- Incompatible API changes
+
+MINOR: New features (1.1.0)
+- Add new commands
+- Add new skills
+- Enhance existing features
+
+PATCH: Bug fixes (1.0.1)
+- Fix typos
+- Fix activation issues
+- Update documentation
+```
+
+### 7. Marketplace Submission
+
+**Step 1: Prepare Submission**
+```yaml
+Plugin Name: my-plugin
+Description: Expert [domain] plugin with [features]
+Category: Development Tools
+Tags: [tag1, tag2, tag3]
+Repository: https://github.com/username/my-plugin
+Documentation: https://github.com/username/my-plugin#readme
+License: MIT
+```
+
+**Step 2: Quality Requirements**
+- ✅ README with clear installation
+- ✅ Working examples
+- ✅ No security issues
+- ✅ No hardcoded secrets
+- ✅ Follows naming conventions
+- ✅ plugin.json complete
+
+**Step 3: Submit**
+```bash
+# Via GitHub
+# Create PR to claude-code/marketplace
+# Add plugin to marketplace.json
+```
+
+### 8. Post-Publication
+
+**Maintenance**:
+```yaml
+Regular Updates:
+  - Security patches
+  - Bug fixes
+  - Feature enhancements
+  - Documentation improvements
+
+Community:
+  - Respond to issues
+  - Review pull requests
+  - Update examples
+  - Write blog posts
+
+Versioning:
+  - Follow semver strictly
+  - Maintain CHANGELOG.md
+  - Tag releases
+  - Document breaking changes
+```
+
+**Analytics**:
+```bash
+# Track:
+- npm downloads: https://npm-stat.com/charts.html?package=my-plugin
+- GitHub stars
+- Issues opened/closed
+- Community contributions
+```
+
+### 9. Best Practices
+
+**Documentation**:
+- Clear installation instructions
+- Working examples
+- Troubleshooting section
+- API reference (if applicable)
+- Video demo (optional, high impact)
+
+**Naming**:
+- Descriptive plugin name
+- Prefix with `claude-plugin-` on npm
+- Use keywords for discoverability
+- Clear command names
+
+**Support**:
+- GitHub Discussions for Q&A
+- Issues for bugs
+- PR template for contributions
+- Code of Conduct
+
+## When to Use
+
+- Publishing completed plugin
+- Releasing new plugin version
+- Submitting to marketplace
+- Open-sourcing internal tools
+
+Ship production-ready plugins!