specweave 0.23.2 → 0.23.5

package/plugins/specweave/agents/infrastructure/AGENT.md

@@ -10,6 +10,22 @@ capabilities:
   - Security best practices integration
 ---
 
+# infrastructure Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:infrastructure:infrastructure",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: infrastructure (folder name)
+// - name: infrastructure (from YAML frontmatter above)
+```
 # Infrastructure Agent
 
 I'm a serverless infrastructure specialist who generates production-ready Infrastructure-as-Code (IaC) using Terraform. I transform platform recommendations from the architect agent into deployable infrastructure configurations.

package/plugins/specweave/agents/performance/AGENT.md

@@ -8,6 +8,22 @@ cost_profile: planning
 fallback_behavior: strict
 ---
 
+# performance Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:performance:performance",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: performance (folder name)
+// - name: performance (from YAML frontmatter above)
+```
 # Performance Agent - Optimization & Scalability Expert
 
 You are an expert Performance Engineer with 10+ years of experience optimizing web applications, databases, and distributed systems.

package/plugins/specweave/agents/pm/AGENT.md

@@ -8,6 +8,23 @@ cost_profile: planning
 fallback_behavior: strict
 ---
 
+# Product Manager Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:pm:pm",
+  prompt: "Create product requirements for user dashboard feature"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: pm (folder name)
+// - name: pm (from YAML frontmatter above)
+```
+
 # PM Agent - Product Manager AI Assistant
 
 ## ⛔ CRITICAL: Increment Folder Structure (MANDATORY)

package/plugins/specweave/agents/qa-lead/AGENT.md

@@ -10,6 +10,21 @@ fallback_behavior: flexible
 
 # QA Lead Agent
 
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:qa-lead:qa-lead",
+  prompt: "Create test strategy for permission gates feature"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: qa-lead (folder name)
+// - name: qa-lead (from YAML frontmatter above)
+```
+
 ## 📚 Required Reading (LOAD FIRST)
 
 **CRITICAL**: Before creating test strategies, read this guide:

package/plugins/specweave/agents/reflective-reviewer/AGENT.md

@@ -9,6 +9,22 @@ description: |
 allowed-tools: Read, Grep, Glob
 ---
 
+# reflective-reviewer Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:reflective-reviewer:reflective-reviewer",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: reflective-reviewer (folder name)
+// - name: reflective-reviewer (from YAML frontmatter above)
+```
 # Reflective Reviewer Agent
 
 You are a senior software engineer performing self-reflection on recently completed work. Your role is to analyze code changes comprehensively and provide actionable feedback that helps developers catch issues early, improve code quality, and learn from experience.

package/plugins/specweave/agents/security/AGENT.md

@@ -8,6 +8,22 @@ cost_profile: planning
 fallback_behavior: strict
 ---
 
+# security Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:security:security",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: security (folder name)
+// - name: security (from YAML frontmatter above)
+```
 # Security Agent - Application Security & Threat Modeling Expert
 
 You are an expert Security Engineer with 10+ years of experience in application security, penetration testing, and security compliance across web and cloud applications.

package/plugins/specweave/agents/tdd-orchestrator/AGENT.md

@@ -7,6 +7,22 @@ cost_profile: execution
 fallback_behavior: flexible
 ---
 
+# tdd-orchestrator Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:tdd-orchestrator:tdd-orchestrator",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: tdd-orchestrator (folder name)
+// - name: tdd-orchestrator (from YAML frontmatter above)
+```
 You are an expert TDD orchestrator specializing in comprehensive test-driven development coordination, modern TDD practices, and multi-agent workflow management.
 
 ## Expert Purpose

package/plugins/specweave/agents/tech-lead/AGENT.md

@@ -8,6 +8,22 @@ cost_profile: execution
 fallback_behavior: flexible
 ---
 
+# tech-lead Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:tech-lead:tech-lead",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: tech-lead (folder name)
+// - name: tech-lead (from YAML frontmatter above)
+```
 # Tech Lead Agent - Technical Leadership & Code Excellence
 
 You are an expert Technical Lead with 12+ years of hands-on development experience and 5+ years leading engineering teams. You bridge the gap between architecture and implementation, ensuring code quality, team productivity, and technical excellence.

package/plugins/specweave/agents/test-aware-planner/AGENT.md

@@ -8,6 +8,22 @@ cost_profile: planning
 fallback_behavior: strict
 ---
 
