specweave 0.33.4 → 0.33.5

package/plugins/specweave/commands/specweave-judge.md

@@ -1,276 +0,0 @@
----
-name: specweave:judge
-description: Validate completed work using LLM-as-Judge pattern. Works on any files, not just increments.
----
-
-# /specweave:judge - Work Validation via Judge LLM
-
-Validate any completed work using the LLM-as-Judge pattern with deep reasoning.
-
-## Purpose
-
-Use when you've completed work (files, git changes, any code) and want AI-powered validation:
-- Works on **any files** (not just SpecWeave increments)
-- Uses **chain-of-thought reasoning** for thorough analysis
-- Returns **clear verdict** with detailed reasoning
-
-## Usage
-
-```bash
-# Validate specific files
-/specweave:judge src/file.ts
-/specweave:judge "src/**/*.ts"
-
-# Validate git changes
-/specweave:judge --staged           # Staged changes
-/specweave:judge --last-commit      # Last commit
-/specweave:judge --diff main        # Diff vs branch
-
-# Validation modes
-/specweave:judge src/file.ts --quick    # Fast (~10s)
-/specweave:judge src/file.ts --deep     # Thorough (~60s)
-/specweave:judge src/file.ts --strict   # Fail on any concern
-
-# Additional options
-/specweave:judge src/file.ts --fix      # Include fix suggestions
-/specweave:judge src/file.ts --export   # Export report to markdown
-```
-
-## How It Works
-
-When you invoke `/specweave:judge`, Claude will:
-
-### Step 1: Gather Input
-
-Determine what to validate:
-- If file paths provided → read those files
-- If `--staged` → get staged git changes
-- If `--last-commit` → get files from last commit
-- If `--diff <branch>` → get diff against branch
-
-### Step 2: Analyze with Judge LLM Pattern
-
-Use chain-of-thought reasoning to evaluate:
-
-```markdown
-<thinking>
-1. **Read**: Understand what the code does
-2. **Analyze**: Check for issues across dimensions:
-   - Correctness: Does it work as intended?
-   - Completeness: Are edge cases handled?
-   - Security: Any vulnerabilities?
-   - Performance: Any obvious issues?
-   - Maintainability: Is it clean and clear?
-3. **Evaluate**: Weigh findings by severity
-4. **Decide**: Form verdict based on analysis
-</thinking>
-```
-
-### Step 3: Return Verdict
-
-```
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-JUDGE VERDICT: APPROVED | CONCERNS | REJECTED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Confidence: 0.XX
-Files Analyzed: N
-
-REASONING:
-[Chain-of-thought explanation of findings]
-
-ISSUES (if any):
-🔴 CRITICAL: [title]
-   [description]
-   📍 [file:line]
-   💡 [suggestion]
-
-🟡 HIGH: [title]
-   ...
-
-🟢 LOW: [title]
-   ...
-
-VERDICT: [summary sentence]
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Verdict Meanings
-
-| Verdict | Meaning | Action |
-|---------|---------|--------|
-| **APPROVED** | Work looks good, no significant issues | Safe to proceed |
-| **CONCERNS** | Some issues found, worth addressing | Review and fix if time permits |
-| **REJECTED** | Critical issues found | Must fix before proceeding |
-
-## Validation Modes
-
-### Quick Mode (`--quick`)
-- Fast validation (~10 seconds)
-- Focuses on obvious issues
-- Good for frequent checks during development
-- Cost: ~$0.02-0.05
-
-### Default Mode
-- Balanced validation (~30 seconds)
-- Thorough analysis of all dimensions
-- Good for pre-commit validation
-- Cost: ~$0.05-0.10
-
-### Deep Mode (`--deep`)
-- Most thorough validation (~60 seconds)
-- Extended thinking for complex reasoning
-- Good for critical code or security review
-- Cost: ~$0.10-0.20
-
-### Strict Mode (`--strict`)
-- Any concern results in REJECTED
-- Use for critical paths, security code, or CI gates
-
-## Examples
-
-### Example 1: Validate a new feature
-
-```
-User: /specweave:judge src/core/auth/login.ts
-
-Claude:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-JUDGE VERDICT: APPROVED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Confidence: 0.85
-Files Analyzed: 1
-
-REASONING:
-The login implementation follows security best practices:
-- Password hashing uses bcrypt with appropriate cost factor
-- Rate limiting is implemented (5 attempts, 15 min lockout)
-- Input validation prevents injection attacks
-- Error messages don't leak user existence
-
-No critical or high-severity issues found.
-
-VERDICT: Implementation is solid and ready for use.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Example 2: Validate staged changes
-
-```
-User: /specweave:judge --staged
-
-Claude:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-JUDGE VERDICT: CONCERNS
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Confidence: 0.78
-Files Analyzed: 3
-
-REASONING:
-Changes add new API endpoint but have some issues:
-- Missing input validation on user-provided data
-- Error messages could leak internal paths
-- No rate limiting on new endpoint
-
-🟡 HIGH: Missing Input Validation
-   User input passed directly to database query
-   📍 src/api/users.ts:45
-   💡 Add Zod schema validation before processing
-
-🟡 HIGH: Information Disclosure
-   Stack traces exposed in error responses
-   📍 src/api/users.ts:62
-   💡 Use production error handler that sanitizes output
-
-VERDICT: Address the input validation before merging.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-### Example 3: Deep validation with fixes
-
-```
-User: /specweave:judge src/payments/checkout.ts --deep --fix
-
-Claude:
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-JUDGE VERDICT: REJECTED
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-
-Confidence: 0.92
-Files Analyzed: 1
-
-REASONING:
-Critical security issue found in payment processing:
-- API key hardcoded in source file
-- No HTTPS enforcement for payment requests
-- Missing idempotency key handling
-
-🔴 CRITICAL: Hardcoded API Key
-   Stripe API key exposed in source code
-   📍 src/payments/checkout.ts:12
-   💡 Move to environment variable:
-   ```typescript
-   // Before (INSECURE)
-   const stripe = new Stripe('sk_live_xxx...');
-
-   // After (SECURE)
-   const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
-   ```
-
-🔴 CRITICAL: No HTTPS Enforcement
-   Payment requests may go over HTTP
-   📍 src/payments/checkout.ts:34
-   💡 Add protocol check:
-   ```typescript
-   if (process.env.NODE_ENV === 'production' && !req.secure) {
-     return res.status(403).json({ error: 'HTTPS required' });
-   }
-   ```
-
-VERDICT: MUST FIX before deployment - security critical.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-```
-
-## Difference from /specweave:qa
-
-| Aspect | `/specweave:qa` | `/specweave:judge` |
-|--------|-----------------|-------------------|
-| **Scope** | Increments only | Any files |
-| **Input** | Increment ID | Files, git diff |
-| **Pattern** | 7-dimension scoring | Judge LLM reasoning |
-| **Focus** | Spec quality, risks | Code correctness |
-| **When** | Before increment close | After any work |
-
-## Best Practices
-
-1. **Use frequently**: Run during development, not just at the end
-2. **Use `--staged`**: Validate before committing
-3. **Use `--strict` for critical code**: Payment, auth, security
-4. **Fix CRITICAL issues immediately**: Never ignore these
-5. **Address CONCERNS before release**: They matter
-6. **Use after bug fixes**: Especially effective when work has definitive expected behavior
-
-**Simplest workflow** - just mention "llm judge" in your prompt:
-```
-"llm judge my fix"
-"use llm judge on this"
-```
-
-Claude will automatically gather context and apply the pattern - no need to specify files.
-
-This follows the [LLM-as-Judge pattern](https://www.anthropic.com/engineering/multi-agent-research-system) - single LLM call with structured evaluation proves more consistent than multiple validation passes.
-
-## Limitations
-
-- ❌ Doesn't execute tests (use test runners)
-- ❌ Doesn't auto-apply fixes (only suggests)
-- ❌ May miss domain-specific issues
-- ❌ Not a replacement for human review
-
-## Related
-
-- `/specweave:qa` - Increment-bound quality assessment
-- `/specweave-core:code-review` - Prompt-based code review
-- `ado-sync-judge` agent - Uses judge pattern for sync validation

package/plugins/specweave-docs/commands/preview.md

@@ -1,274 +0,0 @@
----
-name: specweave-docs:preview
-description: Launch Docusaurus documentation server for internal living docs. Validates docs first, auto-fixes issues, auto-setup on first run. Port 3015.
----
-
-# Documentation Preview Command
-
-Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto-generated sidebar.
-
-**CRITICAL**: Runs pre-flight validation to catch issues BEFORE starting the server.
-
-## Your Task
-
-**IMPORTANT**: This command must work in ANY SpecWeave user project, not just the SpecWeave repo itself.
-
-### Step 1: Check Prerequisites
-
-```bash
-# Verify internal docs exist
-ls -la .specweave/docs/internal/
-
-# If missing, inform user:
-# "No internal documentation found at .specweave/docs/internal/.
-#  Run 'specweave init' first or create the folder structure."
-```
-
-### Step 1.5: CRITICAL - Run Pre-Flight Validation
-
-**ALWAYS run validation BEFORE starting the server!**
-
-```typescript
-import { DocsValidator } from '../../../src/utils/docs-validator.js';
-
-const validator = new DocsValidator({
-  docsPath: '.specweave/docs/internal',
-  autoFix: true,  // Auto-fix common issues
-});
-
-console.log('\n🔍 Running pre-flight validation...\n');
-const result = await validator.validate();
-
-// Show summary
-console.log(DocsValidator.formatResult(result));
-
-// If errors remain after auto-fix, STOP and report
-if (!result.valid) {
-  console.log('\n❌ Documentation has errors that must be fixed before preview.');
-  console.log('   Fix the issues above, then try again.\n');
-  process.exit(1);
-}
-
-console.log('\n✅ Validation passed! Starting server...\n');
-```
-
-**What this catches:**
-- YAML frontmatter errors (unquoted colons, tabs)
-- MDX compatibility issues (unquoted attributes, unclosed tags)
-- Duplicate routes
-- Broken internal links
-
-**Auto-fixes applied:**
-- Wraps YAML values with colons in quotes
-- Quotes HTML attributes
-- Adds closing slashes to void elements (`<br>` → `<br />`)
-- Converts tabs to spaces in YAML
-
-### Step 2: Check for Cached Installation
-
-```bash
-# Check if Docusaurus is already set up in cache
-if [ -d ".specweave/cache/docs-site/node_modules" ]; then
-  echo "✓ Docusaurus installation found in cache"
-  NEEDS_INSTALL=false
-else
-  echo "⚙ First-time setup: Installing Docusaurus (~30 seconds)..."
-  NEEDS_INSTALL=true
-fi
-```
-
-### Step 3: First-Time Setup (if needed)
-
-If `NEEDS_INSTALL=true`, create the cached Docusaurus installation:
-
-```bash
-# Create cache directory
-mkdir -p .specweave/cache/docs-site
-
-# Create package.json
-cat > .specweave/cache/docs-site/package.json << 'EOF'
-{
-  "name": "specweave-docs-preview",
-  "version": "1.0.0",
-  "private": true,
-  "scripts": {
-    "start": "docusaurus start --port 3015",
-    "build": "docusaurus build",
-    "clear": "docusaurus clear"
-  },
-  "dependencies": {
-    "@docusaurus/core": "^3.9.2",
-    "@docusaurus/preset-classic": "^3.9.2",
-    "@docusaurus/theme-mermaid": "^3.9.2",
-    "@mdx-js/react": "^3.0.0",
-    "clsx": "^2.0.0",
-    "prism-react-renderer": "^2.3.0",
-    "react": "^19.0.0",
-    "react-dom": "^19.0.0"
-  },
-  "engines": {
-    "node": ">=20.0"
-  }
-}
-EOF
-
-# Create Docusaurus config pointing to internal docs
-cat > .specweave/cache/docs-site/docusaurus.config.ts << 'EOF'
-import {themes as prismThemes} from 'prism-react-renderer';
-import type {Config} from '@docusaurus/types';
-import type * as Preset from '@docusaurus/preset-classic';
-
-const config: Config = {
-  title: 'Internal Documentation',
-  tagline: 'SpecWeave Living Documentation',
-  favicon: 'img/favicon.ico',
-  future: { v4: true },
-  url: 'http://localhost:3015',
-  baseUrl: '/',
-  onBrokenLinks: 'warn',
-  onBrokenMarkdownLinks: 'warn',
-  i18n: { defaultLocale: 'en', locales: ['en'] },
-  markdown: { mermaid: true, format: 'md' },
-  themes: ['@docusaurus/theme-mermaid'],
-  presets: [
-    [
-      'classic',
-      {
-        docs: {
-          // Path relative to this config file → ../../docs/internal/
-          path: '../../docs/internal',
-          routeBasePath: '/',
-          sidebarPath: './sidebars.ts',
-          showLastUpdateTime: true,
-          sidebarCollapsible: true,
-          sidebarCollapsed: true,
-        },
-        blog: false,
-        theme: { customCss: './src/css/custom.css' },
-      } satisfies Preset.Options,
-    ],
-  ],
-  themeConfig: {
-    colorMode: {
-      defaultMode: 'dark',
-      disableSwitch: false,
-      respectPrefersColorScheme: true,
-    },
-    navbar: {
-      title: 'Internal Docs',
-      items: [
-        {to: '/', label: 'Home', position: 'left'},
-        {type: 'search', position: 'right'},
-      ],
-    },
-    footer: {
-      style: 'dark',
-      copyright: `SpecWeave Living Documentation`,
-    },
-    prism: {
-      theme: prismThemes.github,
-      darkTheme: prismThemes.dracula,
-      additionalLanguages: ['bash', 'typescript', 'yaml', 'json'],
-    },
-    mermaid: { theme: {light: 'neutral', dark: 'dark'} },
-  } satisfies Preset.ThemeConfig,
-};
-
-export default config;
-EOF
-
-# Create auto-generated sidebar
-cat > .specweave/cache/docs-site/sidebars.ts << 'EOF'
-import type {SidebarsConfig} from '@docusaurus/plugin-content-docs';
-
-const sidebars: SidebarsConfig = {
-  docs: [
-    {
-      type: 'autogenerated',
-      dirName: '.',
-    },
-  ],
-};
-
-export default sidebars;
-EOF
-
-# Create minimal CSS
-mkdir -p .specweave/cache/docs-site/src/css
-cat > .specweave/cache/docs-site/src/css/custom.css << 'EOF'
-:root {
-  --ifm-color-primary: #2563eb;
-  --ifm-code-font-size: 95%;
-}
-[data-theme='dark'] {
-  --ifm-color-primary: #60a5fa;
-}
-EOF
-
-# Create static folder with placeholder favicon
-mkdir -p .specweave/cache/docs-site/static/img
-echo '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 100 100"><text y=".9em" font-size="90">📚</text></svg>' > .specweave/cache/docs-site/static/img/favicon.ico
-
-# Install dependencies using PUBLIC npm registry (avoids Azure DevOps/private registry issues)
-cd .specweave/cache/docs-site && npm install --registry=https://registry.npmjs.org --legacy-peer-deps
-```
-
-### Step 4: Start the Server
-
-```bash
-cd .specweave/cache/docs-site && npm start
-```
-
-This will:
-- Start Docusaurus on **http://localhost:3015**
-- Enable hot reload (edit markdown, see changes instantly)
-- Render Mermaid diagrams
-- Auto-generate sidebar from folder structure
-
-### Output to User
-
-After starting, display:
-
-```
-📚 Documentation Preview Server Started!
-
-   URL: http://localhost:3015
-   Content: .specweave/docs/internal/
-
-   Features:
-   • Hot reload - edit markdown, see changes instantly
-   • Mermaid diagrams - architecture diagrams render beautifully
-   • Auto sidebar - generated from folder structure
-   • Dark/light mode - toggle in navbar
-
-   Press Ctrl+C to stop the server.
-```
-
-## What You Get
-
-- **Hot reload** - Edit markdown, see changes instantly
-- **Auto sidebar** - Generated from folder structure
-- **Mermaid diagrams** - Architecture diagrams render beautifully
-- **Dark/light mode** - Toggle in navbar
-- **Local search** - Instant search across all docs
-
-## Troubleshooting
-
-### Port already in use
-```bash
-lsof -i :3015 && kill -9 $(lsof -t -i :3015)
-```
-
-### Reinstall from scratch
-```bash
-rm -rf .specweave/cache/docs-site && /specweave-docs:preview
-```
-
-### npm registry issues
-The setup uses `--registry=https://registry.npmjs.org` to bypass private registry configurations.
-
-## See Also
-
-- `/specweave-docs:build` - Build static site for deployment
-- `/specweave-docs:organize` - Generate themed indexes for large folders
-- `/specweave-docs:health` - Documentation health report