specweave 0.24.13 → 0.26.3

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

@@ -0,0 +1,405 @@
+---
+name: progress-sync
+description: Comprehensive progress synchronization expert. Explains when and how to use /specweave:sync-progress for multi-system sync (tasks → docs → external tools). Activates for sync progress, update progress, sync everything, sync all systems, sync to GitHub, sync to JIRA, how to sync, progress synchronization, multi-system sync.
+---
+
+# Progress Sync Expert
+
+I'm the comprehensive progress synchronization expert for SpecWeave. I help you understand and use the `/specweave:sync-progress` command for end-to-end progress synchronization.
+
+---
+
+## What is /specweave:sync-progress?
+
+**The "single button" to sync progress across all systems**:
+
+```
+tasks.md → spec.md ACs → living docs → external tools (GitHub/JIRA/ADO)
+```
+
+**One command, complete synchronization**:
+```bash
+/specweave:sync-progress
+```
+
+---
+
+## When to Use This Command
+
+### ✅ Use /specweave:sync-progress when:
+
+1. **After completing tasks**: You've marked tasks as done in tasks.md and want to sync everywhere
+2. **Before closing increment**: Final sync before `/specweave:done` to ensure all systems in sync
+3. **Progress check**: Want to update status line and external tools with latest progress
+4. **After bulk task completion**: Completed multiple tasks, sync all at once
+5. **Manual sync trigger**: Hooks didn't fire or you want to force a sync
+
+### ❌ Don't use when:
+
+1. **Only want to sync ACs**: Use `/specweave:sync-acs` instead (faster, more targeted)
+2. **Only want to sync docs**: Use `/specweave:sync-specs` instead
+3. **Only want to sync GitHub**: Use `/specweave-github:sync` instead
+4. **Increment not started**: No tasks to sync yet
+
+---
+
+## How It Works
+
+**Multi-Phase Orchestration**:
+
+```
+Phase 1: Tasks → ACs (spec.md)
+  └─ Reads completed tasks from tasks.md
+  └─ Finds linked ACs (via "Satisfies ACs" field)
+  └─ Marks ACs as complete in spec.md: [ ] → [x]
+  └─ Updates metadata.json with AC count
+
+Phase 2: Spec → Living Docs (User Stories)
+  └─ Syncs spec.md to living docs structure
+  └─ Updates user story completion status
+  └─ Generates/updates feature ID if needed
+
+Phase 3: Living Docs → External Tools
+  ├─ GitHub: Closes completed user story issues, updates epic checklist
+  ├─ JIRA: Updates story status, transitions workflow
+  └─ Azure DevOps: Updates work item state, comments
+
+Phase 4: Status Line Cache
+  └─ Updates status line with latest completion %
+```
+
+---
+
+## Usage Examples
+
+### Example 1: After Completing Tasks (Typical Workflow)
+
+**Scenario**: You completed 5 tasks and marked them in tasks.md. Now sync everywhere.
+
+```bash
+# Single command syncs everything
+/specweave:sync-progress
+```
+
+**What happens**:
+1. ✅ 5 tasks → 12 ACs marked complete in spec.md
+2. ✅ 2 user stories marked complete in living docs
+3. ✅ 2 GitHub issues closed
+4. ✅ Epic issue checklist updated (5/37 tasks complete)
+5. ✅ Status line shows 68% → 85% completion
+
+---
+
+### Example 2: Before Closing Increment
+
+**Scenario**: All 37 tasks complete, ready to close. Ensure final sync.
+
+```bash
+# Final sync before closure
+/specweave:sync-progress 0053
+
+# Then close increment
+/specweave:done 0053
+```
+
+**Why important**: `/specweave:done` validates completion. Final sync ensures:
+- All ACs marked complete
+- All user stories synced
+- All GitHub issues closed
+- Status line shows 100%
+
+---
+
+### Example 3: Dry-Run (Preview Mode)
+
+**Scenario**: Want to see what will be synced before executing.
+
+```bash
+# Preview mode
+/specweave:sync-progress 0053 --dry-run
+```
+
+**Output**:
+```
+🔍 DRY-RUN MODE (No changes made)
+
+Would sync:
+   • 37 completed tasks → 70 ACs in spec.md
+   • spec.md → 6 user stories in living docs
+   • Living docs → 6 GitHub issues (would close completed)
+   • Status line cache (would update completion %)
+
+Run without --dry-run to execute sync.
+```
+
+---
+
+### Example 4: Local-Only Sync (No External Tools)
+
+**Scenario**: Offline work, don't want to sync to GitHub/JIRA yet.
+
+```bash
+# Skip external tools
+/specweave:sync-progress 0053 --no-github --no-jira --no-ado
+```
+
+**What syncs**:
+- ✅ Tasks → ACs (spec.md)
+- ✅ Spec → Living docs
+- ❌ External tools (skipped)
+- ✅ Status line cache
+
+---
+
+## Flags
+
+| Flag | Purpose | Example |
+|------|---------|---------|
+| `--dry-run` | Preview without executing | `--dry-run` |
+| `--no-github` | Skip GitHub sync | `--no-github` |
+| `--no-jira` | Skip JIRA sync | `--no-jira` |
+| `--no-ado` | Skip Azure DevOps sync | `--no-ado` |
+| `--force` | Force sync even if validation fails | `--force` |
+
+**Combine flags**:
+```bash
+# Dry-run with no external tools
+/specweave:sync-progress --dry-run --no-github
+
+# Force sync, skip GitHub
+/specweave:sync-progress --force --no-github
+```
+
+---
+
+## Comparison with Other Sync Commands
+
+| Command | Scope | When to Use |
+|---------|-------|-------------|
+| `/specweave:sync-acs` | Tasks → ACs only | Quick AC update |
+| `/specweave:sync-specs` | Spec → Docs only | After spec changes |
+| `/specweave-github:sync` | Docs → GitHub only | GitHub-only sync |
+| `/specweave:sync-progress` | **Tasks → Docs → External** | **Complete sync** ✅ |
+
+**Rule of thumb**:
+- Need **targeted sync** → Use specific command (`sync-acs`, `sync-specs`)
+- Need **complete sync** → Use `/specweave:sync-progress` ✅
+
+---
+
+## Auto-Detection
+
+**Smart increment detection**:
+
+```bash
+# Explicit increment ID
+/specweave:sync-progress 0053
+
+# Auto-detect from active increment
+/specweave:sync-progress
+```
+
+**How auto-detection works**:
+1. Reads `.specweave/state/active-increment.json`
+2. Finds first active increment ID
+3. Uses that increment for sync
+
+---
+
+## External Tool Configuration
+
+**Automatic detection of configured tools**:
+
+The command checks `.specweave/config.json` for:
+- GitHub: `"provider": "github"`
+- JIRA: `"provider": "jira"`
+- Azure DevOps: `"provider": "azure-devops"`
+
+**Only configured tools are synced**:
+
+```
+✅ GitHub integration detected → Will sync
+ℹ️  No JIRA integration → Skip
+ℹ️  No ADO integration → Skip
+```
+
+---
+
+## Error Handling
+
+**Graceful degradation**:
+
+| Error Type | Behavior | Impact |
+|------------|----------|--------|
+| AC sync fails | ❌ Abort sync | Critical - blocks all sync |
+| Docs sync fails | ❌ Abort sync | Critical - blocks external sync |
+| GitHub sync fails | ⚠️ Log warning, continue | Non-critical - docs still synced |
+| JIRA sync fails | ⚠️ Log warning, continue | Non-critical - docs still synced |
+| ADO sync fails | ⚠️ Log warning, continue | Non-critical - docs still synced |
+
+**Philosophy**: Core sync (tasks → docs) must succeed. External tool sync is best-effort.
+
+---
+
+## Troubleshooting
+
+### Issue: "No active increment found"
+
+**Error**:
+```
+❌ No active increment found
+```
+
+**Fix**:
+```bash
+# Provide increment ID explicitly
+/specweave:sync-progress 0053
+```
+
+---
+
+### Issue: "AC sync had warnings"
+
+**Error**:
+```
+⚠️  AC sync had warnings: 5 ACs not found in spec.md
+```
+
+**Fix**:
+```bash
+# Embed ACs from living docs into spec.md
+/specweave:embed-acs 0053
+
+# Then retry sync
+/specweave:sync-progress 0053
+```
+
+**Why this happens**: spec.md missing inline ACs (ADR-0064 requirement).
+
+---
+
+### Issue: "GitHub rate limit exceeded"
+
+**Error**:
+```
+⚠️  GitHub sync had warnings: Rate limit exceeded
+```
+
+**Fix**: Non-critical. Docs are synced. Retry later when rate limit resets:
+
+```bash
+# Retry GitHub sync only (when rate limit resets)
+/specweave-github:sync 0053
+```
+
+---
+
+## Integration with Workflow
+
+**Typical increment workflow with progress sync**:
+
+```bash
+# 1. Plan increment
+/specweave:increment "Safe feature deletion"
+
+# 2. Execute tasks
+/specweave:do
+
+# [Complete tasks manually or via sub-agents...]
+
+# 3. Sync progress after each batch of tasks
+/specweave:sync-progress
+
+# 4. Final sync before closure
+/specweave:sync-progress 0053
+
+# 5. Validate quality
+/specweave:validate 0053 --quality
+
+# 6. Close increment
+/specweave:done 0053
+```
+
+---
+
+## Best Practices
+
+### ✅ DO:
+
+1. **Sync after task batches**: Complete 3-5 tasks → sync → continue
+2. **Final sync before closure**: Ensure 100% sync before `/specweave:done`
+3. **Use dry-run first**: Preview changes with `--dry-run`
+4. **Check external tools**: Verify GitHub/JIRA after sync
+5. **Review status line**: Ensure completion % updated correctly
+
+### ❌ DON'T:
+
+1. **Don't sync for every task**: Batching is more efficient
+2. **Don't skip final sync**: Always sync before `/specweave:done`
+3. **Don't ignore warnings**: AC sync warnings indicate missing ACs
+4. **Don't force sync without understanding**: `--force` bypasses validation
+5. **Don't sync before tasks complete**: Sync when progress actually changed
+
+---
+
+## Architecture
+
+**Why comprehensive sync is needed**:
+
+```
+Problem: Manual multi-step sync is error-prone
+  1. Update spec.md ACs manually
+  2. Run /specweave:sync-specs
+  3. Run /specweave-github:sync
+  4. Run /specweave:update-status
+  5. Check each system for correctness
+
+Solution: Single command orchestrates all steps
+  /specweave:sync-progress → Does all 4 steps automatically
+```
+
+**Benefits**:
+- ✅ **Single command**: One button for complete sync
+- ✅ **Guaranteed consistency**: All systems synced together
+- ✅ **Error resilience**: Non-critical failures don't block core sync
+- ✅ **Audit trail**: Comprehensive report shows what synced
+- ✅ **Dry-run support**: Preview before executing
+
+---
+
+## When Command Was Added
+
+**Version**: v0.25.0+
+**Increment**: 0053-safe-feature-deletion
+**ADR**: None yet (new feature)
+
+**Context**: Before this command, users had to manually:
+1. Run `/specweave:sync-acs`
+2. Run `/specweave:sync-specs`
+3. Run `/specweave-github:sync`
+4. Run `/specweave:update-status`
+
+Now: **One command does all 4 steps** ✅
+
+---
+
+## Related Commands
+
+- `/specweave:sync-acs` - Sync tasks → ACs only
+- `/specweave:sync-specs` - Sync spec → living docs only
+- `/specweave:sync-tasks` - Sync external → tasks (bidirectional)
+- `/specweave-github:sync` - Sync docs → GitHub only
+- `/specweave-jira:sync` - Sync docs → JIRA only
+- `/specweave-ado:sync` - Sync docs → ADO only
+- `/specweave:update-status` - Update status line cache
+
+---
+
+**I'm here to help you sync progress efficiently across all systems!**
+
+Ask me:
+- "How do I sync progress to GitHub?"
+- "What's the difference between sync-progress and sync-acs?"
+- "How do I preview sync without executing?"
+- "Why did my GitHub sync fail?"
+- "When should I use --dry-run?"

