specweave 1.0.49 → 1.0.51

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specweave",
-  "version": "1.0.49",
+  "version": "1.0.51",
   "description": "Spec-driven development framework for Claude Code. AI-native workflow with living documentation, intelligent agents, and multilingual support (9 languages). Enterprise-grade traceability with permanent specs and temporary increments.",
   "type": "module",
   "main": "dist/index.js",

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

@@ -47,18 +47,36 @@ if [ -z "$INCREMENT_ID" ]; then
 fi
 ```
 
-**Validate increment exists**:
+**Validate increment exists** (check active AND archive directories):
 
 ```bash
 INCREMENT_DIR=".specweave/increments/$INCREMENT_ID"
+INCREMENT_STATUS="active"
+
 if [ ! -d "$INCREMENT_DIR" ]; then
-  echo "❌ Increment $INCREMENT_ID not found at $INCREMENT_DIR"
-  exit 1
+  # Check archive directory for completed increments
+  ARCHIVE_DIR=".specweave/increments/_archive/$INCREMENT_ID"
+  if [ -d "$ARCHIVE_DIR" ]; then
+    INCREMENT_DIR="$ARCHIVE_DIR"
+    INCREMENT_STATUS="completed"
+    echo "📦 Found ARCHIVED increment: $INCREMENT_ID (status: completed)"
+  else
+    echo "❌ Increment $INCREMENT_ID not found in active or archive"
+    exit 1
+  fi
+else
+  echo "✅ Found increment: $INCREMENT_ID"
 fi
-
-echo "✅ Found increment: $INCREMENT_ID"
 ```
 
+### ⚠️ IMPORTANT: DO NOT SKIP SYNC FOR COMPLETED/ARCHIVED INCREMENTS
+
+**Even if INCREMENT_STATUS="completed", you MUST proceed with ALL sync steps:**
+- ✅ Still create missing GitHub issues (critical for historical tracking)
+- ✅ Still sync to living docs
+- ✅ Still close issues if they were just created
+- ❌ DO NOT print "no sync needed" for completed increments
+
 **Output**:
 ```
 🔍 Auto-detected active increment: 0053-safe-feature-deletion
@@ -67,6 +85,12 @@ echo "✅ Found increment: $INCREMENT_ID"
 📊 Starting comprehensive progress sync...
 ```
 
+**OR for archived/completed**:
+```
+📦 Found ARCHIVED increment: 0001-content-repurposer-mvp (status: completed)
+📊 Syncing COMPLETED increment (will create/close GitHub issues)...
+```
+
 ---
 
 ## STEP 2: Sync Tasks → Living Docs (ACs and User Stories)
@@ -96,29 +120,42 @@ fi
 - Updates spec.md to mark ACs as complete: `- [ ]` → `- [x]`
 - Updates metadata.json with AC completion count
 
-### 2.2: Sync to Living Docs (User Stories)
+### 2.2: Sync to Living Docs (User Stories) - MANDATORY BEFORE EXTERNAL SYNC
+
+### ⚠️ CRITICAL: THIS STEP IS MANDATORY AND MUST COMPLETE BEFORE ANY EXTERNAL TOOL OPERATIONS
 
-Call the existing `/sw:sync-specs` command:
+**Why?** External tools (GitHub, JIRA, ADO) sync FROM living docs. If you skip this step:
+- External issues will have stale/outdated content
+- User stories won't reflect completed status
+- AC checkboxes in GitHub issues won't be checked
+
+**You MUST invoke the `/sw:sync-specs` command:**
 
 ```bash
 echo "📚 Step 2/5: Syncing increment to living docs..."
+echo "   ⚠️  THIS MUST COMPLETE BEFORE EXTERNAL TOOL SYNC"
 
-# Sync increment specs to living docs structure
+# MANDATORY: Sync increment specs to living docs structure
+# This populates .specweave/docs/internal/specs/{project}/FS-XXX/
 npx specweave sync-specs "$INCREMENT_ID"
 
 if [ $? -eq 0 ]; then
   echo "   ✅ Living docs sync complete"
+  echo "   📁 Updated: .specweave/docs/internal/specs/{project}/FS-XXX/"
 else
