plugin-validator（插件验证器）

Plugin Validator Skill

Purpose: Validate and install SpecWeave plugins when explicitly requested by the user.

Activation: Triggers ONLY when user explicitly requests plugin validation (e.g., "validate plugins", "check plugins", or runs specweave validate-plugins command). Does NOT auto-activate for workflow commands to prevent false positive errors.

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

✅ ONLY activates when explicitly requested:

• You mention "plugin validation" or "validate plugins"
• You mention "environment setup" or "check plugins"
• You run: specweave validate-plugins
• You ask: "Can you validate my plugins?"
• You report: "I'm getting plugin errors"
• During: specweave init (initial setup only)

❌ Does NOT auto-activate for:

• /sw:increment commands
• /sw:do commands
• Any other workflow commands
• Reason: Prevents false positive errors when plugins are installed but detection fails

Validation Process

Phase 1: Marketplace Check

What: Checks if SpecWeave marketplace is registered in Claude Code Where: ~/.claude/settings.json Expected:

{
  "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:

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-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 /sw: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 /sw: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:

specweave validate-plugins

Auto-install missing components:

specweave validate-plugins --auto-install

With context detection:

specweave validate-plugins --context="Add GitHub sync for mobile app"

Dry-run (preview only):

specweave validate-plugins --dry-run --context="Add Stripe billing"

Verbose mode:

specweave validate-plugins --verbose

Combined flags:

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:

{
  "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):

{
  "pluginValidation": {
    "enabled": false
  }
}

Integration with Commands

All SpecWeave commands validate plugins before execution (STEP 0):

• /sw:increment - Validates before PM agent runs
• /sw:do - Validates before task execution
• /sw:next - Validates before next increment
• /sw:done - Validates before completion
• ... (all 22 commands)

Workflow:

User: /sw: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:

{
  "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:

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 sw-github@specweave
/plugin install sw-payments@specweave
/plugin install sw-frontend@specweave

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