@amsterdamdatalabs/enact-extensions 0.1.1 → 0.1.3

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

@@ -0,0 +1,59 @@
+---
+name: tdd
+description: "Red-green-refactor mode for behavior with clear inputs, outputs, and regression value."
+---
+
+# TDD
+
+## Purpose
+
+Use `$tdd` when behavior can be specified before implementation. TDD is for design pressure and regression safety, not for ritual.
+
+## Good TDD Candidates
+
+- business rules
+- API contracts
+- parsing, formatting, or validation
+- state transitions
+- algorithms and utility behavior
+
+## Skip TDD For
+
+- pure layout and styling work
+- config-only changes
+- trivial glue code
+- exploratory prototypes where behavior is not yet known
+
+## Iron Law
+
+No production code without a failing test first.
+
+## Cycle
+
+1. Red
+   - write the smallest failing test for the next behavior
+   - run it and prove it fails for the right reason
+2. Green
+   - write the minimum code to make it pass
+   - rerun the test and the relevant suite
+3. Refactor
+   - clean up only after green
+   - keep the suite green after every change
+
+## Rules
+
+- one behavior per cycle
+- do not batch multiple features into one red-green pass
+- prefer regression tests for changed behavior
+- record the verify command in the plan or task notes
+
+## Output Standard
+
+- what behavior the test locked in
+- the failing signal
+- the minimal implementation
+- the final verification command
+
+## 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/team/SKILL.md

