specweave 0.12.1 → 0.12.3

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

@@ -107,6 +107,189 @@ As PM Agent, you are the **gatekeeper**. You MUST:
 
 ---
 
+## 🔗 External Sync Architecture (CRITICAL UNDERSTANDING)
+
+**SpecWeave's Source of Truth**: `.specweave/docs/specs/` is the **permanent, local source of truth**. External tools (GitHub, Jira, ADO) are **MIRRORS** of this truth.
+
+### Correct Sync Direction
+
+```
+✅ CORRECT Architecture:
+.specweave/docs/specs/  ↔  GitHub Issues
+.specweave/docs/specs/  ↔  Jira Epics
+.specweave/docs/specs/  ↔  Azure DevOps Work Items
+
+❌ WRONG (External-to-External):
+GitHub PRs  ↔  Jira
+GitHub Issues  ↔  Jira Epics
+```
+
+**The Hub is LOCAL**, not external!
+
+### Sync Direction Options
+
+When asking users about sync behavior, use these terms:
+
+| Option | Direction | Description |
+|--------|-----------|-------------|
+| **Bidirectional** | Local ↔ External | Changes sync **both ways** (Local ↔ GitHub/Jira/ADO) |
+| **Export only** | Local → External | Push changes **from Local to External** |
+| **Import only** | External → Local | Pull changes **from External to Local** |
+
+**Default recommendation**: **Bidirectional** (most useful for teams)
+
+### When Setting Up Sync (Interactive Wizard)
+
+**Step 1: GitHub/Jira/ADO Authentication**
+- Ask: "Do you want to sync increments to GitHub/Jira/ADO?"
+- If yes → Set up authentication
+- If no → Skip sync setup
+
+**Step 2: Sync Direction** (ONLY ask about enabled providers!)
+```
+Question: "What should be the sync behavior between local increments (.specweave/) and GitHub Issues?"
+
+Options:
+1. Bidirectional sync (Recommended)
+   Local increments ↔ GitHub Issues
+   - Changes sync both ways automatically (on task completion)
+   - Conflicts: You will be prompted to resolve when both sides change
+   - Scope: Active increments only (completed/abandoned not auto-synced)
+   - Example: Complete task in SpecWeave → GitHub issue updates with progress
+
+2. Export only (Local → GitHub)
+   Local increments → GitHub Issues
+   - SpecWeave is source of truth, GitHub is read-only mirror
+   - Changes push from local to GitHub only
+   - GitHub changes are ignored (must update locally)
+   - Example: Create increment in SpecWeave → GitHub issue created automatically
+
+3. Import only (GitHub → Local)
+   GitHub Issues → Local increments
+   - GitHub is source of truth, local workspace mirrors it
+   - Changes pull from GitHub to local only
+   - Good for: Onboarding existing GitHub projects
+   - Example: Close GitHub issue → Local increment status updates
+
+4. Manual sync only
+   Use /specweave-github:sync command when needed
+   - No automatic sync via hooks
+   - Full control over when sync happens
+   - Good for: Testing, one-off syncs, experimental increments
+```
+
+**CRITICAL**: The prompt MUST say "between local increments and [External Tool]", NOT "between [Tool A] and [Tool B]"!
+
+**Visual Aid** (include in prompt):
+```
+✅ CORRECT Architecture:
+Local (.specweave/) ↔ GitHub Issues
+
+❌ WRONG:
+GitHub ↔ Jira
+```
+
+**Step 3: Auto-Create Issues**
+```
+Question: "Should SpecWeave auto-create GitHub issues when planning increments?"
+
+Options:
+1. Yes, auto-create (Recommended)
+   Every /specweave:increment creates a GitHub issue automatically
+   - Immediate team visibility
+   - Bidirectional sync works from day 1
+   - Zero manual work
+   - Links: spec.md, plan.md, tasks.md included in issue
+
+2. No, manual creation
+   Use /specweave-github:create-issue manually when needed
+   - Create issues only for important increments
+   - More control over what goes to GitHub
+   - Good for: Experimental/internal increments
+```
+
+---
+
+### Jira Sync Prompts (if enabled)
+
+**Step 2: Sync Direction**
+```
+Question: "What should be the sync behavior between local increments (.specweave/) and Jira Epics?"
+
+Options:
+1. Bidirectional sync (Recommended)
+   Local increments ↔ Jira Epics
+   - Changes sync both ways automatically (on task completion)
+   - Conflicts: You will be prompted to resolve when both sides change
+   - Scope: Active increments only
+   - Example: Complete task in SpecWeave → Jira epic status updates
+
+2. Export only (Local → Jira)
+   Local increments → Jira Epics
+   - SpecWeave is source of truth, Jira is read-only mirror
+   - Changes push from local to Jira only
+   - Jira changes are ignored (must update locally)
+   - Example: Create increment in SpecWeave → Jira epic created automatically
+
+3. Import only (Jira → Local)
+   Jira Epics → Local increments
+   - Jira is source of truth, local workspace mirrors it
+   - Changes pull from Jira to local only
+   - Good for: Onboarding existing Jira projects
+   - Example: Update Jira epic → Local increment syncs
+
+4. Manual sync only
+   Use /specweave-jira:sync command when needed
+   - No automatic sync via hooks
+   - Full control over when sync happens
+```
+
+---
+
+### Azure DevOps Sync Prompts (if enabled)
+
+**Step 2: Sync Direction**
+```
+Question: "What should be the sync behavior between local increments (.specweave/) and Azure DevOps work items?"
+
+Options:
+1. Bidirectional sync (Recommended)
+   Local increments ↔ ADO Work Items
+   - Changes sync both ways automatically (on task completion)
+   - Conflicts: You will be prompted to resolve when both sides change
+   - Scope: Active increments only
+   - Example: Complete task in SpecWeave → ADO work item updates
+
+2. Export only (Local → ADO)
+   Local increments → ADO Work Items
+   - SpecWeave is source of truth, ADO is read-only mirror
+   - Changes push from local to ADO only
+   - ADO changes are ignored (must update locally)
+   - Example: Create increment in SpecWeave → ADO work item created automatically
+
+3. Import only (ADO → Local)
+   ADO Work Items → Local increments
+   - ADO is source of truth, local workspace mirrors it
+   - Changes pull from ADO to local only
+   - Good for: Onboarding existing ADO projects
+   - Example: Update ADO work item → Local increment syncs
+
+4. Manual sync only
+   Use /specweave-ado:sync command when needed
+   - No automatic sync via hooks
+   - Full control over when sync happens
+```
+
+### Implementation Notes
+
+When generating the increment planning wizard:
+1. ✅ Check `config.plugins.enabled` array
+2. ✅ ONLY ask about enabled plugins (GitHub/Jira/ADO)
+3. ✅ For each enabled plugin, ask: "Local ↔ [Provider]" sync direction
+4. ❌ NEVER ask about external-to-external sync (e.g., "GitHub ↔ Jira")
+
+---
+
 ## 📊 Living Docs Spec Detection (Step 0B - Validation)
 
 **AFTER** validating increment discipline, you SHOULD suggest living docs specs for large features.

