@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.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 (152) hide show
  1. package/README.md +94 -20
  2. package/dist/index.d.ts +3 -3
  3. package/dist/index.d.ts.map +1 -1
  4. package/dist/index.js +2 -2
  5. package/dist/index.js.map +1 -1
  6. package/dist/install.d.ts +89 -0
  7. package/dist/install.d.ts.map +1 -1
  8. package/dist/install.js +219 -18
  9. package/dist/install.js.map +1 -1
  10. package/dist/validate/index.d.ts +21 -0
  11. package/dist/validate/index.d.ts.map +1 -1
  12. package/dist/validate/index.js +77 -0
  13. package/dist/validate/index.js.map +1 -1
  14. package/extensions/cmux/.agents/plugin.json +37 -0
  15. package/extensions/cmux/skills/cmux/SKILL.md +82 -0
  16. package/extensions/cmux/skills/cmux/agents/openai.yaml +4 -0
  17. package/extensions/cmux/skills/cmux/references/handles-and-identify.md +35 -0
  18. package/extensions/cmux/skills/cmux/references/panes-surfaces.md +37 -0
  19. package/extensions/cmux/skills/cmux/references/trigger-flash-and-health.md +23 -0
  20. package/extensions/cmux/skills/cmux/references/windows-workspaces.md +31 -0
  21. package/extensions/cmux/skills/cmux-vm-monitor/SKILL.md +122 -0
  22. package/extensions/cmux/skills/cmux-vm-monitor/agents/openai.yaml +4 -0
  23. package/extensions/cmux/skills/cmux-vm-monitor/references/cmux-commands.md +66 -0
  24. package/extensions/cmux/skills/cmux-vm-monitor/scripts/codex_vm_monitor.sh +45 -0
  25. package/extensions/cmux/skills/cmux-workspace/SKILL.md +93 -0
  26. package/extensions/dev-state/.agents/plugin.json +35 -0
  27. package/extensions/dev-state/skills/dev-state-plan-graduation/SKILL.md +194 -0
  28. package/extensions/dev-state/skills/dev-state-plan-graduation/agents/openai.yaml +4 -0
  29. package/extensions/dev-state/skills/dev-state-plan-graduation/references/reference.md +130 -0
  30. package/extensions/devops/.agents/plugin.json +36 -0
  31. package/extensions/devops/skills/azure-devops-cli/SKILL.md +431 -0
  32. package/extensions/devops/skills/azure-devops-cli/agents/openai.yaml +4 -0
  33. package/extensions/devops/skills/ci-pipeline-strategy/SKILL.md +217 -0
  34. package/extensions/devops/skills/ci-pipeline-strategy/agents/openai.yaml +4 -0
  35. package/{plugins/net-revenue-management/.codex-plugin → extensions/net-revenue-management/.agents}/plugin.json +10 -6
  36. package/extensions/plugin-dev/.agents/plugin.json +42 -0
  37. package/extensions/plugin-dev/.mcp.json +3 -0
  38. package/extensions/plugin-dev/agents/agent-creator.md +199 -0
  39. package/extensions/plugin-dev/agents/plugin-validator.md +91 -0
  40. package/extensions/plugin-dev/agents/skill-reviewer.md +212 -0
  41. package/extensions/plugin-dev/commands/_archive/create-marketplace.md +427 -0
  42. package/extensions/plugin-dev/commands/_archive/plugin-dev-guide.md +12 -0
  43. package/extensions/plugin-dev/commands/create-plugin.md +498 -0
  44. package/extensions/plugin-dev/commands/start.md +81 -0
  45. package/extensions/plugin-dev/hooks/hooks.json +3 -0
  46. package/extensions/plugin-dev/skills/agent-development/SKILL.md +641 -0
  47. package/extensions/plugin-dev/skills/agent-development/examples/agent-creation-prompt.md +250 -0
  48. package/extensions/plugin-dev/skills/agent-development/examples/complete-agent-examples.md +461 -0
  49. package/extensions/plugin-dev/skills/agent-development/references/advanced-agent-fields.md +246 -0
  50. package/extensions/plugin-dev/skills/agent-development/references/agent-creation-system-prompt.md +216 -0
  51. package/extensions/plugin-dev/skills/agent-development/references/permission-modes-rules.md +226 -0
  52. package/extensions/plugin-dev/skills/agent-development/references/system-prompt-design.md +464 -0
  53. package/extensions/plugin-dev/skills/agent-development/references/triggering-examples.md +474 -0
  54. package/extensions/plugin-dev/skills/agent-development/scripts/create-agent-skeleton.sh +176 -0
  55. package/extensions/plugin-dev/skills/agent-development/scripts/test-agent-trigger.sh +227 -0
  56. package/extensions/plugin-dev/skills/agent-development/scripts/validate-agent.sh +227 -0
  57. package/extensions/plugin-dev/skills/command-development/SKILL.md +763 -0
  58. package/extensions/plugin-dev/skills/command-development/examples/plugin-commands.md +612 -0
  59. package/extensions/plugin-dev/skills/command-development/examples/simple-commands.md +527 -0
  60. package/extensions/plugin-dev/skills/command-development/references/advanced-workflows.md +762 -0
  61. package/extensions/plugin-dev/skills/command-development/references/documentation-patterns.md +769 -0
  62. package/extensions/plugin-dev/skills/command-development/references/frontmatter-reference.md +508 -0
  63. package/extensions/plugin-dev/skills/command-development/references/interactive-commands.md +966 -0
  64. package/extensions/plugin-dev/skills/command-development/references/marketplace-considerations.md +943 -0
  65. package/extensions/plugin-dev/skills/command-development/references/plugin-features-reference.md +637 -0
  66. package/extensions/plugin-dev/skills/command-development/references/plugin-integration.md +191 -0
  67. package/extensions/plugin-dev/skills/command-development/references/skill-tool.md +447 -0
  68. package/extensions/plugin-dev/skills/command-development/references/testing-strategies.md +723 -0
  69. package/extensions/plugin-dev/skills/command-development/scripts/check-frontmatter.sh +234 -0
  70. package/extensions/plugin-dev/skills/command-development/scripts/validate-command.sh +160 -0
  71. package/extensions/plugin-dev/skills/hook-development/SKILL.md +861 -0
  72. package/extensions/plugin-dev/skills/hook-development/examples/load-context.sh +55 -0
  73. package/extensions/plugin-dev/skills/hook-development/examples/validate-bash.sh +57 -0
  74. package/extensions/plugin-dev/skills/hook-development/examples/validate-write.sh +48 -0
  75. package/extensions/plugin-dev/skills/hook-development/references/advanced.md +871 -0
  76. package/extensions/plugin-dev/skills/hook-development/references/hook-input-schemas.md +145 -0
  77. package/extensions/plugin-dev/skills/hook-development/references/migration.md +392 -0
  78. package/extensions/plugin-dev/skills/hook-development/references/patterns.md +430 -0
  79. package/extensions/plugin-dev/skills/hook-development/scripts/README.md +181 -0
  80. package/extensions/plugin-dev/skills/hook-development/scripts/hook-linter.sh +153 -0
  81. package/extensions/plugin-dev/skills/hook-development/scripts/test-hook.sh +276 -0
  82. package/extensions/plugin-dev/skills/hook-development/scripts/validate-hook-schema.sh +159 -0
  83. package/extensions/plugin-dev/skills/mcp-integration/SKILL.md +775 -0
  84. package/extensions/plugin-dev/skills/mcp-integration/examples/http-server.json +20 -0
  85. package/extensions/plugin-dev/skills/mcp-integration/examples/sse-server.json +19 -0
  86. package/extensions/plugin-dev/skills/mcp-integration/examples/stdio-server.json +38 -0
  87. package/extensions/plugin-dev/skills/mcp-integration/examples/ws-server.json +26 -0
  88. package/extensions/plugin-dev/skills/mcp-integration/references/authentication.md +601 -0
  89. package/extensions/plugin-dev/skills/mcp-integration/references/server-discovery.md +190 -0
  90. package/extensions/plugin-dev/skills/mcp-integration/references/server-types.md +572 -0
  91. package/extensions/plugin-dev/skills/mcp-integration/references/tool-usage.md +623 -0
  92. package/extensions/plugin-dev/skills/plugin-dev-guide/SKILL.md +222 -0
  93. package/extensions/plugin-dev/skills/plugin-structure/SKILL.md +705 -0
  94. package/extensions/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md +774 -0
  95. package/extensions/plugin-dev/skills/plugin-structure/examples/minimal-plugin.md +83 -0
  96. package/extensions/plugin-dev/skills/plugin-structure/examples/standard-plugin.md +611 -0
  97. package/extensions/plugin-dev/skills/plugin-structure/references/advanced-topics.md +289 -0
  98. package/extensions/plugin-dev/skills/plugin-structure/references/component-patterns.md +592 -0
  99. package/extensions/plugin-dev/skills/plugin-structure/references/github-actions.md +233 -0
  100. package/extensions/plugin-dev/skills/plugin-structure/references/headless-ci-mode.md +193 -0
  101. package/extensions/plugin-dev/skills/plugin-structure/references/manifest-reference.md +625 -0
  102. package/extensions/plugin-dev/skills/plugin-structure/references/output-styles.md +116 -0
  103. package/extensions/plugin-dev/skills/skill-development/SKILL.md +564 -0
  104. package/extensions/plugin-dev/skills/skill-development/examples/complete-skill.md +465 -0
  105. package/extensions/plugin-dev/skills/skill-development/examples/frontmatter-templates.md +167 -0
  106. package/extensions/plugin-dev/skills/skill-development/examples/minimal-skill.md +111 -0
  107. package/extensions/plugin-dev/skills/skill-development/references/advanced-frontmatter.md +225 -0
  108. package/extensions/plugin-dev/skills/skill-development/references/commands-vs-skills.md +39 -0
  109. package/extensions/plugin-dev/skills/skill-development/references/skill-creation-workflow.md +379 -0
  110. package/extensions/plugin-dev/skills/skill-development/references/skill-creator-original.md +210 -0
  111. package/package.json +8 -11
  112. package/scripts/enact-extensions.mjs +751 -16
  113. package/scripts/hooks/session-start-drift-check.mjs +58 -0
  114. package/scripts/lib/build-index.mjs +50 -0
  115. package/scripts/lib/bundle-hash.mjs +137 -0
  116. package/scripts/lib/hooks.mjs +389 -0
  117. package/scripts/lib/ledger.mjs +162 -0
  118. package/scripts/lib/list-bundles.mjs +70 -0
  119. package/scripts/lib/outdated.mjs +144 -0
  120. package/scripts/lib/provision-mcp.mjs +369 -0
  121. package/scripts/lib/resolve-bundle.mjs +121 -0
  122. package/scripts/lib/run-install.mjs +321 -39
  123. package/scripts/lib/run-uninstall.mjs +220 -0
  124. package/scripts/lib/run-update.mjs +152 -0
  125. package/scripts/lib/run-validate.mjs +12 -18
  126. package/scripts/lib/serve.mjs +454 -0
  127. package/scripts/postinstall.mjs +63 -0
  128. package/scripts/setup-enact-context.sh +2 -2
  129. package/spec/index.json +59 -0
  130. package/web/assets/README.md +111 -0
  131. package/web/assets/logo-full.png +0 -0
  132. package/web/assets/logo-slim.png +0 -0
  133. package/web/assets/tokens/base.css +45 -0
  134. package/web/assets/tokens/colors.css +248 -0
  135. package/web/assets/tokens/effects.css +24 -0
  136. package/web/assets/tokens/fonts.css +8 -0
  137. package/web/assets/tokens/index.css +18 -0
  138. package/web/assets/tokens/spacing.css +50 -0
  139. package/web/index.html +1188 -0
  140. package/.agents/plugins/marketplace.json +0 -20
  141. package/catalog/enact-context.json +0 -9
  142. package/catalog/enact-factory.json +0 -7
  143. package/catalog/enact-operator.json +0 -7
  144. package/catalog/enact-wiki.json +0 -7
  145. package/catalog/net-revenue-management.json +0 -8
  146. package/scripts/rename-supervisor-to-operator.pl +0 -66
  147. package/scripts/sync-manifests.mjs +0 -23
  148. package/scripts/validate-catalog.mjs +0 -37
  149. package/scripts/validate-plugin.mjs +0 -10
  150. /package/{plugins → extensions}/net-revenue-management/.mcp.json +0 -0
  151. /package/{plugins → extensions}/net-revenue-management/skills/net-revenue-risks/SKILL.md +0 -0
  152. /package/{plugins → extensions}/net-revenue-management/skills/net-revenue-scenario/SKILL.md +0 -0
