specweave 0.30.13 → 0.30.16

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

@@ -0,0 +1,391 @@
+---
+name: specweave-ado:push
+description: Push local changes to Azure DevOps (like git push). Supports increment, project, or full living docs sync.
+---
+
+# ADO Push Command
+
+**Usage**: `/specweave-ado:push [target] [options]`
+
+**Purpose**: Push local changes to Azure DevOps (like `git push`)
+
+---
+
+## Quick Start
+
+```bash
+# Push current/active increment (simple mode)
+/specweave-ado:push
+
+# Push specific increment
+/specweave-ado:push 0005
+
+# Push ALL local changes to ADO (living docs sync)
+/specweave-ado:push --all
+
+# Push specific project/board
+/specweave-ado:push --project clinical-insights
+
+# Push specific feature hierarchy
+/specweave-ado:push --feature FS-042
+```
+
+---
+
+## Sync Modes
+
+### Mode 1: Increment Sync (Default)
+Pushes task progress from ONE increment to its linked work item.
+
+### Mode 2: Living Docs Sync (--all)
+Pushes ALL local spec changes to corresponding ADO items:
+- Scans `.specweave/docs/internal/specs/` for modified specs
+- Updates status, progress, comments on linked ADO items
+- Respects multi-project folder structure
+
+### Mode 3: Project-Scoped Sync (--project)
+Pushes changes only within a specific project folder.
+
+### Mode 4: Feature Hierarchy Sync (--feature)
+Pushes a feature and all its child user stories.
+
+---
+
+## What Gets Pushed
+
+| Field | Source |
+|-------|--------|
+| **Progress** | Calculated from tasks.md (X/Y tasks, Z%) |
+| **Comment** | Auto-generated with completed tasks list |
+| **Completion %** | Updated on work item custom field |
+| **State** | Updated if threshold crossed (e.g., 100% -> Resolved) |
+
+---
+
+## Command Behavior
+
+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
+const config = JSON.parse(await fs.readFile('.specweave/config.json', 'utf-8'));
+const canUpdateExternal = config?.sync?.settings?.canUpdateExternalItems ?? false;
+
+if (!canUpdateExternal) {
+  console.log(`
+Permission Denied: ADO writes disabled
+
+Current: sync.settings.canUpdateExternalItems = false
+
+To enable writes, update .specweave/config.json:
+  "sync": { "settings": { "canUpdateExternalItems": true } }
+
+Or use read-only mode:
+  /specweave-ado:pull ${incrementId}
+`);
+  return;
+}
+```
+
+### 2. Resolve Increment & Profile
+
+```typescript
+const incrementId = args.incrementId || await findActiveIncrement();
+
+const metadata = JSON.parse(await fs.readFile(
+  `.specweave/increments/${incrementId}/metadata.json`, 'utf-8'
+));
+
+const adoWorkItemId = metadata?.external_sync?.ado?.workItemId;
+if (!adoWorkItemId) {
+  console.log(`Not linked to ADO. Run: /specweave-ado:create ${incrementId}`);
+  return;
+}
+
+const profileName = metadata?.external_sync?.ado?.profile
+  || config?.sync?.defaultProfile;
+```
+
+### 3. Calculate Progress
+
+```typescript
+const tasksContent = await fs.readFile(
+  `.specweave/increments/${incrementId}/tasks.md`, 'utf-8'
+);
+
+const totalTasks = (tasksContent.match(/### T-\d+/g) || []).length;
+const completedTasks = (tasksContent.match(/\[x\] completed/gi) || []).length;
+const percentage = Math.round((completedTasks / totalTasks) * 100);
+
+// Find recently completed tasks (for comment)
+const recentlyCompleted = parseRecentlyCompletedTasks(tasksContent);
+```
+
+### 4. Invoke Push Sync
+
+```
+Use Task tool with subagent_type: "specweave-ado:ado-manager:ado-manager"
+
+Prompt: "Push progress to ADO for increment {increment-id}.
+
+DIRECTION: to-ado
+PERMISSION: canUpdateExternalItems = true (verified)
+
+Profile: {profileName}
+Work Item: #{workItemId}
+
+Progress: {completedTasks}/{totalTasks} ({percentage}%)
+Recently completed: {recentlyCompleted}
+
+Steps:
+1. Format progress comment with task list
+2. POST comment to ADO work item
+3. PATCH work item completion field
+4. Update state if threshold crossed:
+   - 100% completed -> Resolved (if canUpdateStatus)
+5. Update sync timestamp in metadata
+6. Display push summary"
+```
+
+### 5. Display Result
+
+```
+Pushed to ADO
+
+Work Item: #12345
+Profile: ado-my-project
+
+Progress: 6/10 tasks (60%)
+
+Comment posted:
+  "Progress Update: 60% complete
+
+   Recently completed:
+   - T-005: Add payment validation
+   - T-006: Implement refund flow"
+
+Fields updated:
+  Completion: 60%
+
+URL: https://dev.azure.com/org/project/_workitems/edit/12345
+```
+
+---
+
+## Permission Requirements
+
+| Permission | Required | Purpose |
+|------------|----------|---------|
+| `canUpdateExternalItems` | **true** | Write to ADO |
+| `canUpdateStatus` | optional | Change work item state |
+
+If `canUpdateStatus` is false, progress is posted but state unchanged.
+
+---
+
+## Examples
+
+### Example 1: Simple Push
+
+```
+User: /specweave-ado:push
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: true
+
+Pushing to ADO...
+  Increment: 0005-payment-integration
+  Work Item: #12345
+
+Pushed to ADO
+
+Progress: 8/10 tasks (80%)
+Comment posted with 2 recently completed tasks
+
+Push complete!
+```
+
+### Example 2: Permission Denied
+
+```
+User: /specweave-ado:push 0005
+
+Claude:
+Checking permissions...
+  canUpdateExternalItems: false
+
+Permission Denied
+
+To enable ADO writes:
+1. Edit .specweave/config.json
+2. Set sync.settings.canUpdateExternalItems = true
+
+Or use read-only: /specweave-ado:pull 0005
+```
+
+### Example 3: 100% Complete
+
+```
+User: /specweave-ado:push 0005
+
+Claude:
+Pushing to ADO...
+
+Progress: 10/10 tasks (100%)
+
+Comment posted:
+  "Progress Update: 100% complete - All tasks done!"
+
+State updated:
+  Active -> Resolved (canUpdateStatus = true)
+
+Ready to close: /specweave-ado:close 0005
+```
+
+---
+
+## Sync Brief (MANDATORY OUTPUT)
+
+**After EVERY push operation, display a compact summary:**
+
+### Brief Format (Single Increment)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Increment: 0005-payment-integration                    │
+│  Work Item: #12345                                      │
+│  Profile:   ado-techcorp                                │
+├─────────────────────────────────────────────────────────┤
+│  PROGRESS                                               │
+│    Tasks: 8/10 (80%)  ████████░░                        │
+│    ↑ Comment posted: "Progress: 80% complete"           │
+│    ↑ Completion field: 60% → 80%                        │
+├─────────────────────────────────────────────────────────┤
+│  RECENTLY COMPLETED                                     │
+│    ✓ T-007: Add payment validation                      │
+│    ✓ T-008: Implement refund flow                       │
+├─────────────────────────────────────────────────────────┤
+│  Last sync: 2025-12-04 10:32:15 (just now)              │
+│  URL: https://dev.azure.com/.../12345                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Brief Format (Multi-Project --all)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Pushed: 12 specs across 3 projects                     │
+│  Comments posted: 12                                    │
+│  Status transitions: 3                                  │
+│  Duration: 5.1s                                         │
+├─────────────────────────────────────────────────────────┤
+│  BY PROJECT                                             │
+│    techcorp/clinical-insights/   5 pushed               │
+│    techcorp/ai-platform/         4 pushed               │
+│    infrastructure/core/          3 pushed               │
+├─────────────────────────────────────────────────────────┤
+│  CHANGES PUSHED                                         │
+│    ↑ Progress comments: 12                              │
+│    ↑ Completion updates: 8                              │
+│    ↑ Status transitions: 3                              │
+│      • FS-042/us-001: Active → Resolved (100%)          │
+│      • FS-043/us-005: Active → Resolved (100%)          │
+│      • FS-050/us-010: New → Active (started)            │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Brief Format (100% Complete - Ready to Close)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Increment: 0005-payment-integration                    │
+│  Work Item: #12345                                      │
+├─────────────────────────────────────────────────────────┤
+│  PROGRESS                                               │
+│    Tasks: 10/10 (100%)  ██████████  COMPLETE!           │
+│    ↑ Comment: "All tasks complete!"                     │
+│    ↑ Status: Active → Resolved                          │
+├─────────────────────────────────────────────────────────┤
+│  🎉 INCREMENT READY TO CLOSE                            │
+│     Run: /specweave-ado:close 0005                      │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Brief Format (Permission Denied)
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  PUSH BLOCKED                                     ✗ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Permission: canUpdateExternalItems = false             │
+├─────────────────────────────────────────────────────────┤
+│  TO ENABLE:                                             │
+│    Edit .specweave/config.json:                         │
+│    sync.settings.canUpdateExternalItems = true          │
+│                                                         │
+│  OR USE READ-ONLY:                                      │
+│    /specweave-ado:pull 0005                             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Symbols Reference
+
+| Symbol | Meaning |
+|--------|---------|
+| `✓` | Success |
+| `⚠` | Warning (partial success) |
+| `✗` | Error/Failed |
+| `↓` | Pulled from external (incoming) |
+| `↑` | Pushed to external (outgoing) |
+| `+` | Added (new items) |
+| `−` | Removed |
+| `~` | Modified |
+
+---
+
+## 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 |
+|---------|---------|
+| `/specweave-ado:pull` | Pull changes from ADO |
+| `/specweave-ado:sync` | Two-way sync (pull + push) |
+| `/specweave-ado:status` | Check sync status |
+| `/specweave-ado:close` | Close completed work item |

package/plugins/specweave-ado/commands/{specweave-ado-status.md → status.md}

@@ -51,3 +51,15 @@ Sync Enabled: ✅
 
 Next Sync: Automatic on task completion
 ```
+
+---
+
+## Related
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull changes from ADO |
+| `/specweave-ado:push` | Push progress to ADO |
+| `/specweave-ado:sync` | Two-way sync |
+| `/specweave-ado:create` | Create ADO work item |
+| `/specweave-ado:close` | Close work item |

package/plugins/specweave-ado/commands/{specweave-ado-sync.md → 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:
@@ -234,8 +249,85 @@ Options:
 
 ---
 
+## Simpler Alternatives
+
+For most use cases, use the git-style commands:
+
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull changes from ADO (read-only) |
+| `/specweave-ado:push` | Push progress to ADO |
+
+Use `/specweave-ado:sync` when you need explicit two-way sync with options.
+
+---
+
+## Sync Brief (MANDATORY OUTPUT)
+
+**After EVERY sync operation, display a compact two-way summary:**
+
+```
+┌─────────────────────────────────────────────────────────┐
+│  SYNC COMPLETE                                    ✓ ADO │
+├─────────────────────────────────────────────────────────┤
+│  Increment: 0005-payment-integration                    │
+│  Work Item: #12345                                      │
+│  Profile:   ado-techcorp                                │
+│  Direction: two-way (pull + push)                       │
+├─────────────────────────────────────────────────────────┤
+│  PULLED (from ADO)                              ↓       │
+│    ↓ Status:    Active → Resolved  (external wins)      │
+│    ↓ Priority:  P2 → P1                                 │
+│    + Comments:  2 new imported                          │
+├─────────────────────────────────────────────────────────┤
+│  PUSHED (to ADO)                                ↑       │
+│    Tasks: 8/10 (80%)  ████████░░                        │
+│    ↑ Comment posted: "Progress: 80% complete"           │
+│    ↑ Completion: 60% → 80%                              │
+├─────────────────────────────────────────────────────────┤
+│  CONFLICTS RESOLVED: 1                                  │
+│    Status: local "in-progress" vs ADO "Resolved"        │
+│    Winner: ADO (external tool always wins)              │
+├─────────────────────────────────────────────────────────┤
+│  Last sync: 2025-12-04 10:32:15 (just now)              │
+│  URL: https://dev.azure.com/.../12345                   │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Symbols Reference
+
+| Symbol | Meaning |
+|--------|---------|
+| `✓` | Success |
+| `⚠` | Warning |
+| `✗` | Failed |
+| `↓` | Pulled (incoming) |
+| `↑` | Pushed (outgoing) |
+
+---
+
+## 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
 
-- `/specweave-ado:create-workitem` - Create new ADO work item
-- `/specweave-ado:status` - Check sync status (read-only, always allowed)
-- `/specweave-ado:close-workitem` - Close work item when complete
+| Command | Purpose |
+|---------|---------|
+| `/specweave-ado:pull` | Pull from ADO (git-style) |
+| `/specweave-ado:push` | Push to ADO (git-style) |
+| `/specweave-ado:create` | Create new ADO work item |
+| `/specweave-ado:status` | Check sync status |
+| `/specweave-ado:close` | Close work item when complete |

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

@@ -193,7 +193,7 @@ Core hook (330 lines)      ADO plugin hook (150 lines)
 
 - **Core Plugin Hooks**: `plugins/specweave/hooks/README.md`
 - **Architecture Analysis**: `.specweave/increments/0018-strict-increment-discipline-enforcement/reports/HOOKS-ARCHITECTURE-ANALYSIS.md`
-- **ADO Sync Command**: `plugins/specweave-ado/commands/specweave-ado-sync.md`
+- **ADO Sync Command**: `plugins/specweave-ado/commands/sync.md`
 
 ---
 

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

@@ -407,9 +407,9 @@ cat ./docs/api/index.md ./docs/specs/index.md > ./docs/complete-reference.md
 
 ## Related Commands
 
-- `/specweave-docs:docs-init` - Initialize Docusaurus documentation site
-- `/specweave-docs-preview:preview` - Preview generated documentation
-- `/specweave-docs-preview:build` - Build static site from generated docs
+- `/specweave-docs:init` - Initialize Docusaurus documentation site
+- `/specweave-docs:preview` - Preview generated documentation
+- `/specweave-docs:build` - Build static site from generated docs
 
 ## Requirements
 

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

@@ -303,14 +303,14 @@ themeConfig: {
 
 ### Custom Output Directory
 ```bash
-/specweave-docs:docs-init --output ./documentation
+/specweave-docs:init --output ./documentation
 ```
 
 ## Related Commands
 
-- `/specweave-docs:docs-generate` - Generate docs from code/specs
-- `/specweave-docs-preview:preview` - Launch documentation preview server
-- `/specweave-docs-preview:build` - Build static documentation site
+- `/specweave-docs:generate` - Generate docs from code/specs
+- `/specweave-docs:preview` - Launch documentation preview server
+- `/specweave-docs:build` - Build static documentation site
 
 ## Requirements
 

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

@@ -1,6 +1,6 @@
 ---
 name: specweave-docs:preview
-description: Launch Docusaurus documentation server. Supports both public (port 3016) and internal (port 8001) documentation sites.
+description: Launch Docusaurus documentation server. Supports both public (port 3016) and internal (port 3015) documentation sites.
 ---
 
 # Documentation Preview Command
@@ -21,7 +21,7 @@ Launch Docusaurus development server with hot reload, Mermaid diagrams, and auto
 
 | Site | Port | Content | NPM Script |
 |------|------|---------|------------|
-| **Internal** | 8001 | `.specweave/docs/internal/` | `docs:internal` |
+| **Internal** | 3015 | `.specweave/docs/internal/` | `docs:internal` |
 | **Public** | 3016 | `docs-site/docs/` | `docs:dev` |
 
 ## Your Task
@@ -40,7 +40,7 @@ if [ "$PUBLIC_FLAG" = "--public" ]; then
   echo ""
   npm run docs:dev
 else
-  echo "Launching INTERNAL documentation on port 8001..."
+  echo "Launching INTERNAL documentation on port 3015..."
   echo "Content: .specweave/docs/internal/"
   echo ""
   npm run docs:internal
@@ -83,7 +83,7 @@ This installs Docusaurus dependencies (~200MB, ~30 seconds).
 | Script | Port | URL |
 |--------|------|-----|
 | `docs:dev` | 3016 | http://localhost:3016 |
-| `docs:internal` | 8001 | http://localhost:8001 |
+| `docs:internal` | 3015 | http://localhost:3015 |
 
 ## Internal Docs Structure
 
@@ -115,7 +115,7 @@ This installs Docusaurus dependencies (~200MB, ~30 seconds).
 ### Port already in use
 ```bash
 # Find process using port
-lsof -i :8001
+lsof -i :3015
 
 # Kill it
 kill -9 <PID>

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-github/agents/user-story-updater/AGENT.md

@@ -161,7 +161,7 @@ Agent: "I'll update GitHub issue #501 for US-004 to include checkable ACs and ta
 
 **Related Files**:
 - `plugins/specweave-github/lib/user-story-content-builder.ts` - Core builder class
-- `plugins/specweave-github/commands/specweave-github-update-user-story.md` - Command spec
+- `plugins/specweave-github/commands/update-user-story.md` - Command spec
 - `.specweave/docs/internal/specs/{project}/FS-*/us-*.md` - User story files
 
 **Testing**:

package/plugins/specweave-github/commands/{specweave-github-close-issue.md → close.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave-github:close-issue
+name: specweave-github:close
 description: Close GitHub issue for completed SpecWeave increment. Posts completion summary with final stats, deliverables, and closes the issue. Links closure in increment metadata.
 ---
 
@@ -7,7 +7,7 @@ description: Close GitHub issue for completed SpecWeave increment. Posts complet
 
 Close the GitHub issue associated with a completed SpecWeave increment.
 
-## Usage
+**Usage**: `/specweave-github:close <increment-id>`
 
 ```bash
 /specweave:github:close-issue <increment-id> [options]

package/plugins/specweave-github/commands/{specweave-github-create-issue.md → create.md}

@@ -1,5 +1,5 @@
 ---
-name: specweave-github:create-issue
+name: specweave-github:create
 description: Create a GitHub issue for a SpecWeave increment. Generates issue from increment specs with task checklist, labels, and milestone. Links issue to increment metadata.
 ---
 
@@ -7,7 +7,7 @@ description: Create a GitHub issue for a SpecWeave increment. Generates issue fr
 
 Create a GitHub issue for the specified SpecWeave increment.
 
-## Usage
+**Usage**: `/specweave-github:create <increment-id>`
 
 ```bash
 /specweave:github:create-issue <increment-id> [options]