specweave 0.30.14 → 0.30.16

package/plugins/specweave/commands/specweave-living-docs.md

@@ -0,0 +1,321 @@
+---
+name: specweave:living-docs
+description: Launch or resume Living Docs Builder independently. Generates documentation from codebase analysis with AI-powered insights.
+usage: /specweave:living-docs [--resume <jobId>] [--depth <level>] [--priority <modules>] [--sources <folders>] [--depends-on <jobIds>] [--foreground]
+---
+
+# Living Docs Builder (Standalone)
+
+**Usage**: `/specweave:living-docs [options]`
+
+---
+
+## Purpose
+
+Launch the Living Docs Builder independently of `specweave init`. This is essential for:
+- **Resuming after crash** - Claude Code crashed after init, need to restart living docs
+- **On-demand analysis** - Re-analyze codebase after major changes
+- **Large brownfield projects** - Run targeted analysis on specific modules
+- **CI/CD integration** - Automate documentation generation
+
+---
+
+## Command Options
+
+| Option | Description |
+|--------|-------------|
+| (none) | Interactive mode - prompts for configuration |
+| `--resume <jobId>` | Resume orphaned/paused living-docs job |
+| `--depth <level>` | Analysis depth: `quick`, `standard`, `deep-native`, `deep-api` |
+| `--priority <modules>` | Priority modules (comma-separated): `auth,payments,api` |
+| `--sources <folders>` | Additional doc folders (comma-separated): `docs/,wiki/` |
+| `--depends-on <jobIds>` | Wait for jobs before starting (comma-separated) |
+| `--foreground` | Run in current session instead of background |
+
+---
+
+## Quick Start
+
+### Launch New Analysis (Interactive)
+
+```bash
+/specweave:living-docs
+
+# Prompts for:
+# 1. Analysis depth (quick/standard/deep-native/deep-api)
+# 2. Priority modules to focus on
+# 3. Additional documentation sources
+# 4. Confirmation to launch
+```
+
+### Resume After Crash
+
+```bash
+# Check for orphaned jobs first
+/specweave:jobs
+
+# If you see an orphaned living-docs-builder job:
+/specweave:living-docs --resume abc12345
+
+# Or let it auto-detect:
+/specweave:living-docs
+# → "Found orphaned job abc12345. Resume? [Y/n]"
+```
+
+### Quick Analysis (Non-Interactive)
+
+```bash
+# Quick scan - 5-10 minutes
+/specweave:living-docs --depth quick
+
+# Standard analysis - 15-30 minutes
+/specweave:living-docs --depth standard --priority auth,payments
+
+# AI-powered deep analysis (FREE with MAX subscription)
+/specweave:living-docs --depth deep-native --priority core,api
+```
+
+---
+
+## Analysis Depths
+
+| Depth | Duration | What It Does | Cost |
+|-------|----------|--------------|------|
+| `quick` | ~5-10 min | Structure scan, tech detection, imports map | Free |
+| `standard` | ~15-30 min | Module analysis, exports, dependencies | Free |
+| `deep-native` | Progress-based | AI analysis via Claude Code CLI | FREE (MAX) |
+| `deep-api` | Progress-based | AI analysis via API key | API costs |
+
+### Deep-Native (Recommended for MAX Users)
+
+Uses your Claude MAX subscription via `claude --print`:
+- **No extra cost** - included in MAX
+- Runs in **background** - survives terminal close
+- **Checkpoint/resume** - can resume from any phase
+- Uses **Opus 4.5** for best quality
+
+```bash
+/specweave:living-docs --depth deep-native
+
+# Monitor progress:
+/specweave:jobs --follow <jobId>
+```
+
+---
+
+## Implementation Steps
+
+When this command is invoked:
+
+### Step 1: Check for Orphaned Jobs
+
+```typescript
+import { getOrphanedJobs, getJobManager } from '../../../src/core/background/job-launcher.js';
+
+const orphaned = getOrphanedJobs(projectPath).filter(j => j.type === 'living-docs-builder');
+if (orphaned.length > 0) {
+  // Prompt: "Found orphaned job {id}. Resume? [Y/n]"
+  // If yes: resume job
+  // If no: ask if they want to start fresh
+}
+```
+
+### Step 2: Collect Configuration (if not --resume)
+
+If no `--resume` flag and no auto-resume:
+
+```typescript
+import { collectLivingDocsInputs } from '../../../src/cli/helpers/init/living-docs-preflight.js';
+
+const result = await collectLivingDocsInputs({
+  projectPath,
+  language: 'en',
+  isCi: hasFlags, // Skip prompts if flags provided
+});
+```
+
+Override with flags:
+- `--depth` → `result.userInputs.analysisDepth`
+- `--priority` → `result.userInputs.priorityAreas`
+- `--sources` → `result.userInputs.additionalSources`
+
+### Step 3: Launch Job
+
+```typescript
+import { launchLivingDocsJob } from '../../../src/core/background/job-launcher.js';
+
+const { job, pid, isBackground } = await launchLivingDocsJob({
+  projectPath,
+  userInputs: result.userInputs,
+  dependsOn: dependsOnJobIds,
+  foreground: hasForegroundFlag,
+});
+```
+
+### Step 4: Display Status
+
+```
+✅ Living Docs Builder launched!
+
+   Job ID: ldb-abc12345
+   Depth: deep-native (Claude Code Opus 4.5)
+   Priority: auth, payments, api
+   PID: 45678
+
+   Monitor: /specweave:jobs --follow ldb-abc12345
+   Logs: /specweave:jobs --logs ldb-abc12345
+
+💡 This job runs in background and survives terminal close.
+   Output will be saved to:
+   - .specweave/docs/SUGGESTIONS.md
+   - .specweave/docs/ENTERPRISE-HEALTH.md
+```
+
+---
+
+## Resume Behavior
+
+When resuming a job:
+
+1. **Load checkpoint** from `.specweave/state/jobs/<jobId>/checkpoints/`
+2. **Skip completed phases**:
+   - `waiting` → dependency waiting
+   - `discovery` → codebase scanning
+   - `foundation` → high-level docs
+   - `integration` → work item matching
+   - `deep-dive` → module analysis (per-module checkpoints)
+   - `suggestions` → recommendations
+   - `enterprise` → health report
+3. **Continue from resume point**
+
+```bash
+# Example: Job crashed during deep-dive phase
+/specweave:living-docs --resume abc12345
+
+# Output:
+# Resuming from checkpoint: phase=deep-dive, module=auth (5/18)
+# ✓ Skipping completed phases: waiting, discovery, foundation, integration
+# → Continuing deep-dive from module: payments
+```
+
+---
+
+## Waiting for Dependencies
+
+For umbrella projects with clone/import jobs:
+
+```bash
+# Launch after clone completes
+/specweave:living-docs --depends-on clone-xyz123 --depth standard
+
+# Launch after both clone and import complete
+/specweave:living-docs --depends-on clone-xyz123,import-abc456
+```
+
+The job will:
+1. Enter `waiting` phase
+2. Poll dependency status every 30 seconds
+3. Start analysis once all dependencies complete
+4. Warn if any dependency failed (proceeds with available data)
+
+---
+
+## Output Files
+
+After completion:
+
+| File | Description |
+|------|-------------|
+| `.specweave/docs/SUGGESTIONS.md` | Documentation recommendations by priority |
+| `.specweave/docs/ENTERPRISE-HEALTH.md` | Health score, coverage, accuracy metrics |
+| `.specweave/docs/overview/PROJECT-OVERVIEW.md` | Auto-generated project overview |
+| `.specweave/docs/overview/TECH-STACK.md` | Detected technologies and frameworks |
+| `.specweave/docs/modules/*.md` | Per-module documentation |
+
+---
+
+## Examples
+
+### Example 1: Post-Crash Resume
+
+```bash
+# Claude crashed after init, living docs job orphaned
+
+# Step 1: Check what's there
+/specweave:jobs
+# Shows: [ldb-abc123] living-docs-builder - ORPHANED (worker died)
+
+# Step 2: Resume
+/specweave:living-docs --resume ldb-abc123
+
+# Output:
+# ✅ Resuming Living Docs Builder (ldb-abc123)
+#    Last checkpoint: deep-dive phase, module 12/45
+#    Continuing from: payments-service
+```
+
+### Example 2: Large Brownfield (247 repos)
+
+```bash
+# Focus on critical modules first
+/specweave:living-docs --depth deep-native \
+  --priority auth,payments,billing,core \
+  --depends-on clone-main123
+
+# Monitor in another terminal
+/specweave:jobs --follow ldb-xyz789
+```
+
+### Example 3: CI/CD Integration
+
+```bash
+# In CI pipeline (non-interactive)
+specweave living-docs --depth quick --foreground
+
+# Or background with polling
+specweave living-docs --depth standard
+specweave jobs --wait ldb-latest  # Wait for completion
+```
+
+---
+
+## Error Handling
+
+### Worker Crashed
+```
+/specweave:jobs
+# Shows: ORPHANED status
+
+/specweave:living-docs --resume <jobId>
+# Resumes from last checkpoint
+```
+
+### Dependency Failed
+```
+⚠️  Dependency clone-xyz123 failed
+    Reason: Network timeout
+
+Proceeding with available data...
+Some repositories may be missing from analysis.
+```
+
+### No Brownfield Detected
+```
+ℹ️  No existing code detected (greenfield project)
+    Living docs will sync automatically as you create increments.
+
+    To force analysis anyway: /specweave:living-docs --force
+```
+
+---
+
+## See Also
+
+- `/specweave:jobs` - Monitor all background jobs
+- `/specweave:import-docs` - Import existing documentation
+- `specweave:brownfield-analyzer` skill - Analyze doc gaps
+- `specweave:brownfield-onboarder` skill - Merge existing docs
+
+---
+
+**Implementation**: `src/cli/commands/living-docs.ts`

