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
@@ -44,7 +44,7 @@ This is a **SpecWeave project** where specifications and documentation are the s
44
44
  .claude/ # Claude Code components (if using Claude)
45
45
  ├── agents/ # Specialized roles (PM, Architect, DevOps, etc.)
46
46
  ├── skills/ # Capabilities (increment-planner, context-loader, etc.)
47
- └── commands/ # Slash commands (/inc, /do, /done)
47
+ └── commands/ # Slash commands (/specweave:increment, /specweave:do, /specweave:done)
48
48
 
49
49
  plugins/ # Optional plugins (extended capabilities)
50
50
  └── specweave-{name}/
@@ -212,7 +212,7 @@ cat plugins/specweave-github/commands/github-sync.md
212
212
  ### What Are Commands?
213
213
 
214
214
  Commands are **executable workflows** defined as `.md` files in `plugins/specweave/commands/`. Each file contains:
215
- - Command name (from filename, e.g., `inc.md` → `/inc`)
215
+ - Command name (from filename, e.g., `specweave-increment.md` → `/specweave:increment`)
216
216
  - Complete workflow instructions
217
217
  - Parameters and usage examples
218
218
  - Step-by-step execution guide
@@ -228,15 +228,15 @@ Commands are **executable workflows** defined as `.md` files in `plugins/specwea
228
228
  ls plugins/specweave/commands/
229
229
 
230
230
  # Common output:
231
- # inc.md - Plan new increment (/inc "feature")
232
- # do.md - Execute implementation (/do)
233
- # done.md - Close increment (/done 0001)
234
- # validate.md - Validate increment (/validate 0001)
235
- # progress.md - Check status (/progress)
236
- # sync-docs.md - Sync living docs (/sync-docs)
237
- # next.md - Smart increment transition
238
- # costs.md - Display AI cost dashboard
239
- # translate.md - Translate content
231
+ # specweave-increment.md - Plan new increment (/specweave:increment "feature")
232
+ # specweave-do.md - Execute implementation (/specweave:do)
233
+ # specweave-done.md - Close increment (/specweave:done 0001)
234
+ # specweave-validate.md - Validate increment (/specweave:validate 0001)
235
+ # specweave-progress.md - Check status (/specweave:progress)
236
+ # specweave-sync-docs.md - Sync living docs (/specweave:sync-docs)
237
+ # specweave-next.md - Smart increment transition (/specweave:next)
238
+ # specweave-costs.md - Display AI cost dashboard (/specweave:costs)
239
+ # specweave-translate.md - Translate content (/specweave:translate)
240
240
  # tdd-*.md - TDD workflow commands
241
241
  # ... (17 commands total)
242
242
  ```
@@ -256,18 +256,18 @@ ls plugins/specweave-github/commands/
256
256
 
257
257
  ### How to Execute Commands (Step-by-Step)
258
258
 
259
- **When user says**: "create new increment for user auth" or "run /inc user auth"
259
+ **When user says**: "create new increment for user auth" or "run /specweave:increment user auth"
260
260
 
261
261
  **You should**:
262
262
 
263
263
  1. **Identify the command**:
264
- - Keywords match: "create increment" → `inc.md`
265
- - Explicit slash: "/inc" → `inc.md`
264
+ - Keywords match: "create increment" → `specweave-increment.md`
265
+ - Explicit slash: "/specweave:increment" → `specweave-increment.md`
266
266
  - Map request to command file
267
267
 
268
268
  2. **Read the command file**:
269
269
  ```bash
270
- cat plugins/specweave/commands/inc.md
270
+ cat plugins/specweave/commands/specweave-increment.md
271
271
  ```
272
272
 
273
273
  3. **Parse the workflow**:
@@ -287,7 +287,7 @@ ls plugins/specweave-github/commands/
287
287
  - Show created files
288
288
  - Suggest next steps
289
289
 
290
- ### Example: Executing /inc Command
290
+ ### Example: Executing /specweave:increment Command
291
291
 