-  echo "   ❌ Living docs sync failed"
+  echo "   ❌ Living docs sync failed - BLOCKING external sync"
   exit 1
 fi
 ```
 
 **What this does**:
-- Syncs spec.md → living docs user stories
+- Syncs spec.md → living docs user stories in `.specweave/docs/internal/specs/`
 - Updates user story completion status
 - Generates/updates feature ID if needed
 - Updates README.md in feature folder
+- **Creates the content that external tools will sync FROM**
+
+### ⛔ DO NOT PROCEED TO STEP 3 UNTIL THIS COMPLETES SUCCESSFULLY
 
 ---
 
@@ -188,22 +225,43 @@ fi
 
 ---
 
-## STEP 4: AUTO-CREATE Missing External Issues (ALWAYS - Unless --no-create)
+## STEP 4: External Issues - ALWAYS Create If Missing, Then Sync/Close
+
+**CRITICAL BEHAVIOR (v1.0.50+)**: ALWAYS create missing issues, regardless of status:
+
+| INCREMENT_STATUS | Issue EXISTS | Action |
+|------------------|--------------|--------|
+| `active` | No | ✅ AUTO-CREATE new issue |
+| `active` | Yes | ✅ SYNC (update progress) |
+| `completed` | No | ✅ AUTO-CREATE + IMMEDIATELY CLOSE (historical tracking) |
+| `completed` | Yes | ✅ CLOSE the existing issue |
 
-**CRITICAL BEHAVIOR CHANGE (v1.0.48+)**: This command **ALWAYS auto-creates missing external issues** unless `--no-create` flag is passed. No config flag required!
+### ✅ CRITICAL RULE: ALWAYS CREATE IF MISSING
 
-**Philosophy**: `/sw:sync-progress` is the "single button" - it should JUST WORK. If GitHub is configured and no issue exists, CREATE IT.
+**For ALL increments (active OR completed):**
+- ✅ If NO issue exists → AUTO-CREATE the issue
+- ✅ If completed → CREATE then immediately CLOSE (for historical tracking)
 
-**Check and auto-create**:
+**Why?** Historical tracking is important. Completed work should have GitHub issues for:
+- Team visibility
+- Sprint retrospectives
+- Release notes generation
+- Audit trails
+
+**For completed increments:**
+- ✅ AUTO-CREATE if no issue exists (historical tracking)
+- ✅ Then IMMEDIATELY CLOSE the created issue (since work is done)
+
+**Check and handle based on status**:
 
 ```bash
-echo "🔗 Step 4/5: Ensuring external issues exist (auto-create if missing)..."
+echo "🔗 Step 4/5: Handling external issues based on increment status..."
 
 METADATA="$INCREMENT_DIR/metadata.json"
 NO_CREATE_FLAG="${NO_CREATE:-false}"  # --no-create flag disables auto-create
 
 # ══════════════════════════════════════════════════════════════════
-# GITHUB: Check and auto-create missing issues
+# GITHUB: Check and handle based on INCREMENT_STATUS
 # ══════════════════════════════════════════════════════════════════
 if [[ " ${EXTERNAL_TOOLS[@]} " =~ " github " ]] && [ "$NO_GITHUB" != "true" ]; then
   echo ""
@@ -223,44 +281,45 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " github " ]] && [ "$NO_GITHUB" != "true" ]; t
     ' "$METADATA" 2>/dev/null)
 
     if [ -z "$GITHUB_ISSUE" ] || [ "$GITHUB_ISSUE" = "null" ]; then
+      # NO ISSUE EXISTS - ALWAYS create (v1.0.50+)
       if [ "$NO_CREATE_FLAG" = "true" ]; then
         echo "      ⚠️  No GitHub issue linked (--no-create flag set, skipping auto-create)"
         echo "      💡 To create manually: /sw-github:create $INCREMENT_ID"
       else
-        echo "      📝 No GitHub issue linked - AUTO-CREATING..."
-
-        # Use the github-manager agent to create the issue
-        # This handles multi-project configs properly
+        # ALWAYS AUTO-CREATE issue (active OR completed)
+        if [ "$INCREMENT_STATUS" = "completed" ]; then
+          echo "      📝 No GitHub issue linked - AUTO-CREATING for historical tracking..."
+          echo "      📋 (Completed increment - will create AND close immediately)"
+        else
+          echo "      📝 No GitHub issue linked - AUTO-CREATING..."
+        fi
         echo "      ⏳ Creating GitHub issue via /sw-github:create..."
 
         # INVOKE: /sw-github:create $INCREMENT_ID
