@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.1

package/extensions/cmux/skills/cmux-vm-monitor/scripts/codex_vm_monitor.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+set -euo pipefail
+
+WORKSPACE_REF="${CMUX_MONITOR_WORKSPACE:-workspace:1}"
+SURFACE_REF="${CMUX_MONITOR_SURFACE:-surface:2}"
+RELAY_WORKSPACE_REF="${CMUX_MONITOR_RELAY_WORKSPACE:-workspace:1}"
+RELAY_SURFACE_REF="${CMUX_MONITOR_RELAY_SURFACE:-surface:1}"
+LINES="${CMUX_MONITOR_LINES:-180}"
+LOG_FILE="${CMUX_MONITOR_LOG:-/tmp/codex_vm_monitor.log}"
+LOCAL_WAKE_MESSAGE_TEMPLATE="${CMUX_MONITOR_WAKE_MESSAGE:-[VM monitor __TIMESTAMP__] 30-minute check. Use exact cmux commands against __WORKSPACE__/__SURFACE__: 1) cmux capture-pane --workspace __WORKSPACE__ --surface __SURFACE__ --lines 120 2) cmux send --workspace __WORKSPACE__ --surface __SURFACE__ \"Status check from the local monitor. In exactly 8 lines, summarize: current phase, current file or slice, last completed step, last red proof, last green proof, blocker if any, next exact action, and whether OVERNIGHT_MERGE_STATUS.md is updated.\" 3) cmux send-key --workspace __WORKSPACE__ --surface __SURFACE__ Enter 4) cmux capture-pane --workspace __WORKSPACE__ --surface __SURFACE__ --lines 120 Then decide nothing | steer | stop.}"
+
+timestamp() {
+  date -u +"%Y-%m-%dT%H:%M:%SZ"
+}
+
+capture() {
+  cmux capture-pane --workspace "$WORKSPACE_REF" --surface "$SURFACE_REF" --lines "$LINES"
+}
+
+relay_local() {
+  local message="$1"
+  cmux send --workspace "$RELAY_WORKSPACE_REF" --surface "$RELAY_SURFACE_REF" "$message"
+  cmux send-key --workspace "$RELAY_WORKSPACE_REF" --surface "$RELAY_SURFACE_REF" tab
+}
+
+snapshot="$(capture 2>&1 || true)"
+
+{
+  printf '=== %s ===\n' "$(timestamp)"
+  printf 'workspace=%s surface=%s\n' "$WORKSPACE_REF" "$SURFACE_REF"
+  printf '%s\n' "$snapshot"
+  printf '\n'
+} >> "$LOG_FILE"
+
+if grep -q "Error: not_found\\|ERROR: Surface not found" <<<"$snapshot"; then
+  printf '[%s] monitor: surface missing\n' "$(timestamp)" >> "$LOG_FILE"
+  relay_local "[VM monitor $(timestamp)] surface missing for $WORKSPACE_REF/$SURFACE_REF"
+  exit 0
+fi
+
+wake_message="${LOCAL_WAKE_MESSAGE_TEMPLATE/__TIMESTAMP__/$(timestamp)}"
+wake_message="${wake_message//__WORKSPACE__/$WORKSPACE_REF}"
+wake_message="${wake_message//__SURFACE__/$SURFACE_REF}"
+printf '[%s] monitor: local wake injected; vm pane captured only\n' "$(timestamp)" >> "$LOG_FILE"
+relay_local "$wake_message"

package/extensions/cmux/skills/cmux-workspace/SKILL.md

