specweave 0.23.16 → 0.24.0

package/plugins/specweave/commands/check-hooks.md

@@ -1,257 +0,0 @@
----
-description: Validate hook health and display performance metrics (Tier 2 monitoring)
----
-
-# /specweave:check-hooks - Hook Health Dashboard
-
-**Purpose:** Display comprehensive hook performance metrics, detection rates, and health status.
-
-**Tier 2 Feature:** This command validates the PreToolUse coordination layer is working correctly.
-
----
-
-## Instructions for Claude
-
-When this command is executed, perform the following analysis:
-
-### 1. **Read Hook Metrics File**
-
-Location: `.specweave/state/hook-metrics.jsonl`
-
-The metrics file contains JSONL (JSON Lines) format - one JSON object per line.
-
-Each entry has:
-```json
-{
-  "timestamp": "2025-11-22T01:30:00Z",
-  "hook": "pre-edit-spec|post-edit-spec|pre-write-spec|post-write-spec",
-  "event": "file_detected|tier2_success|tier1_fallback",
-  "file_path": "/path/to/file.md",
-  "method": "pretooluse|env_content|env_result|env_args|mtime"
-}
-```
-
-### 2. **Calculate Key Metrics**
-
-**Tier 2 Success Rate:**
-```
-Tier 2 Rate = (tier2_success events) / (total post-tool events) * 100%
-```
-
-**Target:** >95% (Tier 2 should handle most cases)
-
-**Detection Method Breakdown:**
-- `pretooluse`: Tier 2 PreToolUse coordination (best)
-- `env_content`: Environment variable (TOOL_USE_CONTENT)
-- `env_result`: Environment variable (TOOL_RESULT)
-- `env_args`: Environment variable (TOOL_USE_ARGS)
-- `mtime`: File modification time fallback (Tier 1)
-
-**Fallback Rate:**
-```
-Fallback Rate = (mtime detections) / (total detections) * 100%
-```
-
-**Target:** <5% (should rarely need mtime fallback)
-
-### 3. **Check Hook Health Status**
-
-**Circuit Breaker Status:**
-- File: `.specweave/state/.hook-circuit-breaker`
-- If exists: Read failure count
-- If count ≥ 3: ⚠️ CIRCUIT BREAKER OPEN (hooks disabled)
-- If count < 3: ✅ Circuit breaker OK
-- If doesn't exist: ✅ No failures detected
-
-**Kill Switch Status:**
-- Check environment variable: `SPECWEAVE_DISABLE_HOOKS`
-- If set to "1": ⚠️ HOOKS MANUALLY DISABLED
-- If not set or "0": ✅ Hooks enabled
-
-**Lock Files Status:**
-- Check for stale locks:
-  - `.specweave/state/.hook-post-edit.lock`
-  - `.specweave/state/.hook-post-write.lock`
-- If older than 10 seconds: ⚠️ Stale lock detected
-- If not present: ✅ No locks
-
-### 4. **Read Recent Hook Logs**
-
-Location: `.specweave/logs/hooks-debug.log`
-
-**Look for:**
-- Recent errors or warnings
-- Debounce effectiveness (count "Debounced" messages)
-- PreToolUse signal messages
-- Circuit breaker trips
-
-**Time window:** Last 100 lines or last 1 hour
-
-### 5. **Output Format**
-
-Display results in this format:
-
-```
-🔍 SpecWeave Hook Health Dashboard (Tier 2)
-═══════════════════════════════════════════════════════════
-
-📊 DETECTION METRICS (Last 24 hours)
-────────────────────────────────────
-Total Hook Executions:        156
-Tier 2 Success (PreToolUse):  149 (95.5%) ✅
-Tier 1 Fallback (env vars):     5 (3.2%)
-Tier 1 Fallback (mtime):        2 (1.3%)
-
-Detection Method Breakdown:
-  • pretooluse:     149 (95.5%) ✅ Target: >95%
-  • env_content:      3 (1.9%)
-  • env_args:         2 (1.3%)
-  • mtime:            2 (1.3%)  ✅ Target: <5%
-
-🏥 HEALTH STATUS
-────────────────────────────────────
-Circuit Breaker:      ✅ OK (0 failures)
-Kill Switch:          ✅ Hooks enabled
-Stale Locks:          ✅ None detected
-Debounce Efficiency:  87% (136/156 skipped)
-
-⚡ PERFORMANCE
-────────────────────────────────────
-Average Hook Latency:     ~3ms
-Debounce Window:          5 seconds
-Background Updates:       Active
-Metrics Collection:       Active
-
-📝 RECENT ACTIVITY (Last 10 events)
-────────────────────────────────────
-[2025-11-22 01:30:15] post-edit-spec: File from PreToolUse signal: /path/to/spec.md
-[2025-11-22 01:30:10] pre-edit-spec: Signaled PostToolUse for: /path/to/spec.md
-[2025-11-22 01:29:45] post-edit-spec: Debounced (2s since last update)
-...
-
-✅ SUMMARY
-────────────────────────────────────
-Status: HEALTHY ✅
-
-Tier 2 coordination is working correctly (95.5% success rate).
-Fallback rate is within acceptable range (<5%).
-No health issues detected.
-
-Recommendations:
-  • None - system performing optimally
-
-To disable hooks temporarily:
-  export SPECWEAVE_DISABLE_HOOKS=1
-
-To reset circuit breaker:
-  rm .specweave/state/.hook-circuit-breaker
-```
-
-### 6. **Health Assessment Logic**
-
-**Determine overall status:**
-
-- ✅ **HEALTHY** if:
-  - Tier 2 success rate >90%
-  - Fallback rate <10%
-  - No circuit breaker trips
-  - Hooks enabled
-
-- ⚠️ **WARNING** if:
-  - Tier 2 success rate 70-90%
-  - Fallback rate 10-30%
-  - Circuit breaker count 1-2
-
-- ❌ **CRITICAL** if:
-  - Tier 2 success rate <70%
-  - Fallback rate >30%
-  - Circuit breaker open (count ≥ 3)
-  - Hooks manually disabled
-
-### 7. **Troubleshooting Recommendations**
-
-Based on status, provide targeted recommendations:
-
-**If Tier 2 success rate <95%:**
-```
-⚠️ PreToolUse coordination not working optimally
-
-Recommendations:
-1. Check if PreToolUse hooks are registered in plugin.json
-2. Verify hook files are executable (chmod +x)
-3. Review .specweave/logs/hooks-debug.log for PreToolUse errors
-4. Consider filing bug with Anthropic (environment variable passing)
-```
-
-**If fallback rate >10%:**
-```
-⚠️ High fallback rate detected
-
-Recommendations:
-1. Tier 2 coordination may not be working
-2. Environment variables still not being passed
-3. Consider Tier 3 implementation (filesystem watcher)
-```
-
-**If circuit breaker open:**
-```
-❌ Hooks disabled due to consecutive failures
-
-Immediate actions:
-1. Review .specweave/logs/hooks-debug.log for errors
-2. Fix underlying issues
-3. Reset circuit breaker: rm .specweave/state/.hook-circuit-breaker
-4. Restart Claude Code
-```
-
-### 8. **Error Handling**
-
-If metrics file doesn't exist:
-```
-⚠️ No metrics data available
-
-This is normal for:
-  • New SpecWeave installation
-  • First run after Tier 2 upgrade
-
-Metrics will be collected automatically as you work.
-Run this command again after a few Edit/Write operations.
-```
-
-If logs not accessible:
-```
-⚠️ Could not read hook logs
-
-Check file permissions:
-  .specweave/logs/hooks-debug.log
-  .specweave/state/hook-metrics.jsonl
-```
-
----
-
-## Implementation Notes
-
-**For Claude:**
-1. Parse JSONL file line by line (each line is a JSON object)
-2. Calculate metrics using simple counting
-3. Display results using the template above
-4. Adjust recommendations based on actual metrics
-5. Keep output concise but informative
-
-**Time-based filtering:**
-- Default: Last 24 hours
-- Option: All time (if user requests)
-- Filter by comparing timestamp field
-
-**Edge cases:**
-- Empty metrics file → Show "waiting for data" message
-- Corrupted JSONL → Skip invalid lines, report count
-- Missing state directory → Create it, show initialization message
-
----
-
-## Related Documentation
-
-- ADR-0060: Hook Performance Optimization
-- `.specweave/increments/0050-*/reports/hook-crash-analysis.md`
-- CLAUDE.md: "Hook Performance Best Practices"