292
292
  **User says**: "create new increment for user authentication"
293
293
 
@@ -295,13 +295,13 @@ ls plugins/specweave-github/commands/
295
295
 
296
296
  ```bash
297
297
  # Step 1: Identify command
298
- # "create increment" → inc.md
298
+ # "create increment" → specweave-increment.md
299
299
 
300
300
  # Step 2: Read command file
301
- cat plugins/specweave/commands/inc.md
301
+ cat plugins/specweave/commands/specweave-increment.md
302
302
  ```
303
303
 
304
- **After reading inc.md, you learn**:
304
+ **After reading specweave-increment.md, you learn**:
305
305
  - This is PM-led increment planning
306
306
  - Requires: feature description
307
307
  - Creates: spec.md, plan.md, tasks.md, tests.md
@@ -355,7 +355,7 @@ cat plugins/specweave/commands/inc.md
355
355
 
356
356
  ✅ Increment 0001-user-authentication ready!
357
357
 
358
- Next: /do 0001 (execute implementation)
358
+ Next: /specweave:do (execute implementation)
359
359
  ```
360
360
 
361
361
  **Step 5: Confirm completion**:
@@ -371,7 +371,7 @@ Files:
371
371
 
372
372
  Next steps:
373
373
  1. Review generated files
374
- 2. Run: /do 0001 (execute implementation)
374
+ 2. Run: /specweave:do (execute implementation)
375
375
  ```
376
376
 
377
377
  ### Core Command Reference
@@ -380,21 +380,21 @@ Next steps:
380
380
 
381
381
  | Command | File | Purpose | Example |
382
382
  |---------|------|---------|---------|
383
- | `/inc` | `inc.md` | Plan new increment | `/inc "user auth"` |
384
- | `/do` | `do.md` | Execute implementation | `/do 0001` |
385
- | `/done` | `done.md` | Close increment | `/done 0001` |
386
- | `/validate` | `validate.md` | Validate quality | `/validate 0001` |
387
- | `/progress` | `progress.md` | Check status | `/progress` |
383
+ | `/specweave:increment` | `specweave-increment.md` | Plan new increment | `/specweave:increment "user auth"` |
384
+ | `/specweave:do` | `specweave-do.md` | Execute implementation | `/specweave:do` |
385
+ | `/specweave:done` | `specweave-done.md` | Close increment | `/specweave:done 0001` |
386
+ | `/specweave:validate` | `specweave-validate.md` | Validate quality | `/specweave:validate 0001` |
387
+ | `/specweave:progress` | `specweave-progress.md` | Check status | `/specweave:progress` |
388
388
 
389
389
  **Specialized** (use when needed):
390
390
 
391
391
  | Command | File | Purpose | Example |
392
392
  |---------|------|---------|---------|
393
- | `/sync-docs` | `sync-docs.md` | Sync living docs | `/sync-docs update` |
394
- | `/next` | `next.md` | Smart increment transition | `/next` |
395
- | `/costs` | `costs.md` | AI cost dashboard | `/costs 0001` |
396
- | `/translate` | `translate.md` | Translate content | `/translate ru` |
397
- | `/tdd-cycle` | `tdd-cycle.md` | TDD workflow | `/tdd-cycle` |
393
+ | `/specweave:sync-docs` | `specweave-sync-docs.md` | Sync living docs | `/specweave:sync-docs update` |
394
+ | `/specweave:next` | `specweave-next.md` | Smart increment transition | `/specweave:next` |
395
+ | `/specweave:costs` | `specweave-costs.md` | AI cost dashboard | `/specweave:costs 0001` |
396
+ | `/specweave:translate` | `specweave-translate.md` | Translate content | `/specweave:translate ru` |
397
+ | `/specweave:tdd-cycle` | `specweave-tdd-cycle.md` | TDD workflow | `/specweave:tdd-cycle` |
398
398
 