@@ -0,0 +1,93 @@
+---
+name: cmux-workspace
+description: This skill should be used when work should stay inside the current cmux workspace and terminal, including workspace-scoped pane or surface inspection, non-disruptive terminal automation, and sibling-surface coordination messages.
+---
+
+# cmux Workspace
+Use this skill when work should stay scoped to the caller's cmux workspace and surface.
+
+## Default Rule
+Scope actions to the current caller workspace unless the user explicitly names another workspace, tab, or window.
+
+Start by resolving the live caller context:
+```bash
+printf 'workspace=%s\nsurface=%s\nsocket=%s\n' \
+  "${CMUX_WORKSPACE_ID:-}" \
+  "${CMUX_SURFACE_ID:-}" \
+  "${CMUX_SOCKET_PATH:-}"
+cmux identify --json
+```
+
+If the env vars are empty, use `cmux identify --json` and be explicit that you are falling back to the currently focused cmux context.
+
+## Non-Disruptive Automation
+Never change visible focus unless the user explicitly asked for it.
+
+Do not call these speculatively:
+- `cmux select-workspace`
+- `cmux focus-pane`
+- `cmux focus-panel`
+
+Prefer explicit `--workspace` and `--surface` flags for mutating actions.
+
+## Messaging Pattern
+For sibling-surface coordination, the default submission pattern is:
+
+```bash
+cmux send --workspace workspace:N --surface surface:N "<message>"
+cmux send-key --workspace workspace:N --surface surface:N Enter
+cmux capture-pane --workspace workspace:N --surface surface:N --lines 120
+```
+
+Rules:
+- Use `cmux send` plus `cmux send-key Enter` as the default pattern.
+- Always verify delivery with `cmux capture-pane`; do not trust `OK` from `cmux send` alone.
+- If the pane is busy, expect the message to remain queued in the composer. Report that exact state instead of claiming the message was accepted.
+- Only interrupt a busy pane if the user explicitly wants immediate submission.
+
+## Coordination Prefixes
+When you send a coordination message yourself, prefix it so direction is obvious:
+
+- `[sidecar -> enact-agent-config]`
+- `[enact-agent-config -> sidecar]`
+
+Rules:
+- Prefix only the coordination messages you send or relay.
+- Do not assume the user's own plain-text messages already carry a prefix.
+- Keep coordination updates short and operational: owner, current status, blocker, next step.
+
+## Caller Terminal
+Treat the caller surface as the safest anchor for relative operations:
+
+```bash
+cmux send --surface "${CMUX_SURFACE_ID:-}" "git status"
+cmux send-key --surface "${CMUX_SURFACE_ID:-}" Enter
+```
+
+## Inspect Workspace State
+Useful inspection commands:
+
+```bash
+cmux identify --json
+cmux list-workspaces --json
+cmux list-panes --workspace "${CMUX_WORKSPACE_ID:-}" --json
+cmux list-pane-surfaces --workspace "${CMUX_WORKSPACE_ID:-}" --json
+cmux capture-pane --workspace "${CMUX_WORKSPACE_ID:-}" --surface "${CMUX_SURFACE_ID:-}" --lines 120
+```
+
+## Right-Side Helper Policy
+When auxiliary work is needed in the caller workspace:
+- reuse an existing non-caller helper pane if one already exists
+- otherwise create exactly one helper pane to the right
+- avoid creating extra splits when a new surface in the helper pane is enough
+
+Example:
+```bash
+cmux new-pane --workspace "${CMUX_WORKSPACE_ID:-}" --type terminal --direction right --focus false
+```
+
+## Stop Conditions
+Stop and report instead of guessing when:
+- the target workspace or surface cannot be identified confidently
+- the pane stays busy and the message remains queued
+- a command would require focus-changing behavior the user did not request

package/extensions/dev-state/.agents/plugin.json

@@ -0,0 +1,35 @@
+{
+  "name": "dev-state",
+  "version": "0.1.0",
+  "description": "Dev-state lifecycle skills for Enact: graduating development_state plans into durable documentation.",
+  "author": {
+    "name": "Amsterdam Data Labs"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "dev-state",
+    "plans",
+    "lifecycle",
+    "documentation"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "Dev State",
+    "shortDescription": "Graduate development_state plans into durable docs.",
+    "developerName": "Amsterdam Data Labs",
+    "category": "Developer Tools",
+    "capabilities": [
+      "plan graduation",
+      "dev-state lifecycle"
+    ]
+  },
+  "factory": {
+    "firstParty": true,
+    "operatorScope": "global"
+  }
+}

