specweave 0.28.3 → 0.28.5

package/plugins/specweave-release/hooks/post-task-completion.sh.backup

@@ -0,0 +1,110 @@
+#!/bin/bash
+# Post-Increment-Completion Hook - DORA Metrics Tracking
+#
+# Fires after: /specweave:done completes
+# Purpose: Automatically track DORA metrics and update living docs dashboard
+#
+# Integration: plugins/specweave-release/hooks/hooks.json
+
+set -euo pipefail
+
+# Constants
+SPECWEAVE_ROOT="${SPECWEAVE_ROOT:-$(pwd)}"
+METRICS_DIR="${SPECWEAVE_ROOT}/.specweave/metrics"
+HISTORY_FILE="${METRICS_DIR}/dora-history.jsonl"
+DASHBOARD_FILE="${SPECWEAVE_ROOT}/.specweave/docs/internal/delivery/dora-dashboard.md"
+DORA_CALCULATOR="${SPECWEAVE_ROOT}/dist/src/metrics/dora-calculator.js"
+LATEST_FILE="${METRICS_DIR}/dora-latest.json"
+
+# Logging
+LOG_FILE="${SPECWEAVE_ROOT}/.specweave/logs/dora-tracking.log"
+mkdir -p "$(dirname "$LOG_FILE")"
+
+log() {
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] $*" | tee -a "$LOG_FILE"
+}
+
+log "🎯 Post-Increment-Completion Hook Triggered"
+
+# Check if DORA calculator exists
+if [[ ! -f "$DORA_CALCULATOR" ]]; then
+  log "⚠️  DORA calculator not found at $DORA_CALCULATOR"
+  log "   Run: npm run build"
+  exit 0  # Non-blocking
+fi
+
+# Check if GitHub token is available
+if [[ -z "${GITHUB_TOKEN:-}" ]]; then
+  log "⚠️  GITHUB_TOKEN not set. DORA metrics require GitHub API access."
+  log "   Set GITHUB_TOKEN in environment or .env file"
+  exit 0  # Non-blocking
+fi
+
+# Step 1: Calculate DORA metrics
+log "📊 Calculating DORA metrics..."
+if ! node "$DORA_CALCULATOR"; then
+  log "❌ Failed to calculate DORA metrics"
+  exit 0  # Non-blocking
+fi
+
+# Step 2: Append to history (JSONL format)
+log "💾 Appending metrics to history..."
+mkdir -p "$METRICS_DIR"
+
+if [[ -f "$LATEST_FILE" ]]; then
+  cat "$LATEST_FILE" >> "$HISTORY_FILE"
+  log "   ✓ Appended to $HISTORY_FILE"
+else
+  log "⚠️  Latest metrics file not found: $LATEST_FILE"
+fi
+
+# Step 3: Update living docs dashboard
+log "📝 Updating DORA dashboard..."
+DASHBOARD_GENERATOR="${SPECWEAVE_ROOT}/dist/plugins/specweave-release/lib/dashboard-generator.js"
+
+if [[ -f "$DASHBOARD_GENERATOR" ]]; then
+  if node "$DASHBOARD_GENERATOR"; then
+    log "   ✓ Dashboard updated: $DASHBOARD_FILE"
+  else
+    log "⚠️  Failed to update dashboard"
+  fi
+else
+  log "⚠️  Dashboard generator not found: $DASHBOARD_GENERATOR"
+  log "   Manual dashboard update required"
+fi
+
+# Step 4: Check for degradation (optional)
+log "🔍 Checking for metric degradation..."
+
+# Calculate 30-day average and compare with current
+# (This would be implemented in a TypeScript utility)
+# For now, we'll just log a reminder
+log "   ℹ️  Degradation detection: Manual review recommended"
+log "   See: $DASHBOARD_FILE for trends"
+
+# Step 5: Update main DORA metrics doc
+DORA_METRICS_DOC="${SPECWEAVE_ROOT}/.specweave/docs/internal/delivery/dora-metrics.md"
+if [[ -f "$DORA_METRICS_DOC" && -f "$LATEST_FILE" ]]; then
+  log "📄 Updating dora-metrics.md with latest values..."
+
+  # Extract current values from latest metrics
+  # (This is a simplified version - production would use jq for proper parsing)
+  TIMESTAMP=$(date '+%Y-%m-%d %H:%M UTC')
+
+  # Update "Last Calculated" timestamp
+  if command -v sed &> /dev/null; then
+    sed -i.bak "s/Last Calculated: .*/Last Calculated: $TIMESTAMP/" "$DORA_METRICS_DOC" 2>/dev/null || true
+    rm -f "${DORA_METRICS_DOC}.bak" 2>/dev/null || true
+    log "   ✓ Updated timestamp in dora-metrics.md"
+  fi
+fi
+
+log "✅ DORA metrics tracking complete!"
+log ""
+log "📊 Next steps:"
+log "   1. Review dashboard: $DASHBOARD_FILE"
+log "   2. Check trends: Are metrics improving?"
+log "   3. Take action: Address any degradation"
+log ""
+
+exit 0