-        # The skill invocation will:
-        # 1. Read spec.md to generate issue body
-        # 2. Detect profile from increment's Project field or use active profile
-        # 3. Create issue with proper format: [FS-XXX][US-YYY] Title
-        # 4. Update metadata.json with issue number
-        # 5. Apply labels (specweave, increment)
-
-        # Execute the create command
         /sw-github:create "$INCREMENT_ID"
 
         if [ $? -eq 0 ]; then
           # Re-read metadata to get created issue number
           GITHUB_ISSUE=$(jq -r '.github.issue // .github.issues[0].number // .external_sync.github.issueNumber // ""' "$METADATA" 2>/dev/null)
           echo "      ✅ GitHub issue auto-created: #$GITHUB_ISSUE"
+          GITHUB_CREATED="true"  # Mark as newly created
         else
           echo "      ⚠️  GitHub issue creation failed (will continue with sync)"
           echo "      💡 Debug: Check GITHUB_TOKEN in .env or run 'gh auth status'"
         fi
       fi
     else
+      # ISSUE EXISTS - will sync/close in STEP 5
       echo "      ✅ GitHub issue exists: #$GITHUB_ISSUE"
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      📋 Will close issue in STEP 5 (increment is archived)"
+      fi
     fi
   fi
 fi
 
 # ══════════════════════════════════════════════════════════════════
-# JIRA: Check and auto-create missing issues
+# JIRA: Check and handle based on INCREMENT_STATUS
 # ══════════════════════════════════════════════════════════════════
 if [[ " ${EXTERNAL_TOOLS[@]} " =~ " jira " ]] && [ "$NO_JIRA" != "true" ]; then
   echo ""
@@ -278,11 +337,18 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " jira " ]] && [ "$NO_JIRA" != "true" ]; then
     ' "$METADATA" 2>/dev/null)
 
     if [ -z "$JIRA_ISSUE" ] || [ "$JIRA_ISSUE" = "null" ]; then
+      # NO ISSUE EXISTS - ALWAYS create (v1.0.50+)
       if [ "$NO_CREATE_FLAG" = "true" ]; then
         echo "      ⚠️  No JIRA issue linked (--no-create flag set, skipping auto-create)"
         echo "      💡 To create manually: /sw-jira:create $INCREMENT_ID"
       else
-        echo "      📝 No JIRA issue linked - AUTO-CREATING..."
+        # ALWAYS AUTO-CREATE issue (active OR completed)
+        if [ "$INCREMENT_STATUS" = "completed" ]; then
+          echo "      📝 No JIRA issue linked - AUTO-CREATING for historical tracking..."
+          echo "      📋 (Completed increment - will create AND transition to Done)"
+        else
+          echo "      📝 No JIRA issue linked - AUTO-CREATING..."
+        fi
         echo "      ⏳ Creating JIRA issue via /sw-jira:create..."
 
         # INVOKE: /sw-jira:create $INCREMENT_ID
@@ -291,19 +357,24 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " jira " ]] && [ "$NO_JIRA" != "true" ]; then
         if [ $? -eq 0 ]; then
           JIRA_ISSUE=$(jq -r '.jira.issue // .jira.issues[0].key // .external_sync.jira.issueKey // ""' "$METADATA" 2>/dev/null)
           echo "      ✅ JIRA issue auto-created: $JIRA_ISSUE"
+          JIRA_CREATED="true"  # Mark as newly created
         else
           echo "      ⚠️  JIRA issue creation failed (will continue with sync)"
           echo "      💡 Debug: Check JIRA credentials in .env"
         fi
       fi
     else
+      # ISSUE EXISTS - will sync/close in STEP 5
       echo "      ✅ JIRA issue exists: $JIRA_ISSUE"
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      📋 Will transition to 'Done' in STEP 5 (increment is archived)"
+      fi
     fi
   fi
 fi
 
 # ══════════════════════════════════════════════════════════════════
-# ADO: Check and auto-create missing work items
+# ADO: Check and handle based on INCREMENT_STATUS
 # ══════════════════════════════════════════════════════════════════
 if [[ " ${EXTERNAL_TOOLS[@]} " =~ " ado " ]] && [ "$NO_ADO" != "true" ]; then
   echo ""
