specweave 0.10.0 → 0.11.0

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 (28) hide show
  1. package/.claude-plugin/marketplace.json +2 -2
  2. package/CLAUDE.md +55 -93
  3. package/dist/cli/commands/init.d.ts.map +1 -1
  4. package/dist/cli/commands/init.js +98 -59
  5. package/dist/cli/commands/init.js.map +1 -1
  6. package/dist/cli/helpers/issue-tracker/index.d.ts.map +1 -1
  7. package/dist/cli/helpers/issue-tracker/index.js +39 -0
  8. package/dist/cli/helpers/issue-tracker/index.js.map +1 -1
  9. package/dist/cli/helpers/issue-tracker/jira.d.ts.map +1 -1
  10. package/dist/cli/helpers/issue-tracker/jira.js +2 -9
  11. package/dist/cli/helpers/issue-tracker/jira.js.map +1 -1
  12. package/dist/utils/external-resource-validator.d.ts.map +1 -1
  13. package/dist/utils/external-resource-validator.js +44 -25
  14. package/dist/utils/external-resource-validator.js.map +1 -1
  15. package/package.json +1 -1
  16. package/plugins/specweave/skills/SKILLS-INDEX.md +23 -2
  17. package/plugins/specweave/skills/increment-planner/SKILL.md +13 -92
  18. package/plugins/specweave/skills/plugin-installer/SKILL.md +355 -0
  19. package/plugins/specweave-ado/agents/ado-manager/AGENT.md +2 -0
  20. package/plugins/specweave-ado/commands/specweave-ado-sync.md +102 -9
  21. package/plugins/specweave-ado/skills/ado-sync/SKILL.md +7 -3
  22. package/plugins/specweave-github/agents/github-manager/AGENT.md +14 -4
  23. package/plugins/specweave-github/commands/specweave-github-sync.md +60 -11
  24. package/plugins/specweave-github/skills/github-sync/SKILL.md +3 -1
  25. package/plugins/specweave-jira/agents/jira-manager/AGENT.md +18 -8
  26. package/plugins/specweave-jira/commands/specweave-jira-sync.md +62 -19
  27. package/plugins/specweave-jira/skills/jira-resource-validator/SKILL.md +120 -57
  28. package/plugins/specweave-jira/skills/jira-sync/SKILL.md +5 -3
@@ -2,9 +2,9 @@
2
2
 
3
3
  **Purpose**: Quick reference for all available skills. Read this file BEFORE starting any task.
4
4
 
5
- **Last Updated**: 2025-11-03T04:18:05.042Z (auto-generated, do not edit manually)
5
+ **Last Updated**: 2025-11-10 (manually updated to include plugin-installer and plugin-expert)
6
6
 
7
- **Total Skills**: 12
7
+ **Total Skills**: 14
8
8
 
9
9
  ---
10
10
 
@@ -37,6 +37,26 @@ Step 4: Execute → Follow the increment planning workflow
37
37
 
38
38
  ### Framework Core
39
39
 
40
+ #### plugin-installer
41
+
42
+ **Description**: Proactive just-in-time plugin installation. Auto-detects when specialized plugins are needed (docs-preview, frontend, kubernetes, ML, payments, testing, etc.) and installs them automatically before use. Activates for preview docs, Docusaurus, React, Next.js, K8s, Kubernetes, Helm, TensorFlow, PyTorch, ML model, Stripe, billing, payment, Playwright, E2E testing, Figma, design system, ADO, Azure DevOps, infrastructure, Prometheus, Grafana, monitoring, Node.js, Python backend, REST API, cloud deployment, diagram, Mermaid, C4, architecture diagram.
43
+
44
+ **Activates for**: preview docs, documentation UI, Docusaurus, React, Next.js, frontend, UI component, K8s, Kubernetes, deploy, TensorFlow, ML model, Stripe, billing, E2E testing, Figma, diagram, architecture diagram
45
+
46
+ **Location**: `.claude/skills/plugin-installer/SKILL.md`
47
+
48
+ ---
49
+
50
+ #### plugin-expert
51
+
52
+ **Description**: Expert knowledge of Claude Code's plugin system, marketplace management, and installation commands. Activates for plugin installation, marketplace setup, plugin troubleshooting, plugin commands. Keywords plugin install, plugin marketplace, claude code plugins, plugin management, plugin errors, marketplace add, plugin list.
53
+
54
+ **Activates for**: plugin installation, marketplace setup, plugin troubleshooting, plugin commands, plugin install, plugin marketplace
55
+
56
+ **Location**: `.claude/skills/plugin-expert/SKILL.md`
57
+
58
+ ---
59
+
40
60
  #### context-loader