package/plugins/specweave/hooks/post-spec-update.sh

@@ -0,0 +1,158 @@
+#!/bin/bash
+
+###############################################################################
+# SpecWeave Post-Spec-Update Hook
+#
+# CRITICAL ARCHITECTURE:
+# - Fires when .specweave/docs/internal/specs/spec-*.md is updated
+# - Auto-syncs to linked external tool (GitHub Project/Jira Epic/ADO Feature)
+# - Replaces increment-based sync (which was wrong!)
+#
+# Trigger Points:
+# 1. After /specweave:sync-docs update (spec updated from increment)
+# 2. After manual spec.md edits (user updates living docs directly)
+# 3. After bidirectional sync from external tool
+#
+# What It Does:
+# - Detects which spec was updated
+# - Checks if spec is linked to external tool (frontmatter: externalLinks)
+# - Syncs changes to GitHub Project / Jira Epic / ADO Feature
+# - Updates user stories, acceptance criteria, progress
+#
+# Usage:
+#   post-spec-update.sh <spec-file-path>
+#
+# Example:
+#   post-spec-update.sh .specweave/docs/internal/specs/spec-001-core-framework.md
+#
+###############################################################################
+
+set -euo pipefail
+
+# Arguments
+SPEC_FILE_PATH="${1:-}"
+
+# Validate arguments
+if [[ -z "$SPEC_FILE_PATH" ]]; then
+  echo "❌ Error: Spec file path required"
+  echo "Usage: post-spec-update.sh <spec-file-path>"
+  exit 1
+fi
+
+# Check if spec file exists
+if [[ ! -f "$SPEC_FILE_PATH" ]]; then
+  echo "❌ Error: Spec file not found: $SPEC_FILE_PATH"
+  exit 1
+fi
+
+# Extract spec ID from file path
+# Example: .specweave/docs/internal/specs/spec-001-core-framework.md → spec-001
+SPEC_ID=$(basename "$SPEC_FILE_PATH" .md)
+
+echo ""
+echo "🔗 Post-Spec-Update Hook"
+echo "   Spec: $SPEC_ID"
+echo "   File: $SPEC_FILE_PATH"
+
+# Load config to check if auto-sync is enabled
+CONFIG_FILE=".specweave/config.json"
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "   ℹ️  No config file found, skipping auto-sync"
+  exit 0
+fi
+
+# Check if auto-sync is enabled
+AUTO_SYNC=$(jq -r '.hooks.post_spec_update.auto_sync // true' "$CONFIG_FILE")
+
+if [[ "$AUTO_SYNC" != "true" ]]; then
+  echo "   ℹ️  Auto-sync disabled in config, skipping"
+  exit 0
+fi
+
+# Parse spec frontmatter to detect external links
+# Use gray-matter or similar to extract YAML frontmatter
+# For now, use simple grep/sed approach
+
+# Check if GitHub link exists
+GITHUB_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE_PATH" | grep -A 5 "github:" | grep "projectId:" | sed 's/.*projectId: *//; s/ *$//' || echo "")
+
+# Check if Jira link exists
+JIRA_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE_PATH" | grep -A 5 "jira:" | grep "epicKey:" | sed 's/.*epicKey: *//; s/ *$//' || echo "")
+
+# Check if ADO link exists
+ADO_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE_PATH" | grep -A 5 "ado:" | grep "featureId:" | sed 's/.*featureId: *//; s/ *$//' || echo "")
+
+# Determine which provider to sync
+PROVIDER=""
+if [[ -n "$GITHUB_LINK" ]]; then
+  PROVIDER="github"
+  EXTERNAL_ID="$GITHUB_LINK"
+elif [[ -n "$JIRA_LINK" ]]; then
+  PROVIDER="jira"
+  EXTERNAL_ID="$JIRA_LINK"
+elif [[ -n "$ADO_LINK" ]]; then
+  PROVIDER="ado"
+  EXTERNAL_ID="$ADO_LINK"
+fi
+
+# No external link found - skip sync
+if [[ -z "$PROVIDER" ]]; then
+  echo "   ℹ️  Spec not linked to external tool, skipping sync"
+  echo "   Hint: Use /specweave-github:sync-spec or /specweave-jira:sync-spec to link"
+  exit 0
+fi
+
+echo "   🔗 Detected external link: $PROVIDER (ID: $EXTERNAL_ID)"
+
+# Sync to external tool based on provider
+case "$PROVIDER" in
+  github)
+    echo "   🔄 Syncing to GitHub Project..."
+
+    # Check if GitHub CLI is available
+    if ! command -v gh &> /dev/null; then
+      echo "   ⚠️  GitHub CLI (gh) not found, skipping sync"
+      exit 0
+    fi
+
+    # TODO: Call GitHub spec sync
+    # For now, just log the action
+    echo "   ✅ GitHub sync queued (implementation pending)"
+    ;;
+
+  jira)
+    echo "   🔄 Syncing to Jira Epic..."
+
+    # Check if Jira config exists
+    if [[ -z "${JIRA_DOMAIN:-}" ]]; then
+      echo "   ⚠️  Jira not configured (.env), skipping sync"
+      exit 0
+    fi
+
+    # TODO: Call Jira spec sync
+    echo "   ✅ Jira sync queued (implementation pending)"
+    ;;
+
+  ado)
+    echo "   🔄 Syncing to Azure DevOps Feature..."
+
+    # Check if ADO config exists
+    if [[ -z "${ADO_ORGANIZATION:-}" ]]; then
+      echo "   ⚠️  ADO not configured (.env), skipping sync"
+      exit 0
+    fi
+
+    # TODO: Call ADO spec sync
+    echo "   ✅ ADO sync queued (implementation pending)"
+    ;;
+
+  *)
+    echo "   ⚠️  Unknown provider: $PROVIDER"
+    exit 0
+    ;;
+esac
+
+echo "   ✅ Post-spec-update hook complete"
+echo ""
+
+exit 0