@@ -321,11 +392,18 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " ado " ]] && [ "$NO_ADO" != "true" ]; then
     ' "$METADATA" 2>/dev/null)
 
     if [ -z "$ADO_ITEM" ] || [ "$ADO_ITEM" = "null" ]; then
+      # NO WORK ITEM EXISTS - ALWAYS create (v1.0.50+)
       if [ "$NO_CREATE_FLAG" = "true" ]; then
         echo "      ⚠️  No ADO work item linked (--no-create flag set, skipping auto-create)"
         echo "      💡 To create manually: /sw-ado:create $INCREMENT_ID"
       else
-        echo "      📝 No ADO work item linked - AUTO-CREATING..."
+        # ALWAYS AUTO-CREATE work item (active OR completed)
+        if [ "$INCREMENT_STATUS" = "completed" ]; then
+          echo "      📝 No ADO work item linked - AUTO-CREATING for historical tracking..."
+          echo "      📋 (Completed increment - will create AND transition to Closed)"
+        else
+          echo "      📝 No ADO work item linked - AUTO-CREATING..."
+        fi
         echo "      ⏳ Creating ADO work item via /sw-ado:create..."
 
         # INVOKE: /sw-ado:create $INCREMENT_ID
@@ -334,13 +412,18 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " ado " ]] && [ "$NO_ADO" != "true" ]; then
         if [ $? -eq 0 ]; then
           ADO_ITEM=$(jq -r '.ado.workItem // .ado.workItems[0].id // .external_sync.ado.workItemId // ""' "$METADATA" 2>/dev/null)
           echo "      ✅ ADO work item auto-created: #$ADO_ITEM"
+          ADO_CREATED="true"  # Mark as newly created
         else
           echo "      ⚠️  ADO work item creation failed (will continue with sync)"
           echo "      💡 Debug: Check AZURE_DEVOPS_PAT in .env"
         fi
       fi
     else
+      # WORK ITEM EXISTS - will sync/close in STEP 5
       echo "      ✅ ADO work item exists: #$ADO_ITEM"
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      📋 Will transition to 'Closed' in STEP 5 (increment is archived)"
+      fi
     fi
   fi
 fi
@@ -389,6 +472,13 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " github " ]] && [ "$NO_GITHUB" != "true" ]; t
       else
         echo "      ⚠️  GitHub sync had warnings (check logs)"
       fi
+
+      # SPECIAL CASE: For completed/archived increments, also CLOSE the issue
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      🔒 Closing GitHub issue (increment is completed)..."
+        /sw-github:close "$INCREMENT_ID"
+        echo "      ✅ GitHub issue closed"
+      fi
     fi
   fi
 fi
@@ -401,6 +491,11 @@ fi
 - Updates labels based on status
 - Pulls external changes (comments, status changes from team)
 