41
61
 
42
62
  **Description**: Explains how SpecWeave achieves context efficiency through Claude's native progressive disclosure mechanism and sub-agent parallelization. Skills load only when relevant, sub-agents isolate context. Activates when users ask about context loading, token usage, or how SpecWeave scales. Keywords: context loading, progressive disclosure, token efficiency, sub-agents, context management.
@@ -182,6 +202,7 @@ Step 4: Execute → Follow the increment planning workflow
182
202
 
183
203
  | Your Task | Relevant Skill | Keywords |
184
204
  |-----------|---------------|----------|
205
+ | "Preview internal docs" | `plugin-installer` | "preview docs", "Docusaurus", "documentation UI" |
185
206
  | "Plan a new feature" | `increment-planner` | "feature planning", "create increment" |
186
207
  | "Sync to JIRA" | `jira-sync` | "JIRA sync", "create JIRA issue" |
187
208
  | "Create diagram" | `diagrams-architect` | "architecture diagram", "C4 diagram" |
@@ -522,99 +522,24 @@ created: YYYY-MM-DD
522
522
  - Measurable acceptance criteria
523
523
  - Prioritized user stories (P1/P2/P3)
524
524
 
525
- ### Step 6: Detect Required Plugins & Check PM Tool (INTELLIGENT AUTO-LOADING + PM SYNC)
526
-
527
- **Purpose**: Analyze spec content to identify required SpecWeave plugins AND check if external PM tool sync is configured.
528
-
529
- **⚠️ CRITICAL**: For ALL plugin installations, consult the `plugin-expert` skill for correct syntax. NEVER use `@marketplace` suffix!
530
-
531
- **Why This Matters**:
532
- 1. SpecWeave's plugin system enables context efficiency (70%+ reduction) by loading only relevant capabilities
533
- 2. PM tool integration enables automatic sync of increment progress to external systems (GitHub Issues, Jira, Azure DevOps)
534
-
535
- **Detection Algorithm**:
536
-
537
- 1. **Scan spec.md for keywords**:
538
- ```
539
- Keywords → Plugin Mapping:
540
- - "GitHub", "issue", "pull request", "PR" → specweave-github
541
- - "Jira", "ticket", "epic" → specweave-jira
542
- - "Azure DevOps", "ADO", "work item" → specweave-ado
543
- - "Kubernetes", "K8s", "Helm", "kubectl" → specweave-kubernetes
544
- - "Figma", "design system", "design tokens" → specweave-figma
545
- - "Stripe", "PayPal", "billing", "subscriptions" → specweave-payments
546
- - "React", "Next.js", "Vue", "Angular" → specweave-frontend
547
- - "Express", "Fastify", "NestJS", "FastAPI" → specweave-backend
548
- - "TensorFlow", "PyTorch", "ML", "training" → specweave-ml
549
- - "Prometheus", "Grafana", "monitoring" → specweave-infrastructure
550
- - "Playwright", "E2E", "browser tests" → specweave-testing
551
- - "Mermaid", "C4", "diagrams", "architecture diagrams" → specweave-diagrams
552
- ```
553
-
554
- 2. **Check External PM Tool Configuration** (NEW v0.8.0):
555
- - Read `.specweave/config.json`
556
- - If `externalPM.enabled = true` and `externalPM.tool` is set:
557
- - Check if corresponding plugin installed (specweave-github, specweave-jira, or specweave-ado)
558
- - Prepare to auto-create external issue/work item after increment creation
559
- - If `externalPM.enabled = false` or not configured:
560
- - Skip PM tool sync (local-only mode)
561
-
562
- 3. **Check if plugins are already installed**:
563
- - For Claude Code: Check if plugin available via `/plugin list --installed`
564
- - Skip already-installed plugins
565
-
566
- 4. **🚨 AUTOMATIC PLUGIN INSTALLATION** (if plugins detected):
567
-
568
- **IMPORTANT**: When you detect required plugins, you MUST:
569
- - ✅ Proactively offer to install them (not just suggest)
570
- - ✅ Explain WHY each plugin is needed (based on detected keywords)
571
- - ✅ Show clear install commands
572
- - ✅ Remind user that plugins provide expert AI agents and capabilities
573
-
574
- **Output Format**:
575
- ```
576
- 🔌 Detected plugin requirements from spec content:
525
+ ### Step 6: Check PM Tool Configuration (PM SYNC)
577
526
 
578
- REQUIRED (will significantly improve implementation):
579
- • specweave-github - GitHub Issues integration
580
- Detected: "sync tasks to GitHub issues", "create pull requests"
581
- Provides: GitHub sync, PR automation, issue tracking
582
- → Without this: Manual GitHub sync required
527
+ **Purpose**: Check if external PM tool sync is configured for automatic increment tracking.
583
528
 
584
- specweave-kubernetes - Kubernetes deployment
585
- Detected: "deploy to production cluster", "kubectl apply"
586
- Provides: K8s expert agent, Helm chart generation, deployment validation
587
- → Without this: Manual K8s configuration, no validation
529
+ **Why This Matters**: PM tool integration enables automatic sync of increment progress to external systems (GitHub Issues, Jira, Azure DevOps).
588
530
 
589
- OPTIONAL (helpful but not critical):
590
- • specweave-diagrams - Architecture diagrams
591
- Detected: "system architecture", "component diagram"
592
- Provides: Mermaid + C4 diagram generation
593
- → Without this: Manual diagram creation
531
+ **⚠️ NOTE**: All SpecWeave plugins (19+) are already installed during `specweave init`. No plugin detection or installation needed!
594
532
 
595
- 📦 Install recommended plugins:
596
- /plugin install specweave-github
597
- /plugin install specweave-kubernetes
533
+ **Check External PM Tool Configuration**:
598
534
 
599
- 📦 Install optional plugins:
600
- /plugin install specweave-diagrams
601
-
602
- 💡 Benefits:
603
- Plugins provide specialized AI agents (GitHub expert, K8s expert, etc.)
604
- Skills auto-activate based on context (zero manual invocation)
605
- • 70%+ context reduction (only load what you need)
606
- • Best practices built-in (from real-world experience)
607
-
608
- Would you like me to wait while you install these plugins? (Recommended)
609
- Or shall I continue without them? (Limited capabilities)
610
- ```
611
-
612
- **User Decision Points**:
613
- - If user installs plugins → continue with full capabilities
614
- - If user skips → continue but remind about limitations later
615
- - NEVER block increment creation (plugins are enhancements, not requirements)
535
+ 1. **Read `.specweave/config.json`**:
536
+ - If `externalPM.enabled = true` and `externalPM.tool` is set:
537
+ - Corresponding plugin is already installed (specweave-github, specweave-jira, or specweave-ado)
538
+ - Prepare to auto-create external issue/work item after increment creation
539
+ - If `externalPM.enabled = false` or not configured:
540
+ - Skip PM tool sync (local-only mode)
616
541
 
