@amsterdamdatalabs/enact-extensions 0.1.1 → 0.1.5

package/extensions/enact-operator/hooks/hooks.json

@@ -0,0 +1,126 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook session-start",
+            "statusMessage": "Loading Operator workspace context"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook user-prompt-submit"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-counter reset"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-search-guard reset"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook pre-tool-use",
+            "statusMessage": "Checking Operator shell safety policy"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook post-tool-use",
+            "statusMessage": "Reviewing Operator tool output"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-counter",
+            "statusMessage": "Checking Operator tool-call budget"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-search-guard",
+            "statusMessage": "Checking Operator search deduplication"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook stop",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook pre-compact"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook subagent-tracker start"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook subagent-tracker stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/extensions/enact-operator/skills/_variants.md

@@ -0,0 +1,44 @@
+# Skill Variant Contract
+
+Each skill directory may ship model-specific peer files alongside the default
+`SKILL.md`.
+
+## File Names
+
+- `SKILL.md` is the default prompt body and the required fallback.
+- `gpt.md` is selected for GPT-family model identities.
+- `gemini.md` is selected for Gemini-family model identities.
+- `kimi.md` is selected for Kimi-family model identities.
+- `opus-4-7.md` is selected for Claude Opus 4.7 model identities.
+
+## Selection Rule
+
+The loader resolves variants in this order:
+
+1. first matching model-specific peer file
+2. `SKILL.md` when no model-specific peer matches or no model identity is available
+
+## Model Identity Header
+
+The model identity is propagated through the `X-Model-Identity` header injected
+by enact-gateway on routed requests. Variant selection reads that identity from
+activation metadata. If the header is absent, the loader must fall back to
+`SKILL.md` instead of guessing.
+
+## Testing Constraint
+
+The default `auto` route does not expose a stable raw model identity for prompt
+selection tests. For live gateway pass-through checks, use the confirmed model
+IDs:
+
+- `kimi-for-coding`
+- `MiniMax-M2.7`
+
+Do not use generic labels like `gpt-4` or `gemini` for integration checks.
+Helper/unit tests should inject the model identity directly instead of depending
+on a live gateway route.
+
+## Current Scope
+
+This helper/documentation slice defines the variant selection contract and the
+Ralph Gemini variant file. Full hook/prompt-loader wiring remains a later step.

package/extensions/enact-operator/skills/ai-slop-cleaner/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: ai-slop-cleaner
+description: "Walk the diff for TODO/placeholder/silent-catch noise and replace each with a concrete implementation or remove it entirely."
+---
+
+# AI Slop Cleaner
+
+## Purpose
+Removes low-quality AI-generated residue from code produced in a Operator session: `// TODO`, "for now", "later", silent empty catch blocks, unreachable fallback layers, and placeholder strings. Each removal is replaced with a real implementation or an explicit compile-time error — never just deleted.
+
+## Use When
+- After an implementation pass before the operator accepts the result
+- Before running `$ultraqa` verification gates
+- When a diff review reveals TODO comments, "for now" strings, or swallowed exceptions
+
+## Workflow
+1. Identify the files changed in the current session (operator-driven; use `git diff --name-only`).
+2. For each changed file, scan for these patterns:
+   - `// TODO`, `// FIXME`, `// HACK`, `// XXX`
+   - String literals containing "for now", "placeholder", "stub", "later", "not yet implemented"
+   - Empty catch blocks or catch blocks that only log without re-throwing or handling
+   - Fallback return values that hide real errors (e.g., `return null`, `return []` with no explanation)
+   - Dead code gated on `if (false)` or `if (process.env.NEVER)`
+3. For each hit, choose one action:
+   - Replace with a real implementation if the intent is clear
+   - Replace with an explicit thrown error if the path should never be reached
+   - Remove the dead code entirely if it adds no value
+4. After cleanup, re-run `enact-operator doctor` to confirm nothing broken:
+   ```
+   enact-operator doctor
+   ```
+5. Re-run the project's test suite to confirm no regressions.
+6. Run a second grep pass to confirm zero hits remain:
+   ```
+   grep -rE "TODO|FIXME|HACK|for now|placeholder|stub" <changed-files>
+   ```
+
+## State Contract
+- Reads: changed files in the working tree
+- Writes: same files (in-place edits only); no new files, no new state in `.enact/operator/`
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.
+## Final Check
+- Zero `TODO`, `FIXME`, `HACK`, or placeholder strings in changed files
+- No empty or swallowed catch blocks remain
+- `enact-operator doctor` still passes after cleanup
+- Test suite still passes after cleanup
+- No code was deleted without a replacement or explicit error

