@amsterdamdatalabs/enact-extensions 0.1.1 → 0.1.3

package/extensions/enact-operator/skills/ralph/gemini.md

@@ -0,0 +1,18 @@
+# Ralph (Gemini Variant)
+
+You are running Ralph with a Gemini model identity.
+
+Keep the same durable runtime contract as the default Ralph skill:
+
+- drive the goal to completion with real state updates
+- record evidence for every mandatory gate
+- fail closed when evidence is missing or contradictory
+- do not claim completion until all required gates are passed
+
+## TOOL_CALL_MANDATE
+
+- keep tool usage explicit, short, and sequential
+- prefer direct MCP/tool results over narrative summaries
+- when a gate depends on a command or runtime check, run it first and cite the result
+- if a required tool is not visible, load/search the operator MCP namespace before continuing
+- do not substitute inferred status for tool-backed evidence

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

@@ -0,0 +1,151 @@
+---
+name: ralplan
+description: "Plan-first Operator execution wrapper: write a durable plan, enter the Ralph loop, drive to verified completion."
+lane: true
+mcpToolPrefix: operator_ralplan_
+---
+
+# Ralplan
+
+## Purpose
+
+Use `$ralplan` when the work needs a reviewable execution plan before the Ralph loop starts. Ralplan is the disciplined alternative to `$autopilot` — it gates execution behind a plan the user or reviewer can inspect, then advances into Ralph's self-referential loop with explicit verification checkpoints.
+
+Ralplan is the combination of `$plan` (write artifacts, define slices and verification) and `$ralph` (durable execution loop with phase gates). Neither sub-skill is optional.
+
+## Use When
+
+- The request is clear enough to plan but carries meaningful risk or complexity
+- A written plan artifact needs to exist before any code changes
+- Verification gates need to be defined up front, not discovered mid-execution
+- The user wants to review the plan before execution begins
+
+## Do Not Use When
+
+- The request is still ambiguous — route through `$deep-interview` first, then return here
+- The work is trivial and a plan would add no value
+- The user explicitly wants unattended delivery without a plan review — use `$autopilot`
+
+## 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 ralph, task, and review state current as you go
+- do not advance to the Ralph loop before the plan artifact exists and is reviewed
+
+## Lifecycle
+
+```
+intent → $plan (write plan + verification map) → user review → $ralph start → running → verifying → completed
+```
+
+Each transition is explicit. Never advance to the Ralph loop before the plan artifact exists and is reviewed.
+
+## Workflow
+
+### Phase 1 — Plan
+
+1. Read current Operator artifacts:
+   - MCP: `operator_session_status`, `operator_state_read`
+   - CLI:
+     ```
+     enact-operator session status
+     enact-operator state read
+     ```
+2. Write the plan to `.enact/operator/plans/<phase>.md` following `$plan` conventions:
+   - Named files per slice
+   - Explicit verification per slice
+   - Exit conditions stated
+3. Write the verification map to `.enact/operator/plans/<phase>-verification.md`.
+4. Link the plan artifact to ultrawork if an ultrawork session is active:
+   - MCP: `operator_ultrawork_link_plan` with the plan id
+5. Present the plan for review. Do not advance until it is approved.
+
+### Phase 2 — Execute
+
+6. Start the Ralph loop with the goal and verification gates from the plan:
+   - MCP: `operator_ralph_start` with `goal`
+   - CLI: `enact-operator ralph start "<goal>" --gate g1:"<Gate Name>" --gate g2:"<Gate Name>"`
+7. Confirm Ralph is running:
+   - MCP: `operator_ralph_status`
+   - CLI: `enact-operator ralph status`
+8. Execute each plan slice. After each slice, record evidence:
+   - MCP: `operator_ralph_verify` with `gateId` and `status=passed`
+   - CLI: `enact-operator ralph verify <gateId> passed --evidence "<evidence text>"`
+9. If blocked, record the blocker and pause:
+   - MCP: `operator_ralph_block` with reason, then `operator_ralph_pause`
+   - CLI:
+     ```
+     enact-operator ralph block --note "<reason>"
+     enact-operator ralph pause
+     ```
+   Resolve the block, then resume:
+   - MCP: `operator_ralph_resume`
+   - CLI: `enact-operator ralph resume`
+
+### Phase 3 — Verify and Complete
+
+10. When all gates have evidence, advance to the verifying phase:
+    - MCP: `operator_ralph_advance` with `toPhase=verifying`
+    - CLI: `enact-operator ralph advance verifying`
+11. Run `$review` against the completed work and plan artifacts.
+12. If review passes, complete the Ralph session:
+    - MCP: `operator_ralph_complete` with `summary`
+    - CLI: `enact-operator ralph complete`
+13. If review returns changes requested, advance back to running and address findings:
+    - MCP: `operator_ralph_advance` with `toPhase=running`
+    - CLI: `enact-operator ralph advance running --note "<what changed>"`
+
+## State Contract
+
+Reads:
+- `.enact/operator/plans/` (plan and verification map written in Phase 1)
+- `.enact/operator/state/ralph-state.json` (Ralph loop state)
+
+Writes:
+- `.enact/operator/plans/<phase>.md`
+- `.enact/operator/plans/<phase>-verification.md`
+- Ralph state via MCP tools or CLI commands
+
+## MCP Tools
+
+- `operator_session_status` — read current session state
+- `operator_state_read` — read active operator state
+- `operator_ralph_start` — start a new ralph loop with goal and gates
+- `operator_ralph_status` — read current ralph state
+- `operator_ralph_advance` — transition to a new phase
+- `operator_ralph_verify` — record a gate verdict with evidence
+- `operator_ralph_block` — mark blocked with a reason
+- `operator_ralph_pause` — pause the active loop
+- `operator_ralph_resume` — resume a paused loop
+- `operator_ralph_complete` — close the loop with a summary
+- `operator_ralph_abort` — abort the loop with a reason
+- `operator_ultrawork_link_plan` — link the plan artifact to an active ultrawork session
+
+## Commands
+
+```
+enact-operator session status
+enact-operator state read
+enact-operator ralph start "<goal>" --gate <id>:<name>
+enact-operator ralph status
+enact-operator ralph advance <phase>
+enact-operator ralph verify <gateId> passed --evidence "<text>"
+enact-operator ralph verify <gateId> failed --evidence "<text>"
+enact-operator ralph block --note "<reason>"
+enact-operator ralph pause
+enact-operator ralph resume
+enact-operator ralph complete
+enact-operator ralph abort
+```
+
+## 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
+
+- Plan artifact exists at `.enact/operator/plans/<phase>.md` before Ralph was started
+- All verification gates have evidence recorded, not just a passed status
+- `$review` verdict is approved
+- `operator_ralph_status` shows phase as `completed`
+- No stale Ralph state file remains active under `.enact/operator/state/`