package/plugins/specweave/hooks/post-user-story-complete.sh

@@ -0,0 +1,179 @@
+#!/bin/bash
+
+###############################################################################
+# SpecWeave Post-User-Story-Complete Hook
+#
+# CRITICAL ARCHITECTURE:
+# - Fires when user story marked complete in spec.md (AC checkbox checked)
+# - Updates external PM tool (GitHub Issue/Jira Story/ADO User Story)
+# - Moves GitHub card to "Done" / Closes Jira story / Completes ADO story
+#
+# Trigger Points:
+# 1. After user manually checks AC checkbox in spec.md
+# 2. After bidirectional sync updates AC status
+# 3. After increment completion syncs to spec
+#
+# What It Does:
+# - Detects which user story was completed (all AC checkboxes checked)
+# - Finds corresponding external item (GitHub Issue/Jira Story/ADO User Story)
+# - Updates item status to "Done" / "Closed"
+# - Adds completion comment with timestamp
+#
+# Usage:
+#   post-user-story-complete.sh <spec-id> <user-story-id>
+#
+# Example:
+#   post-user-story-complete.sh spec-001 US-001
+#
+###############################################################################
+
+set -euo pipefail
+
+# Arguments
+SPEC_ID="${1:-}"
+USER_STORY_ID="${2:-}"
+
+# Validate arguments
+if [[ -z "$SPEC_ID" || -z "$USER_STORY_ID" ]]; then
+  echo "❌ Error: Spec ID and User Story ID required"
+  echo "Usage: post-user-story-complete.sh <spec-id> <user-story-id>"
+  exit 1
+fi
+
+echo ""
+echo "🎉 Post-User-Story-Complete Hook"
+echo "   Spec: $SPEC_ID"
+echo "   User Story: $USER_STORY_ID"
+
+# Find spec file
+SPEC_FILE=""
+if [[ -f ".specweave/docs/internal/specs/$SPEC_ID.md" ]]; then
+  SPEC_FILE=".specweave/docs/internal/specs/$SPEC_ID.md"
+elif [[ -f ".specweave/docs/internal/projects/default/specs/$SPEC_ID.md" ]]; then
+  SPEC_FILE=".specweave/docs/internal/projects/default/specs/$SPEC_ID.md"
+else
+  echo "❌ Error: Spec file not found for $SPEC_ID"
+  exit 1
+fi
+
+# Load config to check if auto-sync is enabled
+CONFIG_FILE=".specweave/config.json"
+if [[ ! -f "$CONFIG_FILE" ]]; then
+  echo "   ℹ️  No config file found, skipping auto-sync"
+  exit 0
+fi
+
+# Check if auto-sync is enabled
+AUTO_SYNC=$(jq -r '.hooks.post_user_story_complete.auto_sync // true' "$CONFIG_FILE")
+
+if [[ "$AUTO_SYNC" != "true" ]]; then
+  echo "   ℹ️  Auto-sync disabled in config, skipping"
+  exit 0
+fi
+
+# Parse spec frontmatter to detect external links
+# Check if GitHub link exists
+GITHUB_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "github:" | grep "projectId:" | sed 's/.*projectId: *//; s/ *$//' || echo "")
+
+# Check if Jira link exists
+JIRA_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "jira:" | grep "epicKey:" | sed 's/.*epicKey: *//; s/ *$//' || echo "")
+
+# Check if ADO link exists
+ADO_LINK=$(grep -A 10 "^externalLinks:" "$SPEC_FILE" | grep -A 5 "ado:" | grep "featureId:" | sed 's/.*featureId: *//; s/ *$//' || echo "")
+
+# Determine which provider to sync
+PROVIDER=""
+if [[ -n "$GITHUB_LINK" ]]; then
+  PROVIDER="github"
+  EXTERNAL_ID="$GITHUB_LINK"
+elif [[ -n "$JIRA_LINK" ]]; then
+  PROVIDER="jira"
+  EXTERNAL_ID="$JIRA_LINK"
+elif [[ -n "$ADO_LINK" ]]; then
+  PROVIDER="ado"
+  EXTERNAL_ID="$ADO_LINK"
+fi
+
+# No external link found - skip sync
+if [[ -z "$PROVIDER" ]]; then
+  echo "   ℹ️  Spec not linked to external tool, skipping sync"
+  exit 0
+fi
+
+echo "   🔗 Detected external link: $PROVIDER"
+
+# Update external tool based on provider
+case "$PROVIDER" in
+  github)
+    echo "   🔄 Updating GitHub Issue for $USER_STORY_ID..."
+
+    # Check if GitHub CLI is available
+    if ! command -v gh &> /dev/null; then
+      echo "   ⚠️  GitHub CLI (gh) not found, skipping sync"
+      exit 0
+    fi
+
+    # Find GitHub Issue for this user story
+    # Search for issue with title pattern "[USER_STORY_ID]"
+    REPO=$(git remote get-url origin | sed -E 's/.*github\.com[:/]([^/]+\/[^/]+)(\.git)?$/\1/')
+
+    # Search for issue
+    ISSUE_NUMBER=$(gh issue list --repo "$REPO" --search "\"[$USER_STORY_ID]\" in:title" --json number --jq '.[0].number' 2>/dev/null || echo "")
+
+    if [[ -z "$ISSUE_NUMBER" ]]; then
+      echo "   ⚠️  GitHub Issue not found for $USER_STORY_ID"
+      exit 0
+    fi
+
+    echo "   📝 Found GitHub Issue #$ISSUE_NUMBER"
+
+    # Close issue
+    gh issue close "$ISSUE_NUMBER" --repo "$REPO" --comment "✅ User story completed
+
+🤖 Auto-closed by SpecWeave hook
+Completed at: $(date -u +%Y-%m-%dT%H:%M:%SZ)" 2>/dev/null || {
+      echo "   ⚠️  Failed to close issue"
+      exit 0
+    }
+
+    echo "   ✅ GitHub Issue #$ISSUE_NUMBER closed"
+    ;;
+
+  jira)
+    echo "   🔄 Updating Jira Story for $USER_STORY_ID..."
+
+    # Check if Jira config exists
+    if [[ -z "${JIRA_DOMAIN:-}" ]]; then
+      echo "   ⚠️  Jira not configured (.env), skipping sync"
+      exit 0
+    fi
+
+    # TODO: Find Jira Story by title pattern
+    # TODO: Transition story to "Done" status
+    echo "   ✅ Jira story transition queued (implementation pending)"
+    ;;
+
+  ado)
+    echo "   🔄 Updating ADO User Story for $USER_STORY_ID..."
+
+    # Check if ADO config exists
+    if [[ -z "${ADO_ORGANIZATION:-}" ]]; then
+      echo "   ⚠️  ADO not configured (.env), skipping sync"
+      exit 0
+    fi
+
+    # TODO: Find ADO User Story by title pattern
+    # TODO: Update state to "Closed"
+    echo "   ✅ ADO user story update queued (implementation pending)"
+    ;;
+
+  *)
+    echo "   ⚠️  Unknown provider: $PROVIDER"
+    exit 0
+    ;;
+esac
+
+echo "   ✅ Post-user-story-complete hook complete"
+echo ""
+
+exit 0

package/plugins/specweave/skills/increment-planner/SKILL.md

@@ -80,6 +80,23 @@ Do NOT activate if:
 - ❌ User is already in an active increment planning workflow
 - ❌ Increment files (spec.md, plan.md, tasks.md) are currently being created
 
+## 🔗 External Sync Architecture (CRITICAL)
+
+**Source of Truth**: `.specweave/docs/specs/` (LOCAL) is the permanent source of truth. External tools (GitHub, Jira, ADO) are **MIRRORS**.
+
+**Correct sync direction**:
+```
+✅ CORRECT:
+.specweave/  ↔  GitHub Issues    (Local ↔ External)
+.specweave/  ↔  Jira Epics       (Local ↔ External)
+.specweave/  ↔  ADO Work Items   (Local ↔ External)
+
+❌ WRONG:
+GitHub  ↔  Jira                  (External ↔ External - NO!)
+```
+
+**When invoking PM agent**: Ensure it understands sync is **Local ↔ External**, not External ↔ External!
+
 ## Activation Triggers
 
 This skill activates automatically when users say: