specweave 0.6.8 → 0.7.1

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 (255) hide show
  1. package/.claude-plugin/README.md +1 -1
  2. package/CLAUDE.md +903 -99
  3. package/README.md +143 -207
  4. package/bin/specweave.js +67 -0
  5. package/dist/cli/commands/abandon.d.ts +13 -0
  6. package/dist/cli/commands/abandon.d.ts.map +1 -0
  7. package/dist/cli/commands/abandon.js +15 -0
  8. package/dist/cli/commands/abandon.js.map +1 -0
  9. package/dist/cli/commands/init.d.ts.map +1 -1
  10. package/dist/cli/commands/init.js +94 -18
  11. package/dist/cli/commands/init.js.map +1 -1
  12. package/dist/cli/commands/pause.d.ts +13 -0
  13. package/dist/cli/commands/pause.d.ts.map +1 -0
  14. package/dist/cli/commands/pause.js +15 -0
  15. package/dist/cli/commands/pause.js.map +1 -0
  16. package/dist/cli/commands/qa.d.ts +54 -0
  17. package/dist/cli/commands/qa.d.ts.map +1 -0
  18. package/dist/cli/commands/qa.js +98 -0
  19. package/dist/cli/commands/qa.js.map +1 -0
  20. package/dist/cli/commands/resume.d.ts +12 -0
  21. package/dist/cli/commands/resume.d.ts.map +1 -0
  22. package/dist/cli/commands/resume.js +14 -0
  23. package/dist/cli/commands/resume.js.map +1 -0
  24. package/dist/cli/commands/status.d.ts +12 -0
  25. package/dist/cli/commands/status.d.ts.map +1 -0
  26. package/dist/cli/commands/status.js +23 -0
  27. package/dist/cli/commands/status.js.map +1 -0
  28. package/dist/cli/helpers/issue-tracker/ado.d.ts +57 -0
  29. package/dist/cli/helpers/issue-tracker/ado.d.ts.map +1 -0
  30. package/dist/cli/helpers/issue-tracker/ado.js +223 -0
  31. package/dist/cli/helpers/issue-tracker/ado.js.map +1 -0
  32. package/dist/cli/helpers/issue-tracker/github.d.ts +65 -0
  33. package/dist/cli/helpers/issue-tracker/github.d.ts.map +1 -0
  34. package/dist/cli/helpers/issue-tracker/github.js +284 -0
  35. package/dist/cli/helpers/issue-tracker/github.js.map +1 -0
  36. package/dist/cli/helpers/issue-tracker/index.d.ts +22 -0
  37. package/dist/cli/helpers/issue-tracker/index.d.ts.map +1 -0
  38. package/dist/cli/helpers/issue-tracker/index.js +270 -0
  39. package/dist/cli/helpers/issue-tracker/index.js.map +1 -0
  40. package/dist/cli/helpers/issue-tracker/jira.d.ts +61 -0
  41. package/dist/cli/helpers/issue-tracker/jira.d.ts.map +1 -0
  42. package/dist/cli/helpers/issue-tracker/jira.js +265 -0
  43. package/dist/cli/helpers/issue-tracker/jira.js.map +1 -0
  44. package/dist/cli/helpers/issue-tracker/types.d.ts +86 -0
  45. package/dist/cli/helpers/issue-tracker/types.d.ts.map +1 -0
  46. package/dist/cli/helpers/issue-tracker/types.js +16 -0
  47. package/dist/cli/helpers/issue-tracker/types.js.map +1 -0
  48. package/dist/cli/helpers/issue-tracker/utils.d.ts +103 -0
  49. package/dist/cli/helpers/issue-tracker/utils.d.ts.map +1 -0
  50. package/dist/cli/helpers/issue-tracker/utils.js +240 -0
  51. package/dist/cli/helpers/issue-tracker/utils.js.map +1 -0
  52. package/dist/core/increment/limits.d.ts +68 -0
  53. package/dist/core/increment/limits.d.ts.map +1 -0
  54. package/dist/core/increment/limits.js +224 -0
  55. package/dist/core/increment/limits.js.map +1 -0
  56. package/dist/core/increment/metadata-manager.d.ts +114 -0
  57. package/dist/core/increment/metadata-manager.d.ts.map +1 -0
  58. package/dist/core/increment/metadata-manager.js +320 -0
  59. package/dist/core/increment/metadata-manager.js.map +1 -0
  60. package/dist/core/increment/status-commands.d.ts +43 -0
  61. package/dist/core/increment/status-commands.d.ts.map +1 -0
  62. package/dist/core/increment/status-commands.js +277 -0
  63. package/dist/core/increment/status-commands.js.map +1 -0
  64. package/dist/core/plugin-detector.d.ts +1 -0
  65. package/dist/core/plugin-detector.d.ts.map +1 -1
  66. package/dist/core/plugin-detector.js +25 -0
  67. package/dist/core/plugin-detector.js.map +1 -1
  68. package/dist/core/qa/qa-runner.d.ts +16 -0
  69. package/dist/core/qa/qa-runner.d.ts.map +1 -0
  70. package/dist/core/qa/qa-runner.js +404 -0
  71. package/dist/core/qa/qa-runner.js.map +1 -0
  72. package/dist/core/qa/quality-gate-decider.d.ts +53 -0
  73. package/dist/core/qa/quality-gate-decider.d.ts.map +1 -0
  74. package/dist/core/qa/quality-gate-decider.js +268 -0
  75. package/dist/core/qa/quality-gate-decider.js.map +1 -0
  76. package/dist/core/qa/risk-calculator.d.ts +126 -0
  77. package/dist/core/qa/risk-calculator.d.ts.map +1 -0
  78. package/dist/core/qa/risk-calculator.js +247 -0
  79. package/dist/core/qa/risk-calculator.js.map +1 -0
  80. package/dist/core/qa/types.d.ts +315 -0
  81. package/dist/core/qa/types.d.ts.map +1 -0
  82. package/dist/core/qa/types.js +8 -0
  83. package/dist/core/qa/types.js.map +1 -0
  84. package/dist/core/types/config.d.ts +35 -0
  85. package/dist/core/types/config.d.ts.map +1 -1
  86. package/dist/core/types/config.js +16 -0
  87. package/dist/core/types/config.js.map +1 -1
  88. package/dist/core/types/increment-metadata.d.ts +120 -0
  89. package/dist/core/types/increment-metadata.d.ts.map +1 -0
  90. package/dist/core/types/increment-metadata.js +138 -0
  91. package/dist/core/types/increment-metadata.js.map +1 -0
  92. package/dist/hooks/lib/invoke-translator-skill.d.ts +60 -0
  93. package/dist/hooks/lib/invoke-translator-skill.d.ts.map +1 -0
  94. package/dist/hooks/lib/invoke-translator-skill.js +201 -0
  95. package/dist/hooks/lib/invoke-translator-skill.js.map +1 -0
  96. package/dist/hooks/lib/translate-file.d.ts +59 -0
  97. package/dist/hooks/lib/translate-file.d.ts.map +1 -0
  98. package/dist/hooks/lib/translate-file.js +350 -0
  99. package/dist/hooks/lib/translate-file.js.map +1 -0
  100. package/dist/locales/en/cli.json +3 -1
  101. package/dist/metrics/calculators/change-failure-rate.d.ts +22 -0
  102. package/dist/metrics/calculators/change-failure-rate.d.ts.map +1 -0
  103. package/dist/metrics/calculators/change-failure-rate.js +70 -0
  104. package/dist/metrics/calculators/change-failure-rate.js.map +1 -0
  105. package/dist/metrics/calculators/deployment-frequency.d.ts +20 -0
  106. package/dist/metrics/calculators/deployment-frequency.d.ts.map +1 -0
  107. package/dist/metrics/calculators/deployment-frequency.js +61 -0
  108. package/dist/metrics/calculators/deployment-frequency.js.map +1 -0
  109. package/dist/metrics/calculators/lead-time.d.ts +22 -0
  110. package/dist/metrics/calculators/lead-time.d.ts.map +1 -0
  111. package/dist/metrics/calculators/lead-time.js +82 -0
  112. package/dist/metrics/calculators/lead-time.js.map +1 -0
  113. package/dist/metrics/calculators/mttr.d.ts +21 -0
  114. package/dist/metrics/calculators/mttr.d.ts.map +1 -0
  115. package/dist/metrics/calculators/mttr.js +60 -0
  116. package/dist/metrics/calculators/mttr.js.map +1 -0
  117. package/dist/metrics/dora-calculator.d.ts +24 -0
  118. package/dist/metrics/dora-calculator.d.ts.map +1 -0
  119. package/dist/metrics/dora-calculator.js +104 -0
  120. package/dist/metrics/dora-calculator.js.map +1 -0
  121. package/dist/metrics/github-client.d.ts +51 -0
  122. package/dist/metrics/github-client.d.ts.map +1 -0
  123. package/dist/metrics/github-client.js +133 -0
  124. package/dist/metrics/github-client.js.map +1 -0
  125. package/dist/metrics/types.d.ts +112 -0
  126. package/dist/metrics/types.d.ts.map +1 -0
  127. package/dist/metrics/types.js +10 -0
  128. package/dist/metrics/types.js.map +1 -0
  129. package/dist/metrics/utils/percentile.d.ts +25 -0
  130. package/dist/metrics/utils/percentile.d.ts.map +1 -0
  131. package/dist/metrics/utils/percentile.js +46 -0
  132. package/dist/metrics/utils/percentile.js.map +1 -0
  133. package/dist/metrics/utils/tier-classifier.d.ts +61 -0
  134. package/dist/metrics/utils/tier-classifier.d.ts.map +1 -0
  135. package/dist/metrics/utils/tier-classifier.js +100 -0
  136. package/dist/metrics/utils/tier-classifier.js.map +1 -0
  137. package/dist/utils/auth-helpers.d.ts +58 -0
  138. package/dist/utils/auth-helpers.d.ts.map +1 -0
  139. package/dist/utils/auth-helpers.js +108 -0
  140. package/dist/utils/auth-helpers.js.map +1 -0
  141. package/dist/utils/env-file.d.ts +88 -0
  142. package/dist/utils/env-file.d.ts.map +1 -0
  143. package/dist/utils/env-file.js +180 -0
  144. package/dist/utils/env-file.js.map +1 -0
  145. package/dist/utils/plugin-detection.d.ts +50 -0
  146. package/dist/utils/plugin-detection.d.ts.map +1 -0
  147. package/dist/utils/plugin-detection.js +229 -0
  148. package/dist/utils/plugin-detection.js.map +1 -0
  149. package/dist/utils/secrets-loader.d.ts +88 -0
  150. package/dist/utils/secrets-loader.d.ts.map +1 -0
  151. package/dist/utils/secrets-loader.js +271 -0
  152. package/dist/utils/secrets-loader.js.map +1 -0
  153. package/dist/utils/translation.d.ts +187 -0
  154. package/dist/utils/translation.d.ts.map +1 -0
  155. package/dist/utils/translation.js +414 -0
  156. package/dist/utils/translation.js.map +1 -0
  157. package/package.json +28 -44
  158. package/plugins/specweave/.claude-plugin/plugin.json +3 -3
  159. package/plugins/specweave/agents/pm/AGENT.md +330 -54
  160. package/plugins/specweave/agents/test-aware-planner/AGENT.md +1035 -0
  161. package/plugins/specweave/agents/test-aware-planner/templates/README.md +118 -0
  162. package/plugins/specweave/agents/test-aware-planner/templates/task-non-testable.md.template +24 -0
  163. package/plugins/specweave/agents/test-aware-planner/templates/task-testable.md.template +53 -0
  164. package/plugins/specweave/agents/test-aware-planner/templates/tasks-frontmatter.md.template +11 -0
  165. package/plugins/specweave/commands/README.md +88 -163
  166. package/plugins/specweave/commands/specweave-abandon.md +314 -0
  167. package/plugins/specweave/commands/specweave-check-tests.md +546 -0
  168. package/plugins/specweave/commands/{do.md → specweave-do.md} +5 -7
  169. package/plugins/specweave/commands/{increment.md → specweave-increment.md} +231 -4
  170. package/plugins/specweave/commands/specweave-pause.md +189 -0
  171. package/plugins/specweave/commands/specweave-qa.md +245 -0
  172. package/plugins/specweave/commands/specweave-resume.md +216 -0
  173. package/plugins/specweave/commands/specweave-status.md +397 -0
  174. package/plugins/specweave/commands/specweave-sync-tasks.md +256 -0
  175. package/plugins/specweave/commands/{translate.md → specweave-translate.md} +3 -3
  176. package/plugins/specweave/commands/specweave-update-scope.md +351 -0
  177. package/plugins/specweave/commands/specweave.md +21 -21
  178. package/plugins/specweave/hooks/post-increment-planning.sh +335 -0
  179. package/plugins/specweave/hooks/post-task-completion.sh +141 -0
  180. package/plugins/specweave/skills/SKILLS-INDEX.md +1 -1
  181. package/plugins/specweave/skills/brownfield-analyzer/SKILL.md +9 -9
  182. package/plugins/specweave/skills/increment-planner/SKILL.md +400 -212
  183. package/plugins/specweave/skills/increment-quality-judge-v2/SKILL.md +499 -0
  184. package/plugins/specweave/skills/plugin-detector/SKILL.md +114 -1
  185. package/plugins/specweave/skills/project-kickstarter/SKILL.md +74 -1
  186. package/plugins/specweave/skills/{rfc-generator → spec-generator}/SKILL.md +22 -29
  187. package/plugins/specweave/skills/specweave-detector/SKILL.md +3 -3
  188. package/plugins/specweave/skills/specweave-framework/SKILL.md +2 -2
  189. package/plugins/specweave-ado/.claude-plugin/plugin.json +18 -4
  190. package/plugins/specweave-ado/agents/ado-manager/AGENT.md +426 -0
  191. package/plugins/specweave-ado/commands/close-workitem.md +52 -0
  192. package/plugins/specweave-ado/commands/create-workitem.md +53 -0
  193. package/plugins/specweave-ado/commands/status.md +53 -0
  194. package/plugins/specweave-ado/commands/sync.md +55 -0
  195. package/plugins/specweave-ado/lib/ado-client.ts +361 -0
  196. package/plugins/specweave-ado/reference/ado-specweave-mapping.md +552 -0
  197. package/plugins/specweave-ado/skills/ado-sync/SKILL.md +344 -193
  198. package/plugins/specweave-docs/skills/docusaurus/SKILL.md +73 -0
  199. package/plugins/specweave-github/agents/github-manager/AGENT.md +49 -0
  200. package/plugins/specweave-github/commands/{github-close-issue.md → close-issue.md} +1 -1
  201. package/plugins/specweave-github/commands/{github-create-issue.md → create-issue.md} +1 -1
  202. package/plugins/specweave-github/commands/{github-status.md → status.md} +1 -1
  203. package/plugins/specweave-github/commands/{github-sync-tasks.md → sync-tasks.md} +1 -1
  204. package/plugins/specweave-github/commands/{github-sync.md → sync.md} +1 -1
  205. package/plugins/specweave-github/reference/github-specweave-mapping.md +377 -0
  206. package/plugins/specweave-github/skills/github-sync/SKILL.md +11 -3
  207. package/plugins/specweave-infrastructure/commands/{specweave.monitor-setup.md → monitor-setup.md} +5 -0
  208. package/plugins/specweave-infrastructure/commands/{specweave.slo-implement.md → slo-implement.md} +5 -0
  209. package/plugins/specweave-jira/agents/jira-manager/AGENT.md +380 -0
  210. package/plugins/specweave-jira/commands/{specweave.sync-jira.md → sync.md} +1 -1
  211. package/plugins/specweave-jira/reference/jira-specweave-mapping.md +508 -0
  212. package/plugins/specweave-ml/commands/ml-deploy.md +1 -1
  213. package/plugins/specweave-ml/commands/ml-evaluate.md +1 -1
  214. package/plugins/specweave-ml/commands/ml-explain.md +1 -1
  215. package/plugins/specweave-ml/commands/{specweave.ml-pipeline.md → ml-pipeline.md} +5 -0
  216. package/src/templates/AGENTS.md.template +331 -31
  217. package/src/templates/CLAUDE.md.template +36 -21
  218. package/src/templates/COMPLETION-REPORT.template.md +128 -0
  219. package/src/templates/README.md.template +17 -16
  220. package/src/templates/docs/README.md +11 -9
  221. package/src/templates/docs/spec-template.md +229 -0
  222. package/plugins/specweave/commands/inc.md +0 -85
  223. package/plugins/specweave/commands/list-increments.md +0 -180
  224. package/src/adapters/README.md +0 -275
  225. package/src/adapters/adapter-base.ts +0 -182
  226. package/src/adapters/adapter-interface.ts +0 -166
  227. package/src/adapters/adapter-loader.ts +0 -256
  228. package/src/adapters/agents-md-generator.ts +0 -228
  229. package/src/adapters/claude/README.md +0 -233
  230. package/src/adapters/claude/adapter.ts +0 -468
  231. package/src/adapters/claude-md-generator.ts +0 -377
  232. package/src/adapters/codex/README.md +0 -105
  233. package/src/adapters/codex/adapter.ts +0 -333
  234. package/src/adapters/cursor/.cursor/context/docs-context.md +0 -62
  235. package/src/adapters/cursor/.cursor/context/increments-context.md +0 -71
  236. package/src/adapters/cursor/.cursor/context/strategy-context.md +0 -73
  237. package/src/adapters/cursor/.cursor/context/tests-context.md +0 -89
  238. package/src/adapters/cursor/README.md +0 -283
  239. package/src/adapters/cursor/adapter.ts +0 -451
  240. package/src/adapters/doc-generator.ts +0 -331
  241. package/src/adapters/gemini/README.md +0 -97
  242. package/src/adapters/gemini/adapter.ts +0 -298
  243. package/src/adapters/generic/README.md +0 -277
  244. package/src/adapters/generic/adapter.ts +0 -378
  245. package/src/adapters/registry.yaml +0 -187
  246. /package/plugins/specweave/commands/{costs.md → specweave-costs.md} +0 -0
  247. /package/plugins/specweave/commands/{done.md → specweave-done.md} +0 -0
  248. /package/plugins/specweave/commands/{next.md → specweave-next.md} +0 -0
  249. /package/plugins/specweave/commands/{progress.md → specweave-progress.md} +0 -0
  250. /package/plugins/specweave/commands/{sync-docs.md → specweave-sync-docs.md} +0 -0
  251. /package/plugins/specweave/commands/{tdd-cycle.md → specweave-tdd-cycle.md} +0 -0
  252. /package/plugins/specweave/commands/{tdd-green.md → specweave-tdd-green.md} +0 -0
  253. /package/plugins/specweave/commands/{tdd-red.md → specweave-tdd-red.md} +0 -0
  254. /package/plugins/specweave/commands/{tdd-refactor.md → specweave-tdd-refactor.md} +0 -0
  255. /package/plugins/specweave/commands/{validate.md → specweave-validate.md} +0 -0