package/extensions/enact-operator/skills/remove-deadcode/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: remove-deadcode
+description: "LSP-verified symbol deletion with entry-point guards and candidate-parallel execution."
+---
+
+# Remove Deadcode
+
+## Purpose
+
+Use `$remove-deadcode` to remove provably unused code symbols without damaging runtime entry points.
+
+## Preconditions
+
+- collect candidate symbols before any deletion
+- load optional entry-point guard list from `.enact/operator/remove-deadcode/entry-points.txt`
+
+## Required Safety Contract
+
+For each candidate symbol, the deletion gate is strict:
+
+1. If symbol is listed in the entry-point guard file, skip deletion unconditionally.
+2. Otherwise call `lsp_find_references` (via enact-context).
+3. If references are non-empty, abort deletion for that symbol and emit an explanatory message.
+4. Only delete when references are exactly zero and the symbol is not guarded.
+
+## Execution Model
+
+- batching is explicit: enumerate all candidates first
+- then dispatch parallel `executor` subagents, one candidate per subagent
+- each subagent must apply the same guard-list and `lsp_find_references` checks
+
+## Behavioral Constraints
+
+- no heuristic-only deletion
+- no bypass of entry-point guard list
+- no GitHub-specific assumptions or workflows in deletion decisions
+
+## Verification Expectations
+
+- unit test: non-empty `lsp_find_references` result must refuse deletion
+- unit test: guard-listed symbol must be skipped even when reference count is zero
+
+## 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.

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