@@ -0,0 +1,199 @@
+---
+name: team
+description: "Durable multi-executor orchestration with queueing, claims, inbox, review gates, and tmux-aware lifecycle control."
+lane: true
+mcpToolPrefix: operator_team_
+---
+
+# Team
+
+## Purpose
+
+`$team` is the durable execution mode. Use it when you need a shared queue, executor leases, review handoffs, and a runtime that survives beyond one reasoning burst.
+
+## Team vs Native Fanout
+
+- use native subagents for small, in-session parallelism
+- use `$team` when the work needs durable state, tmux executors, inbox coordination, resumability, or explicit review gates
+
+## Use When
+
+- the work splits into parallel slices
+- one operator needs durable coordination and review history
+- tasks need claims, heartbeats, inbox messages, and resumable state
+
+## Do Not Use When
+
+- the task is sequential and small
+- there is no meaningful slice boundary
+- the cost of queueing and review would exceed the value of parallelism
+
+## Preconditions
+
+Before launching team mode:
+
+1. the current task has a clear objective
+2. the first slices are identifiable
+3. the likely file areas are known
+4. there is a verify path
+
+If those are missing, run `$deep-interview`, `$trace`, or `$plan` first.
+
+## Runtime Contract
+
+- if `operator_*` tools are not visible yet, load/search the Enact Operator MCP namespace before doing team work
+- initialize with `operator_team_init`
+- queue work with `operator_team_queue`
+- claim with executor ids via `operator_team_claim`
+- complete into review with `operator_team_complete`, never straight to done
+- record review decisions with `operator_team_review`
+- use `operator_team_inbox`, `operator_team_logs`, `operator_team_status`, and `operator_hud` to monitor real progress
+- shut down only after terminal state or explicit abort via `operator_team_shutdown`
+- for every `operator_team_*` call, `root` means the repository root that owns `.enact/operator`
+  - it is **not** the task subdirectory
+  - task subdirectories are for code edits and verification only
+- during bootstrap, use sequential MCP calls
+  - first confirm `operator_team_status`
+  - then `operator_team_init` if absent
+  - only after that move to queue / claim / complete / review
+- when no external `taskId` exists, local Operator task discipline is mandatory
+  - queue or bootstrap the first local task immediately
+  - claim, review, and close by local `taskId`
+- current MCP note: some lifecycle calls still carry that local task id in a `taskId` field
+  - do not defer tracker ownership to AzDo
+- executor semantics are team-internal and are not a separate callable skill:
+  - executor is the team-internal execution lane, not a root skill
+  - executor claims exactly one task at a time
+  - executor sends regular heartbeats while active
+  - executor reports completion with non-empty summary
+  - blocked work must be reported explicitly (`BLOCKED: ...`)
+
+## Proof And Closure
+
+- `$team` is a current operator lane and should use real Operator proof
+  surfaces when its work contributes to closure:
+  - `operator_contract_parity_run`
+  - `operator_workflow_reconcile`
+  - `operator_operator_snapshot`
+  - `operator_hud`
+- `contract-parity` should be read from the real gate output, not inferred from
+  queue state or reviewer prose alone.
+- Provider note: Operator may use its adapter over the running
+  `enact-context` server for proof. That is expected and preferable to
+  duplicating analysis in team-local logic.
+
+## Lifecycle
+
+1. Launch the runtime and inspect backend health.
+2. Queue explicit slices, not vague goals.
+3. Ensure every local task claim maps to a real executor id.
+4. Keep heartbeats and logs current.
+5. Move completions into review with a concrete handoff note.
+6. Monitor:
+   - MCP only: `operator_team_init`, `operator_team_status`, `operator_team_spawn`, `operator_team_claim`, `operator_team_heartbeat`, `operator_team_complete`, `operator_team_review`, `operator_team_inbox`, `operator_team_logs`, `operator_team_resume`, `operator_team_shutdown`, `operator_hud`
+7. Shutdown only when active work is terminal or the user wants an abort.
+
+## Closure Protocol
+
+Use this exact closeout order with the current live `operator_team_*` MCP tools:
+
+1. Confirm no in-flight executor work:
+   - `operator_team_status`
+2. Verify task queue is terminal (no `queued` or `claimed` tasks remain):
+   - `operator_team_task_list`
+3. Ensure task completions and reviewer notes are persisted:
+   - `operator_team_complete`
+   - `operator_team_review`
+4. Run shutdown:
+   - `operator_team_shutdown`
+5. Re-check there is no active team:
+   - `operator_team_status`
+
+Do not use non-existent shutdown lifecycle tools (for example `shutdown_request`, `shutdown_approve`, or `shutdown_delete`). The active shutdown surface is `operator_team_shutdown`.
+
+## Root semantics
+
+When the task says “work inside `<path>`”, separate two concepts:
+
+1. **Operator root**
+   - the repository root that owns `.enact/operator`
+   - this is the value passed as `root` to `operator_team_*`
+2. **Task workspace**
+   - the subdirectory where code changes happen
+   - this is where file reads/edits and verification commands should run
+
+Do not point `operator_team_status`, `operator_team_init`, or any other
+`operator_team_*` call at the task subdirectory unless that subdirectory itself
+owns a separate `.enact/operator`.
+
+## Degraded Mode
+
+If tmux is missing, the runtime may fall back to mock mode. That is acceptable for state flow and testing, not as proof of real detached-executor behavior.
+
+## Rules
+
+- no silent completions
+- no review without a readable result note
+- no shutdown while work is still active unless aborting
+- no CLI fallback for lifecycle operations; use the `operator_team_*` MCP surface
+- prefer runtime/state MCP tools over ad-hoc pane hacking
+
+## 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. When no external `taskId` exists, the injected note also means local Operator task discipline is mandatory: queue the first local task immediately and keep queue/review state authoritative in Operator. 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.
+
+Team-driven activation is a separate path: observe/MCP should start the runtime directly with `operator_team_init`, not through `operator_operator_activate`.
+
+
+# Executor (team-internal role)
+
+This page captures the in-team **executor** semantics for the `team` runtime.
+It is reference-only documentation and **not** a standalone callable skill.
+
+Within `$team`, executor-capable work is carried by claimed executor lanes and
+coordinated by team mechanics (spawn, claim, heartbeat, acknowledge, complete).
+
+## Purpose
+
+An executor is the in-team assignee for a single task slice inside a team session.
+The executor claims one task at a time, maintains heartbeat cadence, and
+reports completion or explicit blockage.
+
+## Workflow
+
+1. Check available tasks:
+   - `operator_team_status`
+2. Claim a task:
+   - `operator_team_claim`
+3. Keep heartbeat cadence (typically every 60 seconds):
+   - `operator_team_heartbeat`
+4. Report for clarification or status updates:
+   - `operator_team_message`
+5. Acknowledge injected instructions after applying them:
+   - `operator_team_message_ack`
+6. Complete with summary:
+   - `operator_team_complete`
+7. Report blocked work explicitly:
+   - `operator_team_complete` with a `BLOCKED: ...` summary
+8. Check inbox for operator instructions:
+   - `operator_team_inbox`
+9. Check execution context:
+   - `operator_team_logs`
+
+Example acknowledgement call:
+
+```json
+{
+  "tool": "operator_team_message_ack",
+  "root": "/path/to/repo-root",
+  "executorId": "executor",
+  "messageId": "msg_123"
+}
+```
+
+## Contract checks
+
+- claimed tasks stay in claimed state only with recent heartbeat
+- completed tasks include a non-empty summary
+- blocked completions include a specific reason
+- no second claim without completing or unblocking the first task

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