package/plugins/specweave-ui/commands/ui-automate.md

@@ -11,10 +11,11 @@ Create and execute automated browser workflows using Playwright. Generate script
 ## What I Do
 
 1. **Workflow Planning**: Define step-by-step browser automation sequences
-2. **Script Generation**: Create Playwright TypeScript/JavaScript code
-3. **MCP Integration**: Use Playwright MCP server for browser control
-4. **Error Handling**: Add retry logic, timeouts, and fallbacks
-5. **Output Collection**: Capture screenshots, data, and validation results
+2. **Script Generation**: Create Playwright TypeScript/JavaScript code (code-first approach)
+3. **Error Handling**: Add retry logic, timeouts, and fallbacks
+4. **Output Collection**: Capture screenshots, data, and validation results
+
+> **Why Code-First?** Anthropic research shows [code execution beats MCP tool calls](https://www.anthropic.com/engineering/code-execution-with-mcp) with 98% token reduction. Playwright code is reusable, committable, CI-runnable, and deterministic.
 
 ## Workflow Types
 
@@ -108,30 +109,6 @@ async function automateWorkflow() {
 automateWorkflow();
 ```
 
-## MCP Server Integration
-
-Uses Playwright MCP server for enhanced capabilities:
-- **Session Management**: Reuse browser contexts
-- **Network Interception**: Mock APIs, block resources
-- **Performance Metrics**: Collect timing data
-- **Video Recording**: Capture automation runs
-- **Parallel Execution**: Run multiple automations concurrently
-
-### MCP Configuration
-
-Add to `.claude/mcp_server_config.json`:
-```json
-{
-  "playwright": {
-    "command": "npx",
-    "args": ["playwright-mcp-server"],
-    "env": {
-      "PLAYWRIGHT_BROWSERS_PATH": "~/.cache/playwright"
-    }
-  }
-}
-```
-
 ## Use Cases
 
 ### 1. Regression Testing

package/src/templates/AGENTS.md.template

@@ -77,6 +77,48 @@
 
 **CRITICAL**: Claude Code has automatic hooks. Other tools DO NOT.
 
+### Code-First Approach (MANDATORY for Non-Claude Tools)
+
+> **Engineering insight**: [Anthropic research](https://www.anthropic.com/engineering/code-execution-with-mcp) shows code execution achieves **98% token reduction** vs MCP tool calls.
+>
+> **For non-Claude tools, this is even MORE important** - MCP support varies, but `npx` works everywhere!
+
+**Rule**: Always prefer direct code execution over MCP:
+
+```bash
+# ❌ DON'T: Use Playwright MCP for testing
+# ✅ DO: Write Playwright tests and run with npx
+npx playwright test
+
+# ❌ DON'T: Use Kafka MCP for messaging
+# ✅ DO: Write kafkajs code
+import { Kafka } from 'kafkajs';
+const kafka = new Kafka({ brokers: ['localhost:9092'] });
+
+# ❌ DON'T: Chain multiple MCP tool calls
+# ✅ DO: Write a script that does all the work
+npx ts-node scripts/process-data.ts
+```
+
+**Why code is better**:
+| Aspect | MCP | Code (`npx`) |
+|--------|-----|--------------|
+| Token cost | High (tool defs + data duplication) | Low (only results) |
+| Reusability | Ephemeral | Committed to git |
+| CI/CD | Usually can't run | Native execution |
+| Debugging | Limited | Full stack traces |
+| Works with | Tools with MCP support | ANY tool |
+
+**Pattern for non-Claude tools**:
+```
+1. AI writes code (test, script, automation)
+2. You run: npx <command>
+3. AI analyzes output
+4. Repeat
+```
+
+This gives you the SAME experience as Claude Code with MCP, but deterministic and reusable!
+
 ### What's Different
 
 | Feature | Claude Code | Cursor/Copilot |
@@ -327,7 +369,40 @@ max_context_tokens: 10000
 
 {SKILLS_SECTION}
 
-**Usage**: Check SKILLS-INDEX.md, match task to skill, follow workflow.
+**Usage for Claude Code**: Skills auto-activate based on keywords in your prompt.
+
+**Usage for Non-Claude Tools (Cursor, Copilot, etc.)**:
+Skills don't auto-activate. You must manually load them:
+
+```bash
+# Step 1: Find relevant skill
+ls plugins/specweave*/skills/
+
+# Step 2: Read the skill file
+cat plugins/specweave/skills/increment-planner/SKILL.md
+
+# Step 3: Tell AI to follow the skill's workflow
+"Follow the increment-planner skill workflow to create my feature"
+
+# Step 4: AI reads skill content and follows instructions
+```
+
+**Skill Simulation Pattern**:
+```
+Non-Claude AI Tools simulate skills by:
+1. Reading SKILL.md files from plugins/ folder
+2. Following the workflow instructions inside
+3. Using the patterns and templates provided
+4. Running `npx` commands instead of MCP tools (code-first!)
+```
+
+**Example** - Creating increment with Cursor:
+```
+User: "Create an increment for user authentication"
+AI: [Reads plugins/specweave/skills/increment-planner/SKILL.md]
+AI: [Follows PM workflow: research → spec → plan → tasks]
+AI: [Creates .specweave/increments/0001-auth/spec.md, plan.md, tasks.md]
+```
 
 ---
 
@@ -436,20 +511,28 @@ Or run: `/specweave:sync-tasks`
 
 ### Skills/Agents Not Activating
 
-**Non-Claude tools**: Skills don't auto-activate.
+**Non-Claude tools**: Skills don't auto-activate. This is EXPECTED.
 
-**Manual activation**:
+**Manual activation (Cursor, Copilot, Windsurf, etc.)**:
 ```bash
-# 1. Check skills index
-cat .claude/skills/SKILLS-INDEX.md
+# 1. Find skills in plugins folder (NOT .claude/)
+ls plugins/specweave*/skills/
+
+# 2. Read the skill file
+cat plugins/specweave/skills/e2e-playwright/SKILL.md
 
-# 2. Match your task to a skill
-# 3. Load the skill manually
-cat .claude/skills/increment-planner/SKILL.md
+# 3. Tell AI to follow it
+"Read the e2e-playwright skill and write tests for my login page"
 
-# 4. Follow the skill's workflow
+# 4. AI writes code, YOU run it (code-first!)
+npx playwright test
 ```
 
+**Remember**: Non-Claude tools get SAME functionality by:
+- Reading skill files manually
+- Following the workflows inside
+- Running `npx` instead of MCP tools (better anyway!)
+
 ---
 
 ## Documentation