@@ -0,0 +1,74 @@
+---
+name: research
+description: "Evidence-first research mode for current patterns, implementation risks, and decision support."
+---
+
+# Research
+
+## Purpose
+
+Use `$research` when the correct implementation depends on facts you do not yet have, either from the repo or from current external sources.
+
+## Execution Policy
+
+- start with brownfield evidence from the repo
+- use primary sources for technical questions
+- end with a decision-ready recommendation, not a wall of notes
+- persist findings so the next pass does not repeat the work
+
+## Workflow
+
+1. Identify the actual unknowns.
+2. Separate:
+   - repo truth
+   - external truth
+   - assumptions
+3. Gather only the evidence needed to decide.
+4. Write the result into `.enact/operator/research/summary.md`.
+5. Update any linked ultrawork or task state if the research is part of an active execution lane.
+
+## Parallel Sweep
+
+Run concurrent research agents for independent evidence lanes. The floor is 2 concurrent agents whenever there are both repo-truth and external-truth unknowns.
+
+- minimum concurrent-agent floor: 2
+- recommended split: one agent for internal repo evidence and one agent for external primary sources
+- increase concurrency only when unknowns are independent and synthesis cost remains manageable
+
+Anti-stop rule: do not stop at the first result. Continue each lane until at least one corroborating source is collected per lane, or until an explicit blocker is documented.
+
+## Runtime Clarification
+
+- `$research` is an evidence pass, not a currently exposed closure-owning
+  runtime lane.
+- If research output is being used to support closure on a live task, rely
+  on the real Operator proof surfaces rather than treating research notes as
+  equivalent to parity evidence:
+  - `operator_contract_parity_run`
+  - `operator_workflow_reconcile`
+  - `operator_operator_snapshot`
+
+## Deliverables
+
+- current pattern or contract summary
+- risk list
+- recommendation with concrete tradeoffs
+- open questions that still block planning or execution
+
+### Internal Evidence
+
+- repo paths inspected
+- commands or tools used
+- concrete findings tied to files, code, or runtime state
+- unresolved internal gaps
+
+### External Evidence
+
+- primary sources consulted
+- dated facts and version-sensitive constraints
+- corroboration across at least one additional source
+- unresolved external gaps
+
+## 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.

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

@@ -0,0 +1,58 @@
+---
+name: review
+description: "Findings-first pre-landing review against code, plan completion, verification evidence, and durable runtime state."
+---
+
+# Review
+
+## Purpose
+
+Use `$review` to answer one question: is this actually ready to land? Review is not a summary pass. It is a bug, regression, coverage, and state-integrity pass.
+
+## Execution Policy
+
+- findings first, summary second
+- prefer evidence over author claims
+- check the code, the tests, the plan, and the runtime artifacts
+- if the current context authored the change, prefer a separate reviewer role for approval
+
+## Review Order
+
+1. Read the changed code.
+2. Read the active plan and verification map.
+3. Check what was supposed to happen vs what actually landed.
+4. Verify:
+   - tests and typechecks
+   - docs drift
+   - `.enact/operator/` state drift
+   - task, review, inbox, and ledger accuracy
+5. Produce a verdict:
+   - approved
+   - changes requested
+   - blocked
+
+## Mandatory Checks
+
+- missing or fake verification
+- uncovered changed paths
+- stale docs or setup instructions
+- task marked done but still pending review evidence
+- runtime claiming health while inbox or review queue says otherwise
+
+## Recommended State Reads
+
+- `operator_reviews_list`
+- `operator_inbox_list`
+- `operator_ledger_recent`
+- `operator_hud`
+
+## Output Standard
+
+- findings ordered by severity
+- file references and why they matter
+- residual risk
+- final verdict and next action
+
+## 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.

package/extensions/enact-operator/skills/security-research/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: security-research
+description: "Multi-agent security research with hunter/PoC split and optional critical bug auto-creation in Azure DevOps."
+---
+
+# Security Research
+
+## Purpose
+
+Use `$security-research` to run a focused vulnerability hunt, produce ranked findings, and optionally create Azure DevOps Bug work items for critical issues.
+
+## Parameters
+
+- `autoCreateBugs: boolean` (default `true`)
+- when `false`, no `factory_workitem_sync_once` call is allowed regardless of severity
+
+## Team Topology
+
+- 3 hunter agents:
+- hunter 1: CWE classification
+- hunter 2: CVSS v4 scoring
+- hunter 3: OWASP category mapping
+- 2 PoC engineer agents:
+- PoC 1 and PoC 2: exploitability proof and reproduction quality
+
+## Required Workflow
+
+1. Launch hunters to identify and classify potential vulnerabilities.
+2. Launch PoC engineers on top-ranked findings to validate exploitability.
+3. Merge outputs into a single findings report.
+4. Write report to `.enact/operator/security/<sessionId>/findings.md`.
+5. Rank findings in the report by CVSS v4 severity.
+6. For each finding with CVSS v4 `>= 9.0`, if `autoCreateBugs=true`, call `factory_workitem_sync_once` to create a `Bug` work item.
+7. If `autoCreateBugs=false`, skip all bug auto-creation calls.
+
+## Azure DevOps-Only Contract
+
+- use factory MCP work-item surfaces for bug creation
+- no GitHub Security Advisories, GitHub issue creation, or GitHub-specific security automation assumptions
+
+## Behavioral Constraints
+
+- CVSS scoring must be v4, not v3 fallback
+- critical auto-bug creation threshold is fixed at `>= 9.0`
+- findings must include at least one of: CWE, CVSS v4 vector/score, OWASP mapping
+
+## Verification Expectations
+
+- integration test: findings report includes at least one CWE classification entry
+- integration test: with `autoCreateBugs=false`, verify no `factory_workitem_sync_once` call is made
+
+## 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.

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