617
- 5. **Auto-Sync to PM Tool** (v0.8.0+):
542
+ 2. **Auto-Sync to PM Tool** (v0.8.0+):
618
543
 
619
544
  **🚨 CRITICAL: SpecWeave Repo Dog-Food Requirement**:
620
545
  - IF repo = "anton-abyzov/specweave"
@@ -683,10 +608,6 @@ Files:
683
608
  • plan.md (technical architecture)
684
609
  • tasks.md (implementation steps with embedded tests)
685
610
 
686
- 🔌 Plugin Detection:
687
- Detected: "user authentication", "JWT tokens", "session management"
688
- → No additional plugins required
689
-
690
611
  🔗 External PM Tool Sync:
691
612
  Tool: GitHub Issues
692
613
  Plugin: specweave-github ✅ Installed
@@ -706,7 +627,7 @@ Next steps:
706
627
  ```
707
628
 
708
629
  **Integration with Existing Workflow**:
709
- - Plugin detection is a **suggestion step** (not blocking)
630
+ - All plugins are already installed during `specweave init` (no detection needed)
710
631
  - PM tool sync is **automatic** if configured (zero manual intervention)
711
632
  - Increment creation continues regardless of PM tool status
712
633
  - This implements the "seamless integration" philosophy
@@ -0,0 +1,355 @@
1
+ ---
2
+ name: plugin-installer
3
+ description: DEPRECATED - This skill is no longer needed. All plugins are now installed automatically during specweave init. This skill remains for backward compatibility but should NOT activate.
4
+ ---
5
+
6
+ # Plugin Installer - DEPRECATED
7
+
8
+ **Status**: ⚠️ **DEPRECATED** - Do not use this skill
9
+
10
+ **Reason**: As of v0.11.0+, ALL SpecWeave plugins (19+) are automatically installed during `specweave init`. There is no need for just-in-time plugin installation anymore.
11
+
12
+ **What Changed**:
13
+ - ❌ Old: Selective plugin loading with just-in-time installation
14
+ - ✅ New: All plugins installed upfront during init
15
+
16
+ **If you see this skill activating**, it means you're using an old SpecWeave installation. Run `specweave init` again to get all plugins installed automatically.
17
+
18
+ ---
19
+
20
+ ## For Contributors: Why This Was Deprecated
21
+
22
+ **The Problem with Just-in-Time Installation**:
23
+ - Added complexity to the workflow
24
+ - Users had to wait for installations mid-work
25
+ - Network issues could block work unexpectedly
26
+ - Detection logic was fragile (keyword matching)
27
+
28
+ **The Solution - Install Everything Upfront**:
29
+ - All 19+ plugins installed during `specweave init`
30
+ - Takes ~30 seconds upfront but saves time later
31
+ - All capabilities available immediately
32
+ - No network dependencies during work
33
+ - Simpler, more predictable user experience
34
+
35
+ ---
36
+
37
+ ## Plugin Detection Keywords Map
38
+
39
+ **Use this map to detect which plugin is needed based on user's request keywords:**
40
+
41
+ | User Keywords | Required Plugin | Installation Command |
42
+ |--------------|----------------|---------------------|
43
+ | **Documentation Preview** |
44
+ | "preview docs", "browse docs locally", "documentation UI", "Docusaurus server", "local docs preview" | `specweave-docs-preview` | `/plugin install specweave-docs-preview` |
45
+ | **Frontend Development** |
46
+ | "React", "Next.js", "Vue", "Angular", "frontend", "UI component", "design system", "Tailwind" | `specweave-frontend` | `/plugin install specweave-frontend` |
47
+ | **Kubernetes/DevOps** |
48
+ | "K8s", "Kubernetes", "Helm", "kubectl", "deploy", "container", "pod", "service", "ingress" | `specweave-kubernetes` | `/plugin install specweave-kubernetes` |
49
+ | **Machine Learning** |
50
+ | "TensorFlow", "PyTorch", "ML model", "training", "machine learning", "neural network", "dataset" | `specweave-ml` | `/plugin install specweave-ml` |
51
+ | **Payments** |
52
+ | "Stripe", "PayPal", "billing", "subscription", "payment", "checkout", "PCI compliance" | `specweave-payments` | `/plugin install specweave-payments` |
53
+ | **Testing** |
54
+ | "Playwright", "E2E testing", "browser automation", "visual regression", "test automation" | `specweave-testing` | `/plugin install specweave-testing` |
55
+ | **Figma/Design** |
56
+ | "Figma", "design tokens", "design system", "prototype", "wireframe", "mockup" | `specweave-figma` | `/plugin install specweave-figma` |
57
+ | **Backend Development** |
58
+ | "Node.js backend", "Python backend", ".NET", "Express", "FastAPI", "Django", "REST API" | `specweave-backend` | `/plugin install specweave-backend` |
59
+ | **Infrastructure** |
60
+ | "Hetzner", "cloud infrastructure", "Prometheus", "Grafana", "monitoring", "alerting", "SLO" | `specweave-infrastructure` | `/plugin install specweave-infrastructure` |
61
+ | **Architecture Diagrams** |
62
+ | "Mermaid diagram", "C4 model", "architecture diagram", "sequence diagram", "ER diagram" | `specweave-diagrams` | `/plugin install specweave-diagrams` |
63
+ | **Issue Trackers** (Usually auto-installed during init) |
64
+ | "GitHub Issues", "sync GitHub", "create issue", "PR automation" | `specweave-github` | `/plugin install specweave-github` |
65
+ | "Jira", "epic", "sprint", "story points", "Jira sync" | `specweave-jira` | `/plugin install specweave-jira` |
66
+ | "ADO", "Azure DevOps", "work items", "boards", "ADO sync" | `specweave-ado` | `/plugin install specweave-ado` |
67
+
68
+ ---
69
+
70
+ ## Workflow: Just-in-Time Plugin Installation
71
+
72
+ **CRITICAL**: Follow this workflow EVERY TIME you detect plugin keywords in user's request:
73
+
74
+ ### Step 1: Detect Plugin Requirement
75
+
76
+ When user mentions keywords from the map above, **IMMEDIATELY** check if the required plugin is needed.
77
+
78
+ **Example**:
79
+ ```
80
+ User: "Can you preview the internal docs locally?"
81
+
82
+ Keywords detected: "preview", "docs", "locally"
83
+ → Required plugin: specweave-docs-preview
84
+ ```
85
+
86
+ ### Step 2: Check if Plugin is Installed
87
+
88
+ ```bash
89
+ # Check installed plugins
90
+ /plugin list --installed
91
+ ```
92
+
93
+ **Parse the output** to see if the required plugin is in the list.
94
+
95
+ ### Step 3: Auto-Install if Missing
96
+
97
+ If the plugin is NOT installed:
98
+
99
+ ```bash
100
+ # Install the plugin
101
+ /plugin install <plugin-name>
102
+
103
+ # Example:
104
+ /plugin install specweave-docs-preview
105
+ ```
106
+
107
+ ### Step 4: Notify User (Clear and Friendly)
108
+
109
+ **Good notification format**:
110
+
111
+ ```
112
+ 🔌 Detected need for <plugin-name> plugin
113
+
114
+ 📦 Installing <plugin-name>...
115
+ This plugin provides: <brief description>
116
+
117
+ ✅ Plugin installed successfully!
118
+ You can now: <list capabilities>
119
+
120
+ Proceeding with your request...
121
+ ```
122
+
123
+ **Example**:
124
+
125
+ ```
126
+ 🔌 Detected need for specweave-docs-preview plugin
127
+
128
+ 📦 Installing specweave-docs-preview...
129
+ This plugin provides: Beautiful Docusaurus UI for browsing .specweave/docs/
130
+
131
+ ✅ Plugin installed successfully!
132
+ You can now:
133
+ • Browse documentation in beautiful UI
134
+ • Hot reload when editing markdown files
135
+ • Render Mermaid diagrams automatically
136
+
137
+ Proceeding to launch docs preview server...
138
+ ```
139
+
140
+ ### Step 5: Proceed with User's Request
141
+
142
+ **ONLY AFTER** the plugin is installed, proceed to use its features.
143
+
144
+ ---
145
+
146
+ ## Common Scenarios
147
+
148
+ ### Scenario 1: Documentation Preview
149
+
150
+ **User Request**: "Show me the internal docs in a nice UI"
151
+
152
+ **Workflow**:
153
+ ```
154
+ 1. Detect keywords: "docs", "UI"
155
+ → Required: specweave-docs-preview
156
+
157
+ 2. Check installed: /plugin list --installed
158
+ → Not found
159
+
160
+ 3. Install: /plugin install specweave-docs-preview
161
+
162
+ 4. Notify user:
163
+ 🔌 Installing specweave-docs-preview for beautiful docs UI...
164
+ ✅ Installed!
165
+
166
+ 5. Launch: /specweave:docs preview
167
+ ```
168
+
169
+ ### Scenario 2: Kubernetes Deployment
170
+
171
+ **User Request**: "Help me deploy this to Kubernetes"
172
+
173
+ **Workflow**:
174
+ ```
175
+ 1. Detect keywords: "deploy", "Kubernetes"
176
+ → Required: specweave-kubernetes
177
+
178
+ 2. Check installed: /plugin list --installed
179
+ → Not found
180
+
181
+ 3. Install: /plugin install specweave-kubernetes
182
+
183
+ 4. Notify user:
184
+ 🔌 Installing specweave-kubernetes for K8s deployment...
185
+ ✅ Installed! You can now generate manifests, Helm charts, and validate deployments.
186
+
187
+ 5. Proceed with K8s expert agent for deployment
188
+ ```
189
+
190
+ ### Scenario 3: React Component Development
191
+
192
+ **User Request**: "Create a new React component for user profile"
193
+
194
+ **Workflow**:
195
+ ```
196
+ 1. Detect keywords: "React", "component"
197
+ → Required: specweave-frontend
198
+
199
+ 2. Check installed: /plugin list --installed
200
+ → Not found
201
+
202
+ 3. Install: /plugin install specweave-frontend
203
+
204
+ 4. Notify user:
205
+ 🔌 Installing specweave-frontend for React development...
206
+ ✅ Installed! You can now use frontend expert agent and design system integration.
207
+
208
+ 5. Proceed with component creation
209
+ ```
210
+
211
+ ### Scenario 4: Machine Learning Pipeline
212
+
213
+ **User Request**: "Train a TensorFlow model for image classification"
214
+
215
+ **Workflow**:
216
+ ```
217
+ 1. Detect keywords: "TensorFlow", "model", "training"
218
+ → Required: specweave-ml
219
+
220
+ 2. Check installed: /plugin list --installed
221
+ → Not found
222
+
223
+ 3. Install: /plugin install specweave-ml
224
+
225
+ 4. Notify user:
226
+ 🔌 Installing specweave-ml for ML workflows...
227
+ ✅ Installed! You can now use ML expert agent for training pipelines and deployment.
228
+
229
+ 5. Proceed with ML pipeline setup
230
+ ```
231
+
232
+ ---
233
+
234
+ ## Error Handling
235
+
236
+ ### Plugin Installation Fails
237
+
238
+ If `/plugin install` fails:
239
+
240
+ ```
241
+ ❌ Failed to install <plugin-name>
242
+
243
+ Possible causes:
244
+ 1. Marketplace not registered
245
+ → Try: /plugin marketplace add anton-abyzov/specweave
246
+
247
+ 2. Network connectivity issues
248
+ → Check internet connection and retry
249
+
250
+ 3. Plugin doesn't exist
251
+ → Verify plugin name: /plugin list (shows all available plugins)
252
+
253
+ Would you like to:
254
+ a) Retry installation
255
+ b) Proceed without the plugin (limited capabilities)
256
+ c) Troubleshoot further
257
+ ```
258
+
259
+ ### Plugin Already Installed
260
+
261
+ If plugin is already installed, skip installation and proceed:
262
+
263
+ ```
264
+ ✅ <plugin-name> is already installed
265
+ Proceeding with your request...
266
+ ```
267
+
268
+ ---
269
+
270
+ ## Integration with Other Skills
271
+
272
+ **This skill should be consulted BEFORE other skills attempt to use plugin features.**
273
+
274
+ ### Example: increment-planner skill
275
+
276
+ When increment-planner detects plugin requirements (Step 6), it should:
277
+
278
+ 1. **Detect plugins** (as it already does)
279
+ 2. **Consult plugin-installer skill** (NEW!)
280
+ 3. **Auto-install missing plugins** (via this skill)
281
+ 4. **Then proceed** with increment planning
282
+
283
+ ### Example: docs-preview skill (hypothetical)
284
+
285
+ ```markdown
286
+ # BEFORE using Docusaurus features:
287
+
288
+ 1. Check if specweave-docs-preview is installed
289
+ → If not: Invoke plugin-installer skill
290
+ → Auto-install specweave-docs-preview
291
+
292
+ 2. Then launch Docusaurus server
293
+ ```
294
+
295
+ ---
296
+
297
+ ## Benefits of This Approach
298
+
299
+ ✅ **Zero friction**: Users don't need to manually install plugins
300
+ ✅ **Proactive**: Detects requirements automatically
301
+ ✅ **Clear UX**: Users see what's being installed and why
302
+ ✅ **Just-in-time**: Only installs plugins when actually needed
303
+ ✅ **Fail-safe**: Handles installation errors gracefully
304
+
305
+ ---
306
+
307
+ ## Testing This Skill
308
+
309
+ **Test Case 1: Docs Preview**
310
+ ```
311
+ User: "Show me the internal documentation in a browser"
312
+
313
+ Expected:
314
+ 1. Detects "documentation", "browser" → specweave-docs-preview
315
+ 2. Checks installed
316
+ 3. Auto-installs if missing
317
+ 4. Launches preview
318
+ ```
319
+
320
+ **Test Case 2: K8s Deployment**
321
+ ```
322
+ User: "Deploy this application to Kubernetes cluster"
323
+
324
+ Expected:
325
+ 1. Detects "Kubernetes" → specweave-kubernetes
326
+ 2. Checks installed
327
+ 3. Auto-installs if missing
328
+ 4. Proceeds with deployment
329
+ ```
330
+
331
+ **Test Case 3: React Development**
332
+ ```
333
+ User: "Add a React component for user settings"
334
+
335
+ Expected:
336
+ 1. Detects "React", "component" → specweave-frontend
337
+ 2. Checks installed
338
+ 3. Auto-installs if missing
339
+ 4. Proceeds with component creation
340
+ ```
341
+
342
+ ---
343
+
344
+ ## References
345
+
346
+ - **Plugin Expert Skill**: Consult for correct installation syntax
347
+ - **Official Docs**: https://code.claude.com/docs/en/plugins
348
+ - **SpecWeave Marketplace**: .claude-plugin/marketplace.json
349
+ - **CLAUDE.md**: Plugin architecture and detection phases
350
+
351
+ ---
352
+
353
+ **Key Principle**: ALWAYS install plugins BEFORE attempting to use their features. Never fail silently - always notify users of installation steps.
354
+
355
+ **Last Updated**: 2025-11-10 (v0.10.0)
@@ -23,6 +23,8 @@ context: |
23
23
  - API authentication and rate limiting
24
24
  - Error handling and retry strategies
25
25
 
26
+ **Default Behavior**: **Bidirectional sync** (two-way) - Synchronizes changes in both directions automatically
27
+
26
28
  ---
27
29
 
28
30
  ## 🚨 CRITICAL: Concept Mapping (MANDATORY)
@@ -1,49 +1,142 @@
1
1
  ---
2
2
  name: specweave-ado:sync
3
- description: Sync SpecWeave increment progress with Azure DevOps work item
3
+ description: Bidirectional sync between SpecWeave increment and Azure DevOps work item (two-way sync by default)
4
4
  ---
5
5
 
6
6
  # Sync ADO Work Item Command
7
7
 
8
- **Usage**: `/specweave-ado:sync <increment-id>`
8
+ **Usage**: `/specweave-ado:sync <increment-id> [options]`
9
9
 
10
- **Purpose**: Update ADO work item with current increment progress
10
+ **Purpose**: Bidirectional synchronization between SpecWeave increment and Azure DevOps work item
11
+
12
+ **Default**: Two-way sync (bidirectional)
11
13
 
12
14
  ---
13
15
 
14
- ## Command Behavior
16
+ ## Options
17
+
18
+ - `--direction <mode>`: Sync direction (default: `bidirectional`)
19
+ - `bidirectional`: SpecWeave ↔ ADO (default - recommended)
20
+ - `to-ado`: SpecWeave → ADO only (push progress)
21
+ - `from-ado`: ADO → SpecWeave only (pull updates)
22
+
23
+ ## Examples
24
+
25
+ ```bash
26
+ # Bidirectional sync (default - two-way)
27
+ /specweave-ado:sync 0005
28
+
29
+ # Push only (one-way to ADO)
30
+ /specweave-ado:sync 0005 --direction to-ado
31
+
32
+ # Pull only (one-way from ADO)
33
+ /specweave-ado:sync 0005 --direction from-ado
34
+ ```
35
+
36
+ ---
15
37
 
16
- When user runs this command, invoke `ado-manager` agent to:
38
+ ## Command Behavior
17
39
 
40
+ When user runs this command, invoke `ado-manager` agent to perform bidirectional sync:
41
+
42
+ ### Phase 1: Pull FROM ADO (default behavior)
43
+ 1. Fetch work item state from ADO API
44
+ 2. Detect changes in ADO:
45
+ - State changes (New → Active → Resolved → Closed)
46
+ - Priority changes
47
+ - Iteration/sprint changes
48
+ - Comments from team members
49
+ - Field updates
50
+ 3. Apply ADO changes to SpecWeave increment:
51
+ - Update increment status to match ADO state
52
+ - Update priority in metadata
53
+ - Import team comments to increment notes
54
+ - Update iteration tracking
55
+
56
+ ### Phase 2: Push TO ADO (default behavior)
18
57
  1. Read tasks.md from increment
19
58
  2. Calculate completion percentage
20
59
  3. Identify recently completed tasks
21
60
  4. Format progress update comment
22
61
  5. POST comment to ADO work item
23
62
  6. Update work item state if needed (New → Active → Resolved)
63
+ 7. Update custom fields (completion %, current task, etc.)
24
64
 
25
65
  **Agent Invocation**:
26
66
  ```