+**SPECIAL CASE: Completed/Archived Increments**:
+- If `INCREMENT_STATUS="completed"` and issue was just created → ALSO close the issue
+- Use `/sw-github:close $INCREMENT_ID` to close with completion comment
+- This provides complete historical tracking
+
 ### 5.2: Sync to JIRA (if configured)
 
 ```bash
@@ -412,7 +507,9 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " jira " ]] && [ "$NO_JIRA" != "true" ]; then
 
   if [ -z "$JIRA_ISSUE" ] || [ "$JIRA_ISSUE" = "null" ]; then
     echo "      ⚠️  No JIRA issue linked - skipping sync"
-    echo "      💡 Create issue first: /sw-jira:create $INCREMENT_ID"
+    if [ "$INCREMENT_STATUS" != "completed" ]; then
+      echo "      💡 Create issue first: /sw-jira:create $INCREMENT_ID"
+    fi
   else
     if [ "$DRY_RUN" = "true" ]; then
       echo "      [DRY-RUN] Would sync to JIRA issue $JIRA_ISSUE"
@@ -427,6 +524,13 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " jira " ]] && [ "$NO_JIRA" != "true" ]; then
       else
         echo "      ⚠️  JIRA sync had warnings"
       fi
+
+      # SPECIAL CASE: For completed/archived increments, transition to 'Done'
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      🔒 Transitioning JIRA issue to 'Done' (increment is completed)..."
+        /sw-jira:close "$INCREMENT_ID"
+        echo "      ✅ JIRA issue transitioned to Done"
+      fi
     fi
   fi
 fi
@@ -443,7 +547,9 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " ado " ]] && [ "$NO_ADO" != "true" ]; then
 
   if [ -z "$ADO_ITEM" ] || [ "$ADO_ITEM" = "null" ]; then
     echo "      ⚠️  No ADO work item linked - skipping sync"
-    echo "      💡 Create work item first: /sw-ado:create $INCREMENT_ID"
+    if [ "$INCREMENT_STATUS" != "completed" ]; then
+      echo "      💡 Create work item first: /sw-ado:create $INCREMENT_ID"
+    fi
   else
     if [ "$DRY_RUN" = "true" ]; then
       echo "      [DRY-RUN] Would sync to ADO work item #$ADO_ITEM"
@@ -458,6 +564,13 @@ if [[ " ${EXTERNAL_TOOLS[@]} " =~ " ado " ]] && [ "$NO_ADO" != "true" ]; then
       else
         echo "      ⚠️  ADO sync had warnings"
       fi
+
+      # SPECIAL CASE: For completed/archived increments, transition to 'Closed'
+      if [ "$INCREMENT_STATUS" = "completed" ]; then
+        echo "      🔒 Transitioning ADO work item to 'Closed' (increment is completed)..."
+        /sw-ado:close "$INCREMENT_ID"
+        echo "      ✅ ADO work item transitioned to Closed"
+      fi
     fi
   fi
 fi
@@ -540,7 +653,7 @@ echo "   • Run /sw:done $INCREMENT_ID when ready to close"
 echo ""
 ```
 
-**Example Output**:
+**Example Output (Active Increment)**:
 
 ```
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
@@ -565,6 +678,62 @@ Next steps:
    • Run /sw:done 0053 when ready to close
 ```
 
+**Example Output (COMPLETED/Archived Increment - WITH linked issue)**:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✅ PROGRESS SYNC COMPLETE (ARCHIVED INCREMENT)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Increment: 0001-content-repurposer-mvp
+📊 Status: completed (archived)
+
+✅ Synced:
+   • Tasks → ACs (spec.md)          54/54 ACs ✓
+   • Spec → Living docs             10/10 user stories ✓
+   • Status line cache              100% complete ✓
+
+🔗 External Tools:
+   • GitHub issue #123 SYNCED (final state)
+   • GitHub issue #123 CLOSED (increment complete)
+
+📊 Completion:
+   • Tasks: 35/35 (100%)
+   • ACs: 54/54 (100%)
+   • User Stories: 10/10 (100%)
+
+ℹ️  Archived increment synced successfully!
+   Existing linked issues updated and closed.
+```
+
+**Example Output (COMPLETED/Archived Increment - NO linked issue - NOW CREATES!)**:
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+  ✅ PROGRESS SYNC COMPLETE (ARCHIVED INCREMENT)
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+📦 Increment: 0001-content-repurposer-mvp
+📊 Status: completed (archived)
+
+✅ Synced:
+   • Tasks → ACs (spec.md)          54/54 ACs ✓
+   • Spec → Living docs             10/10 user stories ✓
+   • Status line cache              100% complete ✓
+
+🔗 External Tools:
+   📝 GitHub issue AUTO-CREATED: #456 (historical tracking)
+   🔒 GitHub issue #456 CLOSED (increment already complete)
+
+📊 Completion:
+   • Tasks: 35/35 (100%)
+   • ACs: 54/54 (100%)
+   • User Stories: 10/10 (100%)
+
+✅ Archived increment synced with historical tracking!
+   External issues created and closed for audit trail.
+```
+
 ---
 
 ## STEP 7: Dry-Run Mode (If --dry-run flag)

package/plugins/specweave/skills/progress-sync/SKILL.md

@@ -24,6 +24,23 @@ tasks.md → spec.md ACs → living docs → AUTO-CREATE external issues → syn
 
 **No more "No GitHub issue linked" errors!** The command auto-creates missing issues.
 
