specweave 0.30.14 → 0.30.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (100) hide show
  1. package/CLAUDE.md +43 -0
  2. package/README.md +32 -0
  3. package/bin/specweave.js +28 -0
  4. package/dist/src/cli/commands/commits.d.ts +7 -0
  5. package/dist/src/cli/commands/commits.d.ts.map +1 -0
  6. package/dist/src/cli/commands/commits.js +42 -0
  7. package/dist/src/cli/commands/commits.js.map +1 -0
  8. package/dist/src/cli/commands/living-docs.d.ts +29 -0
  9. package/dist/src/cli/commands/living-docs.d.ts.map +1 -0
  10. package/dist/src/cli/commands/living-docs.js +350 -0
  11. package/dist/src/cli/commands/living-docs.js.map +1 -0
  12. package/dist/src/cli/helpers/ado-area-selector.js +1 -1
  13. package/dist/src/cli/helpers/ado-area-selector.js.map +1 -1
  14. package/dist/src/cli/workers/living-docs-worker.js +80 -44
  15. package/dist/src/cli/workers/living-docs-worker.js.map +1 -1
  16. package/dist/src/core/background/index.d.ts +2 -2
  17. package/dist/src/core/background/index.d.ts.map +1 -1
  18. package/dist/src/core/background/index.js +1 -1
  19. package/dist/src/core/background/index.js.map +1 -1
  20. package/dist/src/core/living-docs/living-docs-sync.d.ts +60 -24
  21. package/dist/src/core/living-docs/living-docs-sync.d.ts.map +1 -1
  22. package/dist/src/core/living-docs/living-docs-sync.js +360 -103
  23. package/dist/src/core/living-docs/living-docs-sync.js.map +1 -1
  24. package/dist/src/core/llm/index.d.ts +1 -0
  25. package/dist/src/core/llm/index.d.ts.map +1 -1
  26. package/dist/src/core/llm/index.js +2 -0
  27. package/dist/src/core/llm/index.js.map +1 -1
  28. package/dist/src/core/llm/providers/anthropic-provider.d.ts.map +1 -1
  29. package/dist/src/core/llm/providers/anthropic-provider.js +15 -26
  30. package/dist/src/core/llm/providers/anthropic-provider.js.map +1 -1
  31. package/dist/src/core/llm/providers/azure-openai-provider.d.ts.map +1 -1
  32. package/dist/src/core/llm/providers/azure-openai-provider.js +13 -5
  33. package/dist/src/core/llm/providers/azure-openai-provider.js.map +1 -1
  34. package/dist/src/core/llm/providers/bedrock-provider.d.ts.map +1 -1
  35. package/dist/src/core/llm/providers/bedrock-provider.js +12 -8
  36. package/dist/src/core/llm/providers/bedrock-provider.js.map +1 -1
  37. package/dist/src/core/llm/providers/claude-code-provider.d.ts.map +1 -1
  38. package/dist/src/core/llm/providers/claude-code-provider.js +15 -25
  39. package/dist/src/core/llm/providers/claude-code-provider.js.map +1 -1
  40. package/dist/src/core/llm/providers/ollama-provider.d.ts.map +1 -1
  41. package/dist/src/core/llm/providers/ollama-provider.js +12 -9
  42. package/dist/src/core/llm/providers/ollama-provider.js.map +1 -1
  43. package/dist/src/core/llm/providers/openai-provider.d.ts.map +1 -1
  44. package/dist/src/core/llm/providers/openai-provider.js +13 -6
  45. package/dist/src/core/llm/providers/openai-provider.js.map +1 -1
  46. package/dist/src/core/llm/providers/vertex-ai-provider.d.ts.map +1 -1
  47. package/dist/src/core/llm/providers/vertex-ai-provider.js +12 -8
  48. package/dist/src/core/llm/providers/vertex-ai-provider.js.map +1 -1
  49. package/dist/src/importers/ado-importer.js +2 -2
  50. package/dist/src/importers/ado-importer.js.map +1 -1
  51. package/dist/src/importers/item-converter.d.ts +6 -1
  52. package/dist/src/importers/item-converter.d.ts.map +1 -1
  53. package/dist/src/importers/item-converter.js +15 -2
  54. package/dist/src/importers/item-converter.js.map +1 -1
  55. package/dist/src/integrations/ado/ado-pat-provider.d.ts +3 -3
  56. package/dist/src/integrations/ado/ado-pat-provider.js +3 -3
  57. package/dist/src/living-docs/epic-id-allocator.d.ts +1 -1
  58. package/dist/src/living-docs/epic-id-allocator.js +1 -1
  59. package/dist/src/living-docs/fs-id-allocator.d.ts +1 -1
  60. package/dist/src/living-docs/fs-id-allocator.js +1 -1
  61. package/dist/src/utils/auth-helpers.d.ts +23 -0
  62. package/dist/src/utils/auth-helpers.d.ts.map +1 -1
  63. package/dist/src/utils/auth-helpers.js +51 -0
  64. package/dist/src/utils/auth-helpers.js.map +1 -1
  65. package/dist/src/utils/feature-id-collision.d.ts +48 -5
  66. package/dist/src/utils/feature-id-collision.d.ts.map +1 -1
  67. package/dist/src/utils/feature-id-collision.js +251 -19
  68. package/dist/src/utils/feature-id-collision.js.map +1 -1
  69. package/dist/src/utils/llm-json-extractor.d.ts +105 -0
  70. package/dist/src/utils/llm-json-extractor.d.ts.map +1 -0
  71. package/dist/src/utils/llm-json-extractor.js +336 -0
  72. package/dist/src/utils/llm-json-extractor.js.map +1 -0
  73. package/dist/src/utils/structure-level-detector.d.ts +105 -0
  74. package/dist/src/utils/structure-level-detector.d.ts.map +1 -0
  75. package/dist/src/utils/structure-level-detector.js +388 -0
  76. package/dist/src/utils/structure-level-detector.js.map +1 -0
  77. package/dist/src/utils/validators/ado-validator.js +2 -2
  78. package/dist/src/utils/validators/ado-validator.js.map +1 -1
  79. package/package.json +1 -2
  80. package/plugins/specweave/commands/specweave-increment.md +57 -9
  81. package/plugins/specweave/commands/specweave-living-docs.md +321 -0
  82. package/plugins/specweave/commands/specweave-sync-specs.md +37 -6
  83. package/plugins/specweave/hooks/hooks.json +10 -0
  84. package/plugins/specweave/hooks/spec-project-validator.sh +111 -0
  85. package/plugins/specweave/hooks/v2/handlers/github-sync-handler.sh +10 -1
  86. package/plugins/specweave/hooks/v2/handlers/living-docs-handler.sh +10 -1
  87. package/plugins/specweave/skills/increment-planner/SKILL.md +109 -10
  88. package/plugins/specweave/skills/increment-planner/templates/spec-multi-project.md +2 -0
  89. package/plugins/specweave/skills/increment-planner/templates/spec-single-project.md +1 -0
  90. package/plugins/specweave/skills/multi-project-spec-mapper/SKILL.md +24 -1
  91. package/plugins/specweave/skills/spec-generator/SKILL.md +18 -0
  92. package/plugins/specweave/skills/specweave-framework/SKILL.md +25 -0
  93. package/plugins/specweave-ado/agents/ado-manager/AGENT.md +58 -0
  94. package/plugins/specweave-ado/commands/pull.md +30 -0
  95. package/plugins/specweave-ado/commands/push.md +30 -0
  96. package/plugins/specweave-ado/commands/sync.md +31 -0
  97. package/plugins/specweave-github/agents/github-manager/AGENT.md +22 -0
  98. package/plugins/specweave-github/hooks/.specweave/logs/hooks-debug.log +14 -0
  99. package/plugins/specweave-jira/agents/jira-manager/AGENT.md +30 -0
  100. package/plugins/specweave-release/hooks/.specweave/logs/dora-tracking.log +21 -0
