@amsterdamdatalabs/enact-extensions 0.1.5 → 0.1.10

package/extensions/devops/skills/azure-devops-cli/SKILL.md

@@ -1,431 +0,0 @@
----
-name: azure-devops-cli
-description: Manage Azure DevOps resources using the az CLI with the azure-devops extension. Covers repositories, pull requests, pipelines, boards, and work items.
----
-
-# Azure DevOps CLI
-
-## Overview
-
-Manage Azure DevOps resources using the `az` CLI with the `azure-devops` extension. Covers repositories, pull requests, pipelines, boards, and work items.
-
-## Prerequisites
-
-```bash
-# Install azure-devops extension (requires az cli 2.30+)
-az extension add --name azure-devops
-
-# Authenticate
-az login
-
-# Set defaults (recommended)
-az devops configure --defaults organization=https://dev.azure.com/YOUR_ORG project=YOUR_PROJECT
-```
-
-## Most-Used Commands
-
-### My Pull Requests
-
-```bash
-# List PRs I created
-az repos pr list --creator "$(az account show --query user.name -o tsv)"
-
-# List PRs assigned to me for review
-az repos pr list --reviewer "$(az account show --query user.name -o tsv)"
-
-# Show PR details
-az repos pr show --id <pr-id>
-
-# Checkout PR locally
-az repos pr checkout --id <pr-id>
-```
-
-### My Work Items
-
-```bash
-# List work items assigned to me
-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"
-
-# Show work item details
-az boards work-item show --id <work-item-id>
-
-# Create work item
-az boards work-item create --title "Task title" --type "Task"
-
-# Update work item state
-az boards work-item update --id <id> --state "In Progress"
-```
-
-### Pipelines
-
-```bash
-# List pipelines
-az pipelines list
-
-# List recent runs
-az pipelines runs list --top 10
-
-# Show run details (result, status, logs URL)
-az pipelines runs show --id <run-id>
-```
-
-> **⛔ NEVER use `az pipelines run` to manually trigger a CI run as a substitute
-> for a PR push.** Manual runs do not update PR build status and give false
-> confidence. If CI is not triggering on a PR, push a new commit to the source
-> branch instead — even an empty one:
->
-> ```bash
-> git commit --allow-empty -m "ci: re-trigger pipeline"
-> git push
-> ```
->
-> The only permitted use of `az pipelines run` is a deliberate Publish-stage
-> retag/hotfix on `main`, performed explicitly by the repo owner.
-
-### Reading Build Failure Output
-
-AzDO pipeline logs expire quickly (timeline returns HTTP 204 after ~24h). Get them while the run is fresh.
-
-```bash
-# Get failure summary from the build timeline (works while logs are live)
-TOKEN=$(az account get-access-token \
-  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
-  --query accessToken -o tsv)
-
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/build/builds/<buildId>/timeline?api-version=7.1" \
-  | python3 -c "
-import sys, json
-d = json.load(sys.stdin)
-failed = [r for r in d.get('records', [])
-          if r.get('result') == 'failed' and r.get('type') in ('Task','Job','Stage')]
-for r in sorted(failed, key=lambda x: x.get('order', 0)):
-    print(r.get('type'), '|', r.get('name'))
-    for i in (r.get('issues') or [])[:3]:
-        print('  !', i.get('message', '')[:300])
-"
-
-# Get the logs container URL from a run (use this to build the logs URL)
-az pipelines runs show --id <run-id> --output json \
-  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['logs']['url'])"
-
-# Fetch specific log entry (replace <logId> with an entry ID from the logs index)
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/build/builds/<buildId>/logs/<logId>?api-version=7.1"
-```
-
-**Important:** `az rest` does NOT work for AzDO URLs — it cannot derive the right AAD scope.
-Use `az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798` + `curl` instead.
-Timeline returns HTTP 204 (empty) once logs have expired — check the AzDO web UI in that case.
-
-### Authorizing Variable Groups for Pipelines
-
-First-time pipelines using a variable group require authorization. Check and fix via REST:
-
-```bash
-TOKEN=$(az account get-access-token \
-  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
-  --query accessToken -o tsv)
-
-# Get variable group ID
-az pipelines variable-group list --output table
-
-# Authorize the group for specific pipelines (replace groupId and pipeline IDs)
-curl -s -X PATCH \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/pipelines/pipelinePermissions/variablegroup/<groupId>?api-version=7.1-preview.1" \
-  -d '{"pipelines": [{"id": 9, "authorized": true}, {"id": 10, "authorized": true}]}'
-
-# Or authorize for ALL pipelines in the project at once:
-curl -s -X PATCH \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/pipelines/pipelinePermissions/variablegroup/<groupId>?api-version=7.1-preview.1" \
-  -d '{"allPipelines": {"authorized": true}}'
-```
-
-### Diagnosing Why CI Did Not Trigger on a PR
-
-CI should trigger automatically when commits are pushed to a PR source branch. If it
-does not, do NOT manually queue a run. Instead:
-
-1. **Push a new commit** (even empty) to the source branch:
-   ```bash
-   git commit --allow-empty -m "ci: re-trigger pipeline"
-   git push
-   ```
-2. Check the PR's **build validation policy** is enabled (pipeline must be registered
-   and the policy must reference the correct pipeline ID).
-3. Check the PR is open and targeting `integration`. Closed or draft PRs do not
-   trigger CI.
-
-Manual re-queueing (`az pipelines run`) is **only** for deliberate Publish-stage retags
-on `main` performed by the repo owner. For bootstrap PRs introducing `azure-pipelines.yml`
-for the first time, use `git push --force-with-lease` to force a new push event.
-
-### Enforcing Merge Strategy on a Branch
-
-> **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.
-
-All enact-os repos enforce merge strategy via AzDO branch policies (policy type `fa4e907d-c16b-4a4c-9dfa-4916e5d171ab`).
-
-**integration — squash only** (1 clean commit per PR, linear history):
-
-```bash
-TOKEN=$(az account get-access-token \
-  --resource 499b84ac-1321-427f-aa17-267ca6975798 \
-  --query accessToken -o tsv)
-
-curl -s -X POST \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/policy/configurations?api-version=7.1" \
-  -d '{
-    "isEnabled": true, "isBlocking": true,
-    "type": {"id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"},
-    "settings": {
-      "allowSquash": true,
-      "allowNoFastForward": false,
-      "allowRebase": false,
-      "allowRebaseMerge": false,
-      "scope": [{"repositoryId": "<repo-id>", "refName": "refs/heads/integration", "matchKind": "exact"}]
-    }
-  }'
-```
-
-**main — basic merge or fast-forward, no squash** (preserves full integration history on promotion):
-
-```bash
-# If no existing policy: POST (same URL as above, change settings)
-# If existing policy exists, use PUT to update:
-curl -s -X PUT \
-  -H "Authorization: Bearer $TOKEN" \
-  -H "Content-Type: application/json" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/policy/configurations/<policy-id>?api-version=7.1" \
-  -d '{
-    "isEnabled": true, "isBlocking": true,
-    "type": {"id": "fa4e907d-c16b-4a4c-9dfa-4916e5d171ab"},
-    "settings": {
-      "allowSquash": false,
-      "allowNoFastForward": true,
-      "allowRebase": true,
-      "allowRebaseMerge": false,
-      "scope": [{"repositoryId": "<repo-id>", "refName": "refs/heads/main", "matchKind": "exact"}]
-    }
-  }'
-```
-
-**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:
-
-```bash
-curl -s -H "Authorization: Bearer $TOKEN" \
-  "https://dev.azure.com/amsterdamdatalabs/Enact/_apis/policy/configurations?api-version=7.1" \
-  | python3 -c "
-import sys,json
-MERGE_TYPE='fa4e907d-c16b-4a4c-9dfa-4916e5d171ab'
-for p in json.load(sys.stdin).get('value',[]):
-    if p.get('type',{}).get('id') == MERGE_TYPE:
-        for s in p['settings'].get('scope',[]):
-            print(p['id'], s.get('repositoryId'), s.get('refName'))
-"
-```
-
-### Auto-delete Source Branch
-
-AzDO has no repo-level policy to force-delete branches on merge. Enforce at PR creation:
-
-```bash
-# Always include both flags — never omit --delete-source-branch
-az repos pr create \
-  --source-branch feat/my-branch \
-  --target-branch integration \
-  --title "feat: description" \
-  --auto-complete true \
-  --delete-source-branch true \
-  --detect
-```
-
-### First-Run Checklist (new pipeline bootstrap)
-
-Before triggering a new pipeline for the first time:
-
-1. **Validate YAML locally:** `python3 -c "import yaml; yaml.safe_load(open('azure-pipelines.yml')); print('OK')"`
-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)
-3. **Variable group authorized:** Run `az pipelines variable-group list` to get group ID, then use the authorization API above
-4. **Multi-checkout repos accessible:** If `resources: repositories` is used, confirm service connection has read access to each sibling repo
-
-### Repositories
-
-```bash
-# List repositories
-az repos list
-
-# Show repo details
-az repos show --repository <repo-name>
-
-# Create repository
-az repos create --name "new-repo"
-```
-
-### Pull Request Workflow
-
-```bash
-# Before starting any new task, sync local integration and branch from it
-git checkout integration
-git pull --ff-only origin integration
-git checkout -b feat/my-branch   # or fix/my-branch
-
-# Create PR to integration — always use auto-complete + delete-source-branch
-az repos pr create \
-  --source-branch feat/my-branch \
-  --target-branch integration \
-  --title "feat: description" \
-  --auto-complete true \
-  --delete-source-branch true \
-  --detect
-# CI passes → PR auto-merges. No reviewer required on integration.
-
-# Promotion PR to main (integration→main) — create or update automatically,
-# but merge remains manual. Never auto-complete the main PR.
-az repos pr create \
-  --source-branch integration \
-  --target-branch main \
-  --title "release: promote integration → main" \
-  --detect
-# NO --auto-complete  ← never on main PRs
-# NO --delete-source-branch  ← integration is permanent
-
-# Enable auto-complete on an existing PR
-az repos pr update --id <pr-id> --auto-complete true --delete-source-branch true --org https://dev.azure.com/amsterdamdatalabs
-
-# Add reviewers (for main PRs)
-az repos pr update --id <pr-id> --reviewers user@email.com
-
-# Set vote (approve: 10, approve with suggestions: 5, wait: -5, reject: -10)
-az repos pr set-vote --id <pr-id> --vote 10
-
-# Complete/merge PR manually
-az repos pr update --id <pr-id> --status completed
-```
-
-## enact-os Specific
-
-### Set org/project defaults (once per machine)
-
-```bash
-az devops configure --defaults \
-  organization=https://dev.azure.com/amsterdamdatalabs \
-  project=Enact
-```
-
-After this, `--org` and `--project` can be omitted from all commands.
-
-### Register a pipeline
-
-```bash
-# Run from inside the repo directory — --detect infers org/project/repo
-az pipelines create \
-  --name "<package-name> CI" \
-  --repository <repo-name> \
-  --repository-type tfsgit \
-  --branch <default-branch> \
-  --yml-path azure-pipelines.yml \
-  --skip-first-run \
-  --detect
-```
-
-### Create a blocking build-validation policy
-
-```bash
-az repos policy build create \
-  --repository-id <repo-id> \
-  --branch integration \
-  --build-definition-id <pipeline-id> \
-  --queue-on-source-update-only false \
-  --manual-queue-only false \
-  --valid-duration 0 \
-  --blocking true \
-  --enabled true \
-  --display-name "CI must pass before merge" \
-  --detect
-```
-
-Get `--repository-id` via `az repos show --repository <repo-name> --query id -o tsv --detect`.
-
-### List / delete a policy
-
-```bash
-# List policies for a repo
-az repos policy list --repository-id <repo-id> --detect -o table
-
-# Delete a policy (use when correcting a policy on the wrong branch)
-az repos policy delete --id <policy-id> --detect
-```
-
-### Pipeline and policy registry (enact-os)
-
-See `../ci-pipeline-strategy/SKILL.md` for the full table of pipeline IDs, policy IDs, and gate branches across all 10 packages.
-
-## Common Flags
-
-Most commands support:
-
-| Flag                | Description                                         |
-| ------------------- | --------------------------------------------------- |
-| `--org`             | Organization URL (or set via `az devops configure`) |
-| `--project`         | Project name (or set via `az devops configure`)     |
-| `--detect`          | Auto-detect org/project from git remote             |
-| `-o json/table/tsv` | Output format                                       |
-
-## Troubleshooting
-
-```bash
-# Check current config
-az devops configure --list
-
-# Verify authentication
-az account show
-
-# Check extension version
-az extension show --name azure-devops
-```
-
-### Extension fails with `No module named 'msrestazure'`
-
-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:
-
-```bash
-# Find az's Python
-az --version 2>&1 | grep "Python location"
-# e.g. Python location '/opt/homebrew/Cellar/azure-cli/2.76.0/libexec/bin/python'
-
-# Install into that Python
-/opt/homebrew/Cellar/azure-cli/<version>/libexec/bin/python -m pip install msrestazure
-
-# If the extension directory is corrupt, remove and reinstall
-rm -rf ~/.azure/cliextensions/azure-devops
-az extension add --name azure-devops
-```
-
-### PR commands live under `az repos`, not `az devops`
-
-```bash
-# WRONG — 'pr' is not a subcommand of az devops
-az devops pr create ...
-
-# CORRECT
-az repos pr create --source-branch feature/x --target-branch integration --detect
-```
-
-`--detect` auto-infers org and project from the git remote — no need to set defaults explicitly when inside a repo directory.
-
-### Set org/project defaults once per machine
-
-```bash
-az devops configure --defaults \
-  organization=https://dev.azure.com/amsterdamdatalabs \
-  project=Enact
-```
-
-After this, `--org` and `--project` flags can be omitted from all commands.