399
399
  **Plugin Commands** (when plugins installed):
400
400
 
@@ -402,6 +402,88 @@ Next steps:
402
402
  |---------|------|---------|--------|
403
403
  | `/github:sync` | `plugins/specweave-github/commands/github-sync.md` | Sync to GitHub | specweave-github |
404
404
  | `/github:create-issue` | `plugins/specweave-github/commands/github-create-issue.md` | Create GitHub issue | specweave-github |
405
+ | `/sync-tasks` | `commands/sync-tasks.md` | Sync tasks.md status | specweave (core) |
406
+
407
+ ---
408
+
409
+ ### 🚨 CRITICAL: Task Completion Tracking
410
+
411
+ **Problem**: Commands like `/progress`, `/validate`, `/done` rely on `tasks.md` status being accurate.
412
+ If tasks.md shows "1/24 complete" but you've actually finished 24 tasks, everything breaks!
413
+
414
+ **Solution**: Update `tasks.md` after EACH task completes.
415
+
416
+ #### For Claude Code Users (Automatic ✅)
417
+
418
+ **Good news**: This happens automatically via `post-task-completion.sh` hook!
419
+
420
+ When you complete a task (mark todo as done), the hook:
421
+ 1. ✅ Detects completion
422
+ 2. ✅ Updates corresponding task in tasks.md
423
+ 3. ✅ Recalculates progress %
424
+ 4. ✅ Syncs to GitHub issue (if enabled)
425
+
426
+ **You don't need to do anything manually!**
427
+
428
+ #### For Other AI Tools (Manual ⚠️)
429
+
430
+ **⚠️ IMPORTANT**: After completing EACH task, manually update tasks.md:
431
+
432
+ **Step-by-Step**:
433
+
434
+ ```bash
435
+ # Example: You just completed T-001
436
+
437
+ # 1. Open tasks.md
438
+ vim .specweave/increments/0007-feature-name/tasks.md
439
+
440
+ # 2. Find the task you completed
441
+ #### T-001: Implement authentication service
442
+
443
+ # 3. Change status from pending to completed
444
+ **Status**: [ ] pending
445
+ # ↓ Change to ↓
446
+ **Status**: [x] completed
447
+
448
+ # 4. Update progress counters at the top
449
+ **Completed**: 0 # ← Increment this (0 → 1)
450
+ **Progress**: 0% # ← Recalculate (1/24 = 4%)
451
+
452
+ # 5. Save and commit
453
+ git add .specweave/increments/0007-feature-name/tasks.md
454
+ git commit -m "chore: mark T-001 as complete"
455
+ ```
456
+
457
+ **Why This Matters**:
458
+ - `/progress` shows accurate completion % ✅
459
+ - `/validate` checks pass ✅
460
+ - `/done` can close the increment ✅
461
+ - Team knows real status ✅
462
+
463
+ **Validation Check**:
464
+ ```bash
465
+ # Verify tasks.md is in sync
466
+ /sync-tasks --validate
467
+
468
+ # If out of sync:
469
+ /sync-tasks # Auto-fix from GitHub or git history
470
+ ```
471
+
472
+ **Quick Reference Card** (print and keep handy):
473
+
474
+ ```
475
+ ┌────────────────────────────────────────────────┐
476
+ │ AFTER EACH TASK: Update tasks.md Status │
477
+ ├────────────────────────────────────────────────┤
478
+ │ 1. Open: .specweave/increments/XXXX/tasks.md │
479
+ │ 2. Find: #### T-XXX │
480
+ │ 3. Change: [ ] pending → [x] completed │
481
+ │ 4. Update: Completed count & Progress % │
482
+ │ 5. Commit: git commit -m "chore: mark done" │
483
+ └────────────────────────────────────────────────┘
484
+ ```
485
+
486
+ ---
405
487
 
406
488
  ### Command Execution Pattern (Template)
407
489
 
@@ -1067,6 +1149,224 @@ Only **Claude Code** has automatic hooks that remind you to update docs.
1067
1149
 
1068
1150
  ---
1069
1151
 
1152
+ ## 🔗 External Tracker Sync (CRITICAL FOR NON-CLAUDE TOOLS)
1153
+
1154
+ **IMPORTANT**: Claude Code has automatic hooks that sync to external trackers (GitHub Issues, Jira, Azure DevOps) after each task completion. **GitHub Copilot, Cursor, and other tools DO NOT have these hooks!**
1155
+
1156
+ ### You MUST Manually Sync to External Trackers After Every Task
1157
+
1158
+ When you complete ANY task, you MUST sync progress to external trackers if they are enabled for the project.
1159
+
1160
+ #### Step 1: Detect Which Trackers Are Enabled
1161
+
1162
+ Check the current increment's `metadata.json`:
1163
+
1164
+ ```bash
1165
+ # Find current increment (latest non-backlog increment)
1166
+ CURRENT_INCREMENT=$(ls -t .specweave/increments/ 2>/dev/null | grep -v "_backlog" | head -1)
1167
+
1168
+ # Check metadata
1169
+ cat .specweave/increments/$CURRENT_INCREMENT/metadata.json
1170
+ ```
1171
+
1172
+ **Example metadata.json**:
1173
+ ```json
1174
+ {
1175
+ "id": "0007-smart-increment-discipline",
1176
+ "title": "Increment Management v2.0",
1177
+ "status": "active",
1178
+ "github": {
1179
+ "issue": 4,
1180
+ "url": "https://github.com/anton-abyzov/specweave/issues/4"
1181
+ },
1182
+ "jira": {
1183
+ "issue": "PROJ-123",
1184
+ "url": "https://company.atlassian.net/browse/PROJ-123"
1185
+ },
1186
+ "ado": {
1187
+ "item": 456,
1188
+ "url": "https://dev.azure.com/org/project/_workitems/edit/456"
1189
+ }
1190
+ }
1191
+ ```
1192
+
1193
+ #### Step 2: Sync to Each Enabled Tracker
1194
+
1195
+ **For GitHub** (if `github.issue` exists):
1196
+
1197
+ ```bash
1198
+ # Get issue number
1199
+ GITHUB_ISSUE=$(jq -r '.github.issue' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
1200
+
1201
+ # Post progress comment
1202
+ gh issue comment "$GITHUB_ISSUE" --body "Progress update: Task T-XXX completed in increment $CURRENT_INCREMENT
1203
+
1204
+ Details:
1205
+ - Task: [Task description]
1206
+ - Status: Completed
1207
+ - Timestamp: $(date -u +"%Y-%m-%dT%H:%M:%SZ")
1208
+
1209
+ Next: [Next task or completion status]
1210
+ "
1211
+ ```
1212
+
1213
+ **For Jira** (if `jira.issue` exists):
1214
+
1215
+ ```bash
1216
+ # Get issue key
1217
+ JIRA_ISSUE=$(jq -r '.jira.issue' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
1218
+
1219
+ # Add comment (requires jira CLI: https://github.com/ankitpokhrel/jira-cli)
1220
+ jira issue comment add "$JIRA_ISSUE" "Progress update: Task T-XXX completed
1221
+
1222
+ Details:
1223
+ - Task: [Task description]
1224
+ - Status: Completed
1225
+ - Increment: $CURRENT_INCREMENT
1226
+ "
1227
+
1228
+ # Update status if task is major milestone
1229
+ # jira issue move "$JIRA_ISSUE" "In Progress" / "Review" / "Done"
1230
+ ```
1231
+
1232
+ **For Azure DevOps** (if `ado.item` exists):
1233
+
1234
+ ```bash
1235
+ # Get work item ID
1236
+ ADO_ITEM=$(jq -r '.ado.item' .specweave/increments/$CURRENT_INCREMENT/metadata.json)
1237
+
1238
+ # Add comment (requires az CLI: https://aka.ms/azure-cli)
1239
+ az boards work-item update --id "$ADO_ITEM" --discussion "Progress update: Task T-XXX completed
1240
+
1241
+ Details:
1242
+ - Task: [Task description]
1243
+ - Status: Completed
1244
+ - Increment: $CURRENT_INCREMENT
1245
+ "
1246
+ ```
1247
+
1248
+ #### Step 3: When to Sync
1249
+
1250
+ **After EVERY task completion**, sync to all enabled trackers:
1251
+
1252
+ ```bash
1253
+ # Example workflow after completing T-003:
1254
+
1255
+ # 1. Mark task complete in tasks.md
1256
+ vim .specweave/increments/0007-feature/tasks.md
1257
+ # Change: - [ ] T003: Task → - [x] T003: Task ✅
1258
+
1259
+ # 2. Update increment documentation (plan.md, etc.)
1260
+ # [See "Documentation Updates" section above]
1261
+
1262
+ # 3. Sync to external trackers
1263
+ gh issue comment 4 --body "✅ T-003 Complete: Create test-aware-planner structure
1264
+
1265
+ Directory structure created at plugins/specweave/agents/test-aware-planner/
1266
+
1267
+ Next: T-004 - Write test-aware-planner AGENT.md prompt
1268
+ "
1269
+
1270
+ # 4. Continue to next task
1271
+ ```
1272
+
1273
+ #### Step 4: Update Task Checklist in GitHub/Jira
1274
+
1275
+ **For GitHub Issues with task checklists**:
1276
+
1277
+ The issue body likely contains a task checklist:
1278
+
1279
+ ```markdown
1280
+ ## Tasks
1281
+ - [x] T-001: Update plan.md
1282
+ - [x] T-002: Add auto-sync hook
1283
+ - [ ] T-003: Create test-aware-planner structure
1284
+ - [ ] T-004: Write AGENT.md prompt
1285
+ ```
1286
+
1287
+ **Update the checklist** after each task:
1288
+
1289
+ ```bash
1290
+ # Get current issue body
1291
+ gh issue view 4 --json body -q .body > issue-body.md
1292
+
1293
+ # Edit the checklist (mark T-003 as done)
1294
+ vim issue-body.md
1295
+ # Change: - [ ] T-003 → - [x] T-003
1296
+
1297
+ # Update issue
1298
+ gh issue edit 4 --body-file issue-body.md
1299
+ ```
1300
+
1301
+ **For Jira** (subtasks):
1302
+
1303
+ If tasks are represented as subtasks:
1304
+
1305
+ ```bash
1306
+ # List subtasks
1307
+ jira issue list --parent PROJ-123
1308
+
1309
+ # Update subtask status
1310
+ jira issue move PROJ-123-SUB1 "Done"
1311
+ ```
1312
+
1313
+ #### Step 5: Sync Increment Status Changes
1314
+
1315
+ When increment status changes (active → paused → completed), sync that too:
1316
+
1317
+ ```bash
1318
+ # Example: Increment completed
1319
+ gh issue comment 4 --body "🎉 INCREMENT COMPLETED!
1320
+
1321
+ All 24 tasks finished. Increment 0007-smart-increment-discipline is now complete.
1322
+
1323
+ See completion report: .specweave/increments/0007-smart-increment-discipline/reports/COMPLETION-SUMMARY.md
1324
+ "
1325
+
1326
+ # Close the issue
1327
+ gh issue close 4 --comment "Increment completed and merged to main branch."
1328
+ ```
1329
+
1330
+ ### Why This Matters
1331
+
1332
+ **Without external tracker sync**:
1333
+ - ❌ Stakeholders don't see progress
1334
+ - ❌ Team members work in isolation
1335
+ - ❌ No audit trail of work done
1336
+ - ❌ GitHub/Jira becomes stale and useless
1337
+
1338
+ **With external tracker sync**:
1339
+ - ✅ Real-time visibility into progress
1340
+ - ✅ Team stays informed
1341
+ - ✅ Stakeholders can track without asking
1342
+ - ✅ Complete audit trail
1343
+ - ✅ GitHub/Jira remains the source of truth
1344
+
1345
+ ### Tools That Need Manual Sync
1346
+
1347
+ These tools **DO NOT** have automatic external tracker sync:
1348
+ - GitHub Copilot (all versions)
1349
+ - Cursor
1350
+ - Windsurf
1351
+ - Gemini CLI
1352
+ - Generic AI tools (ChatGPT, Claude web, etc.)
1353
+
1354
+ Only **Claude Code** has automatic hooks (via `post-task-completion.sh`) that sync to external trackers.
1355
+
1356
+ ### Summary Checklist (After Every Task)
1357
+
1358
+ When you complete a task in non-Claude tools:
1359
+
1360
+ 1. ✅ Mark task complete in tasks.md
1361
+ 2. ✅ Update living docs (see "Documentation Updates" section)
1362
+ 3. ✅ **Sync to GitHub/Jira/ADO** (this section)
1363
+ 4. ✅ Update RFC if applicable (if task implements architecture decision)
1364
+ 5. ✅ Continue to next task
1365
+
1366
+ **Remember**: In Claude Code, steps 3-4 happen automatically via hooks. In other tools, YOU must do them manually!
1367
+
1368
+ ---
1369
+
1070
1370
  ## Security Considerations