package/plugins/specweave/commands/specweave-archive-increments.md

@@ -1,82 +0,0 @@
----
-name: specweave:archive-increments
-description: Archive completed increments to keep workspace clean
----
-
-# Archive Increments Command
-
-Archives completed increments to `_archive/` folder, keeping only the most recent N increments in the main folder.
-
-## Usage
-
-```bash
-# Interactive mode - prompts for options
-/specweave:archive-increments
-
-# Keep last 5 increments, archive the rest
-/specweave:archive-increments --keep-last 5
-
-# Archive specific increments
-/specweave:archive-increments --increments 0001,0002,0003
-
-# Dry run - see what would be archived without moving
-/specweave:archive-increments --dry-run
-
-# Archive all completed increments older than 30 days
-/specweave:archive-increments --older-than 30d
-
-# Keep only active/paused, archive all completed
-/specweave:archive-increments --archive-completed
-```
-
-## Default Behavior
-
-- Keeps last 10 increments by default
-- Preserves all active/paused increments
-- Never archives abandoned increments (they stay in `_abandoned/`)
-- Creates `_archive/` folder if it doesn't exist
-- Preserves increment structure and all contents
-
-## Smart Detection
-
-The command intelligently:
-- Checks increment status from metadata.json
-- Preserves increments with active GitHub/JIRA/ADO issues
-- Warns before archiving increments with uncommitted changes
-- Groups related increments (e.g., all v0.8.0 stabilization increments)
-
-## Configuration
-
-Set defaults in `.specweave/config.json`:
-
-```json
-{
-  "archiving": {
-    "keepLast": 10,
-    "autoArchive": true,
-    "archiveAfterDays": 60,
-    "preserveActive": true,
-    "archiveCompleted": true
-  }
-}
-```
-
-## Examples
-
-### Keep workspace clean
-```bash
-# Archive all but last 5 increments
-/specweave:archive-increments --keep-last 5
-```
-
-### Prepare for release
-```bash
-# Archive all v0.7.x increments after v0.8.0 release
-/specweave:archive-increments --pattern "v0.7"
-```
-
-### Clean old work
-```bash
-# Archive increments older than 2 months
-/specweave:archive-increments --older-than 60d
-```

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