@@ -0,0 +1,431 @@
1
+ ---
2
+ name: azure-devops-cli
3
+ description: Manage Azure DevOps resources using the az CLI with the azure-devops extension. Covers repositories, pull requests, pipelines, boards, and work items.
4
+ ---
5
+
6
+ # Azure DevOps CLI
7
+
8
+ ## Overview
9
+
10
+ Manage Azure DevOps resources using the `az` CLI with the `azure-devops` extension. Covers repositories, pull requests, pipelines, boards, and work items.
11
+
12
+ ## Prerequisites
13
+
14
+ ```bash
15
+ # Install azure-devops extension (requires az cli 2.30+)
16
+ az extension add --name azure-devops
17
+
18
+ # Authenticate
19
+ az login
20
+
21
+ # Set defaults (recommended)
22
+ az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
23
+ ```
24
+
25
+ ## Most-Used Commands
26
+
27
+ ### My Pull Requests
28
+
29
+ ```bash
30
+ # List PRs I created
31
+ az repos pr list --creator "$(az account show --query user.name -o tsv)"
32
+
33
+ # List PRs assigned to me for review
34
+ az repos pr list --reviewer "$(az account show --query user.name -o tsv)"
35
+
36
+ # Show PR details
37
+ az repos pr show --id <pr-id>
38
+
39
+ # Checkout PR locally
40
+ az repos pr checkout --id <pr-id>
41
+ ```
42
+
43
+ ### My Work Items
44
+
45
+ ```bash
46
+ # List work items assigned to me
47
+ az boards query --wiql "SELECT [System.Id], [System.Title], [System.State] FROM WorkItems WHERE [System.AssignedTo] = @Me AND [System.State] <> 'Closed' ORDER BY [System.ChangedDate] DESC"
48
+
49
+ # Show work item details
50
+ az boards work-item show --id <work-item-id>
51
+
52
+ # Create work item
53
+ az boards work-item create --title "Task title" --type "Task"
54
+
55
+ # Update work item state
56
+ az boards work-item update --id <id> --state "In Progress"
57
+ ```
58
+
59
+ ### Pipelines
60
+
61
+ ```bash
62
+ # List pipelines
63
+ az pipelines list
64
+
65
+ # List recent runs
66
+ az pipelines runs list --top 10
67
+
68
+ # Show run details (result, status, logs URL)
69
+ az pipelines runs show --id <run-id>
70
+ ```
71
+
72
+ > **⛔ NEVER use `az pipelines run` to manually trigger a CI run as a substitute
73
+ > for a PR push.** Manual runs do not update PR build status and give false
74
+ > confidence. If CI is not triggering on a PR, push a new commit to the source
75
+ > branch instead — even an empty one:
76
+ >
77
+ > ```bash
78
+ > git commit --allow-empty -m "ci: re-trigger pipeline"
79
+ > git push
80
+ > ```
81
+ >
82
+ > The only permitted use of `az pipelines run` is a deliberate Publish-stage
83
+ > retag/hotfix on `main`, performed explicitly by the repo owner.
84
+
85
+ ### Reading Build Failure Output
86
+
87
+ AzDO pipeline logs expire quickly (timeline returns HTTP 204 after ~24h). Get them while the run is fresh.
88
+
89
+ ```bash
90
+ # Get failure summary from the build timeline (works while logs are live)
91
+ TOKEN=$(az account get-access-token \
92
+ --resource 499b84ac-1321-427f-aa17-267ca6975798 \
93
+ --query accessToken -o tsv)
94
+
95
+ curl -s -H "Authorization: Bearer $TOKEN" \
96
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/build/builds/<buildId>/timeline?api-version=7.1" \
97
+ | python3 -c "
98
+ import sys, json
99
+ d = json.load(sys.stdin)
100
+ failed = [r for r in d.get('records', [])
101
+ if r.get('result') == 'failed' and r.get('type') in ('Task','Job','Stage')]
102
+ for r in sorted(failed, key=lambda x: x.get('order', 0)):
103
+ print(r.get('type'), '|', r.get('name'))
104
+ for i in (r.get('issues') or [])[:3]:
105
+ print(' !', i.get('message', '')[:300])
106
+ "
107
+
108
+ # Get the logs container URL from a run (use this to build the logs URL)
109
+ az pipelines runs show --id <run-id> --output json \
110
+ | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['logs']['url'])"
111
+
112
+ # Fetch specific log entry (replace <logId> with an entry ID from the logs index)
113
+ curl -s -H "Authorization: Bearer $TOKEN" \
114
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/build/builds/<buildId>/logs/<logId>?api-version=7.1"
115
+ ```
116
+
117
+ **Important:** `az rest` does NOT work for AzDO URLs — it cannot derive the right AAD scope.
118
+ Use `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798` + `curl` instead.
119
+ Timeline returns HTTP 204 (empty) once logs have expired — check the AzDO web UI in that case.
120
+
121
+ ### Authorizing Variable Groups for Pipelines
122
+
123
+ First-time pipelines using a variable group require authorization. Check and fix via REST:
124
+
125
+ ```bash
126
+ TOKEN=$(az account get-access-token \
127
+ --resource 499b84ac-1321-427f-aa17-267ca6975798 \
128
+ --query accessToken -o tsv)
129
+
130
+ # Get variable group ID
131
+ az pipelines variable-group list --output table
132
+
133
+ # Authorize the group for specific pipelines (replace groupId and pipeline IDs)
134
+ curl -s -X PATCH \
135
+ -H "Authorization: Bearer $TOKEN" \
136
+ -H "Content-Type: application/json" \
137
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/pipelines/pipelinePermissions/variablegroup/<groupId>?api-version=7.1-preview.1" \
138
+ -d '{"pipelines": [{"id": 9, "authorized": true}, {"id": 10, "authorized": true}]}'
139
+
140
+ # Or authorize for ALL pipelines in the project at once:
141
+ curl -s -X PATCH \
142
+ -H "Authorization: Bearer $TOKEN" \
143
+ -H "Content-Type: application/json" \
144
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/pipelines/pipelinePermissions/variablegroup/<groupId>?api-version=7.1-preview.1" \
145
+ -d '{"allPipelines": {"authorized": true}}'
146
+ ```
147
+
148
+ ### Diagnosing Why CI Did Not Trigger on a PR
149
+
150
+ CI should trigger automatically when commits are pushed to a PR source branch. If it
151
+ does not, do NOT manually queue a run. Instead:
152
+
153
+ 1. **Push a new commit** (even empty) to the source branch:
154
+ ```bash
155
+ git commit --allow-empty -m "ci: re-trigger pipeline"
156
+ git push
157
+ ```
158
+ 2. Check the PR's **build validation policy** is enabled (pipeline must be registered
159
+ and the policy must reference the correct pipeline ID).
160
+ 3. Check the PR is open and targeting `integration`. Closed or draft PRs do not
161
+ trigger CI.
162
+
163
+ Manual re-queueing (`az pipelines run`) is **only** for deliberate Publish-stage retags
164
+ on `main` performed by the repo owner. For bootstrap PRs introducing `azure-pipelines.yml`
165
+ for the first time, use `git push --force-with-lease` to force a new push event.
166
+
167
+ ### Enforcing Merge Strategy on a Branch
168
+
169
+ > **Do NOT use `az repos policy merge-strategy create`** — it is an extension command and emits `WARNING: This command is from the following extension: azure-devops`. Use the REST API directly via Bearer token + curl instead (shown below). No warnings, no extension dependency.
170
+
171
+ All enact-os repos enforce merge strategy via AzDO branch policies (policy type `fa4e907d-c16b-4a4c-9dfa-4916e5d171ab`).
172
+
173
+ **integration — squash only** (1 clean commit per PR, linear history):
174
+
175
+ ```bash
176
+ TOKEN=$(az account get-access-token \
177
+ --resource 499b84ac-1321-427f-aa17-267ca6975798 \
178
+ --query accessToken -o tsv)
179
+
180
+ curl -s -X POST \
181
+ -H "Authorization: Bearer $TOKEN" \
182
+ -H "Content-Type: application/json" \
183
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/policy/configurations?api-version=7.1" \
184
+ -d '{
185
+ "isEnabled": true, "isBlocking": true,
186
+ "type": {"id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"},
187
+ "settings": {
188
+ "allowSquash": true,
189
+ "allowNoFastForward": false,
190
+ "allowRebase": false,
191
+ "allowRebaseMerge": false,
192
+ "scope": [{"repositoryId": "<repo-id>", "refName": "refs/heads/integration", "matchKind": "exact"}]
193
+ }
194
+ }'
195
+ ```
196
+
197
+ **main — basic merge or fast-forward, no squash** (preserves full integration history on promotion):
198
+
199
+ ```bash
200
+ # If no existing policy: POST (same URL as above, change settings)
201
+ # If existing policy exists, use PUT to update:
202
+ curl -s -X PUT \
203
+ -H "Authorization: Bearer $TOKEN" \
204
+ -H "Content-Type: application/json" \
205
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/policy/configurations/<policy-id>?api-version=7.1" \
206
+ -d '{
207
+ "isEnabled": true, "isBlocking": true,
208
+ "type": {"id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"},
209
+ "settings": {
210
+ "allowSquash": false,
211
+ "allowNoFastForward": true,
212
+ "allowRebase": true,
213
+ "allowRebaseMerge": false,
214
+ "scope": [{"repositoryId": "<repo-id>", "refName": "refs/heads/main", "matchKind": "exact"}]
215
+ }
216
+ }'
217
+ ```
218
+
219
+ **Note:** POST fails with "rejected by policy" if a merge strategy policy already exists on that branch — use PUT with the existing policy ID instead. Find existing IDs:
220
+
221
+ ```bash
222
+ curl -s -H "Authorization: Bearer $TOKEN" \
223
+ "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/policy/configurations?api-version=7.1" \
224
+ | python3 -c "
225
+ import sys,json
226
+ MERGE_TYPE='fa4e907d-c16b-4a4c-9dfa-4916e5d171ab'
227
+ for p in json.load(sys.stdin).get('value',[]):
228
+ if p.get('type',{}).get('id') == MERGE_TYPE:
229
+ for s in p['settings'].get('scope',[]):
230
+ print(p['id'], s.get('repositoryId'), s.get('refName'))
231
+ "
232
+ ```
233
+
234
+ ### Auto-delete Source Branch
235
+
236
+ AzDO has no repo-level policy to force-delete branches on merge. Enforce at PR creation:
237
+
238
+ ```bash
239
+ # Always include both flags — never omit --delete-source-branch
240
+ az repos pr create \
241
+ --source-branch feat/my-branch \
242
+ --target-branch integration \
243
+ --title "feat: description" \
244
+ --auto-complete true \
245
+ --delete-source-branch true \
246
+ --detect
247
+ ```
248
+
249
+ ### First-Run Checklist (new pipeline bootstrap)
250
+
251
+ Before triggering a new pipeline for the first time:
252
+
253
+ 1. **Validate YAML locally:** `python3 -c "import yaml; yaml.safe_load(open('azure-pipelines.yml')); print('OK')"`
254
+ 2. **Check tool versions exist:** For Zig, verify at `https://ziglang.org/download/<version>/zig-linux-x86_64-<version>.tar.xz` (curl -sI, expect 200)
255
+ 3. **Variable group authorized:** Run `az pipelines variable-group list` to get group ID, then use the authorization API above
256
+ 4. **Multi-checkout repos accessible:** If `resources: repositories` is used, confirm service connection has read access to each sibling repo
257
+
258
+ ### Repositories
259
+
260
+ ```bash
261
+ # List repositories
262
+ az repos list
263
+
264
+ # Show repo details
265
+ az repos show --repository <repo-name>
266
+
267
+ # Create repository
268
+ az repos create --name "new-repo"
269
+ ```
270
+
271
+ ### Pull Request Workflow
272
+
273
+ ```bash
274
+ # Before starting any new task, sync local integration and branch from it
275
+ git checkout integration
276
+ git pull --ff-only origin integration
277
+ git checkout -b feat/my-branch # or fix/my-branch
278
+
279
+ # Create PR to integration — always use auto-complete + delete-source-branch
280
+ az repos pr create \
281
+ --source-branch feat/my-branch \
282
+ --target-branch integration \
283
+ --title "feat: description" \
284
+ --auto-complete true \
285
+ --delete-source-branch true \
286
+ --detect
287
+ # CI passes → PR auto-merges. No reviewer required on integration.
288
+
289
+ # Promotion PR to main (integration→main) — create or update automatically,
290
+ # but merge remains manual. Never auto-complete the main PR.
291
+ az repos pr create \
292
+ --source-branch integration \
293
+ --target-branch main \
294
+ --title "release: promote integration → main" \
295
+ --detect
296
+ # NO --auto-complete ← never on main PRs
297
+ # NO --delete-source-branch ← integration is permanent
298
+
299
+ # Enable auto-complete on an existing PR
300
+ az repos pr update --id <pr-id> --auto-complete true --delete-source-branch true --org https://dev.azure.com/amsterdamdatalabs
301
+
302
+ # Add reviewers (for main PRs)
303
+ az repos pr update --id <pr-id> --reviewers user@email.com
304
+
305
+ # Set vote (approve: 10, approve with suggestions: 5, wait: -5, reject: -10)
306
+ az repos pr set-vote --id <pr-id> --vote 10
307
+
308
+ # Complete/merge PR manually
309
+ az repos pr update --id <pr-id> --status completed
310
+ ```
311
+
312
+ ## enact-os Specific
313
+
314
+ ### Set org/project defaults (once per machine)
315
+
316
+ ```bash
317
+ az devops configure --defaults \
318
+ organization=https://dev.azure.com/amsterdamdatalabs \
319
+ project=Enact
320
+ ```
321
+
322
+ After this, `--org` and `--project` can be omitted from all commands.
323
+
324
+ ### Register a pipeline
325
+
326
+ ```bash
327
+ # Run from inside the repo directory — --detect infers org/project/repo
328
+ az pipelines create \
329
+ --name "<package-name> CI" \
330
+ --repository <repo-name> \
331
+ --repository-type tfsgit \
332
+ --branch <default-branch> \
333
+ --yml-path azure-pipelines.yml \
334
+ --skip-first-run \
335
+ --detect
336
+ ```
337
+
338
+ ### Create a blocking build-validation policy
339
+
340
+ ```bash
341
+ az repos policy build create \
342
+ --repository-id <repo-id> \
343
+ --branch integration \
344
+ --build-definition-id <pipeline-id> \
345
+ --queue-on-source-update-only false \
346
+ --manual-queue-only false \
347
+ --valid-duration 0 \
348
+ --blocking true \
349
+ --enabled true \
350
+ --display-name "CI must pass before merge" \
351
+ --detect
352
+ ```
353
+
354
+ Get `--repository-id` via `az repos show --repository <repo-name> --query id -o tsv --detect`.
355
+
356
+ ### List / delete a policy
357
+
358
+ ```bash
359
+ # List policies for a repo
360
+ az repos policy list --repository-id <repo-id> --detect -o table
361
+
362
+ # Delete a policy (use when correcting a policy on the wrong branch)
363
+ az repos policy delete --id <policy-id> --detect
364
+ ```
365
+
366
+ ### Pipeline and policy registry (enact-os)
367
+
368
+ See `../ci-pipeline-strategy/SKILL.md` for the full table of pipeline IDs, policy IDs, and gate branches across all 10 packages.
369
+
370
+ ## Common Flags
371
+
372
+ Most commands support:
373
+
374
+ | Flag | Description |
375
+ | ------------------- | --------------------------------------------------- |
376
+ | `--org` | Organization URL (or set via `az devops configure`) |
377
+ | `--project` | Project name (or set via `az devops configure`) |
378
+ | `--detect` | Auto-detect org/project from git remote |
379
+ | `-o json/table/tsv` | Output format |
380
+
381
+ ## Troubleshooting
382
+
383
+ ```bash
384
+ # Check current config
385
+ az devops configure --list
386
+
387
+ # Verify authentication
388
+ az account show
389
+
390
+ # Check extension version
391
+ az extension show --name azure-devops
392
+ ```
393
+
394
+ ### Extension fails with `No module named 'msrestazure'`
395
+
396
+ The `azure-devops` extension depends on `msrestazure`, which is not bundled in newer Homebrew `azure-cli` installs. Fix by installing it into az's own Python:
397
+
398
+ ```bash
399
+ # Find az's Python
400
+ az --version 2>&1 | grep "Python location"
401
+ # e.g. Python location '/opt/homebrew/Cellar/azure-cli/2.76.0/libexec/bin/python'
402
+
403
+ # Install into that Python
404
+ /opt/homebrew/Cellar/azure-cli/<version>/libexec/bin/python -m pip install msrestazure
405
+
406
+ # If the extension directory is corrupt, remove and reinstall
407
+ rm -rf ~/.azure/cliextensions/azure-devops
408
+ az extension add --name azure-devops
409
+ ```
410
+
411
+ ### PR commands live under `az repos`, not `az devops`
412
+
413
+ ```bash
414
+ # WRONG — 'pr' is not a subcommand of az devops
415
+ az devops pr create ...
416
+
417
+ # CORRECT
418
+ az repos pr create --source-branch feature/x --target-branch integration --detect
419
+ ```
420
+
421
+ `--detect` auto-infers org and project from the git remote — no need to set defaults explicitly when inside a repo directory.
422
+
423
+ ### Set org/project defaults once per machine
424
+
425
+ ```bash
426
+ az devops configure --defaults \
427
+ organization=https://dev.azure.com/amsterdamdatalabs \
428
+ project=Enact
429
+ ```
430
+
431
+ After this, `--org` and `--project` flags can be omitted from all commands.
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "Azure DevOps CLI"
3
+ short_description: "Use az CLI and REST patterns for PRs, work items, pipelines, and branch policies."
4
+ default_prompt: "Use this skill to manage Azure DevOps with az CLI plus REST fallbacks for pipelines, policies, PRs, work items, and CI diagnostics."
@@ -0,0 +1,217 @@
1
+ ---
2
+ name: ci-pipeline-strategy
3
+ description: >-
4
+ Documents the enact-os CI/CD branching strategy and pipeline conventions.
5
+ Use when working on Azure Pipelines, branch triggers, publish gates, or
6
+ advising on where a PR should target. Covers local Docker CI testing,
7
+ trigger rules, version management, and the integration→main promotion flow.
8
+ related:
9
+ - ../azure-devops-cli/SKILL.md
10
+ - ../../../../enact-docs/05-operations/cross-package/git-branching-strategy.md
11
+ ---
12
+
13
+ # CI/CD Pipeline Strategy — enact-os
14
+
15
+ ## Branch flow
16
+
17
+ ```text
18
+ feat/* ── push CI ──► PR to integration ── PR CI ──► auto-merge to integration
19
+ fix/* ── local CI ─► PR to integration ── PR CI ──► auto-merge to integration
20
+ integration ── automation creates or updates one PR to main ──► main
21
+ main ── manual approval + CI ──► publish
22
+ ```
23
+
24
+ ## Rules
25
+
26
+ ### Developer workflow
27
+
28
+ 0. Before starting any new task, sync local `integration` with remote `integration`
29
+ and branch from that refreshed base:
30
+
31
+ ```bash
32
+ git checkout integration
33
+ git pull --ff-only origin integration
34
+ git checkout -b feat/my-branch # or fix/my-branch
35
+ ```
36
+
37
+ 1. Work on a `feat/*` or `fix/*` branch.
38
+ 2. Run local Docker CI before opening a PR:
39
+
40
+ Each package has its own Docker wrapper at `./scripts/ci-local-<package>.sh`
41
+ (run from the `enact-os` workspace root). Current scripts:
42
+
43
+ - `ci-local-agent.sh` · `ci-local-context.sh` · `ci-local-eval.sh`
44
+ - `ci-local-factory.sh` · `ci-local-gateway.sh` · `ci-local-observe.sh`
45
+ - `ci-local-operator.sh` · `ci-local-proc-tap.sh` · `ci-local-runtime.sh`
46
+ - `ci-local-voice.sh` · `ci-local-watchdog.sh` · `ci-local-wiki.sh`
47
+
48
+ (Verify the exact set with `ls scripts/ci-local-*.sh` — it grows as packages are
49
+ added.) For `enact-factory` and `enact-wiki`, the Docker wrapper is the source of
50
+ truth for Azure parity; direct host-local Vitest can differ because of optional
51
+ native bindings on non-Linux machines.
52
+
53
+ 3. Open PR targeting **`integration`** only — never directly to `main`:
54
+
55
+ ```bash
56
+ az repos pr create \
57
+ --source-branch feat/my-branch \
58
+ --target-branch integration \
59
+ --title "feat: description" \
60
+ --auto-complete true \
61
+ --delete-source-branch true \
62
+ --detect
63
+ ```
64
+
65
+ 4. CI runs automatically on the PR. When CI passes the PR **auto-merges** into `integration`.
66
+ The repository setting **"Set PRs to auto-complete on creation by default"**
67
+ (Project settings → Repositories → Settings) is enabled, **but it applies only to
68
+ PRs created in the web UI** — PRs created via `az repos pr create` / REST do NOT
69
+ inherit it (verified: a CLI-created PR had auto-complete OFF despite the default).
70
+ So for the CLI workflow, always pass **both** `--auto-complete true` and
71
+ `--delete-source-branch true` explicitly.
72
+ 5. After each successful merge to `integration`, automation creates or updates one open `integration → main` PR.
73
+ 6. The `integration → main` PR stays manual. Approval on that PR is the release gate.
74
+
75
+ ### CI triggers
76
+
77
+ | Trigger | What runs |
78
+ | ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
79
+ | Push to `feat/*` | Build + test + lint |
80
+ | Push to `fix/*` | **Nothing** — local Docker CI is the gate |
81
+ | PR opened / updated targeting `integration` | Build + test + lint |
82
+ | Push to `integration` (after PR merged) | Build + test + lint |
83
+ | Push to `main` (after PR merged) | Build + test + lint + **Publish** for publishable packages; CI only for internal-only packages |
84
+
85
+ ### Publish gate
86
+
87
+ - Publish only runs on `refs/heads/main`.
88
+ - `main` is branch-protected — direct push is blocked; only PR merges allowed.
89
+ - Internal-only packages can omit a publish stage while keeping the same `integration` / `main` CI trigger pattern.
90
+ - Merging the `integration → main` PR IS the manual approval for publish.
91
+ - Version bumps are done manually by the repo owner before approving the `integration → main` PR.
92
+
93
+ ### Version management
94
+
95
+ - No automated changesets or version bots.
96
+ - Repo owner bumps `package.json` / `Cargo.toml` version manually.
97
+ - Automation opens or updates the `integration → main` PR.
98
+ - Repo owner merges the `integration → main` PR to trigger publish.
99
+
100
+ ## Pipeline trigger config (all packages)
101
+
102
+ ```yaml
103
+ trigger:
104
+ branches:
105
+ include:
106
+ - integration
107
+ - feat/*
108
+ - main
109
+
110
+ pr:
111
+ branches:
112
+ include:
113
+ - integration
114
+ ```
115
+
116
+ `feat/*` is included so pushes to feature branches run CI (per the table above);
117
+ `fix/*` is intentionally excluded — local Docker CI is its only gate.
118
+
119
+ Publish stage condition:
120
+
121
+ ```yaml
122
+ condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
123
+ ```
124
+
125
+ ## Version pins for local CI scripts
126
+
127
+ Tool versions for all `ci-local-*.sh` scripts are pinned in `scripts/ci-versions.env`.
128
+
129
+ ```bash
130
+ # scripts/ci-versions.env (single source of truth for local CI versions)
131
+ NODE_IMAGE="node:22-bookworm"
132
+ ZIG_VERSION="0.14.0"
133
+ PYTHON_IMAGE="python:3.12-bookworm"
134
+ UV_VERSION="0.11.8" # must match enact-observe/pyproject.toml [tool.uv]
135
+ ```
136
+
137
+ When upgrading a tool version:
138
+
139
+ 1. Update `scripts/ci-versions.env`
140
+ 2. **Also** update the `variables:` block in the relevant `azure-pipelines.yml` — Azure Pipelines does NOT read this file; the two must be kept in sync manually.
141
+
142
+ ## Version-skip pattern
143
+
144
+ All publish steps must handle already-published versions gracefully:
145
+
146
+ - **npm public**: check `npm view <pkg> version`, skip if matches local
147
+ - **Azure Artifacts**: catch `403|409|already exist|upstream sources` and exit 0
148
+ - **cargo**: check Azure Artifacts sparse index or crates.io API, skip if version exists
149
+
150
+ ## Creating PRs via Azure DevOps CLI
151
+
152
+ The project default "Set PRs to auto-complete on creation by default" applies to
153
+ **web-UI PRs only** — `az`/REST-created PRs do NOT inherit it. So always pass BOTH
154
+ `--auto-complete true` and `--delete-source-branch true`:
155
+
156
+ ```bash
157
+ # From inside the repo directory (--detect infers org + project)
158
+ az repos pr create \
159
+ --source-branch feat/my-branch \
160
+ --target-branch integration \
161
+ --title "feat: description" \
162
+ --auto-complete true \
163
+ --delete-source-branch true \
164
+ --detect
165
+ ```
166
+
167
+ If a PR was opened before the default existed (or without the flags), fix it after
168
+ the fact:
169
+
170
+ ```bash
171
+ az repos pr update --id <N> --auto-complete true --delete-source-branch true
172
+ ```
173
+
174
+ See `../azure-devops-cli/SKILL.md` for full CLI reference.
175
+
176
+ ## Packages with pipelines
177
+
178
+ Policies created on 2026-05-19 via:
179
+
180
+ ```bash
181
+ az repos policy build create \
182
+ --repository-id <repo-id> \
183
+ --branch integration \
184
+ --build-definition-id <pipeline-id> \
185
+ --queue-on-source-update-only false \
186
+ --manual-queue-only false \
187
+ --valid-duration 0 \
188
+ --blocking true \
189
+ --enabled true \
190
+ --display-name "CI must pass before merge"
191
+ ```
192
+
193
+ ## Pipeline bootstrap gotchas
194
+
195
+ ### First PR that adds `azure-pipelines.yml` will not trigger CI
196
+
197
+ Azure DevOps evaluates the `pr:` trigger using the YAML **in the target branch**
198
+ (`integration`). If `azure-pipelines.yml` doesn't exist in `integration` yet (because the
199
+ PR that adds it hasn't merged), the trigger never fires. Merge the bootstrap PR
200
+ manually once — subsequent PRs will auto-trigger.
201
+
202
+ ### Variable group authorization on first run
203
+
204
+ A pipeline that references a variable group (e.g. `enact-dev-secrets`) for the
205
+ first time will queue but stay `notStarted` until an admin permits it. Navigate
206
+ to the stuck run's URL in Azure DevOps and click **Permit** on the variable group.
207
+ The authorization persists for that pipeline permanently.
208
+
209
+ ```bash
210
+ # Find stuck runs
211
+ az pipelines runs list --pipeline-id <id> --output table
212
+ # Then open: https://dev.azure.com/amsterdamdatalabs/Enact/_build/results?buildId=<run-id>
213
+ ```
214
+
215
+ ## Canonical doc
216
+
217
+ `enact-docs/05-operations/cross-package/git-branching-strategy.md`
@@ -0,0 +1,4 @@
1
+ interface:
2
+ display_name: "CI Pipeline Strategy"
3
+ short_description: "Explain enact-os branch flow, trigger rules, publish gates, and PR targeting."
4
+ default_prompt: "Use this skill to explain or apply the enact-os CI/CD branch strategy, trigger rules, local Docker CI expectations, and develop-to-main promotion flow."
@@ -14,6 +14,11 @@
14
14
  "analytics",
