specweave 0.9.1 → 0.10.0

package/plugins/specweave/skills/plugin-validator/SKILL.md

@@ -0,0 +1,427 @@
+---
+name: plugin-validator
+description: Proactively validates SpecWeave plugin installation before workflows execute. Auto-activates when /specweave:* commands detected. Ensures marketplace registered, core plugin installed, and context-specific plugins available. Prevents cryptic errors from missing plugins. Enables seamless environment migration (local → VM → Cloud IDE). Activates for plugin validation, environment setup, missing plugins, specweave commands, marketplace registration, plugin installation, environment migration, fresh setup.
+allowed-tools: Read, Bash, Grep
+---
+
+# Plugin Validator Skill
+
+**Purpose**: Proactively validate and install SpecWeave plugins before workflow commands execute.
+
+**Auto-Activation**: Triggers when `/specweave:*` commands are detected or when plugin-related issues arise.
+
+## What This Skill Does
+
+This skill ensures that your SpecWeave environment is properly configured with all required plugins BEFORE you start working. It prevents frustrating errors and wasted time from missing components.
+
+### Key Features
+
+1. **Marketplace Validation**: Ensures SpecWeave marketplace is registered in `~/.claude/settings.json`
+2. **Core Plugin Check**: Verifies `specweave` plugin is installed
+3. **Context Detection**: Analyzes your increment description and suggests relevant plugins
+4. **Auto-Installation**: Can automatically install missing components (with your permission)
+5. **Clear Guidance**: Shows exactly what's missing and how to fix it
+
+## When This Skill Activates
+
+✅ **Automatically activates when**:
+- You run any `/specweave:*` command (increment, do, next, etc.)
+- You mention "plugin validation" or "environment setup"
+- You encounter errors related to missing plugins
+- You're setting up SpecWeave in a new environment
+
+✅ **Manual activation**:
+- Run: `specweave validate-plugins`
+- Ask: "Can you validate my plugins?"
+- Report: "I'm getting plugin errors"
+
+## Validation Process
+
+### Phase 1: Marketplace Check
+
+**What**: Checks if SpecWeave marketplace is registered in Claude Code
+**Where**: `~/.claude/settings.json`
+**Expected**:
+```json
+{
+  "extraKnownMarketplaces": {
+    "specweave": {
+      "source": {
+        "source": "github",
+        "repo": "anton-abyzov/specweave",
+        "path": ".claude-plugin"
+      }
+    }
+  }
+}
+```
+
+**If missing**: Auto-creates the configuration
+
+### Phase 2: Core Plugin Check
+
+**What**: Verifies `specweave` plugin is installed
+**Command**: `/plugin list --installed | grep "specweave"`
+**Expected**: Plugin appears in the list
+
+**If missing**: Suggests `/plugin install specweave`
+
+### Phase 3: Context-Aware Plugin Detection
+
+**What**: Scans your increment description for keywords
+**Examples**:
+
+| Your Description | Detected Keywords | Suggested Plugin |
+|-----------------|-------------------|------------------|
+| "Add GitHub sync" | github, sync | specweave-github |
+| "Stripe billing with React UI" | stripe, billing, react, ui | specweave-payments, specweave-frontend |
+| "Deploy to Kubernetes" | kubernetes, deploy | specweave-kubernetes |
+| "Add Jira integration" | jira, integration | specweave-jira |
+
+**Full Keyword Map** (15+ plugins):
+- **specweave-github**: github, git, issues, pull request, pr, repository
+- **specweave-jira**: jira, epic, story, sprint, backlog
+- **specweave-ado**: azure devops, ado, work item, boards
+- **specweave-payments**: stripe, billing, payment, subscription, invoice
+- **specweave-frontend**: react, nextjs, vue, angular, frontend, ui
+- **specweave-kubernetes**: kubernetes, k8s, helm, pod, deployment
+- **specweave-ml**: machine learning, ml, tensorflow, pytorch, model
+- **specweave-observability**: prometheus, grafana, monitoring, metrics
+- **specweave-security**: security, owasp, vulnerability, audit
+- **specweave-diagrams**: diagram, c4, mermaid, architecture
+- **specweave-backend-nodejs**: nodejs, express, fastify, nestjs, backend
+- **specweave-backend-python**: python, fastapi, django, flask
+- **specweave-backend-dotnet**: dotnet, .net, aspnet, c#
+- **specweave-docs-preview**: documentation, docs, preview, docusaurus
+- **specweave-e2e-testing**: playwright, e2e, end-to-end, browser
+
+## Usage Examples
+
+### Example 1: Fresh Environment
+
+**Scenario**: You cloned a project to a new VM and want to start working.
+
+**Action**: Run `/specweave:increment "Add authentication"`
+
+**What Happens**:
+```
+🔍 Validating SpecWeave environment...
+
+❌ Missing components detected:
+   • SpecWeave marketplace not registered
+   • Core plugin (specweave) not installed
+
+📦 Installing missing components...
+   ✅ Marketplace registered (.claude/settings.json)
+   ✅ Core plugin installed (specweave v0.9.4)
+
+🎉 Environment ready! Proceeding with increment planning...
+```
+
+### Example 2: Context Detection
+
+**Scenario**: You're adding a new feature that uses GitHub and React.
+
+**Action**: Run `/specweave:increment "Add GitHub sync with React UI"`
+
+**What Happens**:
+```
+🔍 Validating SpecWeave environment...
+
+✅ Marketplace registered
+✅ Core plugin installed (specweave v0.9.4)
+
+🔎 Detected context plugins from your description:
+   • specweave-github (keywords: github, sync)
+   • specweave-frontend (keywords: react, ui)
+
+❌ Missing context plugins:
+   • specweave-github
+   • specweave-frontend
+
+📦 Would you like to install these plugins?
+   They provide specialized expertise for your use case.
+
+   1. Yes, install now (recommended)
+   2. No, skip for now (limited capabilities)
+
+Your choice [1]:
+```
+
+### Example 3: Manual Validation
+
+**Scenario**: You want to check your environment without running a command.
+
+**Action**: Run `specweave validate-plugins --verbose`
+
+**What Happens**:
+```
+[PluginValidator] Checking marketplace registration...
+[PluginValidator] Marketplace registered ✓
+[PluginValidator] Checking core plugin (specweave)...
+[PluginValidator] Core plugin installed ✓ (0.9.4)
+
+✅ All plugins validated!
+   • Core plugin: installed (v0.9.4)
+   • Cache: miss
+```
+
+### Example 4: Dry-Run Mode
+
+**Scenario**: You want to see what would be installed without actually installing.
+
+**Action**: Run `specweave validate-plugins --context="Add Stripe billing" --dry-run`
+
+**What Happens**:
+```
+🔍 Validating SpecWeave environment...
+
+✅ Marketplace registered
+✅ Core plugin installed
+
+🔎 Detected context plugins:
+   • specweave-payments (keywords: stripe, billing)
+
+❌ Missing: specweave-payments
+
+💡 Dry-run mode: No changes made.
+   To install, remove --dry-run flag.
+```
+
+## CLI Command Reference
+
+**Basic validation**:
+```bash
+specweave validate-plugins
+```
+
+**Auto-install missing components**:
+```bash
+specweave validate-plugins --auto-install
+```
+
+**With context detection**:
+```bash
+specweave validate-plugins --context="Add GitHub sync for mobile app"
+```
+
+**Dry-run (preview only)**:
+```bash
+specweave validate-plugins --dry-run --context="Add Stripe billing"
+```
+
+**Verbose mode**:
+```bash
+specweave validate-plugins --verbose
+```
+
+**Combined flags**:
+```bash
+specweave validate-plugins --auto-install --context="Deploy to Kubernetes" --verbose
+```
+
+## Troubleshooting
+
+### Error: "Claude CLI not available"
+
+**Symptom**: Validation fails with "command not found"
+
+**Solution**:
+1. Ensure Claude Code is installed
+2. Restart your terminal
+3. Verify: `claude --version`
+4. If still failing, install plugins manually using `/plugin install` command
+
+### Error: "Marketplace configuration invalid"
+
+**Symptom**: Marketplace is registered but validation fails
+
+**Solution**:
+1. Check `~/.claude/settings.json` structure
+2. Ensure marketplace points to GitHub source
+3. If using local marketplace (dev mode), this is expected
+4. Re-run validation to auto-fix configuration
+
+### Error: "Plugin installation failed"
+
+**Symptom**: Auto-install tries but fails
+
+**Solution**:
+1. Check internet connection (GitHub access required)
+2. Verify Claude Code is running
+3. Try manual installation: `/plugin install specweave`
+4. Check Claude Code logs for detailed errors
+
+### False Positive: Wrong Plugin Suggested
+
+**Symptom**: Context detection suggests irrelevant plugin
+
+**Example**: Description "Add GitHub Actions" suggests specweave-github (but you meant CI/CD, not issue tracking)
+
+**Solution**:
+1. Skip the suggestion (choose option 2)
+2. Install correct plugin manually later
+3. This is rare (2+ keyword matches required for suggestion)
+
+## Performance
+
+**Validation Speed**:
+- ✅ With cache: <2 seconds
+- ✅ Without cache: <5 seconds
+- ✅ With auto-install: <30 seconds (1-2 plugins)
+
+**Caching**:
+- Results cached for 5 minutes
+- Speeds up repeated commands
+- Invalidated after plugin changes
+- Cache location: `~/.specweave/validation-cache.json`
+
+## Configuration
+
+**Validation can be configured** in `.specweave/config.json`:
+
+```json
+{
+  "pluginValidation": {
+    "enabled": true,           // Enable/disable validation (default: true)
+    "autoInstall": true,       // Auto-install missing components (default: true)
+    "verbose": false,          // Show detailed logs (default: false)
+    "cacheValidation": true,   // Cache results (default: true)
+    "cacheTTL": 300            // Cache TTL in seconds (default: 300 = 5 min)
+  }
+}
+```
+
+**Disable validation** (not recommended):
+```json
+{
+  "pluginValidation": {
+    "enabled": false
+  }
+}
+```
+
+## Integration with Commands
+
+**All SpecWeave commands validate plugins** before execution (STEP 0):
+
+- `/specweave:increment` - Validates before PM agent runs
+- `/specweave:do` - Validates before task execution
+- `/specweave:next` - Validates before next increment
+- `/specweave:done` - Validates before completion
+- ... (all 22 commands)
+
+**Workflow**:
+```
+User: /specweave:increment "Add feature"
+        ↓
+   [STEP 0: Plugin Validation]
+        ↓ (only proceeds if valid)
+   [STEP 1: PM Agent Planning]
+        ↓
+   [STEP 2: Architect Design]
+        ↓
+   [STEP 3: Implementation]
+```
+
+## Benefits
+
+✅ **Zero manual setup** - Plugins install automatically
+✅ **Seamless migration** - Works across local/VM/Cloud IDE
+✅ **Context-aware** - Suggests relevant plugins based on your work
+✅ **Clear errors** - No more cryptic "command not found" messages
+✅ **Fast** - Caching ensures minimal overhead (<2s cached, <5s uncached)
+✅ **Non-blocking** - Can skip validation if needed (not recommended)
+
+## Edge Cases
+
+**1. Offline Mode**
+- Validation detects missing plugins but can't install
+- Shows manual instructions instead
+- Validation still useful (identifies what's missing)
+
+**2. Development Mode**
+- Local marketplace detected (not GitHub)
+- Shows warning: "Development mode detected"
+- Validation passes (assumes dev knows what they're doing)
+
+**3. Concurrent Validation**
+- Multiple commands run simultaneously
+- Uses cache to prevent duplicate validations
+- Race conditions handled gracefully
+
+**4. Partial Installation**
+- Marketplace exists, but plugin missing (or vice versa)
+- Installs only missing components
+- Doesn't reinstall existing components
+
+## Manual Installation (Fallback)
+
+**If auto-install fails**, follow these steps:
+
+### Step 1: Register Marketplace
+
+Edit `~/.claude/settings.json`:
+```json
+{
+  "extraKnownMarketplaces": {
+    "specweave": {
+      "source": {
+        "source": "github",
+        "repo": "anton-abyzov/specweave",
+        "path": ".claude-plugin"
+      }
+    }
+  }
+}
+```
+
+### Step 2: Install Core Plugin
+
+In Claude Code, run:
+```
+/plugin install specweave
+```
+
+### Step 3: Restart Claude Code
+
+Close and reopen Claude Code for changes to take effect.
+
+### Step 4: Verify Installation
+
+Run:
+```bash
+specweave validate-plugins
+```
+
+Should show:
+```
+✅ All plugins validated!
+   • Core plugin: installed (v0.9.4)
+```
+
+### Step 5: Install Context Plugins (Optional)
+
+If you need specific plugins:
+```
+/plugin install specweave-github
+/plugin install specweave-payments
+/plugin install specweave-frontend
+```
+
+## Summary
+
+**This skill ensures you NEVER waste time debugging plugin issues.**
+
+It proactively validates your environment, auto-installs missing components, and suggests relevant plugins based on your work. The result: you focus on building features, not troubleshooting setup.
+
+**Questions?**
+- Check troubleshooting section above
+- Run `specweave validate-plugins --help`
+- Visit: https://spec-weave.com/docs/plugin-validation
+
+---
+
+**Skill Version**: 1.0.0
+**Introduced**: SpecWeave v0.9.4
+**Last Updated**: 2025-11-09

package/plugins/specweave-ado/.claude-plugin/plugin.json

@@ -6,10 +6,8 @@
     "name": "SpecWeave Team",
     "url": "https://spec-weave.com"
   },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/anton-abyzov/specweave"
-  },
+  "homepage": "https://spec-weave.com",
+  "repository": "https://github.com/anton-abyzov/specweave",
   "keywords": [
     "azure-devops",
     "ado",