@@ -0,0 +1,41 @@
+---
+name: trace
+description: "Execution-path mapping for entry points, data flow, side effects, and blast radius before risky work."
+---
+
+# Trace
+
+## Purpose
+
+Use `$trace` before a risky edit or review when you need to know what code path actually runs, what it touches, and what could break downstream.
+
+## Workflow
+
+1. Find the entry points.
+2. Follow data flow through the changed or targeted path.
+3. Map side effects:
+   - storage writes
+   - network calls
+   - UI state changes
+   - background work
+4. Identify risky branches and missing guards.
+5. Name the concrete files the next pass should touch.
+
+## Suggested Tools
+
+- `ctx_search` for symbol and path discovery
+- `ctx_read` for call-path confirmation
+- `ctx_semantic_search` or `ctx_graph` when lexical search is not enough
+- `operator_hud` when runtime state matters to the path
+
+## Output Standard
+
+- entry points
+- downstream side effects
+- risky branches
+- likely blast radius
+- recommended edit 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.

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

@@ -0,0 +1,99 @@
+---
+name: ultragoal
+description: "Long-horizon goal mode that manages cross-session continuity for a durable objective, using ultrawork for each individual session."
+lane: true
+mcpToolPrefix: operator_ultragoal_
+---
+
+# Ultragoal
+
+## Purpose
+
+Wraps a multi-session, long-running objective that cannot be completed in a single context window. Ultragoal continuity lives in reviewable artifacts under `.enact/operator/ultragoal/`, while each individual execution burst is tracked through the real Operator runtime state (`$ultrawork`, and when needed `$autopilot`, `$ralph`, or `$team`).
+
+## Use When
+
+- a goal spans multiple days or context-window boundaries
+- you need cross-session continuity for a complex engineering objective
+- individual `$ultrawork` sessions should contribute to a shared, durable goal artifact
+- you need one authoritative goal artifact listing remaining vs completed slices across sessions
+
+## Workflow
+
+1. Define the goal and create or update the goal artifact in `.enact/operator/ultragoal/<goalId>.json`.
+   - Prefer MCP: `operator_ultragoal_update`
+   - Record at least: `title`, `goal`, `planPath`, `status`, `remainingPbis`, `completedPbis`, `updatedAt`
+2. Start or refresh the current session:
+   - MCP: `operator_session_start`
+   - CLI fallback: `enact-operator session start`
+3. Start ultrawork for the current execution burst:
+   - MCP: `operator_ultrawork_start`
+   - CLI fallback: `enact-operator ultrawork start "<goal>"`
+   - Do not depend on custom `activationMetadata` shapes for continuity.
+     Goal-level continuity belongs in the ultragoal artifact itself; runtime
+     activation metadata is only optional provenance.
+4. Link the relevant plan ids and external task ids into ultrawork state when those
+   concrete ids exist:
+    - MCP: `operator_ultrawork_link_plan`, `operator_ultrawork_link_task`
+    - CLI fallback: `enact-operator ultrawork link-plan <planId>`
+    - The linked external identifier parameter is `taskId`.
+5. Within each burst, run tasks using `$ultrawork` and keep the ultragoal
+   artifact updated as slices move from `remainingPbis` to `completedPbis`.
+6. At natural stopping points, record verified progress:
+   - MCP: `operator_ultrawork_verify`
+   - CLI fallback: `enact-operator ultrawork verify "<evidence>"`
+7. For closure-sensitive goals, also keep the real parity/hygiene surfaces in
+   view across sessions:
+   - `operator_contract_parity_run`
+   - `operator_operator_snapshot`
+   - `operator_hud`
+   - `operator_workflow_reconcile`
+8. On the next session, resume by reading:
+   - `.enact/operator/ultragoal/<goalId>.json`
+   - `operator_ultrawork_status`
+   - `operator_session_status`
+   - `operator_hud`
+9. When the goal is fully achieved:
+   - complete the active runtime burst (`operator_ultrawork_complete`)
+   - update the ultragoal artifact to `status: completed`
+   - ensure no dangling active runtime remains in HUD/state
+
+## State Contract
+
+- reads:
+  - `.enact/operator/ultragoal/<goalId>.json`
+  - plan files
+  - session / ultrawork / HUD state
+- writes:
+  - `.enact/operator/ultragoal/<goalId>.json`
+  - linked ultrawork state via `operator_ultrawork_*`
+  - optional parity evidence via `operator_contract_parity_run`
+
+## Commands
+
+```
+enact-operator session start
+enact-operator ultragoal status <goalId>
+enact-operator ultragoal update <goalId>
+enact-operator ultrawork start "<goal>"
+enact-operator ultrawork status
+enact-operator ultrawork verify "<evidence>"
+enact-operator ultrawork link-plan <planId>
+enact-operator ultrawork link-task <taskId>
+enact-operator ultrawork complete "<summary>"
+enact-operator ultrawork abort "<reason>"
+enact-operator session status
+```
+
+## 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/ultragoal/<goalId>.json` reflects current progress after each session
+- `remainingPbis` and `completedPbis` stay truthful to the codebase
+- no session ends without either verification evidence or a completion summary
+- plan files stay in sync with actual completed work
+- when the goal is done, ultrawork is completed and no dangling execution session remains
+- if closure criteria exist, use the real `contract-parity` gate rather than a
+  purely narrative reviewer summary

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