@@ -1,340 +0,0 @@
----
-name: plugin-expert
-description: Expert knowledge of Claude Code's plugin system, marketplace management, and installation commands. Activates for plugin installation, marketplace setup, plugin troubleshooting, plugin commands. Keywords plugin install, plugin marketplace, claude code plugins, plugin management, plugin errors, marketplace add, plugin list.
----
-
-# Plugin Expert - Claude Code Plugin System Authority
-
-**Purpose**: Authoritative source of truth for Claude Code's plugin system, marketplace management, and correct installation syntax.
-
-**When to Consult**: ANY time you need to install, manage, or reference Claude Code plugins.
-
----
-
-## 🚨 CRITICAL: Correct Plugin Installation Format
-
-**ALWAYS use this format**:
-```bash
-/plugin install <plugin-name>
-```
-
-**Examples**:
-```bash
-# ✅ CORRECT
-/plugin install specweave-github
-/plugin install specweave-jira
-/plugin install specweave-kubernetes
-
-# ❌ WRONG - NEVER use @marketplace suffix
-/plugin install specweave-github@specweave
-/plugin install specweave-jira@specweave
-```
-
-**Why this matters**:
-- Claude Code automatically resolves plugins from registered marketplaces
-- The `@marketplace` syntax does NOT exist in Claude Code
-- Using wrong syntax causes installation failures
-
----
-
-## Official Documentation
-
-**Primary Sources** (ALWAYS defer to these):
-1. **Plugin System**: https://code.claude.com/docs/en/plugins
-2. **Marketplaces**: https://code.claude.com/docs/en/plugin-marketplaces
-3. **Blog Post**: https://claude.com/blog/claude-code-plugins
-
----
-
-## Plugin Commands Reference
-
-### Installation
-
-```bash
-# Install plugin from registered marketplace
-/plugin install <plugin-name>
-
-# Examples
-/plugin install specweave
-/plugin install specweave-github
-/plugin install specweave-jira
-```
-
-### Marketplace Management
-
-```bash
-# List all available marketplaces
-/plugin marketplace list
-
-# Add marketplace (GitHub)
-/plugin marketplace add <owner>/<repo>
-# Example: /plugin marketplace add anton-abyzov/specweave
-
-# Add marketplace (local directory - development only)
-/plugin marketplace add /path/to/.claude-plugin
-
-# Remove marketplace
-/plugin marketplace remove <marketplace-name>
-```
-
-### Plugin Management
-
-```bash
-# List installed plugins
-/plugin list --installed
-
-# List all available plugins from marketplaces
-/plugin list
-
-# Get plugin info
-/plugin info <plugin-name>
-
-# Uninstall plugin
-/plugin uninstall <plugin-name>
-
-# Update plugin
-/plugin update <plugin-name>
-```
-
----
-
-## SpecWeave Marketplace Setup
-
-### User Projects (Production)
-
-SpecWeave automatically registers the GitHub marketplace during `specweave init`:
-
-**File**: `.claude/settings.json`
-```json
-{
-  "extraKnownMarketplaces": {
-    "specweave": {
-      "source": {
-        "source": "github",
-        "repo": "anton-abyzov/specweave",
-        "path": ".claude-plugin"
-      }
-    }
-  }
-}
-```
-
-**Result**: Claude Code fetches plugins from GitHub on-demand (no local copies)
-
-### SpecWeave Repo (Development)
-
-For contributors working on SpecWeave itself:
-
-```bash
-# Add local marketplace (CLI only - settings.json doesn't support local paths)
-/plugin marketplace add ./.claude-plugin
-
-# Then install plugins
-/plugin install specweave
-/plugin install specweave-github
-```
-
----
-
-## Available SpecWeave Plugins
-
-### Core (Auto-Installed)
-
-- **specweave** - Framework essentials (increment planning, PM/Architect agents, living docs)
-  - Auto-installed during `specweave init`
-  - Provides: 9 skills, 22 agents, 22 commands, 8 hooks
-
-### Issue Trackers
-
-- **specweave-github** - GitHub Issues integration
-  - Install: `/plugin install specweave-github`
-  - Provides: GitHub sync, PR automation, issue tracking
-
-- **specweave-jira** - Jira integration
-  - Install: `/plugin install specweave-jira`
-  - Provides: Jira sync, epic management, sprint tracking
-
-- **specweave-ado** - Azure DevOps integration
-  - Install: `/plugin install specweave-ado`
-  - Provides: ADO work items, boards, sprints
-
-### Tech Stacks
-
-- **specweave-frontend** - React, Next.js, Vue, Angular
-  - Install: `/plugin install specweave-frontend`
-  - Provides: Frontend expert agent, component generation, design system integration
-
-- **specweave-kubernetes** - K8s, Helm, kubectl
-  - Install: `/plugin install specweave-kubernetes`
-  - Provides: K8s expert agent, Helm chart generation, deployment validation
-
-- **specweave-ml** - TensorFlow, PyTorch, ML workflows
-  - Install: `/plugin install specweave-ml`
-  - Provides: ML expert agent, training pipelines, model deployment
-
-### Utilities
-
-- **specweave-diagrams** - Mermaid + C4 diagrams
-  - Install: `/plugin install specweave-diagrams`
-  - Provides: Architecture diagram generation, C4 model support
-
----
-
-## Common Mistakes to Avoid
-
-### ❌ Wrong: Using @marketplace Syntax
-
-```bash
-# NEVER DO THIS
-/plugin install specweave-github@specweave
-/plugin install specweave-jira@specweave
-```
-
-**Why wrong**: Claude Code doesn't support `@marketplace` suffix
-
-**Correct**:
-```bash
-/plugin install specweave-github
-/plugin install specweave-jira
-```
-
-### ❌ Wrong: Using Local Paths in settings.json
-
-```json
-{
-  "extraKnownMarketplaces": {
-    "specweave": {
-      "source": "./.claude-plugin"  // ❌ NOT supported
-    }
-  }
-}
-```
-
-**Why wrong**: `extraKnownMarketplaces` in settings.json only supports remote sources (GitHub, Git)
-
-**Correct for development**:
-```bash
-# Use CLI instead
-/plugin marketplace add ./.claude-plugin
-```
-
-### ❌ Wrong: Forgetting Marketplace Registration
-
-```bash
-# Install without marketplace registered
-/plugin install specweave-github  # ❌ Fails: marketplace not found
-```
-
-**Correct**:
-```bash
-# 1. Register marketplace first (or ensure settings.json has it)
-/plugin marketplace add anton-abyzov/specweave
-
-# 2. Then install plugins
-/plugin install specweave-github
-```
-
----
-
-## Troubleshooting
-
-### "Marketplace not found" Error
-
-**Symptom**: `/plugin install specweave-xxx` fails with "marketplace not found"
-
-**Fix**:
-```bash
-# Check registered marketplaces
-/plugin marketplace list
-
-# If specweave not listed, add it
-/plugin marketplace add anton-abyzov/specweave
-
-# Then retry install
-/plugin install specweave-xxx
-```
-
-### Plugin Not Auto-Activating
-
-**Symptom**: Plugin installed but skills/agents not working
-
-**Causes**:
-1. Claude Code needs restart after plugin install
-2. Skill description keywords don't match user's context
-3. Plugin has errors (check plugin logs)
-
-**Fix**:
-```bash
-# 1. Verify plugin installed
-/plugin list --installed
-
-# 2. Restart Claude Code
-
-# 3. Check skill descriptions match your context
-```
-
-### Installation Hangs or Fails
-
-**Symptom**: `/plugin install` hangs or times out
-
-**Causes**:
-1. Network issues (GitHub fetch failed)
-2. Marketplace not registered
-3. Plugin doesn't exist in marketplace
-
-**Fix**:
-```bash
-# 1. Check marketplace registered
-/plugin marketplace list
-
-# 2. Verify plugin exists
-/plugin list  # Shows all available plugins
-
-# 3. Check network connectivity
-# Try re-adding marketplace (refreshes cache)
-/plugin marketplace remove specweave
-/plugin marketplace add anton-abyzov/specweave
-```
-
----
-
-## How Other Skills Should Use This
-
-**Example: increment-planner skill recommending plugins**
-
-```markdown
-**Step 6: Detect Required Plugins**
-
-When recommending plugins, ALWAYS use correct format:
-
-✅ CORRECT:
-📦 Install recommended plugins:
-  /plugin install specweave-github
-  /plugin install specweave-kubernetes
-
-❌ WRONG:
-  /plugin install specweave-github@specweave  # NEVER use @marketplace
-```
-
-**Example: Auto-installation in TypeScript**
-
-```typescript
-// ✅ CORRECT
-execFileNoThrowSync('claude', ['plugin', 'install', 'specweave-github']);
-
-// ❌ WRONG
-execFileNoThrowSync('claude', ['plugin', 'install', 'specweave-github@specweave']);
-```
-
----
-
-## References
-
-- **Official Docs**: https://code.claude.com/docs/en/plugins
-- **Marketplaces**: https://code.claude.com/docs/en/plugin-marketplaces
-- **Blog**: https://claude.com/blog/claude-code-plugins
-- **SpecWeave Marketplace**: https://github.com/anton-abyzov/specweave/.claude-plugin
-
----
-
-**Last Updated**: 2025-01-06 (v0.8.18)