+### ✅ Archived Increment Behavior (v1.0.50+)
+
+**For archived/completed increments, this command ALWAYS creates issues for historical tracking:**
+
+| Situation | Action |
+|-----------|--------|
+| Issue EXISTS | ✅ Sync final state + Close/Transition |
+| NO issue linked | ✅ AUTO-CREATE + IMMEDIATELY CLOSE (historical tracking) |
+
+**Why?** Historical tracking is important! Completed work should have external issues for:
+- Team visibility
+- Sprint retrospectives
+- Release notes generation
+- Audit trails
+
+**For all increments (active or completed)**: Auto-creates issues if missing (the "single button" philosophy)
+
 ---
 
 ## When to Use This Command

package/plugins/specweave-github/commands/close.md

@@ -7,6 +7,29 @@ description: Close GitHub issue for completed SpecWeave increment. Posts complet
 
 Close the GitHub issue associated with a completed SpecWeave increment.
 
+## ⛔ MANDATORY: Sync Living Docs BEFORE Closing
+
+**GitHub issue content is generated FROM living docs.** If living docs are stale, the closing summary will have outdated information.
+
+**You MUST run `/sw:sync-specs` BEFORE closing (unless using /sw:sync-progress):**
+
+```bash
+# STEP 1: Ensure living docs reflect final state
+/sw:sync-specs <increment-id>
+
+# STEP 2: Then close GitHub issue
+/sw-github:close <increment-id>
+```
+
+**Why?**
+- Closing comment includes final stats from living docs
+- User story completion status read from living docs
+- AC checkboxes reflect living docs state
+
+**Note:** `/sw:done` and `/sw:sync-progress` call sync-specs automatically.
+
+---
+
 **Usage**: `/sw-github:close <increment-id>`
 
 ```bash

package/plugins/specweave-github/commands/create.md

@@ -7,6 +7,30 @@ description: Create a GitHub issue for a SpecWeave increment. Generates issue fr
 
 Create a GitHub issue for the specified SpecWeave increment.
 
+## ⛔ MANDATORY: Sync Living Docs BEFORE Creating Issue
+
+**GitHub issue content is generated FROM living docs.** If living docs don't exist or are stale, the issue will be incomplete.
+
+**You MUST run `/sw:sync-specs` BEFORE creating (unless using /sw:sync-progress):**
+
+```bash
+# STEP 1: Ensure living docs exist and are current
+/sw:sync-specs <increment-id>
+
+# STEP 2: Then create GitHub issue
+/sw-github:create <increment-id>
+```
+
+**Why?**
+- Issue body is generated from `.specweave/docs/internal/specs/FS-XXX/`
+- User stories and ACs come from living docs
+- Task checklist reflects living docs structure
+- Without sync-specs, issue will be created from raw increment spec.md (less structured)
+
+**Note:** `/sw:sync-progress` calls sync-specs automatically before creating issues.
+
+---
+
 **Usage**: `/sw-github:create <increment-id>`
 
 ```bash

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

@@ -5,9 +5,30 @@ description: Synchronize SpecWeave increment with GitHub issue (Multi-Project Su
 
 # Sync Increment with GitHub Issue (Multi-Project)
 
-## ⚠️ CRITICAL: Sync Routing (Read First!)
+## ⚠️ CRITICAL: Pre-Sync Requirements (Read First!)
 
-**Before executing ANY sync, you MUST determine the correct sync path:**
+### ⛔ MANDATORY: Sync Living Docs BEFORE GitHub Sync
+
+**GitHub sync reads FROM living docs.** If living docs are stale, GitHub issues will have outdated content.
+
+**You MUST run `/sw:sync-specs` (or ensure it ran) BEFORE this command:**
+
+```bash
+# STEP 1: Ensure living docs are current (MANDATORY)
+/sw:sync-specs <increment-id>
+
+# STEP 2: Then sync to GitHub
+/sw-github:sync <increment-id>
+```
+
+**Why?**
+- GitHub issues are generated FROM `.specweave/docs/internal/specs/FS-XXX/`
+- If you skip sync-specs, GitHub will show stale user stories/ACs
+- `/sw:sync-progress` calls sync-specs automatically, but `/sw-github:sync` does NOT
+
+**If you're calling this directly (not via /sw:sync-progress), run sync-specs first!**
+
+---
 
 ### Step 0: Detect Project Structure