1071
1371
 
1072
1372
  - Never commit secrets (use `.env` files, gitignored)
@@ -330,6 +330,29 @@ Plugins are detected and suggested during `specweave init` based on:
330
330
 
331
331
  ---
332
332
 
333
+ ## Frequently Asked Questions
334
+
335
+ **New to SpecWeave?** Check out the [FAQ](https://spec-weave.com/docs/faq) for answers to common questions:
336
+
337
+ ### Quick Answers
338
+ - **Why specs in two locations?** Living Docs (permanent, complete feature) vs Increment Specs (temporary, current work)
339
+ - **When do I need living docs spec?** Major features (3+ increments), brownfield integration, or external PM tools
340
+ - **Can I delete increment specs?** YES, after completion. Living docs specs are NEVER deleted (permanent)
341
+ - **Which spec is source of truth?** Living docs spec (when it exists), otherwise increment spec
342
+
343
+ ### Key Topics Covered
344
+ - ✅ Two-spec architecture explained
345
+ - ✅ When to create living docs specs
346
+ - ✅ Increment spec lifecycle
347
+ - ✅ Brownfield documentation linking
348
+ - ✅ External PM tool integration (Jira, ADO, GitHub)
349
+ - ✅ Small vs large feature decisions
350
+ - ✅ Project structure and organization
351
+
352
+ **[View Complete FAQ →](https://spec-weave.com/docs/faq)**
353
+
354
+ ---
355
+
333
356
  ## Testing
334
357
 
335
358
  **Four Levels**:
@@ -351,29 +374,21 @@ Plugins are detected and suggested during `specweave init` based on:
351
374
 
352
375
  | User Says | Use Command | What It Does |
353
376
  |-----------|-------------|--------------|
354
- | "Let's build [feature]" | `/inc "[feature]"` | Plan new increment |
355
- | "Start implementing" | `/do` | Execute tasks (smart resume) |
356
- | "What's the status?" | `/progress` | Show task completion % |
357
- | "Is this ready?" | `/validate 0001` | Validate increment quality |
358
- | "We're done" | `/done 0001` | Close increment |
377
+ | "Let's build [feature]" | `/specweave:increment "[feature]"` | Plan new increment |
378
+ | "Start implementing" | `/specweave:do` | Execute tasks (smart resume) |
379
+ | "What's the status?" | `/specweave:progress` | Show task completion % |
380
+ | "Is this ready?" | `/specweave:validate 0001` | Validate increment quality |
381
+ | "We're done" | `/specweave:done 0001` | Close increment |
359
382
 
360
383
  **Plugin Commands** (when installed):
361
384
  | "Sync to GitHub" | `/specweave:github:sync` | Export to GitHub issues |
362
385
  | "Sync to Jira" | `/specweave:jira:sync` | Export to Jira |
363
386
 
364
- ### Command Aliases
365
-
366
- - `/inc` = `/specweave inc` = `/specweave:inc`
367
- - `/do` = `/specweave do` = `/specweave:do`
368
- - `/validate` = `/specweave validate` = `/specweave:validate`
369
- - `/done` = `/specweave done` = `/specweave:done`
370
- - `/progress` = `/specweave progress` = `/specweave:progress`
371
-
372
387
  ---
373
388
 
374
389
  ## Key SpecWeave Principles
375
390
 
376
- 1. **Specification-First**: Always start with `/inc` to create specs before coding
391
+ 1. **Specification-First**: Always start with `/specweave:increment` to create specs before coding
377
392
  2. **Documentation = Source of Truth**: Specs guide implementation, not the reverse
378
393
  3. **Incremental**: Work in small, measurable increments
379
394
  4. **Validated**: Every increment validated before closure
@@ -394,19 +409,19 @@ Plugins are detected and suggested during `specweave init` based on:
394
409
 
395
410
  **Create your first feature**:
396
411
  ```bash
397
- /inc "your feature description"
412
+ /specweave:increment "your feature description"
398
413
  ```
399
414
 
400
415
  **Typical Workflow**:
401
- 1. `/inc "feature"` → SpecWeave creates specs
416
+ 1. `/specweave:increment "feature"` → SpecWeave creates specs
402
417
  2. Review specs (spec.md, plan.md, tasks.md)
403
- 3. `/do` → Claude implements the code
404
- 4. `/progress` → Check status anytime
405
- 5. `/validate 0001` → Validate quality (optional)
406
- 6. `/done 0001` → Close when complete
418
+ 3. `/specweave:do` → Claude implements the code
419
+ 4. `/specweave:progress` → Check status anytime
420
+ 5. `/specweave:validate 0001` → Validate quality (optional)
421
+ 6. `/specweave:done 0001` → Close when complete
407
422
 
408
423
  **Remember**:
409
- - Type `/inc` first, THEN implement
424
+ - Type `/specweave:increment` first, THEN implement
410
425
  - Keep root clean (use increment folders)
411
426
  - All agents/skills activate automatically
412
427
 
@@ -0,0 +1,128 @@
1
+ # Increment {{ID}}: {{TITLE}}
2
+
3
+ **Status**: {{STATUS}}
4
+ **Type**: {{TYPE}}
5
+ **Created**: {{CREATED_DATE}}
6
+ **Completed**: {{COMPLETED_DATE}}
7
+
8
+ ---
9
+
10
+ ## Original Scope (Planned)
11
+
12
+ ### User Stories
13
+
14
+ {{ORIGINAL_USER_STORIES}}
15
+
16
+ ### Tasks
17
+
18
+ {{ORIGINAL_TASKS}}
19
+
20
+ **Estimated Effort**: {{ESTIMATED_HOURS}} hours
21
+
22
+ ---
23
+
24
+ ## Scope Evolution (Living Updates)
25
+
26
+ _This section is updated during the increment whenever scope changes occur._
27
+
28
+ {{#SCOPE_CHANGES}}
29
+ ### {{CHANGE_DATE}}: {{CHANGE_TITLE}}
30
+
31
+ **Changed**: {{WHAT_CHANGED}}
32
+ **Reason**: {{WHY_CHANGED}}
33
+ **Impact**: {{IMPACT_HOURS}} hours ({{IMPACT_DIRECTION}})
34
+ **Decision**: {{WHO_APPROVED}}
35
+ **Documentation**: {{DOCUMENTATION_LINKS}}
36
+
37
+ ---
38
+ {{/SCOPE_CHANGES}}
39
+
40
+ {{#IF_NO_CHANGES}}
41
+ _No scope changes during this increment._
42
+ {{/IF_NO_CHANGES}}
43
+
44
+ ---
45
+
46
+ ## Final Delivery
47
+
48
+ ### Completed User Stories
49
+
50
+ {{COMPLETED_USER_STORIES}}
51
+
52
+ ### Deferred User Stories
53
+
54
+ {{DEFERRED_USER_STORIES}}
55
+
56
+ ### Added User Stories
57
+
58
+ {{ADDED_USER_STORIES}}
59
+
60
+ **Delivered**: {{DELIVERED_COUNT}} user stories ({{PLANNED_COUNT}} originally planned, {{ADDED_COUNT}} added, {{DEFERRED_COUNT}} deferred)
61
+ **Actual Effort**: {{ACTUAL_HOURS}} hours (vs {{ESTIMATED_HOURS}} estimated)
62
+
63
+ ---
64
+
65
+ ## What Changed and Why
66
+
67
+ ### Deferrals
68
+
69
+ {{#DEFERRALS}}
70
+ - **{{DEFERRED_ITEM}}**: {{DEFERRAL_REASON}}
71
+ - Business value: {{BUSINESS_VALUE_ASSESSMENT}}
72
+ - Can be added later: {{CAN_ADD_LATER}}
73
+ {{/DEFERRALS}}
74
+
75
+ ### Additions
76
+
77
+ {{#ADDITIONS}}
78
+ - **{{ADDED_ITEM}}**: {{ADDITION_REASON}}
79
+ - Stakeholder: {{STAKEHOLDER}}
80
+ - Scope approved by: {{APPROVER}}
81
+ {{/ADDITIONS}}
82
+
83
+ ### Technical Pivots
84
+
85
+ {{#TECHNICAL_PIVOTS}}
86
+ - **{{PIVOT_DESCRIPTION}}**: {{PIVOT_DECISION}}
87
+ - Documented in: {{ADR_LINK}}
88
+ - Impact: {{PIVOT_IMPACT}}
89
+ {{/TECHNICAL_PIVOTS}}
90
+
91
+ ---
92
+
93
+ ## Lessons Learned
94
+
95
+ {{#LESSONS}}
96
+ 1. **{{LESSON_TITLE}}**: {{LESSON_DESCRIPTION}}
97
+ {{/LESSONS}}
98
+
99
+ ---
100
+
101
+ ## Metrics
102
+
103
+ - **Velocity**: {{ACTUAL_HOURS}} hours / {{DAYS_TAKEN}} days = {{HOURS_PER_DAY}} hours/day
104
+ - **Scope creep**: {{SCOPE_CREEP_ANALYSIS}}
105
+ - **Test coverage**: {{TEST_COVERAGE}}% (target: 80%)
106
+ - **Defects found**: {{DEFECTS_COUNT}} ({{CRITICAL_COUNT}} critical, {{MINOR_COUNT}} minor)
107
+
108
+ ---
109
+
110
+ ## Related Documentation
111
+
112
+ {{#RELATED_DOCS}}
113
+ - {{DOC_TYPE}}: [{{DOC_TITLE}}]({{DOC_LINK}})
114
+ {{/RELATED_DOCS}}
115
+
116
+ ---
117
+
118
+ **Report Version**: v{{REPORT_VERSION}} (updated {{UPDATE_COUNT}} times during increment)
119
+ **Last Updated**: {{LAST_UPDATED}}
120
+ **Updated By**: {{UPDATED_BY}}
121
+
122
+ ---
123
+
124
+ ## Update History
125
+
126
+ {{#UPDATE_HISTORY}}
127
+ - v{{VERSION}}: {{UPDATE_DATE}} - {{UPDATE_DESCRIPTION}}
128
+ {{/UPDATE_HISTORY}}