@@ -0,0 +1,91 @@
+---
+name: enact-operator-setup
+description: "Initialize the Enact Operator control-plane: install the enact-operator CLI if needed, then install hooks and agents and verify the runtime is healthy."
+---
+
+# Enact Operator Setup
+
+## Runtime Prerequisite
+
+Before running the workflow, make sure the `enact-operator` CLI exists:
+
+```bash
+which enact-operator || bash scripts/install.sh
+```
+
+## Purpose
+Bootstraps a project to use Enact Operator by laying out the `.enact/operator/` directory tree and installing Operator hooks and agents. Plugin installation and host registry ownership belongs to enact-extensions.
+
+## Use When
+- First-time installation of enact-operator in a project
+- Reinstalling after a version bump or broken hook state
+- Validating that an existing installation is coherent before running team or staged review workflows
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- if `operator_*` tools are not visible yet, load/search the Enact Operator MCP namespace before running setup/readiness checks
+- drive setup through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep state current as you go — confirm each step before advancing
+
+## Workflow
+1. Run the top-level installer:
+   - MCP: `operator_setup`
+   - CLI: `enact-operator setup`
+2. Install Claude Code hooks (pre/post tool hooks that integrate with the operator runtime):
+   - No MCP tool for hooks install — use CLI: `enact-operator hooks install`
+3. Check hook registration status:
+   - MCP: `operator_hooks_status`
+   - CLI: `enact-operator hooks status`
+4. Install the Core 7 Codex agent roster into the project:
+   - MCP: `operator_agents_pack_install`
+   - CLI: `enact-operator agents install-pack`
+5. Validate the plugin bundle source is coherent (skills, hooks, agents all present):
+   - MCP: `operator_plugin_validate`
+   - CLI: `enact-operator plugins validate`
+6. Check the install registry for operator-owned hooks and agents:
+   - MCP: `operator_install_registry`
+   - CLI: (no direct equivalent — use `operator_install_registry`)
+7. Run the doctor to confirm runtime health:
+   - MCP: `operator_doctor`
+   - CLI: `enact-operator doctor`
+8. Check replacement-readiness to confirm Operator is ready to take over provider roles:
+   - MCP: `operator_audit_replacement_readiness`
+   - CLI: `enact-operator audit replacement-readiness`
+
+## State Contract
+- Reads: project root, existing `.claude/settings.json`, existing hook files
+- Writes: `.enact/operator/` directory tree (`cache`, `jobs`, `logs`, `memory`, `plans`, `reports`, `research`, `sessions`, `state`, `team`, `ultragoal`, `metrics.json`), hook entries in `.claude/settings.json`
+
+## MCP Tools
+
+- `operator_setup` — run the top-level installer
+- `operator_hooks_status` — verify hook registration state
+- `operator_agents_install` — install individual agent templates
+- `operator_agents_pack_install` — install the full Core 7 Codex agent roster
+- `operator_plugin_validate` — check plugin bundle source coherence
+- `operator_install_registry` — read the install registry
+- `operator_doctor` — confirm runtime health
+- `operator_audit_replacement_readiness` — confirm Operator is ready to take over provider roles
+
+Note: hooks install has no MCP equivalent — use `enact-operator hooks install` via CLI.
+
+## Commands
+```
+enact-operator setup
+enact-operator hooks install
+enact-operator hooks status
+enact-operator agents install-pack
+enact-operator plugins validate
+enact-operator doctor
+enact-operator audit replacement-readiness
+```
+
+## 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
+- `operator_doctor` (or `enact-operator doctor`) reports no errors
+- `operator_plugin_validate` reports the enact-operator source bundle is valid
+- `operator_hooks_status` shows all required hooks registered
+- `.enact/operator/` directory exists with expected subdirectories