package/extensions/dev-state/skills/dev-state-plan-graduation/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: dev-state-plan-graduation
+description: >-
+  Graduates completed work from 07-plans/active/ into durable 02-architecture/
+  and 04-contracts/ docs, archives done plans under 07-plans/archive/{component}/,
+  updates CHANGELOG.md and DOCS-MAP.md, and uses `ctx_knowledge` to recall prior
+  graduation context and record completions. Use when cleaning the development
+  pipeline, closing a plan, archiving completed slices, syncing architecture
+  docs, or when the user mentions plan migration, docs cleanup, archive, or
+  graduation alongside architecture documentation.
+---
+
+# Development state — plan graduation (enact-docs)
+
+Keeps **`07-plans/active/`** for **active** work only. Done outcomes
+live in **`02-architecture/`** and **`04-contracts/`** (normative), then land in
+**`07-plans/archive/{component}/`**.
+
+## Directory layout
+
+```
+enact-docs/
+├── 02-architecture/{component}/   # Normative architecture — authoritative
+├── 04-contracts/{component}/      # Contracts, target configs — authoritative
+├── 05-operations/{component}/     # Runbooks, ops guides
+├── 06-decisions/                  # ADRs
+├── 07-plans/
+│   ├── active/                    # Active + proposed plans (status in frontmatter)
+│   └── archive/{component}/       # Historical — not authoritative
+├── CHANGELOG.md
+├── DOCS-MAP.md
+└── GLOSSARY.md
+```
+
+Components: `factory`, `memory`, `context`, `runtime`, `watchdog`, `gateway`,
+`mission-control`, `proc-tap`, `omx`.
+
+## When to apply
+
+- A plan in `07-plans/active/` is fully implemented and tests pass.
+- User wants architecture docs updated to reflect shipped behavior.
+- User says "archive", "graduate", "move plan to archive", or "cleanup plans".
+- At the end of a session where multiple slices were shipped.
+
+## Knowledge recall first
+
+**Before doing anything**, use `ctx_knowledge` to recall prior context:
+
+```
+ctx_knowledge(action="search", query="plan graduation {component}")
+ctx_knowledge(action="recall", key="graduation:{component}")
+```
+
+If you find prior graduation records, use them to avoid re-processing already-archived plans.
+
+**After graduation**, record the completion:
+
+```
+ctx_knowledge(action="remember", key="graduation:{component}:{date}", value="archived:07-plans/archive/{component}/{plan-file};normative:{architecture-doc-path}")
+ctx_knowledge(action="remember", key="graduation:{component}:summary", value="Graduated {N} plans; updated {paths}")
+```
+
+## Operating principles
+
+1. **Architecture + contracts describe what IS.** Plans describe what was scheduled; after graduation the durable truth is `02-architecture/` + `04-contracts/` + CHANGELOG, not plan files.
+2. **Archive is not authoritative.** `07-plans/archive/` is historical. Never cite archive paths as spec — always point to `02-architecture/` or `04-contracts/`.
+3. **No silent loss.** Every moved plan must have a normative doc that captures its durable facts.
+4. **Architecture-first gate.** A plan cannot leave active until its durable facts are reflected in `02-architecture/{component}/` and/or `04-contracts/{component}/`. If no architecture delta is needed, record an explicit "no architecture delta" rationale in CHANGELOG.
+5. **Component subfolders.** Always archive under `07-plans/archive/{component}/` — not at the archive root.
+
+## Workflow
+
+### 1) Recall + inventory
+
+1. Run `ctx_knowledge` search/recall for prior graduation context (see above).
+2. List `07-plans/active/` — read each plan's frontmatter `status` field.
+3. For each plan assign:
+   - **Primary topic** (vocabulary cleanup, scheduler, closure contracts, DB migration, …)
+   - **Target normative doc(s)** — prefer extending existing files in `02-architecture/{component}/` or `04-contracts/{component}/`
+   - **Disposition**: `archive` | `keep-active` | `update-status-to-deferred`
+
+### 2) Documentation sweep — find every doc that needs updating
+
+**Do this before writing a single word.** Never hand-pick files from memory — always search first.
+
+#### Step A — ripgrep for all relevant terms
+
+Extract the key terms from the plan: API paths, function names, event names, error strings, feature labels, component names. Run one search across the entire doc tree:
+
+```bash
+# From enact-docs root
+rg -l "<term1>|<term2>|<term3>" --type md .
+```
+
+Example for a gateway plan touching `/v1/responses` and streaming:
+
+```bash
+rg -l "/v1/responses|response\.created|chatCompletionStream|OutputTextDelta" --type md .
+```
+
+Collect every matching path into a **candidate list**.
+
+#### Step B — follow frontmatter `related:` chains
+
+For **every file** in the candidate list, read its `related:` frontmatter and add those paths to the candidate list too. Also follow `related:` from the plan file itself and from any normative doc you already intend to update:
+
+```bash
+# Extract related: entries from a candidate file
+grep -A 20 "^related:" <file> | grep "^\s*-\s" | sed 's/.*- //'
+```
+
+Repeat until no new files are added.
+
+#### Step C — read and classify each candidate
+
+For each file in the final candidate list:
+
+1. Read the file (or scan it for the key terms)
+2. Classify each hit:
+   - **Stale claim** — says the feature is unavailable, broken, incomplete, or missing → **must update**
+   - **Status reference** — links to or describes the plan's status → **update to reflect completion**
+   - **Generic usage** — uses the term in English prose without making a feature claim → **skip**
+3. Build a final **update list** of must-update files
+
+#### Step D — confirm plan-linking docs
+
+```bash
+# Find docs that link directly to the plan file by name
+grep -rl "$(basename <plan-file> .md)" . --include="*.md"
+```
+
+Add any hits not already in the update list.
+
+Only after completing A–D should you proceed to step 3.
+
+### 3) Merge durable facts
+
+- Copy only stable behavior, file paths, contracts — not stale TODOs.
+- Update the relevant architecture/contract doc with the shipped behavior.
+- Where deferred scope exists that could be mistaken for shipped behavior, add a **Watchout** note in the normative doc.
+- Update STATUS comments in `04-contracts/` YAML/MD files from "not yet implemented" to "implemented in {src path}".
+- Update every file on the **update list** from step 2. Record which files were updated.
+
+### 4) Archive
+
+- Move completed plans: `git mv 07-plans/active/{plan}.md 07-plans/archive/{component}/{plan}.md`
+- Update the plan's frontmatter: `status: archived`, add `archived_date` and `normative_target:` fields.
+- For partially-completed plans: update `status: partial-complete`, add a note listing done vs pending at the top of the file before archiving.
+- Plans that are active but need more work: update `status` field and leave in active.
+
+### 5) Update index docs
+
+- **CHANGELOG.md** — append under `[Unreleased]` with Added/Changed entries listing:
+  - Plans archived (with archive path)
+  - Normative docs updated (with paths)
+  - All other docs updated from the sweep (with paths)
+- **DOCS-MAP.md** — refresh any stale entries that pointed to now-archived plans.
+- **GLOSSARY.md** — update any terms that changed with the vocabulary cleanup.
+
+### 6) Verification
+
+- Confirm documentation sweep was completed (candidate list built, all items classified):
+  ```bash
+  # Re-run the rg sweep and confirm no new hits appeared that you missed
+  rg -l "<key terms>" --type md .
+  ```
+- Grep for broken links to old active-plan paths:
+  ```bash
+  grep -r "07-plans/active/{archived-plan-name}" . --include="*.md"
+  ```
+- Confirm at least one `02-architecture/` or `04-contracts/` doc changed.
+- Run `ctx_knowledge remember` (see Knowledge recall first section).
+
+## Topic → normative doc mapping (enact-factory)
+
+| Topic                                                    | First-fit normative doc                                  |
+| -------------------------------------------------------- | -------------------------------------------------------- |
+| Vocabulary / stage names (coder/critic/stage-documenter) | `02-architecture/factory/pair-pipeline-and-workitems.md` |
+| Config schema (projects/path/heartbeatMs)                | `04-contracts/factory/config-target-design.yaml`         |
+| Operator activation / handoff                            | `04-contracts/factory/handoff-and-scheduler.md`          |
+| Closure contracts / scheduler loop                       | `02-architecture/factory/pair-pipeline-and-workitems.md` |
+| DB / postgres / sqlite                                   | `05-operations/factory/`                                 |
+| WorkItem state axes                                      | `04-contracts/factory/`                                  |
+| MCP tools                                                | `04-contracts/factory/`                                  |
+
+## Git notes
+
+- Use `git mv` for archive moves so history is traceable.
+- Do NOT stage or commit unless the user asks — they handle their own commit workflow.
+- Stage explicit file paths, not `git add .`, to avoid sweeping unrelated changes.
+
+## Reference
+
+- Full checklist template and archive layout: [references/reference.md](references/reference.md)