27
67
  Use Task tool with subagent_type: "ado-manager"
28
68
 
29
- Prompt: "Sync progress for increment 0005-payment-integration to ADO.
69
+ Prompt: "Bidirectional sync for increment 0005-payment-integration with ADO.
30
70
 
31
- Steps:
71
+ Phase 1 - Pull FROM ADO:
72
+ 1. Fetch work item #12345 from ADO API
73
+ 2. Detect changes: state, priority, iteration, comments
74
+ 3. Apply ADO changes to increment metadata
75
+ 4. Import team comments to increment notes
76
+
77
+ Phase 2 - Push TO ADO:
32
78
  1. Read .specweave/increments/0005/tasks.md
33
79
  2. Calculate: X/Y tasks complete (Z%)
34
80
  3. Identify: Recently completed tasks
35
81
  4. Format comment with progress update
36
82
  5. Load work item ID from increment-metadata.json
37
83
  6. POST comment to ADO API
38
- 7. Display: Sync confirmation"
84
+ 7. Update work item state/fields
85
+
86
+ Display: Bidirectional sync summary"
39
87
  ```
40
88
 
41
89
  ---
42
90
 
43
91
  ## Example Output
44
92
 
93
+ ### Bidirectional Sync (Default)
94
+
95
+ ```
96
+ 🔄 Bidirectional sync for increment 0005...
97
+
98
+ ✓ Azure DevOps work item: #12345
99
+ ✓ Sync direction: bidirectional (two-way)
100
+
101
+ Detecting changes (both directions)...
102
+
103
+ FROM ADO:
104
+ ✓ Work item state changed: Active → Resolved
105
+ ✓ Iteration updated: Sprint 23 → Sprint 24
106
+ ✓ Priority changed: 2 → 1
107
+ ✓ 3 new comments from team
108
+
109
+ FROM SpecWeave:
110
+ ✓ 2 new tasks completed (T-005, T-006)
111
+ ✓ Progress: 40% → 60% (6/10 tasks)
112
+ ✓ Current task: T-007
113
+
114
+ Syncing TO ADO...
115
+ ✓ Posted progress comment (ID: 98765)
116
+ ✓ Updated completion: 60%
117
+ ✓ Updated current task field: T-007
118
+
119
+ Syncing FROM ADO...
120
+ ✓ Updated increment status: active → completed
121
+ ✓ Updated priority: P2 → P1
122
+ ✓ Updated iteration tracking: Sprint 24
123
+ ✓ Imported 3 team comments to increment notes
124
+
125
+ ✅ Bidirectional Sync Complete!
126
+
127
+ SpecWeave ↔ ADO synchronized
128
+ • Pushed: Progress (60%), 2 task updates
129
+ • Pulled: State (Resolved), priority (P1), iteration, 3 comments
130
+
131
+ ADO Work Item: https://dev.azure.com/myorg/MyProject/_workitems/edit/12345
132
+ Last synced: just now
133
+ Next sync: Automatic (hook-based) or manual when ready
134
+ ```
135
+
136
+ ### One-Way Sync (to-ado)
137
+
45
138
  ```
46
- Synced to ADO Epic #12345
139
+ Pushed to ADO Work Item #12345
47
140
 
48
141
  Progress: 60% complete (6/10 tasks)
49
142