@@ -176,6 +176,81 @@ echo "Using coverageTarget: $coverageTarget"
176
176
 
177
177
  **Store these values for use in STEP 4 and STEP 7!**
178
178
 
179
+ ### STEP 0B: Detect Structure Level & Select Project/Board (MANDATORY!)
180
+
181
+ **⚠️ CRITICAL: Before generating spec.md, you MUST know the target project (and board for 2-level structures)!**
182
+
183
+ **Structure Levels:**
184
+ - **1-Level**: `internal/specs/{project}/FS-XXX/` - requires `project` in spec.md
185
+ - **2-Level**: `internal/specs/{project}/{board}/FS-XXX/` - requires BOTH `project` AND `board`
186
+
187
+ **Detection Logic** (use `src/utils/structure-level-detector.ts`):
188
+
189
+ ```typescript
190
+ import { detectStructureLevel, getRequiredSpecFields } from './utils/structure-level-detector.js';
191
+
192
+ const structureConfig = detectStructureLevel(projectRoot);
193
+ console.log(`Structure level: ${structureConfig.level}`);
194
+ console.log(`Detection reason: ${structureConfig.detectionReason}`);
195
+ console.log(`Available projects: ${structureConfig.projects.map(p => p.id).join(', ')}`);
196
+
197
+ if (structureConfig.level === 2 && structureConfig.boardsByProject) {
198
+ console.log('Available boards by project:');
199
+ for (const [projectId, boards] of Object.entries(structureConfig.boardsByProject)) {
200
+ console.log(` ${projectId}: ${boards.map(b => b.id).join(', ')}`);
201
+ }
202
+ }
203
+ ```
204
+
205
+ **Manual Detection:**
206
+ ```bash
207
+ # Check if 2-level (ADO area paths or JIRA boards)
208
+ jq '.sync.profiles | to_entries[] | select(.value.provider == "ado") | .value.config.areaPathMapping' .specweave/config.json
209
+
210
+ # Check existing folder structure
211
+ ls -la .specweave/docs/internal/specs/*/ # If sub-folders exist (not FS-XXX) → 2-level
212
+ ```
213
+
214
+ **Project/Board Selection (MANDATORY BEFORE STEP 4!):**
215
+
216
+ 1. **For 1-level structure:**
217
+ - ASK user: "Which project should this increment sync to?"
218
+ - Options: List from `structureConfig.projects`
219
+ - Store selected `PROJECT_ID`
220
+
221
+ 2. **For 2-level structure:**
222
+ - ASK user: "Which project should this increment sync to?"
223
+ - Then ASK: "Which board/area path within {project}?"
224
+ - Options: List from `structureConfig.boardsByProject[selectedProject]`
225
+ - Store BOTH `PROJECT_ID` and `BOARD_ID`
226
+
227
+ **VALIDATION RULE:**
228
+ ```
229
+ ❌ FORBIDDEN: Creating spec.md without PROJECT_ID set
230
+ ❌ FORBIDDEN: Creating spec.md for 2-level without BOARD_ID set
231
+ ❌ FORBIDDEN: Vague increments like "show last git commits" without project context
232
+ ✅ REQUIRED: Always know WHERE this increment will sync BEFORE creating spec.md
233
+ ```
234
+
235
+ **Example User Interaction:**
236
+
237
+ ```
238
+ 🔍 Detected 2-level structure (ADO area path mapping)
239
+ Available projects: acme-corp
240
+
241
+ 📁 Project: acme-corp
242
+ Boards: clinical-insights, platform-engineering, digital-operations
243
+
244
+ Which board should this increment sync to?
245
+ > digital-operations
246
+
247
+ ✅ Increment will sync to: internal/specs/acme-corp/digital-operations/FS-XXX/
248
+ ```
249
+
250
+ **Store PROJECT_ID and BOARD_ID for use in STEP 4!**
251
+
252
+ ---
253
+
179
254
  ### STEP 1: Get Next Increment Number