package/extensions/dev-state/skills/dev-state-plan-graduation/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Plan Graduation"
+  short_description: "Graduate completed enact-docs plans into architecture/contracts and archive them cleanly."
+  default_prompt: "Use this skill to graduate completed enact-docs plans into durable architecture and contract docs, archive the plans, update changelog/index docs, and record graduation context in ctx_knowledge."

package/extensions/dev-state/skills/dev-state-plan-graduation/references/reference.md

@@ -0,0 +1,130 @@
+# Reference — plan graduation artifacts (enact-docs)
+
+## Archive subfolder layout
+
+Always archive under a component subfolder, never at the archive root:
+
+```
+07-plans/archive/
+├── factory/       # enact-factory plans
+├── memory/        # enact-wiki plans
+├── context/       # enact-context plans
+├── runtime/       # enact-runtime plans (Governed Execution DAG)
+├── omx/           # OMX operator plans
+└── cross-repo/    # plans spanning multiple components
+```
+
+## Plan frontmatter fields
+
+```yaml
+---
+type: reference
+status: active
+owner: enact-factory
+archived_date: 2026-05-16
+normative_target: 04-contracts/factory/handoff-and-scheduler.md
+---
+```
+
+Valid `type` values: `plan`, `contract`, `architecture`, `decision`, `reference`
+Valid `status` values: `active`, `proposed`, `partial-complete`, `archived`, `deferred`
+
+## Archive checklist (per plan)
+
+Before moving a plan to archive, verify:
+
+**Documentation sweep (must complete before any edits):**
+
+- [ ] `rg -l` run for all key terms from the plan (API paths, function names, event names, feature labels, error strings)
+- [ ] Candidate list built from all rg hits
+- [ ] Frontmatter `related:` chains followed from every candidate file AND from the plan file itself — new hits added to candidate list
+- [ ] Frontmatter `related:` chains followed transitively until no new files are added
+- [ ] Every candidate file read and classified: stale claim / status reference / generic usage
+- [ ] Plan-linking grep run: `grep -rl "$(basename <plan-file> .md)" . --include="*.md"` — any hits added to update list
+- [ ] All stale-claim and status-reference files updated, paths listed in CHANGELOG entry
+
+**Architecture gate:**
+
+- [ ] At least one `02-architecture/{component}/` or `04-contracts/{component}/` doc updated with durable facts from this plan
+- [ ] STATUS comments in YAML/MD contracts updated from "SA proposal" / "not yet implemented" → "implemented in src/..."
+
+**Index docs:**
+
+- [ ] CHANGELOG.md has an entry under `[Unreleased]` with the archive path, normative doc paths, and all sweep-updated doc paths
+- [ ] No broken links to the old `07-plans/active/` path remain (grep check)
+- [ ] `ctx_knowledge` memory entry recorded
+
+## CHANGELOG.md entry shape
+
+```markdown
+### Changed (documentation)
+
+- Archived `07-plans/active/2026-05-16-operator-vocabulary-cleanup.md`
+  → `07-plans/archive/factory/2026-05-16-operator-vocabulary-cleanup.md`
+  Normative: `02-architecture/factory/pair-pipeline-and-workitems.md`,
+  `04-contracts/factory/config-target-design.yaml`
+```
+
+## `ctx_knowledge` patterns
+
+```
+# Search before starting
+ctx_knowledge(action="search", query="factory plan graduation")
+
+# Record after archiving
+ctx_knowledge(action="remember", key="plan:2026-05-16-operator-vocabulary-cleanup:archived_to", value="07-plans/archive/factory/2026-05-16-operator-vocabulary-cleanup.md")
+ctx_knowledge(action="remember", key="plan:2026-05-16-operator-vocabulary-cleanup:normative_target", value="02-architecture/factory/pair-pipeline-and-workitems.md")
+
+# Session note
+ctx_knowledge(action="remember", key="session:2026-05-16:graduation-summary", value="graduated 2 factory plans; VC slices 2-5 complete; SA phases A/B/C done")
+```
+
+## Documentation sweep commands
+
+Run all of these **before writing a single word** of documentation updates.
+
+```bash
+# Step A — find every doc that mentions the plan's key terms
+# Replace terms with API paths, function names, event names, feature labels from the plan
+rg -l "<term1>|<term2>|<term3>" --type md .
+
+# Example for a gateway plan touching /v1/responses and streaming events:
+rg -l "/v1/responses|response\.created|chatCompletionStream|OutputTextDelta|response\.output_item" --type md .
+
+# Step B — for each candidate file, extract its related: frontmatter entries
+# Run this for every file in the candidate list and for the plan file itself
+grep -A 20 "^related:" <candidate-file> | grep "^\s*-\s" | sed 's/.*- //'
+
+# Step C — find docs that link directly to the plan file by name
+grep -rl "$(basename <plan-file> .md)" . --include="*.md"
+
+# Confirm sweep found architecture/contracts candidates
+echo "Architecture candidates:"; rg -l "<term1>|<term2>" --type md 02-architecture/ 04-contracts/
+```
+
+Repeat Step B until no new files are added. Only then proceed to classify (stale claim / status reference / generic) and edit.
+
+## Grep hygiene
+
+```bash
+# Find broken links to archived plan (run from enact-docs root)
+grep -r "07-plans/active/2026-05-16-operator-vocabulary-cleanup" . --include="*.md"
+
+# Confirm architecture/contracts docs were touched
+git diff --name-only | grep -E "^(02-architecture|04-contracts)/.*\.md"
+
+# Find STATUS comments still saying "not yet implemented"
+grep -r "not yet implemented\|SA proposal — not yet\|not yet read by" 04-contracts/ --include="*.md" --include="*.yaml"
+```
+
+## Partial-complete plan note template
+
+Add at the top of a partially-done plan before archiving:
+
+```markdown
+<!-- ARCHIVED 2026-05-16
+Done: Slice 1 (vocab cleanup), Slice 2 (MCP renames), Slice 3 (stage keys)
+Pending: D13 (reseed detection — deferred to post live-testing)
+Normative: 02-architecture/factory/pair-pipeline-and-workitems.md
+-->
+```

package/extensions/devops/.agents/plugin.json

@@ -0,0 +1,36 @@
+{
+  "name": "devops",
+  "version": "0.1.0",
+  "description": "DevOps skills for Enact: Azure DevOps CLI workflows and CI pipeline strategy for branch, build, and release operations.",
+  "author": {
+    "name": "Amsterdam Data Labs"
+  },
+  "license": "UNLICENSED",
+  "keywords": [
+    "devops",
+    "azure-devops",
+    "ci",
+    "pipeline",
+    "release"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "skills": "./skills/",
+  "interface": {
+    "displayName": "DevOps",
+    "shortDescription": "Azure DevOps CLI and CI pipeline strategy skills.",
+    "developerName": "Amsterdam Data Labs",
+    "category": "Developer Tools",
+    "capabilities": [
+      "azure devops cli",
+      "ci pipeline strategy"
+    ]
+  },
+  "factory": {
+    "firstParty": true,
+    "operatorScope": "global"
+  }
+}