package/extensions/enact-operator/skills/analyze/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: analyze
+description: "Read-only analysis of a Operator repo, runtime, or codebase surface. No mutations; output is plain text findings."
+---
+
+# Analyze
+
+## Purpose
+Performs a structured, read-only investigation of Operator runtime state, plugin surfaces, provider boundaries, hooks, or codebase structure. Nothing is written or changed. Output is a structured findings report delivered as text. Use this skill before proposing changes so that recommendations are grounded in observed state.
+
+## Use When
+- You need to understand what exists before planning a change
+- Diagnosing why a Operator surface behaves unexpectedly
+- Producing an audit report for operator review
+- Checking provider boundary ownership before a team hand-off
+
+## Workflow
+1. Identify the target surface (codebase, runtime state, hooks, plugins, or provider boundaries).
+2. Run the relevant read-only commands in order:
+   - Operator health:
+     ```
+     enact-operator doctor
+     ```
+   - Plugin and hook inventory:
+     ```
+     enact-operator plugins status
+     enact-operator hooks status
+     ```
+   - Provider boundary audit:
+     ```
+     enact-operator audit provider-boundary
+     ```
+   - Replacement readiness:
+     ```
+     enact-operator audit replacement-readiness
+     ```
+   - Task and session state:
+     ```
+     enact-operator task list
+     enact-operator session status
+     ```
+  - For codebase-level exploration, use `enact-context` tools such as `ctx_search`, `ctx_semantic_search`, `ctx_graph`, and `ctx_tree`.
+3. Read relevant state files directly if CLI output is insufficient:
+   - `.enact/operator/state/`
+   - `.enact/operator/sessions/<id>/`
+4. Synthesize findings into a structured report with sections: Summary, Observations, Gaps, Recommendations.
+5. Deliver report as plain text. Do not write it to disk unless the operator explicitly requests an artifact.
+
+## Complex Investigation
+
+If a single read pass cannot answer the question, escalate with a required two-call delegation pattern before concluding.
+
+1. Run one broad, repository-wide call to map candidate surfaces and narrow the search space.
+2. Run one targeted follow-up call scoped to the highest-signal surface from step 1.
+
+Required 2-call escalation/delegation example:
+
+```bash
+# Call 1: broad sweep to locate candidate ownership and state surfaces
+ctx_search query="provider boundary hooks runtime state orchestration" path="."
+
+# Call 2: delegated deep read on the most likely owner from call 1
+ctx_read path="enact-factory/<resolved-file-or-dir>" mode="summary"
+```
+
+Do not skip the second call when the first call returns multiple plausible surfaces.
+
+## State Contract
+- Reads: all `.enact/operator/` state, CLI output from `doctor`, `audit`, `plugins status`, `hooks status`
+- Writes: nothing (read-only mode)
+
+## Commands
+```
+enact-operator doctor
+enact-operator plugins status
+enact-operator hooks status
+enact-operator audit provider-boundary
+enact-operator audit replacement-readiness
+enact-operator task list
+enact-operator session status
+enact-operator hud
+```
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.
+## Final Check
+- No files were modified during this skill's execution
+- Findings are grounded in actual CLI output, not assumptions
+- Report includes a Gaps section if any expected surfaces are missing
+- Recommendations are labeled as recommendations, not implemented changes

package/extensions/enact-operator/skills/ask/SKILL.md

