@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

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

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

@@ -0,0 +1,99 @@
+---
+name: cancel
+description: "Explicit termination of any active Operator mode (ralph, ultrawork, team). Cleans up state and leaves no dangling sessions."
+---
+
+# Cancel
+
+## Purpose
+Stops all active Operator execution modes cleanly. Each running mode (ralph loops, ultrawork sessions, team sessions) must be explicitly aborted or shut down — not just ignored. After cancel completes, no session remains in a running, claimed, or paused state.
+
+## Use When
+- A ralph loop, ultrawork session, or team session must be stopped before it completes
+- A session is stuck, blocked indefinitely, or no longer relevant
+- The operator wants a clean slate before starting a new workflow
+
+## 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 doing cancellation work
+- drive cancellation through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep state current as you go — confirm each abort before moving to the next mode
+
+## Lifecycle
+
+### Step 1 — Inventory active modes
+Check each execution surface for active state:
+- MCP: `operator_ralph_status`, `operator_ultrawork_status`, `operator_team_status`
+- CLI:
+  ```
+  enact-operator ralph status
+  enact-operator ultrawork status
+  enact-operator team status
+  ```
+
+### Step 2 — Cancel ralph loops
+For each loop returned by ralph status that is not already complete:
+- MCP: `operator_ralph_abort` with `reason`
+- CLI: `enact-operator ralph abort <loopId>`
+
+### Step 3 — Cancel ultrawork sessions
+For each session returned by ultrawork status that is not already complete:
+- MCP: `operator_ultrawork_abort` with `reason`
+- CLI: `enact-operator ultrawork abort <sessionId>`
+
+### Step 4 — Shut down team sessions
+For each team session returned by team status that is live:
+- MCP: `operator_team_shutdown`
+- CLI fallback: `enact-operator team shutdown`
+
+### Step 5 — Verify clean state
+Re-run each status command and confirm no active sessions remain:
+- MCP: `operator_ralph_status`, `operator_ultrawork_status`, `operator_team_status`
+- CLI:
+  ```
+  enact-operator ralph status
+  enact-operator ultrawork status
+  enact-operator team status
+  ```
+
+### Step 6 — Confirm with doctor
+- MCP: `operator_doctor`
+- CLI: `enact-operator doctor`
+
+## State Contract
+- Reads: active session IDs from ralph status, ultrawork status, team status
+- Writes: abort/shutdown records in `.enact/operator/state/` (managed by MCP tools or CLI commands)
+- Does NOT delete `.enact/operator/` audit history unless the operator explicitly requests it
+
+## MCP Tools
+
+- `operator_ralph_status` — read current ralph state
+- `operator_ralph_abort` — abort a ralph loop with a reason
+- `operator_ultrawork_status` — read current ultrawork state
+- `operator_ultrawork_abort` — abort an ultrawork session with a reason
+- `operator_team_status` — read current team session state
+- `operator_doctor` — confirm runtime health after cancellation
+
+Prefer `operator_team_shutdown` when the Operator MCP namespace is available. The CLI remains a fallback operator surface.
+
+## Commands
+```
+enact-operator ralph status
+enact-operator ralph abort <loopId>
+enact-operator ultrawork status
+enact-operator ultrawork abort <sessionId>
+enact-operator team status
+enact-operator team shutdown
+enact-operator doctor
+```
+
+## 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_ralph_status` shows no loops in `running` or `paused` state
+- `operator_ultrawork_status` shows no sessions in `running` or `blocked` state
+- `operator_team_status` shows no active team session
+- `operator_doctor` reports clean
+- Audit history in `.enact/operator/` is intact unless operator requested a clear

package/extensions/enact-operator/skills/configure-notifications/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: configure-notifications
+description: "Operator-level notification configuration: read and write .enact/operator/state/notifications.json to control Operator runtime visibility."
+---
+
+# Configure Notifications
+
+## Purpose
+Manages operator notification preferences for Operator runtime events. Notification configuration is stored in `.enact/operator/state/notifications.json`. This skill reads the current config, applies the requested changes, and verifies that Operator health is unaffected. There is no dedicated CLI command for notifications yet; this skill is operator-driven via direct file editing.
+
+## Use When
+- The operator wants to change which Operator events trigger notifications
+- Notification delivery is broken or generating noise and needs to be adjusted
+- Setting up notification preferences for the first time in a new project
+
+## Workflow
+1. Read the current notification configuration:
+   ```
+   enact-operator state read notifications
+   ```
+   If no file exists, the default is all events enabled.
+
+2. Identify the notification contract. The file at `.enact/operator/state/notifications.json` is the operator's truth. Its shape:
+   ```json
+   {
+     "events": {
+       "ralph.complete": true,
+       "ralph.fail": true,
+       "ultrawork.complete": true,
+       "ultrawork.block": true,
+       "team.task.complete": true,
+       "team.task.blocked": true,
+       "doctor.fail": true
+     },
+     "delivery": {
+       "console": true,
+       "hud": true
+     }
+   }
+   ```
+
+3. Edit `.enact/operator/state/notifications.json` with the requested changes.
+
+4. Verify the configuration is valid JSON (no trailing commas, well-formed):
+   ```
+   node -e "JSON.parse(require('fs').readFileSync('.enact/operator/state/notifications.json','utf8'))"
+   ```
+
+5. Run doctor to confirm Operator runtime is unaffected:
+   ```
+   enact-operator doctor
+   ```
+
+6. Check the HUD to confirm visibility settings reflect the new configuration:
+   ```
+   enact-operator hud
+   ```
+
+## State Contract
+- Reads: `.enact/operator/state/notifications.json`
+- Writes: `.enact/operator/state/notifications.json`
+
+## Commands
+```
+enact-operator state read notifications
+enact-operator doctor
+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
+- `.enact/operator/state/notifications.json` is valid JSON
+- Requested event flags match the operator's intent
+- `enact-operator doctor` passes after the edit
+- `enact-operator hud` reflects updated visibility settings