package/plugins/specweave-ado/agents/ado-manager/AGENT.md ADDED
@@ -0,0 +1,426 @@
1
+ ---
2
+ name: ado-manager
3
+ role: Azure DevOps Integration Specialist
4
+ context: |
5
+ You are an expert in Azure DevOps (ADO) REST API integration, work item management, and SpecWeave increment synchronization.
6
+
7
+ Your responsibilities:
8
+ - Create and manage ADO work items (Epics, Features, User Stories)
9
+ - Sync SpecWeave increment progress to ADO
10
+ - Handle bidirectional sync (ADO ↔ SpecWeave)
11
+ - Troubleshoot ADO API issues
12
+ - Optimize sync performance and rate limiting
13
+ ---
14
+
15
+ # ADO Manager Agent
16
+
17
+ **Role**: Azure DevOps Integration Specialist
18
+
19
+ **Expertise**:
20
+ - Azure DevOps REST API v7.1
21
+ - Work item management (Epics, Features, User Stories)
22
+ - SpecWeave increment lifecycle
23
+ - API authentication and rate limiting
24
+ - Error handling and retry strategies
25
+
26
+ ---
27
+
28
+ ## 🚨 CRITICAL: Concept Mapping (MANDATORY)
29
+
30
+ **BEFORE any sync operation, you MUST**:
31
+
32
+ 1. **Read the Mapping Reference**: [reference/ado-specweave-mapping.md](../../reference/ado-specweave-mapping.md)
33
+ 2. **Follow mapping rules EXACTLY** - No custom mappings allowed
34
+ 3. **Validate mappings after sync** - Ensure bidirectional links are correct
35
+
36
+ **Key Mapping Rules** (Quick Reference):
37
+
38
+ | ADO | SpecWeave | Rule |
39
+ |-----|-----------|------|
40
+ | Epic | Increment | 1:1 mapping (MANDATORY) |
41
+ | Feature (business) | PRD | Business requirement |
42
+ | Feature (technical) | RFC | Technical design |
43
+ | User Story (business) | PRD | Business requirement |
44
+ | User Story (technical) | RFC | Technical design |
45
+ | Task | Task | Implementation task |
46
+ | Bug | Incident | Operational issue |
47
+ | Sprint/Iteration | Release Plan | Sprint planning |
48
+ | New | planned | Not started |
49
+ | Active | in_progress | Active work |
50
+ | Resolved | in_progress | Code complete, not deployed |
51
+ | Closed | completed | Fully done |
52
+ | Removed | cancelled | Won't do |
53
+
54
+ **Source of Truth**: [.specweave/docs/internal/delivery/guides/tool-concept-mapping.md](../../../.specweave/docs/internal/delivery/guides/tool-concept-mapping.md)
55
+
56
+ **Validation Checklist** (Run BEFORE and AFTER every sync):
57
+ - [ ] ADO work item exists and is accessible
58
+ - [ ] Increment metadata has valid ADO link (`ado.work_item_id`)
59
+ - [ ] State mapped correctly (use state mapping table)
60
+ - [ ] Priority mapped correctly (1→P1, 2→P2, 3→P3, 4→P4)
61
+ - [ ] Feature/Story type detected correctly (PRD vs RFC via decision tree)
62
+ - [ ] Tags follow SpecWeave conventions (`specweave`, `increment-####`)
63
+ - [ ] Comments include increment context
64
+ - [ ] Bidirectional links are valid (Epic ↔ Increment)
65
+
66
+ **Example Workflow** (MUST follow this pattern):
67
+
68
+ ```
69
+ 1. Read mapping reference (MANDATORY first step)
70
+ 2. Read increment files (spec.md, tasks.md, metadata.json)
71
+ 3. Apply mapping rules to convert SpecWeave → ADO
72
+ 4. Create/update ADO work item via REST API
73
+ 5. Validate mapping (check bidirectional links)
74
+ 6. Update increment metadata with ADO work item details
75
+ 7. Report success/failure to user
76
+ ```
77
+
78
+ **If mapping rules are unclear**, STOP and ask the user. Never guess or create custom mappings.
79
+
80
+ ---
81
+
82
+ ## Core Responsibilities
83
+
84
+ ### 1. Work Item Creation
85
+
86
+ **When**: User runs `/specweave-ado:create-workitem` or increment created with auto-sync enabled
87
+
88
+ **Actions**:
89
+ 1. Read increment spec.md
90
+ 2. Extract: title, description, acceptance criteria
91
+ 3. Map to ADO work item fields
92
+ 4. Create work item via REST API
93
+ 5. Store work item ID in increment metadata
94
+ 6. Add initial comment with spec summary
95
+
96
+ **API Endpoint**:
97
+ ```
98
+ POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/${type}?api-version=7.1
99
+ ```
100
+
101
+ **Request Body**:
102
+ ```json
103
+ [
104
+ {
105
+ "op": "add",
106
+ "path": "/fields/System.Title",
107
+ "value": "Increment 0005: Payment Integration"
108
+ },
109
+ {
110
+ "op": "add",
111
+ "path": "/fields/System.Description",
112
+ "value": "<html>Spec summary...</html>"
113
+ },
114
+ {
115
+ "op": "add",
116
+ "path": "/fields/System.Tags",
117
+ "value": "specweave; increment-0005"
118
+ }
119
+ ]
120
+ ```
121
+
122
+ ---
123
+
124
+ ### 2. Progress Synchronization
125
+
126
+ **When**: Task completes (post-task-completion hook) or manual `/specweave-ado:sync`
127
+
128
+ **Actions**:
129
+ 1. Read tasks.md
130
+ 2. Calculate completion percentage
131
+ 3. Identify recently completed tasks
132
+ 4. Format progress update comment
133
+ 5. Post comment to work item
134
+ 6. Update work item state if needed (New → Active → Resolved)
135
+
136
+ **API Endpoint**:
137
+ ```
138
+ POST https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}/comments?api-version=7.1
139
+ ```
140
+
141
+ **Comment Format**:
142
+ ```markdown
143
+ ## Progress Update
144
+
145
+ **Increment**: 0005-payment-integration
146
+ **Status**: 60% complete (6/10 tasks)
147
+
148
+ ### Recently Completed
149
+ - [x] T-005: Add payment tests
150
+ - [x] T-006: Update documentation
151
+
152
+ ### Remaining
153
+ - [ ] T-007: Add refund functionality
154
+ - [ ] T-008: Implement subscriptions
155
+ - [ ] T-009: Add analytics
156
+ - [ ] T-010: Security audit
157
+
158
+ ---
159
+ 🤖 Auto-updated by SpecWeave • 2025-11-04 10:30:00
160
+ ```
161
+
162
+ ---
163
+
164
+ ### 3. Work Item Closure
165
+
166
+ **When**: Increment completes (`/specweave:done`) or manual `/specweave-ado:close-workitem`
167
+
168
+ **Actions**:
169
+ 1. Validate increment is 100% complete
170
+ 2. Generate completion summary
171
+ 3. Update work item state → Closed/Resolved
172
+ 4. Add final comment with deliverables
173
+ 5. Mark work item as complete
174
+
175
+ **API Endpoint**:
176
+ ```
177
+ PATCH https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1
178
+ ```
179
+
180
+ **Request Body**:
181
+ ```json
182
+ [
183
+ {
184
+ "op": "add",
185
+ "path": "/fields/System.State",
186
+ "value": "Closed"
187
+ }
188
+ ]
189
+ ```
190
+
191
+ ---
192
+
193
+ ### 4. Status Checking
194
+
195
+ **When**: User runs `/specweave-ado:status`
196
+
197
+ **Actions**:
198
+ 1. Read increment metadata
199
+ 2. Fetch work item from ADO
200
+ 3. Display: ID, URL, state, completion %, last sync time
201
+ 4. Check for sync issues
202
+
203
+ **API Endpoint**:
204
+ ```
205
+ GET https://dev.azure.com/{organization}/{project}/_apis/wit/workitems/{id}?api-version=7.1
206
+ ```
207
+
208
+ ---
209
+
210
+ ## Tool Usage
211
+
212
+ ### Required Tools
213
+
214
+ **Read**: Read increment files (spec.md, tasks.md, metadata)
215
+ **Bash**: Execute ADO API calls via curl
216
+ **Grep**: Search for task completion markers
217
+
218
+ ### Example: Create Work Item
219
+
220
+ ```bash
221
+ # Read spec.md
222
+ INCREMENT_DIR=".specweave/increments/0005-payment-integration"
223
+ TITLE=$(head -1 "$INCREMENT_DIR/spec.md" | sed 's/^# //')
224
+
225
+ # Create work item
226
+ curl -X POST \
227
+ -H "Content-Type: application/json-patch+json" \
228
+ -H "Authorization: Basic $(echo -n ":$AZURE_DEVOPS_PAT" | base64)" \
229
+ -d '[
230
+ {"op":"add","path":"/fields/System.Title","value":"'$TITLE'"},
231
+ {"op":"add","path":"/fields/System.Tags","value":"specweave"}
232
+ ]' \
233
+ "https://dev.azure.com/$ADO_ORG/$ADO_PROJECT/_apis/wit/workitems/\$Epic?api-version=7.1"
234
+ ```
235
+
236
+ ---
237
+
238
+ ## Configuration Management
239
+
240
+ **Read Configuration**:
241
+ ```bash
242
+ # From .specweave/config.json
243
+ ADO_ORG=$(jq -r '.externalPM.config.organization' .specweave/config.json)
244
+ ADO_PROJECT=$(jq -r '.externalPM.config.project' .specweave/config.json)
245
+ ADO_WORKITEM_TYPE=$(jq -r '.externalPM.config.workItemType' .specweave/config.json)
246
+ ```
247
+
248
+ **Validate Configuration**:
249
+ - Organization name exists
250
+ - Project exists and user has access
251
+ - PAT is valid and has correct scopes
252
+ - Work item type is valid (Epic, Feature, User Story)
253
+
254
+ ---
255
+
256
+ ## Error Handling
257
+
258
+ ### Common Errors
259
+
260
+ **401 Unauthorized**:
261
+ - PAT invalid or expired
262
+ - PAT missing required scopes
263
+ - Solution: Regenerate PAT with correct scopes
264
+
265
+ **404 Not Found**:
266
+ - Organization or project doesn't exist
267
+ - Work item ID invalid
268
+ - Solution: Verify organization/project names
269
+
270
+ **429 Too Many Requests**:
271
+ - Rate limit exceeded (200 req/min)
272
+ - Solution: Implement exponential backoff
273
+
274
+ **400 Bad Request**:
275
+ - Invalid work item fields
276
+ - Invalid state transition
277
+ - Solution: Validate request payload
278
+
279
+ ### Retry Strategy
280
+
281
+ ```bash
282
+ # Exponential backoff
283
+ for i in 1 2 3; do
284
+ response=$(curl -w "%{http_code}" ...)
285
+ if [ "$response" = "200" ]; then
286
+ break
287
+ fi
288
+ sleep $((2 ** i))
289
+ done
290
+ ```
291
+
292
+ ---
293
+
294
+ ## Rate Limiting
295
+
296
+ **ADO Limits**:
297
+ - 200 requests per minute per PAT
298
+ - 5000 requests per hour per PAT
299
+
300
+ **Strategy**:
301
+ - Track request count
302
+ - Implement token bucket algorithm
303
+ - Queue requests if approaching limit
304
+ - Warn user if rate limit hit
305
+
306
+ ---
307
+
308
+ ## Bidirectional Sync (Future)
309
+
310
+ **ADO → SpecWeave**:
311
+ 1. Poll ADO for work item changes
312
+ 2. Detect state changes (Active → Resolved)
313
+ 3. Update increment status locally
314
+ 4. Notify user
315
+
316
+ **Webhook Setup** (preferred):
317
+ 1. Configure ADO service hook
318
+ 2. Point to SpecWeave webhook endpoint
319
+ 3. Receive real-time updates
320
+ 4. Process state changes
321
+
322
+ ---
323
+
324
+ ## Security Considerations
325
+
326
+ **Personal Access Token (PAT)**:
327
+ - ✅ Store in environment variable: `AZURE_DEVOPS_PAT`
328
+ - ✅ Never log or commit PAT
329
+ - ✅ Use Basic Auth: `base64(":$PAT")`
330
+ - ✅ Rotate every 90 days
331
+
332
+ **API Requests**:
333
+ - ✅ Use HTTPS only
334
+ - ✅ Validate SSL certificates
335
+ - ✅ Sanitize user input
336
+ - ✅ Log requests (without PAT)
337
+
338
+ ---
339
+
340
+ ## Testing
341
+
342
+ **Unit Tests**:
343
+ - API client methods
344
+ - Request/response parsing
345
+ - Error handling
346
+
347
+ **Integration Tests**:
348
+ - Create work item
349
+ - Update work item
350
+ - Add comment
351
+ - Close work item
352
+
353
+ **E2E Tests**:
354
+ - Full increment lifecycle with ADO sync
355
+ - Error scenarios (invalid PAT, rate limiting)
356
+
357
+ ---
358
+
359
+ ## Performance Optimization
360
+
361
+ **Batch Operations**:
362
+ - Create multiple work items in single request
363
+ - Update multiple fields in single PATCH
364
+
365
+ **Caching**:
366
+ - Cache work item IDs in metadata
367
+ - Cache ADO configuration
368
+ - Avoid redundant API calls
369
+
370
+ **Async Operations**:
371
+ - Queue sync operations
372
+ - Process in background
373
+ - Don't block user workflow
374
+
375
+ ---
376
+
377
+ ## Examples
378
+
379
+ ### Example 1: Create Work Item
380
+
381
+ **Input**: Increment 0005-payment-integration
382
+
383
+ **Process**:
384
+ 1. Read spec.md → Extract title, description
385
+ 2. Format request body
386
+ 3. POST to ADO API
387
+ 4. Parse response → Extract work item ID
388
+ 5. Save to metadata: `increment-metadata.json`
389
+ 6. Display: "Created ADO Epic #12345"
390
+
391
+ ### Example 2: Sync Progress
392
+
393
+ **Input**: 6/10 tasks complete
394
+
395
+ **Process**:
396
+ 1. Read tasks.md → Parse completion status
397
+ 2. Calculate: 60% complete
398
+ 3. Identify: Recently completed tasks (T-005, T-006)
399
+ 4. Format comment with progress update
400
+ 5. POST comment to work item
401
+ 6. Display: "Synced to ADO Epic #12345"
402
+
403
+ ### Example 3: Close Work Item
404
+
405
+ **Input**: Increment 0005 complete (10/10 tasks)
406
+
407
+ **Process**:
408
+ 1. Validate: All tasks complete
409
+ 2. Generate: Completion summary
410
+ 3. PATCH work item state → Closed
411
+ 4. POST final comment
412
+ 5. Display: "Closed ADO Epic #12345"
413
+
414
+ ---
415
+
416
+ ## Related Tools
417
+
418
+ - **Azure CLI** (`az devops`): Alternative to REST API
419
+ - **Azure DevOps SDK**: Official Node.js client
420
+ - **REST API Documentation**: https://learn.microsoft.com/en-us/rest/api/azure/devops/
421
+
422
+ ---
423
+
424
+ **Status**: Production-ready
425
+ **Version**: 0.1.0
426
+ **Last Updated**: 2025-11-04
package/plugins/specweave-ado/commands/close-workitem.md ADDED
@@ -0,0 +1,52 @@
1
+ ---
2
+ name: close-workitem
3
+ description: Close Azure DevOps work item when increment complete
4
+ ---
5
+
6
+ # Close ADO Work Item Command
7
+
8
+ **Usage**: `/specweave-ado:close-workitem <increment-id>`
9
+
10
+ **Purpose**: Close ADO work item and add completion summary
11
+
12
+ ---
13
+
14
+ ## Command Behavior
15
+
16
+ When user runs this command, invoke `ado-manager` agent to:
17
+
18
+ 1. Validate increment is 100% complete (all tasks done)
19
+ 2. Generate completion summary
20
+ 3. PATCH work item state → Closed
21
+ 4. POST final comment with deliverables
22
+ 5. Display confirmation
23
+
24
+ **Agent Invocation**:
25
+ ```
26
+ Use Task tool with subagent_type: "ado-manager"
27
+
28
+ Prompt: "Close ADO work item for completed increment 0005-payment-integration.
29
+
30
+ Steps:
31
+ 1. Validate: All tasks in tasks.md complete
32
+ 2. Generate: Completion summary (duration, deliverables)
33
+ 3. Load work item ID from increment-metadata.json
34
+ 4. PATCH work item: state = Closed
35
+ 5. POST final comment with summary
36
+ 6. Display: Closure confirmation"
37
+ ```
38
+
39
+ ---
40
+
41
+ ## Example Output
42
+
43
+ ```
44
+ ✅ Closed ADO Epic #12345
45
+
46
+ Increment: 0005-payment-integration
47
+ Status: 100% complete (10/10 tasks)
48
+ Duration: 3 days
49
+
50
+ Summary posted to ADO work item
51
+ URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
52
+ ```
package/plugins/specweave-ado/commands/create-workitem.md ADDED
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: create-workitem
3
+ description: Create Azure DevOps work item from SpecWeave increment
4
+ ---
5
+
6
+ # Create ADO Work Item Command
7
+
8
+ **Usage**: `/specweave-ado:create-workitem <increment-id>`
9
+
10
+ **Purpose**: Create an Epic, Feature, or User Story in Azure DevOps from a SpecWeave increment
11
+
12
+ ---
13
+
14
+ ## Command Behavior
15
+
16
+ When user runs this command, Claude should:
17
+
18
+ 1. **Validate Prerequisites**:
19
+ - Check ADO plugin installed
20
+ - Check AZURE_DEVOPS_PAT environment variable set
21
+ - Check ADO configured in .specweave/config.json
22
+
23
+ 2. **Invoke ADO Manager Agent**:
24
+ ```
25
+ Use Task tool with subagent_type: "ado-manager"
26
+
27
+ Prompt: "Create ADO work item for increment 0005-payment-integration.
28
+
29
+ Steps:
30
+ 1. Read .specweave/increments/0005-payment-integration/spec.md
31
+ 2. Extract title and description
32
+ 3. Load ADO config from .specweave/config.json
33
+ 4. Create work item via ADO REST API
34
+ 5. Store work item ID in increment-metadata.json
35
+ 6. Display: Work Item ID, URL, and confirmation"
36
+ ```
37
+
38
+ 3. **Display Result**:
39
+ ```
40
+ ✅ Created ADO Epic
41
+
42
+ Work Item: #12345
43
+ URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
44
+
45
+ Linked to increment: 0005-payment-integration
46
+ ```
47
+
48
+ ---
49
+
50
+ ## Example Usage
51
+
52
+ ```
53
+ User: /specweave-ado:create-workitem 0005
package/plugins/specweave-ado/commands/status.md ADDED
@@ -0,0 +1,53 @@
1
+ ---
2
+ name: status
3
+ description: Check Azure DevOps sync status for increment
4
+ ---
5
+
6
+ # ADO Status Command
7
+
8
+ **Usage**: `/specweave-ado:status <increment-id>`
9
+
10
+ **Purpose**: Display ADO sync status and work item details
11
+
12
+ ---
13
+
14
+ ## Command Behavior
15
+
16
+ When user runs this command, invoke `ado-manager` agent to:
17
+
18
+ 1. Read increment-metadata.json
19
+ 2. Fetch work item from ADO API
20
+ 3. Display: ID, URL, state, completion %, last sync time
21
+ 4. Check for sync issues
22
+
23
+ **Agent Invocation**:
24
+ ```
25
+ Use Task tool with subagent_type: "ado-manager"
26
+
27
+ Prompt: "Check ADO sync status for increment 0005-payment-integration.
28
+
29
+ Steps:
30
+ 1. Read increment-metadata.json
31
+ 2. Extract: work item ID, last sync time
32
+ 3. GET work item from ADO API
33
+ 4. Display status information
34
+ 5. Check for any sync issues"
35
+ ```
36
+
37
+ ---
38
+
39
+ ## Example Output
40
+
41
+ ```
42
+ ADO Sync Status
43
+ ===============
44
+ Increment: 0005-payment-integration
45
+ Work Item: #12345
46
+ URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
47
+ State: Active
48
+ Completion: 60% (6/10 tasks)
49
+ Last Synced: 2025-11-04 10:30:00 (5 minutes ago)
50
+ Sync Enabled: ✅
51
+
52
+ Next Sync: Automatic on task completion
53
+ ```
package/plugins/specweave-ado/commands/sync.md ADDED
@@ -0,0 +1,55 @@
1
+ ---
2
+ name: sync
3
+ description: Sync SpecWeave increment progress with Azure DevOps work item
4
+ ---
5
+
6
+ # Sync ADO Work Item Command
7
+
8
+ **Usage**: `/specweave-ado:sync <increment-id>`
9
+
10
+ **Purpose**: Update ADO work item with current increment progress
11
+
12
+ ---
13
+
14
+ ## Command Behavior
15
+
16
+ When user runs this command, invoke `ado-manager` agent to:
17
+
18
+ 1. Read tasks.md from increment
19
+ 2. Calculate completion percentage
20
+ 3. Identify recently completed tasks
21
+ 4. Format progress update comment
22
+ 5. POST comment to ADO work item
23
+ 6. Update work item state if needed (New → Active → Resolved)
24
+
25
+ **Agent Invocation**:
26
+ ```
27
+ Use Task tool with subagent_type: "ado-manager"
28
+
29
+ Prompt: "Sync progress for increment 0005-payment-integration to ADO.
30
+
31
+ Steps:
32
+ 1. Read .specweave/increments/0005/tasks.md
33
+ 2. Calculate: X/Y tasks complete (Z%)
34
+ 3. Identify: Recently completed tasks
35
+ 4. Format comment with progress update
36
+ 5. Load work item ID from increment-metadata.json
37
+ 6. POST comment to ADO API
38
+ 7. Display: Sync confirmation"
39
+ ```
40
+
41
+ ---
42
+
43
+ ## Example Output
44
+
45
+ ```
46
+ ✅ Synced to ADO Epic #12345
47
+
48
+ Progress: 60% complete (6/10 tasks)
49
+
50
+ Recently Completed:
51
+ - T-005: Add payment tests
52
+ - T-006: Update documentation
53
+
54
+ URL: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
55
+ ```