specweave 1.0.235 → 1.0.239

package/plugins/specweave/skills/team-status/SKILL.md

@@ -0,0 +1,89 @@
+---
+description: Show status of parallel development agents launched by team-orchestrate. Activates for: team status, agent status, parallel status, check agents.
+---
+
+# Team Status
+
+**Show progress of parallel development agents.**
+
+## Usage
+
+```bash
+/sw:team-status
+/sw:team-status --watch          # Auto-refresh every 2s
+/sw:team-status --json           # Machine-readable output
+```
+
+## What This Skill Does
+
+Reads the parallel session state and each agent's increment to produce a status table. Supports both native Agent Teams mode and subagent fallback mode.
+
+## Mode Detection
+
+Check which mode is active:
+
+1. **Native Agent Teams mode** — if `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS` is set and a team session is active, query teammates directly for status
+2. **Subagent mode** — read `.specweave/state/parallel/session.json` and check each agent's TaskOutput
+
+## Implementation Steps
+
+### Native Agent Teams Mode
+
+1. List active teammates in the current team
+2. For each teammate, check their assigned increment's `tasks.md`
+3. Query teammate status (idle, working, completed)
+4. Display terminal pane info (tmux pane index or in-process index)
+
+### Subagent Mode (Fallback)
+
+1. **Read session state** from `.specweave/state/parallel/session.json`
+2. **For each agent**, read its increment's `tasks.md` to compute completion percentage
+3. **Check agent task status** via TaskOutput (if still running)
+4. **Check heartbeat** — if last heartbeat > 5 minutes, mark as potentially stale
+
+### Display Summary
+
+4. **Display summary table**
+
+## Output Format
+
+```
+Team Status: session-uuid (started 2h ago)
+Mode: Native Agent Teams (tmux split panes)
+
+| Agent    | Domain   | Increment               | Tasks  | Progress | Status  |
+|----------|----------|-------------------------|--------|----------|---------|
+| Agent 1  | frontend | 0193-checkout-frontend  | 5/8    | 62%      | running |
+| Agent 2  | backend  | 0194-checkout-backend   | 3/6    | 50%      | running |
+| Agent 3  | shared   | 0195-checkout-shared    | 4/4    | 100%     | done    |
+
+Overall: 12/18 tasks (67%)
+Active Skills: sw-frontend:frontend-architect, sw:architect, sw:architect
+```
+
+## Agent State Icons
+
+| Icon | Status |
+|------|--------|
+| `⏳` | pending — agent not yet spawned |
+| `🔄` | running — agent actively working |
+| `✅` | done — all tasks completed, quality gate passed |
+| `❌` | failed — agent encountered unrecoverable error |
+| `🚫` | cancelled — agent was stopped by user |
+| `💀` | stale — no heartbeat in >5 minutes (subagent mode) |
+
+## Error Handling
+
+- If no session file exists, report "No active team session"
+- If native Agent Teams mode but no team found, report "No active agent team — try /sw:team-orchestrate first"
+- If an agent's increment is missing, report "increment not found"
+- If a task file can't be parsed, show "?" for progress
+- If agent heartbeat is stale, warn user and suggest checking agent
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--watch` | Auto-refresh every 2 seconds |
+| `--json` | Output as JSON for programmatic use |
+| `--verbose` | Show per-task detail for each agent |

package/plugins/specweave-github/MULTI-PROJECT-SYNC-ARCHITECTURE.md

@@ -1,7 +1,7 @@
 # Multi-Project GitHub Sync Architecture
 
-**Version**: v0.18.0+
-**Date**: 2025-11-11
+**Version**: v1.0.235+ (V2 Integration)
+**Date**: 2026-02-06
 **Status**: Implemented and Tested
 
 ---
@@ -643,16 +643,102 @@ spec-003.md
 
 ---
 
+## Projects V2 Integration (v1.0.235+)
+
+### Overview
+
+The sync system now supports GitHub Projects V2 for visual project management:
+- Issues are added to Projects V2 boards after creation
+- Status and Priority custom fields are synced via configurable mappings
+- Cross-repo issues can be added to the same org-level project
+
+### Architecture
+
+```
+Spec → Push Sync → GitHub Issues → Board Resolver V2 → Projects V2
+                                   Field Sync → Status/Priority fields
+                                   Frontmatter Updater → spec.md metadata
+```
+
+### Key Components
+
+| Module | Purpose |
+|--------|---------|
+| `github-sync-orchestrator.ts` | Composes push + V2 + frontmatter into single flow |
+| `github-board-resolver-v2.ts` | Find/create Projects V2 boards |
+| `github-field-sync.ts` | Sync Status/Priority custom fields |
+| `github-graphql-client.ts` | GraphQL mutations via `gh api graphql` |
+| `github-spec-frontmatter-updater.ts` | Write sync results to spec.md |
+
+### Configuration
+
+```json
+{
+  "sync": {
+    "profiles": {
+      "myproject": {
+        "provider": "github",
+        "config": {
+          "owner": "myorg",
+          "repo": "myrepo",
+          "projectV2Enabled": true,
+          "projectV2Number": 5,
+          "statusFieldMapping": {
+            "planned": "Todo",
+            "in-progress": "In Progress",
+            "completed": "Done"
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+### Pull Sync (GitHub to Spec)
+
+The pull sync fetches GitHub issue state and compares with spec ACs:
+- `github-pull-sync.ts` — fetches issues, compares AC states
+- `github-conflict-resolver.ts` — field-level conflict detection
+- Modes: `github-wins` (default for status/AC), `spec-wins`, `prompt` (for content)
+
+### Cross-Repo Sync
+
+- `github-cross-repo-sync.ts` — creates issues in multiple repos per user story
+- Cross-references added: "Also tracked in: org/other-repo#XX"
+- All cross-repo issues can be added to a shared org-level Projects V2 board
+
+### Batch Sync
+
+- `github-batch-sync.ts` — discovers all specs and syncs sequentially
+- Usage: `batchSyncAllSpecs({ owner, repo, workspaceRoot })`
+- Returns aggregated summary: specs processed, issues created/updated, errors
+
+### Agent Teams Orchestration
+
+Skills for parallel multi-domain development:
+- `/sw:team-orchestrate` — analyze feature, create per-domain increments, spawn agents
+- `/sw:team-status` — show agent progress table
+- `/sw:team-merge` — merge in dependency order, trigger sync per increment
+
 ## References
 
-- **Implementation**: `plugins/specweave-github/lib/github-spec-sync.ts`
-- **Types**: `src/core/types/sync-profile.ts`, `src/core/types/spec-metadata.ts`
-- **Tests**: `tests/e2e/github-sync-multi-project.spec.ts`
-- **Project Management**: `src/core/sync/project-context.ts`
+- **Orchestrator**: `plugins/specweave-github/lib/github-sync-orchestrator.ts`
+- **Push Sync**: `plugins/specweave-github/lib/github-push-sync.ts`
+- **Pull Sync**: `plugins/specweave-github/lib/github-pull-sync.ts`
+- **Board Resolver V2**: `plugins/specweave-github/lib/github-board-resolver-v2.ts`
+- **Field Sync**: `plugins/specweave-github/lib/github-field-sync.ts`
+- **Conflict Resolver**: `plugins/specweave-github/lib/github-conflict-resolver.ts`
+- **Cross-Repo**: `plugins/specweave-github/lib/github-cross-repo-sync.ts`
+- **Batch Sync**: `plugins/specweave-github/lib/github-batch-sync.ts`
+- **GraphQL Client**: `plugins/specweave-github/lib/github-graphql-client.ts`
+- **Types**: `src/core/types/sync-profile.ts`
+- **Tests**: `tests/unit/plugins/github/`
+- **Legacy**: `plugins/specweave-github/lib/github-spec-sync.ts`
 - **Original Architecture Fix**: `plugins/specweave-github/SYNC-ARCHITECTURE-FIX-SUMMARY.md`
 
 ---
 
-**Version**: v0.18.0
-**Last Updated**: 2025-11-11
+**Version**: v1.0.235
+**Last Updated**: 2026-02-06
 **Status**: Complete and Tested

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

@@ -1,10 +1,24 @@
 ---
-description: Synchronize SpecWeave increment with GitHub issue (Multi-Project Support). Select profile, configure time range, and sync with rate limit protection.
+description: "[DEPRECATED] Use /sw-github:sync-spec instead. Legacy increment-based GitHub sync."
 ---
 
-# Sync Increment with GitHub Issue (Multi-Project)
+# DEPRECATED: Use `/sw-github:sync-spec` Instead
 
-## ⚠️ CRITICAL: Pre-Sync Requirements (Read First!)
+> **This command is deprecated as of v1.0.235.** The increment-based sync has been replaced by spec-based sync.
+>
+> **Migration:**
+> - For spec-to-GitHub Issue sync: `/sw-github:sync-spec <spec-id>`
+> - For batch sync: `/sw-github:sync-spec --all`
+> - For pull direction: `/sw-github:sync-spec <spec-id> --direction from-github`
+>
+> The old increment-based sync created issues per-task. The new spec-based sync creates issues per-User-Story,
+> which is the correct granularity for GitHub project management.
+
+---
+
+# Legacy: Sync Increment with GitHub Issue (Multi-Project)
+
+## Pre-Sync Requirements (Read First!)
 
 ### ⛔ MANDATORY: Sync Living Docs BEFORE GitHub Sync
 

package/plugins/specweave-github/hooks/github-ac-sync-handler.sh

@@ -0,0 +1,255 @@
+#!/bin/bash
+
+# SpecWeave GitHub AC Sync Handler (v1.0.236+)
+# Background handler: posts progress comments to GitHub after AC sync.
+#
+# Triggered by post-tool-use.sh after task-ac-sync-guard updates spec.md ACs.
+# Runs in BACKGROUND via safe_run_background — never blocks the main chain.
+#
+# Features:
+# - 5s debounce (batches rapid AC changes)
+# - Circuit breaker (3 consecutive failures → auto-disable)
+# - File locking (prevents concurrent handler executions)
+# - Non-blocking (all errors → exit 0 with logging)
+#
+# Usage: github-ac-sync-handler.sh <INCREMENT_ID>
+# Called by: safe_run_background in post-tool-use.sh
+
+set +e  # Never crash Claude Code
+
+# EMERGENCY KILL SWITCH
+if [[ "${SPECWEAVE_DISABLE_HOOKS:-0}" == "1" ]]; then
+  exit 0
+fi
+
+# ============================================================================
+# PROJECT ROOT DETECTION
+# ============================================================================
+
+find_project_root() {
+  local dir="$1"
+  while [ "$dir" != "/" ]; do
+    if [ -d "$dir/.specweave" ]; then
+      echo "$dir"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+  return 1
+}
+
+PROJECT_ROOT="$(find_project_root "$(pwd)")"
+if [[ -z "$PROJECT_ROOT" ]]; then
+  exit 0
+fi
+cd "$PROJECT_ROOT" 2>/dev/null || exit 0
+
+# ============================================================================
+# ARGUMENTS
+# ============================================================================
+
+INC_ID="$1"
+if [[ -z "$INC_ID" ]]; then
+  exit 0
+fi
+
+SPEC_PATH="$PROJECT_ROOT/.specweave/increments/$INC_ID/spec.md"
+if [[ ! -f "$SPEC_PATH" ]]; then
+  exit 0
+fi
+
+# ============================================================================
+# LOGGING
+# ============================================================================
+
+LOGS_DIR="$PROJECT_ROOT/.specweave/logs"
+LOG_FILE="$LOGS_DIR/github-ac-sync.log"
+mkdir -p "$LOGS_DIR" 2>/dev/null || true
+
+log() {
+  echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-ac-sync] $1" >> "$LOG_FILE" 2>/dev/null || true
+}
+
+# ============================================================================
+# CIRCUIT BREAKER
+# ============================================================================
+
+STATE_DIR="$PROJECT_ROOT/.specweave/state"
+CIRCUIT_BREAKER_FILE="$STATE_DIR/.hook-circuit-breaker-github-ac"
+CIRCUIT_BREAKER_THRESHOLD=3
+
+mkdir -p "$STATE_DIR" 2>/dev/null || true
+
+if [[ -f "$CIRCUIT_BREAKER_FILE" ]]; then
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  if (( FAILURE_COUNT >= CIRCUIT_BREAKER_THRESHOLD )); then
+    log "Circuit breaker OPEN ($FAILURE_COUNT failures). Skipping."
+    exit 0
+  fi
+fi
+
+# ============================================================================
+# FILE LOCKING
+# ============================================================================
+
+LOCK_FILE="$STATE_DIR/.hook-github-ac-sync.lock"
+LOCK_TIMEOUT=15
+
+LOCK_ACQUIRED=false
+for i in {1..10}; do
+  if mkdir "$LOCK_FILE" 2>/dev/null; then
+    LOCK_ACQUIRED=true
+    trap 'rmdir "$LOCK_FILE" 2>/dev/null || true' EXIT
+    break
+  fi
+
+  # Check for stale lock
+  if [[ -d "$LOCK_FILE" ]]; then
+    LOCK_AGE=$(($(date +%s) - $(stat -f "%m" "$LOCK_FILE" 2>/dev/null || echo 0)))
+    if (( LOCK_AGE > LOCK_TIMEOUT )); then
+      rmdir "$LOCK_FILE" 2>/dev/null || true
+      continue
+    fi
+  fi
+
+  sleep 0.3
+done
+
+if [[ "$LOCK_ACQUIRED" == "false" ]]; then
+  log "Lock not acquired. Another instance running. Skipping."
+  exit 0
+fi
+
+# ============================================================================
+# DEBOUNCE (5s window)
+# ============================================================================
+
+SIGNAL_FILE="$STATE_DIR/.github-ac-pending-$INC_ID"
+
+if [[ -f "$SIGNAL_FILE" ]]; then
+  SIGNAL_AGE=$(($(date +%s) - $(stat -f "%m" "$SIGNAL_FILE" 2>/dev/null || echo 0)))
+  if (( SIGNAL_AGE < 5 )); then
+    # Another invocation was recent — let a later one handle it
+    log "Debounce: signal file age ${SIGNAL_AGE}s < 5s. Deferring."
+    exit 0
+  fi
+fi
+
+# Create/update signal file and wait for debounce window
+echo "$(date +%s)" > "$SIGNAL_FILE" 2>/dev/null || true
+sleep 5
+
+# After sleeping, check if a NEWER invocation took over
+if [[ -f "$SIGNAL_FILE" ]]; then
+  CURRENT_SIGNAL=$(cat "$SIGNAL_FILE" 2>/dev/null || echo 0)
+  NOW=$(date +%s)
+  SIGNAL_AGE=$((NOW - CURRENT_SIGNAL))
+  if (( SIGNAL_AGE > 6 )); then
+    # Another invocation wrote a newer timestamp — it will handle this
+    log "Debounce: newer invocation detected. Exiting."
+    exit 0
+  fi
+fi
+
+# Clean up signal file — we're the one handling it
+rm -f "$SIGNAL_FILE" 2>/dev/null || true
+
+# ============================================================================
+# PRECONDITIONS
+# ============================================================================
+
+if ! command -v node &>/dev/null; then
+  log "Node.js not found. Skipping."
+  exit 0
+fi
+
+if ! command -v gh &>/dev/null; then
+  log "GitHub CLI (gh) not found. Skipping."
+  exit 0
+fi
+
+# Check GitHub sync is enabled in config
+CONFIG_FILE="$PROJECT_ROOT/.specweave/config.json"
+if [[ -f "$CONFIG_FILE" ]] && command -v jq >/dev/null 2>&1; then
+  GH_ENABLED=$(jq -r '.sync.github.enabled // false' "$CONFIG_FILE" 2>/dev/null)
+  if [[ "$GH_ENABLED" != "true" ]]; then
+    log "GitHub sync not enabled in config. Skipping."
+    exit 0
+  fi
+fi
+
+# ============================================================================
+# POST PROGRESS COMMENT
+# ============================================================================
+
+log "Posting progress comment for increment $INC_ID..."
+
+# Find the comment poster module
+POSTER_MODULE="$PROJECT_ROOT/plugins/specweave-github/lib/github-ac-comment-poster.js"
+if [[ ! -f "$POSTER_MODULE" ]]; then
+  # Try dist/ fallback
+  POSTER_MODULE="$PROJECT_ROOT/dist/plugins/specweave-github/lib/github-ac-comment-poster.js"
+fi
+
+if [[ ! -f "$POSTER_MODULE" ]]; then
+  log "Comment poster module not found. Skipping."
+  exit 0
+fi
+
+# Run comment poster via node
+OUTPUT=$(node -e "
+  import { postACProgressComments } from '${POSTER_MODULE}';
+  const specPath = '${SPEC_PATH}';
+  const incrementId = '${INC_ID}';
+  // Post for all user stories (the module filters by available issue links)
+  const result = await postACProgressComments(incrementId, [], specPath, {
+    owner: process.env.GITHUB_OWNER || '',
+    repo: process.env.GITHUB_REPO || '',
+  });
+  console.log(JSON.stringify(result));
+" 2>&1) || true
+
+EXIT_CODE=$?
+
+if [[ $EXIT_CODE -ne 0 ]]; then
+  log "Comment poster failed (exit $EXIT_CODE): $OUTPUT"
+
+  # Update circuit breaker
+  FAILURE_COUNT=$(cat "$CIRCUIT_BREAKER_FILE" 2>/dev/null || echo 0)
+  echo "$((FAILURE_COUNT + 1))" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+
+  exit 0
+fi
+
+log "Comment poster completed: $OUTPUT"
+
+# Reset circuit breaker on success
+echo "0" > "$CIRCUIT_BREAKER_FILE" 2>/dev/null || true
+
+# ============================================================================
+# AUTO-CLOSE COMPLETED USER STORIES (v1.0.236+)
+# ============================================================================
+
+CLOSER_MODULE="$PROJECT_ROOT/plugins/specweave-github/lib/github-us-auto-closer.js"
+if [[ ! -f "$CLOSER_MODULE" ]]; then
+  CLOSER_MODULE="$PROJECT_ROOT/dist/plugins/specweave-github/lib/github-us-auto-closer.js"
+fi
+
+if [[ -f "$CLOSER_MODULE" ]]; then
+  log "Running auto-closer for increment $INC_ID..."
+
+  CLOSE_OUTPUT=$(node -e "
+    import { autoCloseCompletedUserStories } from '${CLOSER_MODULE}';
+    const specPath = '${SPEC_PATH}';
+    const incrementId = '${INC_ID}';
+    const result = await autoCloseCompletedUserStories(incrementId, [], specPath, {
+      owner: process.env.GITHUB_OWNER || '',
+      repo: process.env.GITHUB_REPO || '',
+    });
+    console.log(JSON.stringify(result));
+  " 2>&1) || true
+
+  log "Auto-closer completed: $CLOSE_OUTPUT"
+fi
+
+exit 0