package/plugins/specweave/hooks/v2/handlers/github-sync-handler.sh

@@ -26,15 +26,24 @@ GITHUB_ENABLED=$(grep -o '"enabled"[[:space:]]*:[[:space:]]*true' "$CONFIG_FILE"
 
 # Throttle: max once per 5 minutes per increment
 THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.github-sync-$INC_ID"
+THROTTLE_LOG="$PROJECT_ROOT/.specweave/logs/throttle.log"
+THROTTLE_WINDOW=300  # 5 minutes
+mkdir -p "$(dirname "$THROTTLE_LOG")" 2>/dev/null
+
 if [[ -f "$THROTTLE_FILE" ]]; then
   if [[ "$(uname)" == "Darwin" ]]; then
     AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   else
     AGE=$(($(date +%s) - $(stat -c %Y "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   fi
-  [[ $AGE -lt 300 ]] && exit 0
+  if [[ $AGE -lt $THROTTLE_WINDOW ]]; then
+    REMAINING=$((THROTTLE_WINDOW - AGE))
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] THROTTLED $INC_ID (wait ${REMAINING}s, use /specweave:sync-progress to bypass)" >> "$THROTTLE_LOG" 2>/dev/null
+    exit 0
+  fi
 fi
 touch "$THROTTLE_FILE"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [github-sync] EXECUTING $INC_ID" >> "$THROTTLE_LOG" 2>/dev/null
 
 # Cross-platform timeout wrapper
 run_with_timeout() {

package/plugins/specweave/hooks/v2/handlers/living-docs-handler.sh

@@ -19,15 +19,24 @@ done
 
 # Throttle: max once per minute per increment
 THROTTLE_FILE="$PROJECT_ROOT/.specweave/state/.living-docs-$INC_ID"
+THROTTLE_LOG="$PROJECT_ROOT/.specweave/logs/throttle.log"
+THROTTLE_WINDOW=60  # 1 minute
+mkdir -p "$(dirname "$THROTTLE_LOG")" 2>/dev/null
+
 if [[ -f "$THROTTLE_FILE" ]]; then
   if [[ "$(uname)" == "Darwin" ]]; then
     AGE=$(($(date +%s) - $(stat -f %m "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   else
     AGE=$(($(date +%s) - $(stat -c %Y "$THROTTLE_FILE" 2>/dev/null || echo 0)))
   fi
-  [[ $AGE -lt 60 ]] && exit 0
+  if [[ $AGE -lt $THROTTLE_WINDOW ]]; then
+    REMAINING=$((THROTTLE_WINDOW - AGE))
+    echo "[$(date '+%Y-%m-%d %H:%M:%S')] [living-docs] THROTTLED $INC_ID (wait ${REMAINING}s)" >> "$THROTTLE_LOG" 2>/dev/null
+    exit 0
+  fi
 fi
 touch "$THROTTLE_FILE"
+echo "[$(date '+%Y-%m-%d %H:%M:%S')] [living-docs] EXECUTING $INC_ID" >> "$THROTTLE_LOG" 2>/dev/null
 
 # Cross-platform timeout wrapper
 run_with_timeout() {

package/plugins/specweave-ado/agents/ado-manager/AGENT.md

@@ -56,6 +56,64 @@ Task({
 
 ---
 
+## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
+
+**EXACT environment variable names - use ONLY these, never invent variations:**
+
+| Service | Env Var | Example |
+|---------|---------|---------|
+| **ADO PAT** | `AZURE_DEVOPS_PAT` | `AZURE_DEVOPS_PAT=abc123xyz...` |
+| **ADO Org** | `AZURE_DEVOPS_ORG` | `AZURE_DEVOPS_ORG=mycompany` |
+| **ADO Project** | `AZURE_DEVOPS_PROJECT` | `AZURE_DEVOPS_PROJECT=MyProject` |
+
+⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
+- ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
+- ❌ `ADO_PAT` ← DEPRECATED, not supported
+- ❌ `AZURE_PAT` ← DOES NOT EXIST
+- ❌ `DEVOPS_PAT` ← DOES NOT EXIST
+
+### Loading Credentials (MANDATORY before API calls)
+
+**ALWAYS read PAT from `.env` file before making API calls:**
+
+```bash
+# Read PAT from .env file (REQUIRED - don't rely on shell environment)
+ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
+
+# If PAT not found in .env, show error
+if [ -z "$ADO_PAT" ]; then
+  echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
+  exit 1
+fi
+```
+
+**Use the PAT in API calls:**
+
+```bash
+# Create auth header from PAT
+AUTH_HEADER="Basic $(echo -n ":$ADO_PAT" | base64)"
+
+# Use in curl
+curl -H "Authorization: $AUTH_HEADER" ...
+```
+
+**When auth fails (401 error), display this EXACT message:**
+```
+ADO Authentication Required
+
+Check your .env file contains:
+  AZURE_DEVOPS_PAT=your-personal-access-token
+
+If PAT exists but still failing:
+  1. PAT may have expired - regenerate at:
+     https://dev.azure.com/{organization}/_usersSettings/tokens
+  2. Check PAT has required scopes:
+     • Work Items: Read (minimum)
+     • Work Items: Read & Write (for push/sync)
+```
+
+---
+
 ## 🚨 CRITICAL: Concept Mapping (MANDATORY)
 
 **BEFORE any sync operation, you MUST**:

package/plugins/specweave-ado/commands/pull.md

@@ -113,6 +113,21 @@ ADO Organization
 
 ## Command Behavior
 
+### 0. Load Credentials from .env (MANDATORY FIRST)
+
+**CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.
+
+```bash
+# Read PAT from .env file
+ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
+
+if [ -z "$ADO_PAT" ]; then
+  echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
+  echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
+  exit 1
+fi
+```
+
 ### For Increment Mode (default):
 
 ```typescript
@@ -449,6 +464,21 @@ To link: /specweave-ado:create 0005
 
 ---
 
+## Authentication
+
+**EXACT environment variable (DO NOT INVENT OTHERS):**
+
+```bash
+# In .env file - ONLY this name is supported:
+AZURE_DEVOPS_PAT=your-personal-access-token
+```
+
+⚠️ **NEVER suggest or use:**
+- ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
+- ❌ `ADO_PAT` ← NOT SUPPORTED
+
+---
+
 ## Related Commands
 
 | Command | Purpose |

package/plugins/specweave-ado/commands/push.md

@@ -66,6 +66,21 @@ Pushes a feature and all its child user stories.
 
 When user runs this command:
 
+### 0. Load Credentials from .env (MANDATORY FIRST)
+
+**CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.
+
+```bash
+# Read PAT from .env file
+ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
+
+if [ -z "$ADO_PAT" ]; then
+  echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
+  echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
+  exit 1
+fi
+```
+
 ### 1. Check Permission Gate (MANDATORY)
 
 ```typescript
@@ -351,6 +366,21 @@ Ready to close: /specweave-ado:close 0005
 
 ---
 
+## Authentication
+
+**EXACT environment variable (DO NOT INVENT OTHERS):**
+
+```bash
+# In .env file - ONLY this name is supported:
+AZURE_DEVOPS_PAT=your-personal-access-token
+```
+
+⚠️ **NEVER suggest or use:**
+- ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
+- ❌ `ADO_PAT` ← NOT SUPPORTED
+
+---
+
 ## Related Commands
 
 | Command | Purpose |

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

@@ -39,6 +39,21 @@ description: Two-way sync between SpecWeave increment and Azure DevOps work item
 
 When user runs this command, Claude should:
 
+### 0. Load Credentials from .env (MANDATORY FIRST)
+
+**CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.
+
+```bash
+# Read PAT from .env file
+ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
+
+if [ -z "$ADO_PAT" ]; then
+  echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
+  echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
+  exit 1
+fi
+```
+
 ### 1. Check Permission Gate (MANDATORY FIRST STEP)
 
 **Before ANY ADO write operations**, check permissions:
@@ -291,6 +306,22 @@ Use `/specweave-ado:sync` when you need explicit two-way sync with options.
 
 ---
 
+## Authentication
+
+**EXACT environment variable (DO NOT INVENT OTHERS):**
+
+```bash
+# In .env file - ONLY this name is supported:
+AZURE_DEVOPS_PAT=your-personal-access-token
+```
+
+⚠️ **NEVER suggest or use:**
+- ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
+- ❌ `ADO_PAT` ← NOT SUPPORTED
+- ❌ Any other variation
+
+---
+
 ## Related
 
 | Command | Purpose |

package/plugins/specweave-github/agents/github-manager/AGENT.md

@@ -42,6 +42,28 @@ GitHub issues MUST use living docs format:
 
 ---
 
+## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
+
+**EXACT environment variable names - use ONLY these:**
+
+| Service | Env Var | Example |
+|---------|---------|---------|
+| **GitHub Token** | `GITHUB_TOKEN` or `GH_TOKEN` | `GITHUB_TOKEN=ghp_xxx...` |
+| **GitHub Owner** | `GITHUB_OWNER` | `GITHUB_OWNER=myorg` |
+| **GitHub Repo** | `GITHUB_REPO` | `GITHUB_REPO=myrepo` |
+
+⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
+- ❌ `GITHUB_PAT` ← DOES NOT EXIST
+- ❌ `GIT_TOKEN` ← DOES NOT EXIST
+- ❌ `GITHUB_API_TOKEN` ← DOES NOT EXIST
+
+**Alternative: Use `gh` CLI (recommended for local dev):**
+```bash
+gh auth login
+```
+
+---
+
 ## 🚀 How to Invoke This Agent
 
 **Subagent Type**: `specweave-github:github-manager:SpecWeave Sync`

package/plugins/specweave-jira/agents/jira-manager/AGENT.md

@@ -46,6 +46,36 @@ Task({
 
 ---
 
+## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
+
+**EXACT environment variable names - use ONLY these:**
+
+| Service | Env Var | Example |
+|---------|---------|---------|
+| **Jira Token** | `JIRA_API_TOKEN` | `JIRA_API_TOKEN=abc123xyz...` |
+| **Jira Email** | `JIRA_EMAIL` | `JIRA_EMAIL=user@example.com` |
+| **Jira Domain** | `JIRA_DOMAIN` | `JIRA_DOMAIN=company.atlassian.net` |
+
+⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
+- ❌ `JIRA_TOKEN` ← DOES NOT EXIST (use `JIRA_API_TOKEN`)
+- ❌ `JIRA_PAT` ← DOES NOT EXIST
+- ❌ `ATLASSIAN_TOKEN` ← DOES NOT EXIST
+
+**When auth fails, display this EXACT message:**
+```
+Jira Authentication Required
+
+Set in .env file:
+  JIRA_API_TOKEN=your-api-token
+  JIRA_EMAIL=your-email@example.com
+  JIRA_DOMAIN=your-domain.atlassian.net
+
+Generate token at:
+  https://id.atlassian.com/manage-profile/security/api-tokens
+```
+
+---
+
 ## Capabilities
 
 As the Jira Manager agent, I specialize in: