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.
- package/CLAUDE.md +43 -0
- package/README.md +32 -0
- package/bin/specweave.js +28 -0
- package/dist/src/cli/commands/commits.d.ts +7 -0
- package/dist/src/cli/commands/commits.d.ts.map +1 -0
- package/dist/src/cli/commands/commits.js +42 -0
- package/dist/src/cli/commands/commits.js.map +1 -0
- package/dist/src/cli/commands/living-docs.d.ts +29 -0
- package/dist/src/cli/commands/living-docs.d.ts.map +1 -0
- package/dist/src/cli/commands/living-docs.js +350 -0
- package/dist/src/cli/commands/living-docs.js.map +1 -0
- package/dist/src/cli/helpers/ado-area-selector.js +1 -1
- package/dist/src/cli/helpers/ado-area-selector.js.map +1 -1
- package/dist/src/cli/workers/living-docs-worker.js +80 -44
- package/dist/src/cli/workers/living-docs-worker.js.map +1 -1
- package/dist/src/core/background/index.d.ts +2 -2
- package/dist/src/core/background/index.d.ts.map +1 -1
- package/dist/src/core/background/index.js +1 -1
- package/dist/src/core/background/index.js.map +1 -1
- package/dist/src/core/living-docs/living-docs-sync.d.ts +60 -24
- package/dist/src/core/living-docs/living-docs-sync.d.ts.map +1 -1
- package/dist/src/core/living-docs/living-docs-sync.js +360 -103
- package/dist/src/core/living-docs/living-docs-sync.js.map +1 -1
- package/dist/src/core/llm/index.d.ts +1 -0
- package/dist/src/core/llm/index.d.ts.map +1 -1
- package/dist/src/core/llm/index.js +2 -0
- package/dist/src/core/llm/index.js.map +1 -1
- package/dist/src/core/llm/providers/anthropic-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/anthropic-provider.js +15 -26
- package/dist/src/core/llm/providers/anthropic-provider.js.map +1 -1
- package/dist/src/core/llm/providers/azure-openai-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/azure-openai-provider.js +13 -5
- package/dist/src/core/llm/providers/azure-openai-provider.js.map +1 -1
- package/dist/src/core/llm/providers/bedrock-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/bedrock-provider.js +12 -8
- package/dist/src/core/llm/providers/bedrock-provider.js.map +1 -1
- package/dist/src/core/llm/providers/claude-code-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/claude-code-provider.js +15 -25
- package/dist/src/core/llm/providers/claude-code-provider.js.map +1 -1
- package/dist/src/core/llm/providers/ollama-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/ollama-provider.js +12 -9
- package/dist/src/core/llm/providers/ollama-provider.js.map +1 -1
- package/dist/src/core/llm/providers/openai-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/openai-provider.js +13 -6
- package/dist/src/core/llm/providers/openai-provider.js.map +1 -1
- package/dist/src/core/llm/providers/vertex-ai-provider.d.ts.map +1 -1
- package/dist/src/core/llm/providers/vertex-ai-provider.js +12 -8
- package/dist/src/core/llm/providers/vertex-ai-provider.js.map +1 -1
- package/dist/src/importers/ado-importer.js +2 -2
- package/dist/src/importers/ado-importer.js.map +1 -1
- package/dist/src/importers/item-converter.d.ts +6 -1
- package/dist/src/importers/item-converter.d.ts.map +1 -1
- package/dist/src/importers/item-converter.js +15 -2
- package/dist/src/importers/item-converter.js.map +1 -1
- package/dist/src/integrations/ado/ado-pat-provider.d.ts +3 -3
- package/dist/src/integrations/ado/ado-pat-provider.js +3 -3
- package/dist/src/living-docs/epic-id-allocator.d.ts +1 -1
- package/dist/src/living-docs/epic-id-allocator.js +1 -1
- package/dist/src/living-docs/fs-id-allocator.d.ts +1 -1
- package/dist/src/living-docs/fs-id-allocator.js +1 -1
- package/dist/src/utils/auth-helpers.d.ts +23 -0
- package/dist/src/utils/auth-helpers.d.ts.map +1 -1
- package/dist/src/utils/auth-helpers.js +51 -0
- package/dist/src/utils/auth-helpers.js.map +1 -1
- package/dist/src/utils/feature-id-collision.d.ts +48 -5
- package/dist/src/utils/feature-id-collision.d.ts.map +1 -1
- package/dist/src/utils/feature-id-collision.js +251 -19
- package/dist/src/utils/feature-id-collision.js.map +1 -1
- package/dist/src/utils/llm-json-extractor.d.ts +105 -0
- package/dist/src/utils/llm-json-extractor.d.ts.map +1 -0
- package/dist/src/utils/llm-json-extractor.js +336 -0
- package/dist/src/utils/llm-json-extractor.js.map +1 -0
- package/dist/src/utils/structure-level-detector.d.ts +105 -0
- package/dist/src/utils/structure-level-detector.d.ts.map +1 -0
- package/dist/src/utils/structure-level-detector.js +388 -0
- package/dist/src/utils/structure-level-detector.js.map +1 -0
- package/dist/src/utils/validators/ado-validator.js +2 -2
- package/dist/src/utils/validators/ado-validator.js.map +1 -1
- package/package.json +1 -2
- package/plugins/specweave/commands/specweave-increment.md +57 -9
- package/plugins/specweave/commands/specweave-living-docs.md +321 -0
- package/plugins/specweave/commands/specweave-sync-specs.md +37 -6
- package/plugins/specweave/hooks/hooks.json +10 -0
- package/plugins/specweave/hooks/spec-project-validator.sh +111 -0
- package/plugins/specweave/hooks/v2/handlers/github-sync-handler.sh +10 -1
- package/plugins/specweave/hooks/v2/handlers/living-docs-handler.sh +10 -1
- package/plugins/specweave/skills/increment-planner/SKILL.md +109 -10
- package/plugins/specweave/skills/increment-planner/templates/spec-multi-project.md +2 -0
- package/plugins/specweave/skills/increment-planner/templates/spec-single-project.md +1 -0
- package/plugins/specweave/skills/multi-project-spec-mapper/SKILL.md +24 -1
- package/plugins/specweave/skills/spec-generator/SKILL.md +18 -0
- package/plugins/specweave/skills/specweave-framework/SKILL.md +25 -0
- package/plugins/specweave-ado/agents/ado-manager/AGENT.md +58 -0
- package/plugins/specweave-ado/commands/pull.md +30 -0
- package/plugins/specweave-ado/commands/push.md +30 -0
- package/plugins/specweave-ado/commands/sync.md +31 -0
- package/plugins/specweave-github/agents/github-manager/AGENT.md +22 -0
- package/plugins/specweave-github/hooks/.specweave/logs/hooks-debug.log +14 -0
- package/plugins/specweave-jira/agents/jira-manager/AGENT.md +30 -0
- 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 (
|
|
289
|
+
#### 4A: Single-Project Template (1-level structure)
|
|
213
290
|
|
|
214
291
|
**Template File**: `templates/spec-single-project.md`
|
|
215
292
|
|
|
216
|
-
Replace placeholders:
|
|
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 (
|
|
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:
|
|
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
|
-
|
|
225
|
-
|
|
226
|
-
|
|
227
|
-
|
|
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
|
|
|
@@ -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
|
-
-
|
|
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
|