+# test-aware-planner Agent
+
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:test-aware-planner:test-aware-planner",
+  prompt: "Your task description here"
+});
+
+// Naming pattern: {plugin}:{directory}:{name-from-yaml}
+// - plugin: specweave
+// - directory: test-aware-planner (folder name)
+// - name: test-aware-planner (from YAML frontmatter above)
+```
 # Test-Aware Planner Agent
 
 **Role**: Generate implementation tasks with embedded test plans (NO separate tests.md)

package/plugins/specweave/agents/translator/AGENT.md

@@ -1,5 +1,18 @@
 # Translator Agent
 
+## 🚀 How to Invoke This Agent
+
+```typescript
+// CORRECT invocation
+Task({
+  subagent_type: "specweave:translator:AGENT",
+  prompt: "Translate documentation to Spanish"
+});
+
+// Note: This agent uses a special naming pattern
+// Check the plugin configuration for the exact subagent_type
+```
+
 **Role**: Batch Translation Specialist
 **Expertise**: Multi-file translation coordination, consistency management, quality assurance
 **Uses**: translator skill (for actual translation work)

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

@@ -59,6 +59,20 @@ You are acting as the Product Manager to validate increment completion before cl
 
 ```typescript
 import { IncrementCompletionValidator } from '../../../src/core/increment/completion-validator.js';
+import { DesyncDetector } from '../../../src/core/increment/desync-detector.js';
+
+// **NEW (2025-11-20)**: Validate no status desync exists
+// This prevents closing increments with inconsistent metadata.json and spec.md
+const desyncDetector = new DesyncDetector();
+try {
+  await desyncDetector.validateOrThrow(incrementId);
+} catch (error) {
+  console.error('❌ CANNOT CLOSE INCREMENT - Status desync detected');
+  console.error('');
+  console.error(error.message);
+  console.error('');
+  process.exit(1);
+}
 
 // Validate increment is ready for completion
 const validation = await IncrementCompletionValidator.validateCompletion(incrementId);

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

@@ -73,7 +73,17 @@ The command runs 120+ validation checks on increment files:
 
 ### Step 2: AI Quality Assessment (Optional, skip with `--no-ai`)
 
-Invoke the `increment-quality-judge-v2` skill to evaluate:
+**IMPORTANT**: This step uses the `increment-quality-judge-v2` **agent** (not skill).
+
+If implementing programmatically, invoke via Task tool:
+```typescript
+Task({
+  subagent_type: "specweave:increment-quality-judge-v2:increment-quality-judge-v2",
+  prompt: `Assess quality of increment ${incrementId}`
+});
+```
+
+The agent evaluates:
 - **7 Dimensions**:
   1. Clarity (18% weight)
   2. Testability (22% weight)

package/plugins/specweave/commands/specweave-sync-status.md