@@ -0,0 +1,47 @@
+---
+name: ask
+description: "Narrow question-answer mode: answer a specific question about Operator state, behavior, or configuration without mutating anything."
+---
+
+# Ask
+
+## Purpose
+Handles a single, scoped question about Operator runtime state, CLI behavior, configuration, or codebase structure. No files are written, no sessions are started, and no state is mutated. If the question requires deep research, delegate to `$autoresearch-goal` rather than expanding scope here.
+
+## Use When
+- The operator has a specific factual question about Operator behavior
+- Clarifying what a CLI command does or what a state file contains
+- Answering "what is the current value of X" without modifying anything
+
+## Workflow
+1. Read the question and determine the minimum set of sources needed to answer it.
+2. Consult available sources in this order:
+   - Operator CLI output (doctor, status, hooks status, plugins status)
+   - `.enact/operator/state/` files (read via `enact-operator state read <key>`)
+   - Source code or configuration files (read-only)
+   - Skill files in `enact-operator/extensions/skills/` for behavioral questions
+3. If the question requires more than a read pass (e.g., multi-file research or external docs), route to `$autoresearch-goal` and stop here.
+4. Compose a direct, specific answer. Include the exact CLI output or file excerpt that supports it.
+5. If the answer reveals a problem, flag it but do not fix it — report only.
+
+## State Contract
+- Reads: CLI output, `.enact/operator/state/`, source and config files as needed
+- Writes: nothing
+
+## Commands
+```
+enact-operator state read <key>
+enact-operator doctor
+enact-operator plugins status
+enact-operator hooks status
+enact-operator session status
+enact-operator task list
+```
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.
+## Final Check
+- Answer is specific and references the source (file path, CLI output, or line reference)
+- No files were written or mutated
+- If the answer cannot be determined from available sources, that is stated explicitly rather than guessed