@@ -0,0 +1,113 @@
+---
+name: ultraqa
+description: "QA cycling workflow with hard-stop verification gates: tests, lint, doctor, smoke execution, and ralph persistence."
+lane: true
+mcpToolPrefix: operator_ultraqa_
+---
+
+# UltraQA
+
+## Purpose
+Combines `$ralph` (self-referential verification loop) with an explicit set of QA gates. Each gate must pass before the loop advances. The cycle is: implement a fix, run all gates, advance only when green, repeat until every gate is clean in a single run.
+
+## Use When
+- Verification has failed and a structured fix-verify cycle is needed
+- A feature must be proven working end-to-end before merging
+- The operator needs a hard record of each verification pass and failure
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- drive the QA loop through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep ralph and review state current as you go
+- do not stop until all gates pass in a single clean run
+
+## Workflow
+1. Start a ralph loop scoped to the QA goal:
+   - MCP: `operator_ralph_start` with `goal`
+   - CLI: `enact-operator ralph start --goal "<what must be verified>"`
+2. Check current ralph status before each iteration:
+   - MCP: `operator_ralph_status`
+   - CLI: `enact-operator ralph status`
+3. Run each QA gate in sequence. All must pass before advancing:
+   - Unit and integration tests (run the project's test command)
+   - Lint and type checks (run the project's lint command)
+   - Operator doctor:
+     - MCP: `operator_doctor`
+     - CLI: `enact-operator doctor`
+   - Replacement-readiness audit:
+     - MCP: `operator_audit_replacement_readiness`
+     - CLI: `enact-operator audit replacement-readiness`
+   - Real-execution smoke test (invoke the primary feature with real inputs, not mocks)
+4. Check the HUD for a summary view of current mode state:
+   - MCP: `operator_hud`
+   - CLI: `enact-operator hud`
+5. After all gates pass in a single run, record the verification:
+   - MCP: `operator_ralph_verify` with `gateId` and `status=passed`
+   - CLI: `enact-operator ralph verify <loopId> pass`
+
+   If any gate fails, record and continue the loop:
+   - MCP: `operator_ralph_verify` with `gateId` and `status=failed`
+   - CLI: `enact-operator ralph verify <loopId> fail`
+6. Advance to the next iteration:
+   - MCP: `operator_ralph_advance` with `toPhase`
+   - CLI: `enact-operator ralph advance <loopId>`
+7. If a team review is required before completing, request it:
+   - MCP: `operator_team_review`
+8. When all gates have passed in a single clean run, complete the loop:
+   - MCP: `operator_ralph_complete` with `summary`
+   - CLI: `enact-operator ralph complete <loopId>`
+
+## Proof Path
+
+- Use the real `contract-parity` and `state-hygiene` surfaces when QA is part
+  of closure, not just doctor/tests:
+  - `operator_contract_parity_run`
+  - `operator_workflow_reconcile`
+  - `operator_operator_snapshot`
+- Provider note: Operator may use its adapter over the running `enact-context`
+  server for closure proof. That is expected and preferable to duplicate
+  QA-local analysis.
+
+## State Contract
+- Reads: `.enact/operator/state/` (ralph loop state), test and lint output
+- Writes: ralph loop iterations and verification records via MCP tools or CLI
+
+## MCP Tools
+
+- `operator_ralph_start` — start a ralph loop scoped to the QA goal
+- `operator_ralph_status` — read current ralph state
+- `operator_ralph_advance` — transition to the next phase
+- `operator_ralph_verify` — record a gate verdict with evidence
+- `operator_ralph_pause` — pause the active loop
+- `operator_ralph_resume` — resume a paused loop
+- `operator_ralph_complete` — close the loop after all gates pass
+- `operator_ralph_abort` — abort the loop with a reason
+- `operator_doctor` — run the operator doctor gate
+- `operator_audit_replacement_readiness` — run the replacement-readiness gate
+- `operator_hud` — summary view of active mode state
+- `operator_team_review` — request a team review before completing
+
+## Commands
+```
+enact-operator ralph start
+enact-operator ralph status
+enact-operator ralph verify <loopId> pass|fail
+enact-operator ralph advance <loopId>
+enact-operator ralph pause <loopId>
+enact-operator ralph resume <loopId>
+enact-operator ralph complete <loopId>
+enact-operator ralph abort <loopId>
+enact-operator doctor
+enact-operator audit replacement-readiness
+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
+- Every gate (tests, lint, doctor, audit, smoke) passed in a single iteration
+- `ralph verify` recorded as `pass` before `ralph complete` was called
+- No gate was skipped or bypassed
+- `ralph complete` was called; no loop left in `running` or `paused` state

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

@@ -0,0 +1,145 @@
+---
+name: ultrawork
+description: "Default Enact Operator flow for intent -> plan -> execute -> verify, with team escalation only when durable parallelism is justified."
+lane: true
+mcpToolPrefix: operator_ultrawork_
+---
+
+# Ultrawork
+
+## Purpose
+
+`$ultrawork` is the default Enact Operator operating mode. It is the wrapper that decides whether to clarify, plan, execute directly, or escalate to durable team mode. It exists to finish the job end to end without losing state.
+
+## Use When
+
+- the user wants the work shipped, not just discussed
+- the task is larger than a one-shot edit
+- you need one sane default path instead of choosing skills manually
+
+## Routing Rules
+
+- ambiguous intent -> `$deep-interview`
+- clear but broad work -> `$plan`
+- one focused slice with known files -> `$executor`
+- parallel durable work -> `$team`
+- uncertain implementation pattern -> `$research` or `$trace`
+
+## Intent Gate
+
+Before the lane moves past startup, classify the session into one of:
+
+- `research` -> `$trace`
+- `implementation` -> `executor`
+- `investigation` -> `explore`
+- `evaluation` -> `code-reviewer`
+- `fix` -> `executor`
+- `open-ended` -> `$plan`
+
+Record the chosen `intent` in ultrawork state and keep later verification aligned to that class.
+
+## 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 ultrawork lifecycle actions
+- prefer the smallest mode that can finish the job
+- keep session, ultrawork, task, inbox, and review state current as you go
+- when no external `taskId` is linked, local Operator task discipline is mandatory; ultrawork owns a local task and must keep it authoritative
+- do not stop at a partial handoff unless the next owner is explicit
+
+## Workflow
+
+1. Start or refresh the session record:
+   - MCP: `operator_session_start`
+   - CLI fallback: `enact-operator session start`
+2. Read current runtime truth:
+   - MCP: `operator_hud`
+   - CLI fallback: `enact-operator hud`
+3. Start or inspect ultrawork state:
+   - MCP: `operator_ultrawork_start`
+   - CLI fallback: `enact-operator ultrawork start "<intent>"`
+4. Run the ambiguity gate:
+   - if intent is fuzzy, use `$deep-interview`
+   - if intent is clear, continue
+5. Build or refresh the durable plan:
+   - update `.enact/operator/plans/` and `.enact/operator/research/`
+   - link plan or research ids with `operator_ultrawork_link_plan` and `operator_ultrawork_link_research`
+6. Choose execution mode:
+   - direct slice -> `$executor`
+   - durable parallel slices -> `$team`
+7. Keep state current during execution:
+   - `operator_ultrawork_route`
+   - `operator_ultrawork_advance`
+   - `operator_ultrawork_verify`
+   - review-phase flow:
+     - advance into review with `operator_ultrawork_advance` and `toPhase: "review"`
+     - read review queue with `operator_reviews_list`
+     - if review work blocks completion, capture it with `operator_ultrawork_block`
+  - `operator_task_list`
+   - `operator_inbox_list`
+   - `operator_reviews_list`
+   - `operator_contract_parity_run` when closure criteria are declared
+   - `operator_workflow_reconcile` / `operator_operator_snapshot` when state drift is suspected
+8. Finish with explicit verification and a recorded verdict:
+   - MCP: `operator_ultrawork_complete`
+   - CLI fallback: `enact-operator ultrawork complete "<summary>"`
+
+## State Contract
+
+Ultrawork should leave behind:
+
+- a current session
+- a live or intentionally cleared ultrawork state
+- durable local tasks with real status
+- linked plan or research ids where relevant
+- optional external `assignmentId` plus a `subagents` array (empty on fresh sessions; reserved for delegated subagent tracking when that lane writes into ultrawork state)
+- verification evidence in state or artifacts
+- explicit parity/hygiene evidence when the session is being treated as a
+  closure-bearing run
+
+## TDD Mandate
+
+Default sequence is RED -> GREEN -> SURFACE.
+
+- RED: capture the failing proof first
+- GREEN: implement the minimal correction
+- SURFACE: record the user-visible verification evidence after the fix
+
+Exemption whitelist is limited to:
+
+- pure formatting
+- comment-only edits
+- dependency version bumps with no behavior delta
+- rename-only moves
+
+Every exemption must be justified in `.enact/operator/ultrawork/<sessionId>/notepad/decisions.md`.
+
+## Activation
+
+This skill is wired to Operator's UserPromptSubmit hook. When a prompt contains
+an explicit marker like `$enact-operator:ultrawork "<goal>"` or `$ultrawork "<goal>"`
+and the workspace-context hook preset is installed (verified via
+`operator_hooks_status`), the hook automatically:
+
+1. Detects the marker
+2. Starts the durable state at `.enact/operator/state/ultrawork.json` before the agent reads its first turn of context
+3. Adds an MCP-first context note telling the agent to load/search the Enact Operator MCP namespace immediately and continue through `operator_*` tools
+4. Records the activation in `.enact/operator/state/skill-active.json`
+
+That injected startup note is not AzDo-only. If no external `taskId` is linked, treat the local task as mandatory runtime state: read it through `operator_task_list` and keep it current throughout the run.
+
+If hooks are not installed, OR the marker did not include a goal, OR you
+want explicit control, call `operator_operator_activate` with `{skill: 'ultrawork',
+goal: '<goal>'}` from the MCP tool surface. The result is idempotent — if
+an ultrawork session is already active, the activation is a no-op.
+
+## Final Check
+
+- the next action is explicit
+- no fake "done" state exists
+- verification is recorded
+- the work is either completed, in review, or intentionally blocked
+- if closure criteria exist, `contract-parity` should be read from the real
+  gate output, not inferred manually
+- provider note: using the running `enact-context` server through Operator's
+  adapter layer is the intended proof path, not duplicated local analysis

package/extensions/enact-operator/skills/ultrawork/planner.md

@@ -0,0 +1,28 @@
+You are the planner. You DO NOT write code.
+
+Produce structured ultrawork planning output, not prose.
+
+Required content:
+
+## Waves
+
+List execution waves explicitly as `Wave 1`, `Wave 2`, ..., `Wave N`.
+
+## Dependency Matrix
+
+Use this exact dependency matrix table:
+
+| Task | Depends On | Blocks | Can Parallelize With |
+| --- | --- | --- | --- |
+
+## Agent Dispatch
+
+For every TODO include:
+
+- `category`
+- `skills`
+- target agent or lane
+
+## Parallel Speedup
+
+Estimate the expected parallel speedup percentage for the proposed wave plan.