specweave 0.23.16 → 0.24.0

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

@@ -0,0 +1,293 @@
+# /specweave-plugin-dev:plugin-test
+
+Test Claude Code plugins for correctness, activation, and best practices compliance.
+
+You are an expert plugin tester who validates plugin structure and functionality.
+
+## Your Task
+
+Validate plugin structure, test activation, and verify best practices compliance.
+
+### 1. Validation Checklist
+
+**File Structure**:
+```bash
+# Check plugin exists
+ls ~/.claude/plugins/my-plugin
+
+# Verify structure
+tree ~/.claude/plugins/my-plugin
+# Expected:
+# .claude-plugin/plugin.json ✓
+# commands/*.md ✓
+# skills/*/SKILL.md ✓
+```
+
+**plugin.json Validation**:
+```typescript
+interface PluginManifest {
+  name: string;         // Required: kebab-case
+  description: string;  // Required: activation keywords
+  version: string;      // Required: semver
+  author?: {
+    name: string;
+    email: string;
+  };
+  keywords?: string[];
+  homepage?: string;
+  repository?: string;
+  license?: string;
+}
+
+// Validate
+const plugin = JSON.parse(fs.readFileSync('.claude-plugin/plugin.json'));
+assert(plugin.name.match(/^[a-z0-9-]+$/), 'Name must be kebab-case');
+assert(plugin.description.length > 20, 'Description too short');
+assert(semver.valid(plugin.version), 'Invalid version');
+```
+
+**Command Validation**:
+```bash
+# Check header format
+grep -E '^# /[a-z0-9-]+:[a-z0-9-]+$' commands/*.md
+
+# Verify no YAML frontmatter in commands
+! grep -l '^---$' commands/*.md
+
+# Check for clear instructions
+grep -A 20 '## Your Task' commands/*.md
+```
+
+**Skill Validation**:
+```bash
+# Check YAML frontmatter
+grep -l '^---$' skills/*/SKILL.md
+
+# Validate activation keywords
+grep 'Activates for' skills/*/SKILL.md
+
+# Verify subdirectory structure
+find skills -name 'SKILL.md' -not -path 'skills/*/SKILL.md' # Should be empty
+```
+
+### 2. Activation Testing
+
+**Test Slash Command**:
+```bash
+# In Claude Code:
+# 1. Type "/" 
+# 2. Verify command appears in autocomplete
+# 3. Execute: /my-plugin:my-command
+# 4. Verify behavior matches documentation
+```
+
+**Test Skill Auto-Activation**:
+```bash
+# Test each activation keyword
+echo "Testing skill activation..."
+
+# Skill: cost-optimization
+# Keywords: reduce costs, save money, cloud costs, finops
+# Test: Ask "How can I reduce my AWS costs?"
+# Expected: Skill activates, provides cost optimization advice
+
+# Skill: python-expert
+# Keywords: python, optimize python, speed up python
+# Test: Ask "How do I speed up my Python code?"
+# Expected: Skill activates, provides optimization tips
+```
+
+**Test Agent Invocation**:
+```typescript
+// Verify agent exists
+const agentPath = '~/.claude/plugins/my-plugin/agents/my-agent/AGENT.md';
+assert(fs.existsSync(agentPath), 'Agent file missing');
+
+// Test invocation syntax
+Task({
+  subagent_type: "my-plugin:my-agent:my-agent", // plugin:folder:yaml-name
+  prompt: "Test agent invocation"
+});
+```
+
+### 3. Best Practices Validation
+
+**Naming Convention Check**:
+```bash
+# Plugin name: kebab-case only
+echo "my-plugin" | grep -E '^[a-z0-9-]+$' ✓
+echo "MyPlugin" | grep -E '^[a-z0-9-]+$' ✗ # No CamelCase
+
+# Command names: kebab-case
+echo "analyze-costs" | grep -E '^[a-z0-9-]+$' ✓
+echo "analyzeCosts" | grep -E '^[a-z0-9-]+$' ✗ # No camelCase
+```
+
+**Activation Keyword Quality**:
+```yaml
+# ✅ Good: Specific, varied keywords
+description: Expert cost optimization. Activates for reduce costs, save money, aws costs, cloud spending, finops, cost analysis, budget optimization.
+
+# ⚠️ Weak: Too few keywords
+description: Cost expert. Activates for costs.
+
+# ❌ Bad: No keywords
+description: Cost optimization plugin.
+```
+
+**Documentation Quality**:
+```markdown
+# Check for:
+- [ ] Clear "Your Task" section
+- [ ] Code examples with syntax highlighting
+- [ ] Workflow/steps
+- [ ] "When to Use" section
+- [ ] Example usage
+```
+
+### 4. Integration Testing
+
+**Test Plugin Loading**:
+```bash
+# Check Claude Code logs
+tail -f ~/.claude/logs/claude.log | grep 'my-plugin'
+
+# Expected output:
+# ✅ "Loaded plugin: my-plugin"
+# ✅ "Registered command: /my-plugin:my-command"
+# ✅ "Registered skill: my-skill"
+
+# Red flags:
+# ❌ "Failed to parse plugin.json"
+# ❌ "YAML parsing error in SKILL.md"
+# ❌ "Command header malformed"
+```
+
+**Test Cross-Plugin Compatibility**:
+```bash
+# Ensure no conflicts with other plugins
+ls ~/.claude/plugins/
+
+# Check for:
+- Name collisions (same plugin name)
+- Command collisions (same /command)
+- Skill keyword overlap (acceptable, but note)
+```
+
+### 5. Performance Testing
+
+**Skill Activation Speed**:
+```bash
+# Skills should activate in < 100ms
+# Monitor: Does Claude Code lag when typing trigger keywords?
+
+# If slow:
+# - Reduce skill description length
+# - Optimize SKILL.md size (< 50KB)
+# - Avoid complex regex in activation patterns
+```
+
+**Command Execution**:
+```bash
+# Commands should provide first response in < 2s
+# Test with: /my-plugin:my-command
+
+# If slow:
+# - Check for expensive operations in command instructions
+# - Optimize prompt length
+```
+
+### 6. Security Review
+
+**Secret Detection**:
+```bash
+# Check for hardcoded secrets
+grep -r 'API_KEY\|SECRET\|PASSWORD\|TOKEN' .
+
+# ❌ Hardcoded secrets
+const API_KEY = 'sk-1234567890abcdef';
+
+# ✅ Environment variables
+const API_KEY = process.env.API_KEY;
+```
+
+**Input Validation**:
+```bash
+# Ensure commands validate user input
+grep -r 'validate\|sanitize\|escape' commands/
+
+# Commands that execute code should warn about risks
+```
+
+### 7. Testing Workflow
+
+**Manual Testing**:
+1. Install plugin: `cp -r my-plugin ~/.claude/plugins/`
+2. Restart Claude Code
+3. Test commands: `/my-plugin:command`
+4. Test skills: Ask trigger questions
+5. Test agents: Use Task() tool
+6. Check logs: `~/.claude/logs/`
+
+**Automated Testing** (if applicable):
+```bash
+# Validation script
+#!/bin/bash
+
+PLUGIN_DIR="my-plugin"
+
+# Check structure
+test -f "$PLUGIN_DIR/.claude-plugin/plugin.json" || exit 1
+test -d "$PLUGIN_DIR/commands" || exit 1
+test -d "$PLUGIN_DIR/skills" || exit 1
+
+# Validate JSON
+jq . "$PLUGIN_DIR/.claude-plugin/plugin.json" > /dev/null || exit 1
+
+# Check SKILL.md files
+find "$PLUGIN_DIR/skills" -name 'SKILL.md' -path '*/*/SKILL.md' | wc -l
+
+# Validate YAML frontmatter
+for skill in "$PLUGIN_DIR/skills"/*/SKILL.md; do
+  head -n 5 "$skill" | grep -q '^---$' || echo "Missing YAML: $skill"
+done
+
+echo "✅ Plugin validation passed"
+```
+
+### 8. Common Issues
+
+**Issue: Command not appearing**
+```bash
+# Check header format
+# ❌ Wrong: # my-plugin:my-command
+# ❌ Wrong: # /myPlugin:myCommand
+# ✅ Correct: # /my-plugin:my-command
+```
+
+**Issue: Skill not activating**
+```bash
+# Check:
+1. YAML frontmatter present?
+2. Activation keywords in description?
+3. SKILL.md in subdirectory?
+4. Claude Code restarted after changes?
+```
+
+**Issue: YAML parsing error**
+```bash
+# Common causes:
+- Unclosed quotes: description: "Missing end quote
+- Invalid characters: name: my_skill (use hyphens)
+- Missing closing ---
+- Incorrect indentation
+```
+
+## When to Use
+
+- After creating/modifying plugins
+- Before publishing to marketplace
+- Debugging plugin activation issues
+- Pre-release quality assurance
+
+Test plugins thoroughly before release!