package/extensions/enact-operator/skills/autopilot/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: autopilot
+description: "Autonomous end-to-end Operator loop: classify intent, plan, execute, verify, and wrap until the requested outcome is complete."
+lane: true
+mcpToolPrefix: operator_autopilot_
+---
+
+# Autopilot
+
+## Purpose
+
+Use `$autopilot` when the user wants unattended end-to-end delivery rather than a single command. Autopilot classifies the incoming request, routes it through the appropriate sub-skills, and drives the work to a verified conclusion without requiring the user to advance each step manually.
+
+Autopilot is not a single command. It is a routing and orchestration wrapper over `$plan`, `$ralph`, `$ultrawork`, and `$team`.
+
+## Use When
+
+- The request is clear enough to execute but spans multiple steps or files
+- The user wants delivery, not a plan to review before proceeding
+- Work needs to continue across pauses without re-explanation
+- Multiple agents or executors would benefit from a shared local task queue
+
+## Do Not Use When
+
+- The request is ambiguous — route through `$deep-interview` first
+- The user wants to review a plan before any execution begins — use `$ralplan`
+- The change is a trivial single-file edit with obvious acceptance criteria
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- drive the workflow through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep session, ralph, ultrawork, task, inbox, and review state current as you go
+- when no external `taskId` is linked, local Operator task discipline is mandatory; autopilot owns a local task and must keep it authoritative
+- do not stop at a partial handoff unless the next owner is explicit
+- if closure criteria exist, resolve them through `operator_contract_parity_run`
+  before declaring success
+
+## Routing Rules
+
+Classify the request before executing:
+
+| Signal | Route |
+|---|---|
+| Ambiguous intent, unclear scope | `$deep-interview` → `$ralplan` |
+| Clear intent, multi-step, single agent sufficient | `$ralph` |
+| Clear intent, high-throughput or parallel work | `$ultrawork` |
+| Clear intent, requires multiple executors or review gates | `$team` |
+| Any route above, needs a durable plan artifact first | `$plan` before execution |
+
+## Workflow
+
+1. Read current Operator state to orient:
+   - MCP: `operator_session_status`, `operator_state_read`, `operator_task_list`
+   - CLI:
+     ```
+     enact-operator session status
+     enact-operator state read
+enact-operator task list   # local Task runtime state
+     ```
+2. Check the HUD for a summary view:
+   - MCP: `operator_hud`
+   - CLI: `enact-operator hud`
+3. Classify the request using the routing table above.
+4. If the request needs a plan artifact, write it to `.enact/operator/plans/` via `$plan` before advancing.
+5. Start the appropriate execution mode:
+   - Single-agent loop:
+     - MCP: `operator_ralph_start` with `goal`
+     - CLI: `enact-operator ralph start "<goal>"`
+   - High-throughput:
+     - MCP: `operator_ultrawork_start` with `goal`
+     - CLI: `enact-operator ultrawork start "<goal>"`
+   - Multi-executor:
+     - MCP: `operator_team_init`, then `operator_team_queue`
+     - CLI fallback: `enact-operator team init && enact-operator team queue "<title>"`
+6. Monitor progress:
+   - MCP: `operator_ralph_status`, `operator_ultrawork_status`, `operator_team_status`, `operator_inbox_list`
+   - CLI:
+     ```
+     enact-operator ralph status
+     enact-operator ultrawork status
+     enact-operator team status
+     enact-operator team inbox
+     ```
+7. Advance through verification gates:
+   - MCP: `operator_ralph_verify` with `gateId` and `status`, `operator_ralph_advance` with `toPhase`
+   - CLI:
+     ```
+     enact-operator ralph verify <gateId> passed --evidence "<text>"
+     enact-operator ralph advance verifying
+     enact-operator ralph advance completed
+     ```
+8. Run `$review` before declaring the work complete.
+9. Close the active mode on success:
+   - MCP: `operator_ralph_complete` with `summary`, `operator_ultrawork_complete`
+   - CLI:
+     ```
+     enact-operator ralph complete
+     enact-operator ultrawork complete
+     ```
+
+## Runtime Clarification
+
+- `$autopilot` is a router/orchestrator with durable task, session, team, and
+  ultrawork state.
+- It must record the concrete delegated runtime (`ralph`, `ultrawork`, `team`,
+  future runtimes) rather than claiming closure itself through narrative only.
+
+## State Contract
+
+Reads:
+- `.enact/operator/state/` (active mode state)
+- `.enact/operator/plans/` (plan and verification map)
+- `.enact/operator/state/tasks.json` (local task tracker and queue state)
+
+Writes:
+- `.enact/operator/plans/<phase>.md` (if plan is created inline)
+- State transitions via ralph, ultrawork, and team MCP tools or CLI commands
+
+## MCP Tools
+
+The full Autopilot lifecycle is driven through the `enact-operator` MCP server:
+
+- `operator_session_start` — start or refresh the session record
+- `operator_session_status` — read current session state
+- `operator_session_resume` — resume an existing session
+- `operator_state_read` — read active operator state
+- `operator_task_list` — list current local tasks (current enumerated MCP surface)
+- `operator_inbox_list` — read the inbox
+- `operator_hud` — summary view of all active modes
+- `operator_ralph_start` — start a ralph loop
+- `operator_ralph_status` — read ralph state
+- `operator_ralph_advance` — transition ralph to a new phase
+- `operator_ralph_verify` — record a gate verdict with evidence
+- `operator_ralph_pause` — pause an active loop
+- `operator_ralph_resume` — resume a paused loop
+- `operator_ralph_block` — mark ralph blocked with a reason
+- `operator_ralph_complete` — close the ralph loop
+- `operator_ralph_abort` — abort the ralph loop
+- `operator_ultrawork_start` — start an ultrawork session
+- `operator_ultrawork_status` — read ultrawork state
+- `operator_ultrawork_advance` — advance the ultrawork session
+- `operator_ultrawork_complete` — close the ultrawork session
+- `operator_ultrawork_abort` — abort the ultrawork session
+- `operator_team_status` — read team session state
+- `operator_team_inbox` — read team inbox
+
+## Activation
+
+When a prompt contains an explicit marker like `$enact-operator:autopilot "<goal>"`
+or `$autopilot "<goal>"`, Operator's UserPromptSubmit hook can start the durable
+Autopilot state before the agent reads its first turn of context. The hook also
+records the invocation in `.enact/operator/state/skill-active.json` and adds an
+MCP-first context note telling the agent to load/search the Enact Operator MCP
+namespace immediately if `operator_*` tools are not visible yet, then prefer
+`operator_*` tools over the `enact-operator` CLI. That injected startup note is
+not AzDo-only: if no external `taskId` is linked, treat the local
+lane task as mandatory runtime state and keep it current through
+`operator_task_list`.
+
+If hooks are unavailable or explicit control is preferred, use
+`operator_operator_activate { skill: 'autopilot', goal: '<goal>' }` and follow the
+returned required action (`operator_autopilot_start` or
+`operator_autopilot_retarget`).
+## Final Check
+
+- The active mode is closed (ralph, ultrawork, or team) — no dangling state
+- Verification gates have evidence, not just a passed status
+- `$review` verdict is approved before work is reported complete
+- `.enact/operator/state/` contains no stale active-mode files