15
15
  "mcp"
16
16
  ],
17
+ "targets": [
18
+ "claude",
19
+ "codex",
20
+ "cursor"
21
+ ],
17
22
  "skills": "./skills/",
18
23
  "mcpServers": "./.mcp.json",
19
24
  "interface": {
@@ -21,15 +26,14 @@
21
26
  "shortDescription": "RGM modelling: elasticity, P&L cascades, retailer risk.",
22
27
  "longDescription": "Model price-event impacts across 14 SKUs in the Meridian Confections UK Premium Snacks range (January 2026). Covers own-price elasticity, P&L waterfall bridges for conservative/base/optimistic scenarios, Asda delisting-risk detection, split pricing strategies by segment, and a full four-option scenario comparison table.",
23
28
  "developerName": "Amsterdam Data Labs",
24
- "category": "Analytics",
29
+ "category": "Finance",
25
30
  "capabilities": [
26
31
  "Read",
27
32
  "Interactive"
28
- ],
29
- "defaultPrompt": [
30
- "Model a 3% Asda-only investment scenario for Galaxy sharing SKUs.",
31
- "Run the optimistic P&L cascade for the January 2026 price event.",
32
- "Show all retailer terms risks and Asda delisting exposure."
33
33
  ]
34
+ },
35
+ "factory": {
36
+ "firstParty": false,
37
+ "operatorScope": "global"
34
38
  }
35
39
  }