package/extensions/enact-operator/skills/setup/scripts/install.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="@amsterdamdatalabs/enact-operator"
+BIN_NAME="enact-operator"
+
+already_installed() {
+    command -v "${BIN_NAME}" >/dev/null 2>&1
+}
+
+require_npm() {
+    if command -v npm >/dev/null 2>&1; then
+        return 0
+    fi
+
+    echo "ERROR: npm is required to install ${PACKAGE_NAME}." >&2
+    echo "Install Node.js + npm from https://nodejs.org/ and rerun this script." >&2
+    exit 1
+}
+
+install_cli() {
+    echo "Installing ${PACKAGE_NAME} via npm..."
+    npm install -g "${PACKAGE_NAME}"
+}
+
+main() {
+    if already_installed; then
+        local current
+        current="$(${BIN_NAME} --version 2>/dev/null | head -1 || echo 'unknown')"
+        echo "${BIN_NAME} already installed: ${current}"
+        echo "Run '${BIN_NAME} setup' in your repo to initialize Operator state."
+        exit 0
+    fi
+
+    require_npm
+    install_cli
+
+    if ! already_installed; then
+        echo "ERROR: ${BIN_NAME} was installed but is not on PATH." >&2
+        echo "Open a new shell or update your npm global bin PATH, then rerun '${BIN_NAME} --version'." >&2
+        exit 1
+    fi
+
+    local current
+    current="$(${BIN_NAME} --version 2>/dev/null | head -1 || echo 'unknown')"
+    echo "${BIN_NAME} installed: ${current}"
+    echo "Next step: run '${BIN_NAME} setup' in the target workspace."
+}
+
+main "$@"

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

@@ -0,0 +1,82 @@
+---
+name: skill
+description: "Meta-skill: list, discover, and route to available Operator skills. Use when the operator wants to know what skills exist or which skill handles a given task."
+---
+
+# Skill
+
+## Purpose
+Provides a navigable index of all skills available in the enact-operator plugin. When the operator asks "what can Operator do?" or "which skill should I use for X?", this skill answers by listing the catalog and routing to the correct skill. It does not execute work itself.
+
+## Use When
+- The operator wants to see all available Operator skills
+- Choosing between skills for a given task type
+- Checking whether a skill exists before invoking it
+- Auditing the plugin's skill surface for completeness
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- drive discovery through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- this skill is read-only — it writes nothing
+
+## Workflow
+1. List all source skills in the operator bundle:
+   - MCP: `operator_plugin_list`
+   - CLI: `ls enact-operator/extensions/skills/`
+
+   Plugin installation and host registry state are owned by enact-extensions.
+
+2. For a raw directory listing of skill names:
+   ```
+   ls enact-operator/extensions/skills/
+   ```
+
+3. To validate that all skill files are well-formed:
+   ```
+   enact-operator plugins validate
+   ```
+
+4. To read a specific skill's playbook, open its `SKILL.md` directly:
+   ```
+   enact-operator/extensions/skills/<skill-name>/SKILL.md
+   ```
+
+5. Route the operator to the correct skill based on their task:
+
+   | Task type | Skill |
+   |-----------|-------|
+   | First-time install or reinstall | `$setup` |
+   | Durable multi-executor implementation flow | `$team` |
+   | Single executor execution lane | `$executor` |
+   | Long-horizon multi-session goal | `$ultragoal` |
+   | QA cycling with hard-stop gates | `$ultraqa` |
+   | Remove TODO/placeholder noise | `$ai-slop-cleaner` |
+   | Read-only investigation | `$analyze` |
+   | Specific factual question | `$ask` |
+   | Research anchored to a goal | `$autoresearch-goal` |
+   | Stop all active modes | `$cancel` |
+   | Findings-first review | `$review` |
+   | Notification preferences | `$configure-notifications` |
+   | Wiki/reference lookup | `$wiki` |
+
+## State Contract
+- Reads: `enact-operator/extensions/skills/` directory, `operator_plugin_list` output
+- Writes: nothing
+
+## MCP Tools
+
+- `operator_plugin_list` — list local operator plugin bundle sources
+
+## Commands
+```
+enact-operator plugins validate
+```
+
+## 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
+- All skills listed in the routing table are present in `enact-operator/extensions/skills/`
+- `enact-operator plugins validate` passes with no errors
+- The operator was routed to a specific skill, not left with a general answer