package/extensions/enact-operator/skills/autoresearch-goal/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: autoresearch-goal
+description: "Autoresearch directed at a specific durable goal: findings persist to .enact/operator/research/ and can be linked into ultrawork state."
+---
+
+# Autoresearch Goal
+
+## Purpose
+
+Drives a research cycle that is anchored to a concrete, long-running goal rather than a one-off question. Findings are persisted to `.enact/operator/research/` and linked into ultrawork state so the next session can resume with full context. The research is complete only when the findings are specific enough to drive a concrete implementation or rollout decision.
+
+## Use When
+
+- a goal requires understanding a codebase, API, or system before implementation can begin
+- research must span multiple sessions and accumulate incrementally
+- findings need to be accessible to future execution sessions without re-running the research
+
+## Workflow
+
+1. Define the research goal clearly. It must end in a concrete decision or artifact, not an open-ended survey.
+2. Start durable state for the research session:
+   - MCP: `operator_session_start`
+   - CLI fallback: `enact-operator session start`
+3. Start ultrawork to track the research lane:
+   - MCP: `operator_ultrawork_start`
+   - CLI fallback: `enact-operator ultrawork start "Research: <goal description>" --route plan-only`
+4. Link the research handle into ultrawork:
+   - MCP: `operator_ultrawork_link_research`
+   - CLI fallback: `enact-operator ultrawork link-research <goalId>`
+5. Conduct the research:
+   - use `ctx_search`, `ctx_semantic_search`, `ctx_graph`, and `ctx_tree` for codebase-level investigation
+   - use `operator_audit_provider_boundary` for boundary questions
+   - use external documentation tools for API or SDK questions
+6. Write incremental findings to `.enact/operator/research/<goalId>.md` as the research progresses. Each write appends a dated section.
+7. When findings are sufficient to drive a decision, summarize them in a Conclusion section in the research file.
+8. Record verification evidence for the research pass:
+   - MCP: `operator_ultrawork_verify`
+   - CLI fallback: `enact-operator ultrawork verify "<evidence>"`
+9. When the research goal is met, complete the ultrawork session:
+   - MCP: `operator_ultrawork_complete`
+   - CLI fallback: `enact-operator ultrawork complete "<summary>"`
+
+## Runtime Clarification
+
+- `autoresearch` / `autoresearch-goal` remain future lane candidates, not
+  current exposed AzDo runtime values.
+- If research is being used as closure evidence for a live task, prefer the
+  real parity/hygiene surfaces over narrative-only conclusions:
+  - `operator_contract_parity_run`
+  - `operator_workflow_reconcile`
+  - `operator_operator_snapshot`
+
+## State Contract
+
+- reads: codebase files, CLI output, external docs
+- writes:
+  - `.enact/operator/research/<goalId>.md`
+  - ultrawork session state via `operator_ultrawork_*`
+
+## Commands
+
+```
+enact-operator session start
+enact-operator ultrawork start "Research: <goal description>" --route plan-only
+enact-operator ultrawork link-research <goalId>
+enact-operator ultrawork verify "<evidence>"
+enact-operator ultrawork complete "<summary>"
+enact-operator audit provider-boundary
+```
+
+## Activation
+
+When a prompt contains `$enact-operator:<skill-name>` or `$<skill-name>`, Operator's UserPromptSubmit hook records the invocation in `.enact/operator/state/skill-active.json` and adds an MCP-first context note for the agent. That note tells the agent to load/search the Enact Operator MCP namespace immediately if `operator_*` tools are not visible yet, then prefer `operator_*` tools over the `enact-operator` CLI. This skill is operator-driven — there is no durable workflow state to start automatically. The activation log gives operators and the HUD a trace of which skills were explicitly invoked.
+## Final Check
+
+- `.enact/operator/research/<goalId>.md` contains a Conclusion section with a concrete decision or recommendation
+- ultrawork session is verified or completed, not left dangling
+- research artifact is linked to ultrawork state
+- no research session is left active across context boundaries without recorded evidence