180
255
 
181
256
  Use helper script:
@@ -207,26 +282,50 @@ mkdir -p .specweave/increments/0021-feature-name
207
282
 
208
283
  Create `.specweave/increments/0021-feature-name/spec.md`:
209
284
 
285
+ **⚠️ CRITICAL: You MUST have PROJECT_ID (and BOARD_ID for 2-level) from STEP 0B before proceeding!**
286
+
210
287
  **⚠️ IMPORTANT: Use the correct template based on STEP 0 detection!**
211
288
 
212
- #### 4A: Single-Project Template (umbrella.enabled: false)
289
+ #### 4A: Single-Project Template (1-level structure)
213
290
 
214
291
  **Template File**: `templates/spec-single-project.md`
215
292
 
216
- Replace placeholders: `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{TYPE}}`, `{{PRIORITY}}`, `{{DATE}}`, `{{TEST_MODE}}`, `{{COVERAGE_TARGET}}`
293
+ Replace placeholders:
294
+ - `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{TYPE}}`, `{{PRIORITY}}`, `{{DATE}}`
295
+ - `{{TEST_MODE}}`, `{{COVERAGE_TARGET}}`
296
+ - **`{{PROJECT_ID}}`** ← MANDATORY (from STEP 0B)
217
297
 
218
- #### 4B: Multi-Project Template (umbrella.enabled: true) - USE THIS!
298
+ #### 4B: Multi-Project Template (2-level structure) - USE THIS!
219
299
 