@@ -0,0 +1,356 @@
+---
+name: specweave:sync-status
+description: Detect and fix status desyncs between metadata.json and spec.md
+---
+
+# Sync Status - Desync Detection & Recovery
+
+**CRITICAL**: Detects and fixes status desyncs between metadata.json and spec.md to maintain source-of-truth integrity.
+
+## Overview
+
+This command scans increments for status desyncs where metadata.json and spec.md have different status values. This violates CLAUDE.md Rule #7 (source-of-truth discipline) and causes:
+- Status line showing wrong increment
+- Commands operating on wrong data
+- User confusion and broken trust
+
+**Incident Reference**: 2025-11-20 - Silent failure in /specweave:done caused increment 0047 to have metadata.json="completed" while spec.md="active", breaking status line.
+
+## Usage
+
+```bash
+# Scan all increments for desyncs
+/specweave:sync-status
+
+# Check specific increment
+/specweave:sync-status 0047
+
+# Auto-fix all desyncs (non-interactive)
+/specweave:sync-status --fix
+
+# Scan and show detailed report
+/specweave:sync-status --verbose
+```
+
+## Arguments
+
+- `<increment-id>` - Optional. Specific increment to check (e.g., "0047", "0001-test")
+- `--fix` - Auto-fix all desyncs without prompting
+- `--verbose` - Show detailed report including healthy increments
+
+---
+
+## Workflow
+
+### Mode 1: Scan All Increments (Default)
+
+**When to use**: Regular maintenance, pre-commit checks, incident investigation
+
+**Steps**:
+
+1. **Scan all increments**:
+   ```typescript
+   import { DesyncDetector } from '../../../src/core/increment/desync-detector.js';
+
+   const detector = new DesyncDetector();
+   const report = await detector.scanAll();
+   ```
+
+2. **Display report**:
+   ```typescript
+   console.log(detector.formatReport(report));
+   ```
+
+3. **Example output** (desyncs found):
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   STATUS DESYNC DETECTION REPORT
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Total Scanned: 47 increments
+   Healthy: 46
+   Desyncs Found: 1 ⚠️
+   Errors: 0
+
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   DESYNCS DETECTED (CRITICAL!)
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   ❌ 0047-us-task-linkage
+      metadata.json: completed
+      spec.md:       active
+
+   Fix command: /specweave:sync-status --fix
+
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+4. **If desyncs found, prompt user**:
+   ```typescript
+   if (report.totalDesyncs > 0) {
+     const shouldFix = await promptUser(
+       `Found ${report.totalDesyncs} desync(s). Fix them? (y/n): `
+     );
+
+     if (shouldFix) {
+       // Fix all desyncs
+       for (const desync of report.desyncs) {
+         const fixed = await detector.fixDesync(desync.incrementId);
+         if (fixed) {
+           console.log(`✅ Fixed ${desync.incrementId}`);
+         } else {
+           console.error(`❌ Failed to fix ${desync.incrementId}`);
+         }
+       }
+
+       console.log('');
+       console.log('All desyncs fixed! Run /specweave:sync-status to verify.');
+     }
+   }
+   ```
+
+5. **Example output** (no desyncs):
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   STATUS DESYNC DETECTION REPORT
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   Total Scanned: 47 increments
+   Healthy: 47
+   Desyncs Found: 0 ⚠️
+   Errors: 0
+
+   ✅ All increments healthy - no desyncs detected!
+
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+### Mode 2: Check Specific Increment
+
+**When to use**: Investigating specific increment, post-fix verification
+
+**Steps**:
+
+1. **Check increment**:
+   ```typescript
+   const detector = new DesyncDetector();
+   const result = await detector.checkIncrement(incrementId);
+   ```
+
+2. **Display result**:
+   ```typescript
+   if (result.error) {
+     console.error(`❌ Error checking ${incrementId}: ${result.error}`);
+     process.exit(1);
+   }
+
+   if (result.hasDesync) {
+     console.log('━'.repeat(80));
+     console.log(`❌ DESYNC DETECTED: ${incrementId}`);
+     console.log('━'.repeat(80));
+     console.log('');
+     console.log(`metadata.json: ${result.metadataStatus}`);
+     console.log(`spec.md:       ${result.specStatus}`);
+     console.log('');
+     console.log('This violates source-of-truth discipline (CLAUDE.md Rule #7)');
+     console.log('');
+     console.log(`Fix: /specweave:sync-status ${incrementId} --fix`);
+     console.log('━'.repeat(80));
+   } else {
+     console.log(`✅ ${incrementId} - No desync detected`);
+     console.log(`   Status: ${result.metadataStatus}`);
+   }
+   ```
+
+3. **Example output** (desync found):
+   ```
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ❌ DESYNC DETECTED: 0047-us-task-linkage
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+   metadata.json: completed
+   spec.md:       active
+
+   This violates source-of-truth discipline (CLAUDE.md Rule #7)
+
+   Fix: /specweave:sync-status 0047 --fix
+   ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+   ```
+
+### Mode 3: Auto-Fix (Non-Interactive)
+
+**When to use**: CI/CD pipelines, automated recovery, pre-commit hooks
+
+**Steps**:
+
+1. **Scan and fix**:
+   ```typescript
+   const detector = new DesyncDetector();
+   const report = await detector.scanAll();
+
+   if (report.totalDesyncs > 0) {
+     console.log(`Found ${report.totalDesyncs} desync(s) - fixing...`);
+     console.log('');
+
+     for (const desync of report.desyncs) {
+       const fixed = await detector.fixDesync(desync.incrementId);
+       if (fixed) {
+         console.log(`✅ Fixed ${desync.incrementId}: ${desync.specStatus} → ${desync.metadataStatus}`);
+       } else {
+         console.error(`❌ Failed to fix ${desync.incrementId}`);
+       }
+     }
+
+     console.log('');
+     console.log('✅ All desyncs fixed!');
+   } else {
+     console.log('✅ No desyncs found - all healthy');
+   }
+   ```
+
+2. **Example output**:
+   ```
+   Found 1 desync(s) - fixing...
+
+   ✅ Fixed 0047-us-task-linkage: active → completed
+
+   ✅ All desyncs fixed!
+   ```
+
+---
+
+## How Desyncs Are Fixed
+
+**Fix Strategy**: metadata.json is considered the source of truth for status updates.
+
+**Rationale**:
+- metadata.json is updated atomically by CLI commands
+- metadata.json is used for increment state management
+- spec.md should mirror metadata.json for consistency
+
+**Fix Process**:
+1. Read current status from metadata.json
+2. Read current status from spec.md
+3. Update spec.md frontmatter to match metadata.json
+4. Write spec.md atomically (temp file → rename)
+5. Verify fix by re-checking
+
+**What gets updated**:
+- ✅ spec.md YAML frontmatter `status` field
+- ❌ metadata.json (already correct)
+
+**Example fix**:
+```yaml
+# Before (spec.md)
+---
+status: active
+---
+
+# After (spec.md)
+---
+status: completed
+---
+```
+
+---
+
+## Post-Fix Actions
+
+After fixing desyncs, the following actions happen automatically:
+
+1. **Status Line Cache Update**:
+   ```bash
+   # Automatically triggered by spec.md change
+   bash plugins/specweave/hooks/lib/update-status-line.sh
+   ```
+
+2. **Git Status**:
+   ```bash
+   # spec.md will be modified - commit the fix
+   git status
+   git add .specweave/increments/*/spec.md
+   git commit -m "fix: sync spec.md status with metadata.json"
+   ```
+
+3. **Verification**:
+   ```bash
+   # Verify no desyncs remain
+   /specweave:sync-status
+   ```
+
+---
+
+## Error Handling
+
+### Increment Not Found
+```
+❌ Error: Increment 0047-us-task-linkage not found
+
+Check increment ID and try again.
+```
+
+### File Permission Error
+```
+❌ Failed to fix desync for 0047-us-task-linkage
+Error: EACCES: permission denied, open '.specweave/increments/0047-us-task-linkage/spec.md'
+
+Fix permissions:
+  chmod u+w .specweave/increments/0047-us-task-linkage/spec.md
+```
+
+### YAML Parse Error
+```
+❌ Failed to fix desync for 0047-us-task-linkage
+Error: Invalid YAML frontmatter in spec.md
+
+Check YAML syntax:
+  vim .specweave/increments/0047-us-task-linkage/spec.md
+```
+
+---
+
+## Prevention
+
+**To prevent future desyncs**:
+
+1. ✅ **Fixed in v0.23.0+**: Atomic transaction pattern in `metadata-manager.ts`
+   - Updates spec.md FIRST, then metadata.json
+   - If spec.md fails, metadata.json is never updated
+   - No silent failures
+
+2. ✅ **Added in v0.23.0+**: Desync detection in `/specweave:done`
+   - Validates before closing increment
+   - Blocks closure if desync detected
+
+3. ✅ **Added in v0.23.0+**: Pre-commit hook validation
+   - Scans for desyncs before commit
+   - Blocks commit if desyncs found
+   - Auto-fix option available
+
+4. ✅ **Added in v0.23.0+**: Comprehensive tests
+   - Unit tests for DesyncDetector
+   - Integration tests for status updates
+   - E2E tests for recovery scenarios
+
+---
+
+## Related Commands
+
+- `/specweave:done` - Close increment (includes desync validation)
+- `/specweave:validate` - Validate increment quality
+- `/specweave:status` - Show increment status overview
+
+---
+
+## Related Files
+
+- `src/core/increment/desync-detector.ts` - Detection & fix logic
+- `src/core/increment/metadata-manager.ts` - Atomic status updates
+- `src/core/increment/spec-frontmatter-updater.ts` - spec.md updates
+- `scripts/pre-commit-desync-check.sh` - Pre-commit validation
+
+---
+
+**Important**: This command is part of the incident response to the 2025-11-20 silent failure bug. It ensures source-of-truth discipline is maintained across the entire increment lifecycle.
+
+**Best Practice**: Run `/specweave:sync-status` regularly (weekly or before releases) to catch any desyncs early.

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

@@ -232,7 +232,16 @@ Choice: _
 
 ### Step 4: Run AI Quality Assessment (If Approved)
 
-**Invoke `increment-quality-judge` skill** with these parameters:
+**IMPORTANT**: Invoke `increment-quality-judge-v2` **agent** (not skill) via Task tool:
+
+```typescript
+Task({
+  subagent_type: "specweave:increment-quality-judge-v2:increment-quality-judge-v2",
+  prompt: `Assess quality of increment ${incrementId}`
+});
+```
+
+Pass these parameters:
 - increment_id: "0001"
 - files: ["spec.md", "plan.md", "tests.md"]
 - dimensions: ["clarity", "testability", "completeness", "feasibility", "maintainability", "edge_cases"]