package/extensions/devops/skills/azure-devops-cli/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "Azure DevOps CLI"
-  short_description: "Use az CLI and REST patterns for PRs, work items, pipelines, and branch policies."
-  default_prompt: "Use this skill to manage Azure DevOps with az CLI plus REST fallbacks for pipelines, policies, PRs, work items, and CI diagnostics."

package/extensions/devops/skills/ci-pipeline-strategy/SKILL.md

@@ -1,217 +0,0 @@
----
-name: ci-pipeline-strategy
-description: >-
-  Documents the enact-os CI/CD branching strategy and pipeline conventions.
-  Use when working on Azure Pipelines, branch triggers, publish gates, or
-  advising on where a PR should target. Covers local Docker CI testing,
-  trigger rules, version management, and the integration→main promotion flow.
-related:
-  - ../azure-devops-cli/SKILL.md
-  - ../../../../enact-docs/05-operations/cross-package/git-branching-strategy.md
----
-
-# CI/CD Pipeline Strategy — enact-os
-
-## Branch flow
-
-```text
-feat/*  ── push CI ──► PR to integration ── PR CI ──► auto-merge to integration
-fix/*   ── local CI ─► PR to integration ── PR CI ──► auto-merge to integration
-integration ── automation creates or updates one PR to main ──► main
-main ── manual approval + CI ──► publish
-```
-
-## Rules
-
-### Developer workflow
-
-0. Before starting any new task, sync local `integration` with remote `integration`
-   and branch from that refreshed base:
-
-   ```bash
-   git checkout integration
-   git pull --ff-only origin integration
-   git checkout -b feat/my-branch   # or fix/my-branch
-   ```
-
-1. Work on a `feat/*` or `fix/*` branch.
-2. Run local Docker CI before opening a PR:
-
-Each package has its own Docker wrapper at `./scripts/ci-local-<package>.sh`
-(run from the `enact-os` workspace root). Current scripts:
-
-- `ci-local-agent.sh` · `ci-local-context.sh` · `ci-local-eval.sh`
-- `ci-local-factory.sh` · `ci-local-gateway.sh` · `ci-local-observe.sh`
-- `ci-local-operator.sh` · `ci-local-proc-tap.sh` · `ci-local-runtime.sh`
-- `ci-local-voice.sh` · `ci-local-watchdog.sh` · `ci-local-wiki.sh`
-
-(Verify the exact set with `ls scripts/ci-local-*.sh` — it grows as packages are
-added.) For `enact-factory` and `enact-wiki`, the Docker wrapper is the source of
-truth for Azure parity; direct host-local Vitest can differ because of optional
-native bindings on non-Linux machines.
-
-3. Open PR targeting **`integration`** only — never directly to `main`:
-
-   ```bash
-   az repos pr create \
-     --source-branch feat/my-branch \
-     --target-branch integration \
-     --title "feat: description" \
-     --auto-complete true \
-     --delete-source-branch true \
-     --detect
-   ```
-
-4. CI runs automatically on the PR. When CI passes the PR **auto-merges** into `integration`.
-   The repository setting **"Set PRs to auto-complete on creation by default"**
-   (Project settings → Repositories → Settings) is enabled, **but it applies only to
-   PRs created in the web UI** — PRs created via `az repos pr create` / REST do NOT
-   inherit it (verified: a CLI-created PR had auto-complete OFF despite the default).
-   So for the CLI workflow, always pass **both** `--auto-complete true` and
-   `--delete-source-branch true` explicitly.
-5. After each successful merge to `integration`, automation creates or updates one open `integration → main` PR.
-6. The `integration → main` PR stays manual. Approval on that PR is the release gate.
-
-### CI triggers
-
-| Trigger                                     | What runs                                                                                      |
-| ------------------------------------------- | ---------------------------------------------------------------------------------------------- |
-| Push to `feat/*`                            | Build + test + lint                                                                            |
-| Push to `fix/*`                             | **Nothing** — local Docker CI is the gate                                                      |
-| PR opened / updated targeting `integration` | Build + test + lint                                                                            |
-| Push to `integration` (after PR merged)     | Build + test + lint                                                                            |
-| Push to `main` (after PR merged)            | Build + test + lint + **Publish** for publishable packages; CI only for internal-only packages |
-
-### Publish gate
-
-- Publish only runs on `refs/heads/main`.
-- `main` is branch-protected — direct push is blocked; only PR merges allowed.
-- Internal-only packages can omit a publish stage while keeping the same `integration` / `main` CI trigger pattern.
-- Merging the `integration → main` PR IS the manual approval for publish.
-- Version bumps are done manually by the repo owner before approving the `integration → main` PR.
-
-### Version management
-
-- No automated changesets or version bots.
-- Repo owner bumps `package.json` / `Cargo.toml` version manually.
-- Automation opens or updates the `integration → main` PR.
-- Repo owner merges the `integration → main` PR to trigger publish.
-
-## Pipeline trigger config (all packages)
-
-```yaml
-trigger:
-  branches:
-    include:
-      - integration
-      - feat/*
-      - main
-
-pr:
-  branches:
-    include:
-      - integration
-```
-
-`feat/*` is included so pushes to feature branches run CI (per the table above);
-`fix/*` is intentionally excluded — local Docker CI is its only gate.
-
-Publish stage condition:
-
-```yaml
-condition: and(succeeded(), eq(variables['Build.SourceBranch'], 'refs/heads/main'))
-```
-
-## Version pins for local CI scripts
-
-Tool versions for all `ci-local-*.sh` scripts are pinned in `scripts/ci-versions.env`.
-
-```bash
-# scripts/ci-versions.env (single source of truth for local CI versions)
-NODE_IMAGE="node:22-bookworm"
-ZIG_VERSION="0.14.0"
-PYTHON_IMAGE="python:3.12-bookworm"
-UV_VERSION="0.11.8"   # must match enact-observe/pyproject.toml [tool.uv]
-```
-
-When upgrading a tool version:
-
-1. Update `scripts/ci-versions.env`
-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.
-
-## Version-skip pattern
-
-All publish steps must handle already-published versions gracefully:
-
-- **npm public**: check `npm view <pkg> version`, skip if matches local
-- **Azure Artifacts**: catch `403|409|already exist|upstream sources` and exit 0
-- **cargo**: check Azure Artifacts sparse index or crates.io API, skip if version exists
-
-## Creating PRs via Azure DevOps CLI
-
-The project default "Set PRs to auto-complete on creation by default" applies to
-**web-UI PRs only** — `az`/REST-created PRs do NOT inherit it. So always pass BOTH
-`--auto-complete true` and `--delete-source-branch true`:
-
-```bash
-# From inside the repo directory (--detect infers org + project)
-az repos pr create \
-  --source-branch feat/my-branch \
-  --target-branch integration \
-  --title "feat: description" \
-  --auto-complete true \
-  --delete-source-branch true \
-  --detect
-```
-
-If a PR was opened before the default existed (or without the flags), fix it after
-the fact:
-
-```bash
-az repos pr update --id <N> --auto-complete true --delete-source-branch true
-```
-
-See `../azure-devops-cli/SKILL.md` for full CLI reference.
-
-## Packages with pipelines
-
-Policies created on 2026-05-19 via:
-
-```bash
-az repos policy build create \
-  --repository-id <repo-id> \
-  --branch integration \
-  --build-definition-id <pipeline-id> \
-  --queue-on-source-update-only false \
-  --manual-queue-only false \
-  --valid-duration 0 \
-  --blocking true \
-  --enabled true \
-  --display-name "CI must pass before merge"
-```
-
-## Pipeline bootstrap gotchas
-
-### First PR that adds `azure-pipelines.yml` will not trigger CI
-
-Azure DevOps evaluates the `pr:` trigger using the YAML **in the target branch**
-(`integration`). If `azure-pipelines.yml` doesn't exist in `integration` yet (because the
-PR that adds it hasn't merged), the trigger never fires. Merge the bootstrap PR
-manually once — subsequent PRs will auto-trigger.
-
-### Variable group authorization on first run
-
-A pipeline that references a variable group (e.g. `enact-dev-secrets`) for the
-first time will queue but stay `notStarted` until an admin permits it. Navigate
-to the stuck run's URL in Azure DevOps and click **Permit** on the variable group.
-The authorization persists for that pipeline permanently.
-
-```bash
-# Find stuck runs
-az pipelines runs list --pipeline-id <id> --output table
-# Then open: https://dev.azure.com/amsterdamdatalabs/Enact/_build/results?buildId=<run-id>
-```
-
-## Canonical doc
-
-`enact-docs/05-operations/cross-package/git-branching-strategy.md`

package/extensions/devops/skills/ci-pipeline-strategy/agents/openai.yaml

@@ -1,4 +0,0 @@
-interface:
-  display_name: "CI Pipeline Strategy"
-  short_description: "Explain enact-os branch flow, trigger rules, publish gates, and PR targeting."
-  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."