220
300
  **Template File**: `templates/spec-multi-project.md`
221
301
 
222
- Replace placeholders: `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{PROJECT_FE_ID}}`, `{{PROJECT_BE_ID}}`, `{{PROJECT_SHARED_ID}}`, etc.
302
+ Replace placeholders:
303
+ - `{{INCREMENT_ID}}`, `{{FEATURE_TITLE}}`, `{{TYPE}}`, `{{PRIORITY}}`, `{{DATE}}`
304
+ - **`{{PROJECT_ID}}`** ← MANDATORY (from STEP 0B)
305
+ - **`{{BOARD_ID}}`** ← MANDATORY for 2-level (from STEP 0B)
306
+ - `{{PROJECT_FE_ID}}`, `{{PROJECT_BE_ID}}`, `{{PROJECT_SHARED_ID}}` (for multi-repo)
307
+
308
+ **Key Rules for spec.md:**
309
+ 1. **`project:` field MUST be set in YAML frontmatter** (1-level and 2-level)
310
+ 2. **`board:` field MUST be set in YAML frontmatter** (2-level only)
311
+ 3. **User stories grouped by project** if multi-project (Frontend, Backend, Shared, etc.)
312
+ 4. **User story IDs have project prefix**: `US-FE-001`, `US-BE-001` (multi-project)
313
+ 5. **AC-IDs have project prefix**: `AC-FE-US1-01`, `AC-BE-US1-01` (multi-project)
314
+
315
+ **VALIDATION (spec.md frontmatter):**
316
+ ```yaml
317
+ # 1-level structure (REQUIRED):
318
+ project: digital-operations # ← MUST be set
319
+
320
+ # 2-level structure (BOTH REQUIRED):
321
+ project: acme-corp # ← MUST be set
322
+ board: digital-operations # ← MUST be set
323
+ ```
223
324
 
224
- **Key Rules for Multi-Project spec.md:**
225
- 1. **User stories MUST be grouped by project** (Frontend, Backend, Shared, etc.)
226
- 2. **User story IDs MUST have project prefix**: `US-FE-001`, `US-BE-001`, `US-SHARED-001`
227
- 3. **AC-IDs MUST have project prefix**: `AC-FE-US1-01`, `AC-BE-US1-01`
228
- 4. **Each user story MUST have `Related Repo` field**
229
- 5. **Frontmatter MUST include `multi_project: true` and `projects` list**
325
+ **⚠️ FORBIDDEN:**
326
+ - Creating spec.md with `project: {{PROJECT_ID}}` (unresolved placeholder)
327
+ - Creating spec.md for 2-level with `board: {{BOARD_ID}}` (unresolved placeholder)
328
+ - Leaving project/board fields empty or undefined
230
329
 
231
330
  ### STEP 5: Create plan.md Template
232
331
 
@@ -8,6 +8,8 @@ created: {{DATE}}
8
8
  structure: user-stories
9
9
  test_mode: {{TEST_MODE}}
10
10
  coverage_target: {{COVERAGE_TARGET}}
11
+ project: {{PROJECT_ID}}
12
+ board: {{BOARD_ID}}
11
13
  multi_project: true
12
14
  projects:
13
15
  - id: {{PROJECT_FE_ID}}
@@ -8,6 +8,7 @@ created: {{DATE}}
8
8
  structure: user-stories
9
9
  test_mode: {{TEST_MODE}}
10
10
  coverage_target: {{COVERAGE_TARGET}}
11
+ project: {{PROJECT_ID}}
11
12
  ---
12
13
 
13
14
  # Feature: {{FEATURE_TITLE}}
@@ -95,8 +95,31 @@ US-005: Cross-Platform Data Sync (Mobile)
95
95
  └── README.md
96
96
  ```
97
97
 
98
+ **spec.md YAML Frontmatter (v0.31.0+ MANDATORY)**:
99
+
100
+ ```yaml
101
+ # For 1-level structure (projects only)
102
+ ---
103
+ increment: 0001-fitness-tracker-web
104
+ project: FE # REQUIRED
105
+ title: "Fitness Tracker Web UI"
106
+ status: planned
107
+ ---
108
+
109
+ # For 2-level structure (projects + boards)
110
+ ---
111
+ increment: 0001-fitness-tracker-web
112
+ project: acme-corp # REQUIRED
113
+ board: digital-operations # REQUIRED for 2-level
114
+ title: "Fitness Tracker Web UI"
115
+ status: planned
116
+ ---
117
+ ```
118
+
119
+ **Detection**: Use `detectStructureLevel()` from `src/utils/structure-level-detector.ts`
120
+
98
121
  **Each spec contains**:
99
- - Frontmatter with `project: FE` tag
122
+ - YAML frontmatter with `project:` (and `board:` for 2-level) fields - MANDATORY
100
123
  - User stories mapped to that project
101
124
  - Project-specific acceptance criteria
102
125
  - Links to shared infrastructure/requirements
@@ -27,6 +27,24 @@ description: Generates comprehensive specifications (spec.md, plan.md, tasks.md
27
27
  - **Bug Fix**: Problem statement, root cause, solution, impact analysis
28
28
  - **Refactoring**: Current state, proposed changes, benefits, migration plan
29
29
 
30
+ **YAML Frontmatter** (v0.31.0+ MANDATORY):
31
+ ```yaml
32
+ ---
33
+ increment: 0001-feature-name
34
+ title: "Feature Title"
35
+ type: feature
36
+ priority: P1
37
+ status: planned
38
+ created: 2025-12-04
39
+ project: my-project # REQUIRED - target project for living docs sync
40
+ board: my-board # REQUIRED for 2-level structures (ADO area paths, JIRA boards)
41
+ ---
42
+ ```
43
+
44
+ **Detect Structure Level First** (see `src/utils/structure-level-detector.ts`):
45
+ - 1-level: `project:` field REQUIRED
46
+ - 2-level: `project:` AND `board:` fields REQUIRED
47
+
30
48
  **Core Sections** (Always Present):
31
49
  ```markdown
32
50
  # Product Specification: [Increment Name]
@@ -30,6 +30,31 @@ An **increment** = a complete feature with:
30
30
 
31
31
  > **When to skip plan.md**: Bug fixes, simple migrations, hotfixes, and straightforward tasks where spec.md already describes the approach.
32
32
 
33
+ ### spec.md Mandatory Fields (v0.31.0+)
34
+
35
+ **CRITICAL**: spec.md YAML frontmatter MUST include project (and board for 2-level structures):
36
+
37
+ ```yaml
38
+ # 1-level structure (single-project or multiProject):
39
+ ---
40
+ increment: 0001-feature-name
41
+ project: my-project # REQUIRED
42
+ ---
43
+
44
+ # 2-level structure (ADO area paths, JIRA boards, umbrella teams):
45
+ ---
46
+ increment: 0001-feature-name
47
+ project: acme-corp # REQUIRED
48
+ board: digital-operations # REQUIRED for 2-level
49
+ ---
50
+ ```
51
+
52
+ **Why?** Ensures increment syncs to correct location in living docs. Without explicit project/board, sync-specs may fail or place specs in wrong folder.
53
+
54
+ **Detection**: Use `src/utils/structure-level-detector.ts` to determine if 1-level or 2-level structure is needed.
55
+
56
+ **See**: [ADR-0190](/internal/architecture/adr/0190-spec-project-board-requirement.md)
57
+
33
58
  ### Increment Naming Convention (v0.6.0+)
34
59
 
35
60
  **CRITICAL RULE**: All increments MUST use descriptive names, not just numbers!