package/plugins/specweave-plugin-dev/skills/claude-sdk/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: claude-sdk
+description: Expert knowledge of Claude Code SDK, API, tools (Read, Write, Edit, Bash, Grep, Glob), agent tools (Task, Skill, SlashCommand), plugin hooks, MCP integration, and Claude Code extension development. Activates for claude sdk, claude api, claude tools, Read tool, Write tool, Edit tool, Task tool, Skill tool, claude hooks, MCP, claude code api.
+---
+
+# Claude SDK Expert
+
+Expert knowledge of Claude Code SDK, tools, and extension development.
+
+## Core Tools
+
+**File Operations**:
+```typescript
+// Read files
+Read({ file_path: '/absolute/path/file.ts' });
+
+// Write files (creates new or overwrites)
+Write({
+  file_path: '/absolute/path/file.ts',
+  content: 'export const hello = () => "world";'
+});
+
+// Edit files (precise replacements)
+Edit({
+  file_path: '/absolute/path/file.ts',
+  old_string: 'const x = 1;',
+  new_string: 'const x = 2;'
+});
+```
+
+**Search**:
+```typescript
+// Find files by pattern
+Glob({ pattern: '**/*.ts' });
+
+// Search file contents
+Grep({
+  pattern: 'TODO',
+  output_mode: 'files_with_matches'
+});
+
+// Search with context
+Grep({
+  pattern: 'function.*export',
+  output_mode: 'content',
+  '-C': 3, // 3 lines before/after
+  '-n': true // Line numbers
+});
+```
+
+**Execution**:
+```typescript
+// Run commands
+Bash({
+  command: 'npm test',
+  description: 'Run test suite'
+});
+
+// Background processes
+Bash({
+  command: 'npm run dev',
+  run_in_background: true
+});
+```
+
+## Agent Tools
+
+**Sub-agents**:
+```typescript
+// Invoke specialized sub-agent
+Task({
+  subagent_type: 'plugin:agent-folder:agent-name',
+  prompt: 'Analyze this architecture'
+});
+```
+
+**Skills**:
+```typescript
+// Activate skill explicitly
+Skill({ skill: 'skill-name' });
+
+// Or let auto-activation handle it
+```
+
+**Commands**:
+```typescript
+// Execute slash command
+SlashCommand({ command: '/plugin:command arg1 arg2' });
+```
+
+## Plugin Hooks
+
+**Available Hook Events**:
+```typescript
+type HookEvent =
+  | 'PostToolUse'        // After tool executes
+  | 'PreToolUse'         // Before tool executes
+  | 'PermissionRequest'  // User permission dialog
+  | 'Notification'       // System notification
+  | 'UserPromptSubmit'   // After user submits prompt
+  | 'Stop'               // Conversation stopped
+  | 'SubagentStop'       // Sub-agent stopped
+  | 'PreCompact'         // Before context compaction
+  | 'SessionStart'       // Session started
+  | 'SessionEnd';        // Session ended
+```
+
+**Hook Configuration**:
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "TodoWrite",
+        "hooks": [{
+          "type": "command",
+          "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task.sh",
+          "timeout": 10
+        }]
+      }
+    ]
+  }
+}
+```
+
+## MCP (Model Context Protocol)
+
+**MCP Server Integration**:
+```typescript
+// Connect to MCP server
+const mcp = await connectMCP({
+  name: 'filesystem',
+  transport: 'stdio',
+  command: 'node',
+  args: ['mcp-server-filesystem.js']
+});
+
+// Use MCP tools
+mcp.call('read_file', { path: '/path/to/file' });
+```
+
+## Best Practices
+
+**Tool Usage**:
+- Use absolute paths (not relative)
+- Handle errors gracefully
+- Provide clear descriptions
+- Batch independent operations
+
+**Performance**:
+- Minimize tool calls
+- Use Grep before Read (search first)
+- Parallel independent operations
+- Cache results when possible
+
+**Security**:
+- Validate file paths
+- Sanitize user input
+- No hardcoded secrets
+- Use environment variables
+
+Build powerful Claude Code extensions!

package/plugins/specweave-plugin-dev/skills/marketplace-publishing/SKILL.md

@@ -0,0 +1,263 @@
+---
+name: marketplace-publishing
+description: Expert Claude Code marketplace publishing covering npm publishing, GitHub releases, semantic versioning, plugin packaging, README documentation, CHANGELOG management, marketplace submission, and plugin distribution. Activates for publish plugin, npm publish, marketplace, release plugin, semantic versioning, semver, plugin distribution, publish to npm, github release.
+---
+
+# Marketplace Publishing Expert
+
+Expert guidance for publishing Claude Code plugins to npm and marketplace.
+
+## Publishing Platforms
+
+**1. GitHub** (Recommended):
+```bash
+# Install from GitHub
+claude plugin add github:username/plugin-name
+
+# Pros:
+- Free hosting
+- Version control
+- Issue tracking
+- Easy updates
+
+# Requirements:
+- Public repository
+- Proper directory structure
+- README with installation
+```
+
+**2. npm**:
+```bash
+# Install from npm
+claude plugin add plugin-name
+
+# Pros:
+- Centralized registry
+- Semantic versioning
+- Easy discovery
+
+# Requirements:
+- npm account
+- package.json
+- Unique name (prefix: claude-plugin-)
+```
+
+**3. Marketplace**:
+```bash
+# Official Claude Code marketplace
+# PR to marketplace repository
+
+# Requirements:
+- Quality standards
+- Complete documentation
+- No security issues
+- Proper licensing
+```
+
+## Semantic Versioning
+
+**Version Format**: `MAJOR.MINOR.PATCH`
+
+**Rules**:
+```yaml
+MAJOR (1.0.0 → 2.0.0):
+  - Breaking changes
+  - Remove commands
+  - Change skill keywords
+  - Incompatible API changes
+
+MINOR (1.0.0 → 1.1.0):
+  - New features
+  - Add commands
+  - Add skills
+  - Backward compatible
+
+PATCH (1.0.0 → 1.0.1):
+  - Bug fixes
+  - Documentation updates
+  - Performance improvements
+  - No API changes
+```
+
+**Examples**:
+```bash
+# Bug fix
+npm version patch  # 1.0.0 → 1.0.1
+
+# New feature
+npm version minor  # 1.0.1 → 1.1.0
+
+# Breaking change
+npm version major  # 1.1.0 → 2.0.0
+```
+
+## package.json Setup
+
+**Minimum**:
+```json
+{
+  "name": "claude-plugin-my-plugin",
+  "version": "1.0.0",
+  "description": "Expert [domain] plugin for Claude Code",
+  "keywords": ["claude-code", "plugin", "keyword1"],
+  "author": "Your Name",
+  "license": "MIT",
+  "files": [
+    ".claude-plugin",
+    "commands",
+    "skills",
+    "agents",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+**Full**:
+```json
+{
+  "name": "claude-plugin-my-plugin",
+  "version": "1.0.0",
+  "description": "Expert [domain] plugin with [features]",
+  "main": "index.js",
+  "scripts": {
+    "test": "echo \"No tests yet\"",
+    "validate": "bash validate.sh"
+  },
+  "keywords": [
+    "claude-code",
+    "plugin",
+    "development-tools",
+    "keyword1",
+    "keyword2"
+  ],
+  "author": "Your Name <you@example.com>",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/username/my-plugin"
+  },
+  "homepage": "https://github.com/username/my-plugin#readme",
+  "bugs": {
+    "url": "https://github.com/username/my-plugin/issues"
+  },
+  "files": [
+    ".claude-plugin/**/*",
+    "commands/**/*",
+    "skills/**/*",
+    "agents/**/*",
+    "README.md",
+    "LICENSE"
+  ]
+}
+```
+
+## Publishing Workflow
+
+**GitHub Release**:
+```bash
+# 1. Update version
+npm version patch
+
+# 2. Commit changes
+git add .
+git commit -m "Release v1.0.1"
+
+# 3. Create tag
+git tag v1.0.1
+
+# 4. Push
+git push && git push --tags
+
+# 5. Create GitHub release
+gh release create v1.0.1 \
+  --title "v1.0.1" \
+  --notes "Bug fixes and improvements"
+```
+
+**npm Publish**:
+```bash
+# 1. Login
+npm login
+
+# 2. Validate package
+npm pack --dry-run
+
+# 3. Publish
+npm publish
+
+# 4. Verify
+npm view claude-plugin-my-plugin
+```
+
+## Documentation Requirements
+
+**README.md**:
+```markdown
+# Plugin Name
+
+> One-line tagline
+
+Brief description.
+
+## Features
+
+- Feature 1
+- Feature 2
+
+## Installation
+
+\```bash
+claude plugin add github:user/plugin
+\```
+
+## Commands
+
+### /plugin:command
+
+Description.
+
+## Examples
+
+[Working examples]
+
+## License
+
+MIT
+```
+
+**CHANGELOG.md**:
+```markdown
+# Changelog
+
+## [1.0.1] - 2025-01-15
+
+### Fixed
+- Bug fix 1
+- Bug fix 2
+
+## [1.0.0] - 2025-01-01
+
+### Added
+- Initial release
+```
+
+## Quality Checklist
+
+**Pre-publish**:
+- ✅ All commands working
+- ✅ Skills activate correctly
+- ✅ No hardcoded secrets
+- ✅ README with examples
+- ✅ LICENSE file
+- ✅ Semantic versioning
+- ✅ CHANGELOG updated
+- ✅ Git tag created
+
+**Post-publish**:
+- ✅ Test installation
+- ✅ Verify on npm (if published)
+- ✅ Check GitHub release
+- ✅ Update marketplace (if applicable)
+
+Publish professional Claude Code plugins!