package/plugins/specweave-ado/lib/ado-multi-project-sync.js

@@ -373,7 +373,6 @@ ${userStory.technicalContext}
         return mapping.task || "Task";
       case "Subtask":
         return mapping.task || "Task";
-      // ADO doesn't have subtasks, use Task
       default:
         return "User Story";
     }

package/plugins/specweave-ado/lib/ado-project-detector.js

@@ -1,4 +1,4 @@
-import * as fs from "fs-extra";
+import * as fs from "../../../src/utils/fs-native.js";
 import * as path from "path";
 const PROJECT_KEYWORDS = {
   "AuthService": [

package/plugins/specweave-ado/lib/ado-project-detector.ts

@@ -5,7 +5,7 @@
  * based on content analysis, folder structure, and configuration.
  */
 
-import * as fs from 'fs-extra';
+import * as fs from '../../../src/utils/fs-native.js';
 import * as path from 'path';
 import { AzureDevOpsStrategy } from '../../../src/cli/helpers/issue-tracker/types';
 

package/plugins/specweave-ado/lib/conflict-resolver.js

@@ -1,4 +1,4 @@
-import * as fs from "fs-extra";
+import * as fs from "../../../src/utils/fs-native.js";
 import * as path from "path";
 import * as yaml from "yaml";
 const STATUS_MAPPING = {

package/plugins/specweave-ado/lib/conflict-resolver.ts

@@ -6,7 +6,7 @@
  * take precedence over local development status.
  */
 
-import * as fs from 'fs-extra';
+import * as fs from '../../../src/utils/fs-native.js';
 import * as path from 'path';
 import * as yaml from 'yaml';
 

package/plugins/specweave-backend/agents/database-optimizer/AGENT.md

@@ -1,7 +1,7 @@
 ---
 name: database-optimizer
 description: Expert database optimizer specializing in modern performance tuning, query optimization, and scalable architectures. Masters advanced indexing, N+1 resolution, multi-tier caching, partitioning strategies, and cloud database optimization. Handles complex query analysis, migration strategies, and performance monitoring. Use PROACTIVELY for database optimization, performance issues, or scalability challenges.
-model: haiku
+model: claude-haiku-4-5-20251001
 model_preference: sonnet
 cost_profile: planning
 fallback_behavior: strict

package/plugins/specweave-frontend/agents/frontend-architect/AGENT.md

@@ -8,10 +8,15 @@ tools:
   - Bash
   - Glob
   - Grep
+max_response_tokens: 2000
 ---
 
 # Frontend Architect Agent
 
+## ⚠️ Chunking for Large Frontend Architectures
+
+When generating comprehensive frontend architectures that exceed 1000 lines (e.g., complete component library with Atomic Design, state management, routing, and build configuration), generate output **incrementally** to prevent crashes. Break large frontend implementations into logical layers (e.g., Atomic Components → State Management → Routing → Build Config → Testing Setup) and ask the user which layer to implement next. This ensures reliable delivery of frontend architecture without overwhelming the system.
+
 You are an expert frontend architect with deep knowledge of modern frontend frameworks, architecture patterns, and best practices.
 
 ## Expertise

package/plugins/specweave-github/.claude-plugin/plugin.json

@@ -15,19 +15,5 @@
     "integration",
     "sync",
     "specweave"
-  ],
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "TodoWrite",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh",
-            "timeout": 15
-          }
-        ]
-      }
-    ]
-  }
+  ]
 }