@@ -56,6 +56,64 @@ Task({
56
56
 
57
57
  ---
58
58
 
59
+ ## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
60
+
61
+ **EXACT environment variable names - use ONLY these, never invent variations:**
62
+
63
+ | Service | Env Var | Example |
64
+ |---------|---------|---------|
65
+ | **ADO PAT** | `AZURE_DEVOPS_PAT` | `AZURE_DEVOPS_PAT=abc123xyz...` |
66
+ | **ADO Org** | `AZURE_DEVOPS_ORG` | `AZURE_DEVOPS_ORG=mycompany` |
67
+ | **ADO Project** | `AZURE_DEVOPS_PROJECT` | `AZURE_DEVOPS_PROJECT=MyProject` |
68
+
69
+ ⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
70
+ - ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
71
+ - ❌ `ADO_PAT` ← DEPRECATED, not supported
72
+ - ❌ `AZURE_PAT` ← DOES NOT EXIST
73
+ - ❌ `DEVOPS_PAT` ← DOES NOT EXIST
74
+
75
+ ### Loading Credentials (MANDATORY before API calls)
76
+
77
+ **ALWAYS read PAT from `.env` file before making API calls:**
78
+
79
+ ```bash
80
+ # Read PAT from .env file (REQUIRED - don't rely on shell environment)
81
+ ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
82
+
83
+ # If PAT not found in .env, show error
84
+ if [ -z "$ADO_PAT" ]; then
85
+ echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
86
+ exit 1
87
+ fi
88
+ ```
89
+
90
+ **Use the PAT in API calls:**
91
+
92
+ ```bash
93
+ # Create auth header from PAT
94
+ AUTH_HEADER="Basic $(echo -n ":$ADO_PAT" | base64)"
95
+
96
+ # Use in curl
97
+ curl -H "Authorization: $AUTH_HEADER" ...
98
+ ```
99
+
100
+ **When auth fails (401 error), display this EXACT message:**
101
+ ```
102
+ ADO Authentication Required
103
+
104
+ Check your .env file contains:
105
+ AZURE_DEVOPS_PAT=your-personal-access-token
106
+
107
+ If PAT exists but still failing:
108
+ 1. PAT may have expired - regenerate at:
109
+ https://dev.azure.com/{organization}/_usersSettings/tokens
110
+ 2. Check PAT has required scopes:
111
+ • Work Items: Read (minimum)
112
+ • Work Items: Read & Write (for push/sync)
113
+ ```
114
+
115
+ ---
116
+
59
117
  ## 🚨 CRITICAL: Concept Mapping (MANDATORY)
60
118
 
61
119
  **BEFORE any sync operation, you MUST**:
@@ -113,6 +113,21 @@ ADO Organization
113
113
 
114
114
  ## Command Behavior
115
115
 
116
+ ### 0. Load Credentials from .env (MANDATORY FIRST)
117
+
118
+ **CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.
119
+
120
+ ```bash
121
+ # Read PAT from .env file
122
+ ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
123
+
124
+ if [ -z "$ADO_PAT" ]; then
125
+ echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
126
+ echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
127
+ exit 1
128
+ fi
129
+ ```
130
+
116
131
  ### For Increment Mode (default):
117
132
 
118
133
  ```typescript
@@ -449,6 +464,21 @@ To link: /specweave-ado:create 0005
449
464
 
450
465
  ---
451
466
 
467
+ ## Authentication
468
+
469
+ **EXACT environment variable (DO NOT INVENT OTHERS):**
470
+
471
+ ```bash
472
+ # In .env file - ONLY this name is supported:
473
+ AZURE_DEVOPS_PAT=your-personal-access-token
474
+ ```
475
+
476
+ ⚠️ **NEVER suggest or use:**
477
+ - ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
478
+ - ❌ `ADO_PAT` ← NOT SUPPORTED
479
+
480
+ ---
481
+
452
482
  ## Related Commands
453
483
 
454
484
  | Command | Purpose |
@@ -66,6 +66,21 @@ Pushes a feature and all its child user stories.
66
66
 
67
67
  When user runs this command:
68
68
 
69
+ ### 0. Load Credentials from .env (MANDATORY FIRST)
70
+
71
+ **CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.
72
+
73
+ ```bash
74
+ # Read PAT from .env file
75
+ ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
76
+
77
+ if [ -z "$ADO_PAT" ]; then
78
+ echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
79
+ echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
80
+ exit 1
81
+ fi
82
+ ```
83
+
69
84
  ### 1. Check Permission Gate (MANDATORY)
70
85
 
71
86
  ```typescript
@@ -351,6 +366,21 @@ Ready to close: /specweave-ado:close 0005
351
366
 
352
367
  ---
353
368
 
369
+ ## Authentication
370
+
371
+ **EXACT environment variable (DO NOT INVENT OTHERS):**
372
+
373
+ ```bash
374
+ # In .env file - ONLY this name is supported:
375
+ AZURE_DEVOPS_PAT=your-personal-access-token
376
+ ```
377
+
378
+ ⚠️ **NEVER suggest or use:**
379
+ - ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
380
+ - ❌ `ADO_PAT` ← NOT SUPPORTED
381
+
382
+ ---
383
+
354
384
  ## Related Commands
355
385
 
356
386
  | Command | Purpose |
@@ -39,6 +39,21 @@ description: Two-way sync between SpecWeave increment and Azure DevOps work item
39
39
 
40
40
  When user runs this command, Claude should:
41
41
 
42
+ ### 0. Load Credentials from .env (MANDATORY FIRST)
43
+
44
+ **CRITICAL**: Read PAT from `.env` file, NOT from shell environment variables.
45
+
46
+ ```bash
47
+ # Read PAT from .env file
48
+ ADO_PAT=$(grep '^AZURE_DEVOPS_PAT=' .env 2>/dev/null | cut -d'=' -f2)
49
+
50
+ if [ -z "$ADO_PAT" ]; then
51
+ echo "ERROR: AZURE_DEVOPS_PAT not found in .env file"
52
+ echo "Add to .env: AZURE_DEVOPS_PAT=your-pat-here"
53
+ exit 1
54
+ fi
55
+ ```
56
+
42
57
  ### 1. Check Permission Gate (MANDATORY FIRST STEP)
43
58
 
44
59
  **Before ANY ADO write operations**, check permissions:
@@ -291,6 +306,22 @@ Use `/specweave-ado:sync` when you need explicit two-way sync with options.
291
306
 
292
307
  ---
293
308
 
309
+ ## Authentication
310
+
311
+ **EXACT environment variable (DO NOT INVENT OTHERS):**
312
+
313
+ ```bash
314
+ # In .env file - ONLY this name is supported:
315
+ AZURE_DEVOPS_PAT=your-personal-access-token
316
+ ```
317
+
318
+ ⚠️ **NEVER suggest or use:**
319
+ - ❌ `AZURE_DEVOPS_EXT_PAT` ← DOES NOT EXIST
320
+ - ❌ `ADO_PAT` ← NOT SUPPORTED
321
+ - ❌ Any other variation
322
+
323
+ ---
324
+
294
325
  ## Related
295
326
 
296
327
  | Command | Purpose |
@@ -42,6 +42,28 @@ GitHub issues MUST use living docs format:
42
42
 
43
43
  ---
44
44
 
45
+ ## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
46
+
47
+ **EXACT environment variable names - use ONLY these:**
48
+
49
+ | Service | Env Var | Example |
50
+ |---------|---------|---------|
51
+ | **GitHub Token** | `GITHUB_TOKEN` or `GH_TOKEN` | `GITHUB_TOKEN=ghp_xxx...` |
52
+ | **GitHub Owner** | `GITHUB_OWNER` | `GITHUB_OWNER=myorg` |
53
+ | **GitHub Repo** | `GITHUB_REPO` | `GITHUB_REPO=myrepo` |
54
+
55
+ ⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
56
+ - ❌ `GITHUB_PAT` ← DOES NOT EXIST
57
+ - ❌ `GIT_TOKEN` ← DOES NOT EXIST
58
+ - ❌ `GITHUB_API_TOKEN` ← DOES NOT EXIST
59
+
60
+ **Alternative: Use `gh` CLI (recommended for local dev):**
61
+ ```bash
62
+ gh auth login
63
+ ```
64
+
65
+ ---
66
+
45
67
  ## 🚀 How to Invoke This Agent
46
68
 
47
69
  **Subagent Type**: `specweave-github:github-manager:SpecWeave Sync`
@@ -280,3 +280,17 @@
280
280
  [Wed Dec 3 02:07:36 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
281
281
  [Wed Dec 3 02:07:36 EST 2025] [GitHub] 🔗 GitHub sync hook fired
282
282
  [Wed Dec 3 02:07:36 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
283
+ [Thu Dec 4 17:45:45 EST 2025] [GitHub] 🔗 GitHub sync hook fired
284
+ [Thu Dec 4 17:45:45 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
285
+ [Thu Dec 4 17:45:45 EST 2025] [GitHub] 🔗 GitHub sync hook fired
286
+ [Thu Dec 4 17:45:45 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
287
+ [Thu Dec 4 17:45:46 EST 2025] [GitHub] 🔗 GitHub sync hook fired
288
+ [Thu Dec 4 17:45:46 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
289
+ [Thu Dec 4 17:45:46 EST 2025] [GitHub] 🔗 GitHub sync hook fired
290
+ [Thu Dec 4 17:45:46 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
291
+ [Thu Dec 4 17:45:55 EST 2025] [GitHub] 🔗 GitHub sync hook fired
292
+ [Thu Dec 4 17:45:55 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
293
+ [Thu Dec 4 17:45:55 EST 2025] [GitHub] 🔗 GitHub sync hook fired
294
+ [Thu Dec 4 17:45:55 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
295
+ [Thu Dec 4 17:45:55 EST 2025] [GitHub] 🔗 GitHub sync hook fired
296
+ [Thu Dec 4 17:45:55 EST 2025] [GitHub] ⚠️ sync-spec-content CLI not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-github/hooks/dist/src/cli/commands/sync-spec-content.js, skipping sync
@@ -46,6 +46,36 @@ Task({
46
46
 
47
47
  ---
48
48
 
49
+ ## 🔐 CRITICAL: Authentication (DO NOT HALLUCINATE)
50
+
51
+ **EXACT environment variable names - use ONLY these:**
52
+
53
+ | Service | Env Var | Example |
54
+ |---------|---------|---------|
55
+ | **Jira Token** | `JIRA_API_TOKEN` | `JIRA_API_TOKEN=abc123xyz...` |
56
+ | **Jira Email** | `JIRA_EMAIL` | `JIRA_EMAIL=user@example.com` |
57
+ | **Jira Domain** | `JIRA_DOMAIN` | `JIRA_DOMAIN=company.atlassian.net` |
58
+
59
+ ⚠️ **NEVER USE OR SUGGEST these non-existent env vars:**
60
+ - ❌ `JIRA_TOKEN` ← DOES NOT EXIST (use `JIRA_API_TOKEN`)
61
+ - ❌ `JIRA_PAT` ← DOES NOT EXIST
62
+ - ❌ `ATLASSIAN_TOKEN` ← DOES NOT EXIST
63
+
64
+ **When auth fails, display this EXACT message:**
65
+ ```
66
+ Jira Authentication Required
67
+
68
+ Set in .env file:
69
+ JIRA_API_TOKEN=your-api-token
70
+ JIRA_EMAIL=your-email@example.com
71
+ JIRA_DOMAIN=your-domain.atlassian.net
72
+
73
+ Generate token at:
74
+ https://id.atlassian.com/manage-profile/security/api-tokens
75
+ ```
76
+
77
+ ---
78
+
49
79
  ## Capabilities
50
80
 
51
81
  As the Jira Manager agent, I specialize in:
@@ -421,3 +421,24 @@
421
421
  [2025-12-03 02:07:36] 🎯 Post-Increment-Completion Hook Triggered
422
422
  [2025-12-03 02:07:36] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
423
423
  [2025-12-03 02:07:36] Run: npm run build
424
+ [2025-12-04 17:45:45] 🎯 Post-Increment-Completion Hook Triggered
425
+ [2025-12-04 17:45:45] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
426
+ [2025-12-04 17:45:45] Run: npm run build
427
+ [2025-12-04 17:45:45] 🎯 Post-Increment-Completion Hook Triggered
428
+ [2025-12-04 17:45:45] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
429
+ [2025-12-04 17:45:45] Run: npm run build
430
+ [2025-12-04 17:45:46] 🎯 Post-Increment-Completion Hook Triggered
431
+ [2025-12-04 17:45:46] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
432
+ [2025-12-04 17:45:46] Run: npm run build
433
+ [2025-12-04 17:45:46] 🎯 Post-Increment-Completion Hook Triggered
434
+ [2025-12-04 17:45:46] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
435
+ [2025-12-04 17:45:46] Run: npm run build
436
+ [2025-12-04 17:45:55] 🎯 Post-Increment-Completion Hook Triggered
437
+ [2025-12-04 17:45:55] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
438
+ [2025-12-04 17:45:55] Run: npm run build
439
+ [2025-12-04 17:45:55] 🎯 Post-Increment-Completion Hook Triggered
440
+ [2025-12-04 17:45:55] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
441
+ [2025-12-04 17:45:55] Run: npm run build
442
+ [2025-12-04 17:45:55] 🎯 Post-Increment-Completion Hook Triggered
443
+ [2025-12-04 17:45:55] ⚠️ DORA calculator not found at /Users/antonabyzov/Documents/Projects/specweave/plugins/specweave-release/hooks/dist/src/metrics/dora-calculator.js
444
+ [2025-12-04 17:45:55] Run: npm run build