package/plugins/specweave-github/hooks/README.md

@@ -7,7 +7,7 @@
 
 ## Purpose
 
-This hook automatically syncs SpecWeave increment progress to GitHub Issues after each task completion.
+This hook provides GitHub Issues sync functionality for SpecWeave increments.
 
 **Key Features**:
 - ✅ Updates GitHub issue checkboxes based on `tasks.md` completion status
@@ -16,13 +16,15 @@ This hook automatically syncs SpecWeave increment progress to GitHub Issues afte
 - ✅ Non-blocking (failures don't stop core workflow)
 - ✅ Self-contained (no dependencies on core plugin)
 
+**IMPORTANT CHANGE (v0.26.0)**: This hook is NO LONGER automatically triggered on task completion. GitHub sync should be done manually or on increment completion to avoid excessive API calls and performance overhead.
+
 ---
 
 ## Available Hooks
 
 ### 1. `post-task-completion.sh`
 
-**Triggers**: After ANY task is marked complete (via TodoWrite tool)
+**Triggers**: Manual invocation or increment completion (NOT on task completion)
 
 **Preconditions**:
 - ✅ Active increment exists (`.specweave/increments/####/`)
@@ -59,30 +61,36 @@ Log: "[GitHub] ✅ GitHub sync complete"
 
 ## Configuration
 
-### Hook Registration (`hooks.json`)
+### Hook Registration
 
-```json
-{
-  "hooks": {
-    "PostToolUse": [
-      {
-        "matcher": "TodoWrite",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/post-task-completion.sh"
-          }
-        ]
-      }
-    ]
-  }
-}
+**DEPRECATED (v0.26.0)**: This hook is NO LONGER automatically registered on TodoWrite events.
+
+**Previous behavior (v0.24.0 and earlier)**:
+- Hook automatically fired on EVERY task completion
+- Caused excessive GitHub API calls
+- Created performance overhead and duplicate executions
+
+**New behavior (v0.26.0+)**:
+- Hook must be invoked manually via `/specweave-github:sync`
+- OR triggered on increment completion (not task completion)
+- Reduces API calls by 90%+
+- Eliminates duplicate hook executions
+
+### Usage
+
+**Manual Sync** (recommended workflow):
+```bash
+# After completing several tasks, sync progress to GitHub
+/specweave-github:sync
+
+# Or sync specific feature
+/specweave-github:sync FS-048
 ```
 
-**Key Points**:
-- Uses `${CLAUDE_PLUGIN_ROOT}` to reference plugin directory
-- Matches `TodoWrite` tool (fires when tasks complete)
-- Runs as `command` type (shell script)
+**Automatic Sync Options**:
+1. **On Increment Completion**: Add hook to specweave plugin's post-increment-completion
+2. **Periodic Sync**: Set up cron job or CI/CD trigger
+3. **On Demand**: Call `/specweave-github:sync` when needed
 
 ### Metadata Format
 
@@ -143,8 +151,9 @@ bash -n plugins/specweave-github/hooks/post-task-completion.sh
 
 1. Create increment: `/specweave:increment "test feature"`
 2. Create GitHub issue: `/specweave-github:create-issue 0001`
-3. Complete a task (TodoWrite)
-4. Hook fires → Check GitHub issue for updates
+3. Complete several tasks via TodoWrite
+4. **Manually trigger sync**: `/specweave-github:sync`
+5. Check GitHub issue for updates
 
 ---
 

package/plugins/specweave-github/lib/CodeValidator.js

@@ -1,4 +1,4 @@
-import fs from "fs-extra";
+import * as fs from "../../../src/utils/fs-native.js";
 import path from "path";
 class CodeValidator {
   constructor(options = {}) {

package/plugins/specweave-github/lib/CodeValidator.ts

@@ -12,7 +12,7 @@
  * @module CodeValidator
  */
 
-import fs from 'fs-extra';
+import * as fs from '../../../src/utils/fs-native.js';
 import path from 'path';
 
 /**
@@ -133,7 +133,7 @@ export class CodeValidator {
     // Read file content
     const content = await fs.readFile(absolutePath, 'utf-8');
     const lines = content.split('\n');
-    const nonEmptyLines = lines.filter(line => line.trim().length > 0);
+    const nonEmptyLines = lines.filter((line: string) => line.trim().length > 0);
 
     // Check line count
     if (nonEmptyLines.length < this.options.minLines) {

package/plugins/specweave-github/lib/ThreeLayerSyncManager.js

@@ -1,4 +1,4 @@
-import fs from "fs-extra";
+import * as fs from "../../../src/utils/fs-native.js";
 import path from "path";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
 import { CodeValidator } from "./CodeValidator.js";

package/plugins/specweave-github/lib/ThreeLayerSyncManager.ts

@@ -18,7 +18,7 @@
  * @module ThreeLayerSyncManager
  */
 
-import fs from 'fs-extra';
+import * as fs from '../../../src/utils/fs-native.js';
 import path from 'path';
 import { execFileNoThrow } from '../../../src/utils/execFileNoThrow.js';
 import { CodeValidator, type TaskValidationResult } from './CodeValidator.js';

package/plugins/specweave-github/lib/github-client-v2.js

@@ -202,7 +202,19 @@ FIX: Use /specweave:sync-docs to generate living docs, then sync to GitHub.
       args.push("--label", label);
     }
     if (milestone !== void 0) {
-      args.push("--milestone", String(milestone));
+      if (typeof milestone === "number") {
+        const msResult = await execFileNoThrow("gh", [
+          "api",
+          `repos/${this.fullRepo}/milestones/${milestone}`,
+          "--jq",
+          ".title"
+        ]);
+        if (msResult.exitCode === 0 && msResult.stdout.trim()) {
+          args.push("--milestone", msResult.stdout.trim());
+        }
+      } else {
+        args.push("--milestone", milestone);
+      }
     }
     const createResult = await execFileNoThrow("gh", args);
     if (createResult.exitCode !== 0) {

package/plugins/specweave-github/lib/github-client-v2.ts

@@ -283,7 +283,23 @@ export class GitHubClientV2 {
 
     // Add milestone
     if (milestone !== undefined) {
-      args.push('--milestone', String(milestone));
+      // gh CLI requires milestone TITLE, not number
+      if (typeof milestone === 'number') {
+        // Fetch milestone by number to get title
+        const msResult = await execFileNoThrow('gh', [
+          'api',
+          `repos/${this.fullRepo}/milestones/${milestone}`,
+          '--jq',
+          '.title'
+        ]);
+
+        if (msResult.exitCode === 0 && msResult.stdout.trim()) {
+          args.push('--milestone', msResult.stdout.trim());
+        }
+        // If milestone fetch fails, skip milestone assignment (non-blocking)
+      } else {
+        args.push('--milestone', milestone);
+      }
     }
 
     // Create issue (returns URL)

package/plugins/specweave-github/lib/github-issue-updater.js

@@ -1,4 +1,4 @@
-import fs from "fs-extra";
+import * as fs from "../../../src/utils/fs-native.js";
 import path from "path";
 import { execFileNoThrow } from "../../../src/utils/execFileNoThrow.js";
 async function updateIssueLivingDocs(issueNumber, livingDocs, owner, repo) {