@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.25

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

@@ -1,79 +0,0 @@
----
-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

@@ -1,99 +0,0 @@
----
-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

@@ -1,77 +0,0 @@
----
-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

package/extensions/enact-operator/skills/deep-interview/SKILL.md

@@ -1,80 +0,0 @@
----
-name: deep-interview
-description: "Intent-first clarification loop for vague, risky, or product-heavy work before planning or execution."
----
-
-# Deep Interview
-
-## Purpose
-
-Use `$deep-interview` to turn a fuzzy request into an execution-ready spec. This is not generic brainstorming. It is a focused clarification loop that removes ambiguity before planning or coding.
-
-## Use When
-
-- the request describes outcomes, not behavior
-- the user is still discovering what they want
-- scope, non-goals, or decision boundaries are unclear
-- a wrong assumption would create expensive rework
-
-## Do Not Use When
-
-- the request already names files, symbols, and acceptance criteria
-- the user explicitly wants immediate execution and the risk is low
-- the only missing work is architectural decomposition, not intent clarity
-
-## Execution Policy
-
-- ask one question at a time
-- ask only the highest-leverage unresolved question
-- use repo facts before asking about codebase internals
-- force clarity on non-goals and decision boundaries before handoff
-- keep the interview moving toward a durable artifact, not an endless conversation
-
-## Question Order
-
-1. Why does this need to exist?
-2. What should be true when it is done?
-3. How far should it go?
-4. What should explicitly stay out?
-5. What may Enact Operator decide without checking again?
-6. What constraints or preferences are hard?
-
-## Workflow
-
-1. Read current `.enact/operator/` artifacts and inspect the repo if this is brownfield work.
-2. Capture the current hypothesis in `.enact/operator/plans/<phase>-requirements.md`.
-3. Run a one-question loop until these are explicit:
-   - goal
-   - in-scope
-   - out-of-scope
-   - acceptance criteria
-   - decision boundaries
-4. Refresh the session/state record when the interview starts or resumes:
-   - MCP: `operator_session_start`
-   - CLI fallback: `enact-operator session start`
-5. Update:
-   - `.enact/operator/plans/<phase>-requirements.md`
-   - `.enact/operator/research/summary.md`
-   - `.enact/operator/state/planning-state.json`
-6. Hand off to `$plan` when the spec is concrete.
-
-## Output Standard
-
-The finished interview should leave behind:
-
-- clear goal
-- explicit non-goals
-- decision boundaries
-- testable acceptance criteria
-- constraints that downstream execution must honor
-
-## Stop Conditions
-
-Do not hand off while either of these is missing:
-
-- non-goals
-- decision boundaries
-
-## 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/doctor/SKILL.md

@@ -1,48 +0,0 @@
----
-name: doctor
-description: "Health-check mode for Enact Operator install, repo state, plugin wiring, hook status, and runtime degradation."
----
-
-# Doctor
-
-## Purpose
-
-Use `$doctor` when setup, runtime behavior, hooks, or the source plugin bundle feels wrong. This skill is for diagnosis plus the shortest correct remediation path.
-
-## Workflow
-
-1. Run the primary health surface:
-   - MCP: `operator_doctor`
-   - CLI fallback: `enact-operator doctor`
-2. If the problem is plugin-source-related, inspect:
-   - MCP: `operator_plugin_list` / `operator_plugin_validate`
-   - CLI fallback: `enact-operator plugins validate`
-3. If the problem is hook-related, inspect:
-   - MCP: `operator_hooks_status`
-   - CLI fallback: `enact-operator hooks status`
-4. If the problem is session or team-runtime-related, inspect:
-   - `operator_session_status`
-   - `operator_team_status`
-   - `operator_hud`
-5. Turn findings into concrete fixes, not generic advice.
-
-## What to Check
-
-- Node and Codex availability
-- MCP server configured in `~/.codex/config.toml`
-- `.enact/operator/` initialized in the current repo
-- tmux availability vs degraded mock mode
-- source plugin bundle validity; host install and marketplace drift are owned by enact-extensions
-- hook installation state vs feature availability
-- session, inbox, review, and task drift
-
-## Output Standard
-
-- what is healthy
-- what is degraded
-- what is broken
-- the exact command or file change to fix each issue
-
-## 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/hud/SKILL.md

@@ -1,49 +0,0 @@
----
-name: hud
-description: "Runtime-truth mode for reading tasks, sessions, reviews, inbox, and team state before acting."
----
-
-# HUD
-
-## Purpose
-
-Use `$hud` before trusting your memory of what the runtime is doing. The HUD is the fastest way to catch task drift, stale executor state, or fake progress.
-
-## Primary Surfaces
-
-- MCP: `operator_hud`
-- CLI fallback: `enact-operator hud`
-
-## Read It For
-
-- current session and branch
-- active modes
-- queued vs active vs review tasks
-- inbox and review pressure
-- team backend state and stale executors
-- install-registry drift
-- doctor warnings that change operator decisions
-- if `operator_*` tools are not visible yet, load/search the Enact Operator MCP namespace before reading runtime state
-
-## Workflow
-
-1. Read the HUD.
-2. If anything looks wrong, drill down with:
-   - `operator_session_status`
-   - `operator_task_list`
-   - `operator_reviews_list`
-   - `operator_inbox_list`
-   - `operator_team_status`
-   - `operator_ledger_recent`
-3. Compare it against the actual `.enact/operator/` artifacts if needed.
-4. Fix state drift before continuing execution.
-
-## Rules
-
-- if the HUD says a mode is active, there must be durable evidence
-- if the HUD says the team is healthy but inbox or reviews are piling up, the runtime is not healthy
-- prefer MCP state tools when another agent needs machine-readable output
-
-## 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/hyperplan/SKILL.md

@@ -1,47 +0,0 @@
----
-name: hyperplan
-description: "Three-round adversarial planning debate that hands a distilled bundle to $plan instead of writing the final plan directly."
----
-
-# Hyperplan
-
-## Purpose
-
-Use `$hyperplan` when a plan needs adversarial pressure before execution starts.
-
-## Debate Team
-
-Use exactly this 4-agent team:
-
-- `critic`
-- `critic`
-- `architect`
-- `explore`
-
-The original openagent placeholder names are not used here.
-
-## Rounds
-
-Run exactly 3 rounds:
-
-1. independent analysis
-2. cross-attack
-3. defend, refine, or concede
-
-Persist each round under:
-
-- `.enact/operator/hyperplan/<sessionId>/round-1.md`
-- `.enact/operator/hyperplan/<sessionId>/round-2.md`
-- `.enact/operator/hyperplan/<sessionId>/round-3.md`
-
-## Handoff Rule
-
-The lead agent does not write the final implementation plan directly.
-After round 3, hand the distilled debate bundle to a separate `$plan` invocation.
-
-## Execution Notes
-
-- use `explore` to gather the evidence bundle before critique
-- use the two `critic` agents to take opposing positions in the cross-attack round
-- use `architect` to synthesize the final structured verdict and tradeoffs
-- do not skip a round because the first opinion looked sufficient

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

@@ -1,78 +0,0 @@
----
-name: plan
-description: "Execution-plan mode that turns intent into small, verifiable slices backed by durable .enact/operator artifacts."
----
-
-# Plan
-
-## Purpose
-
-Use `$plan` to create execution-ready slices. The output is not a strategy memo. It is the prompt-quality plan that downstream execution can follow without improvising core behavior.
-
-## Use When
-
-- the work is bigger than a one-shot edit
-- the request is clear enough to plan but not yet safe to execute
-- verification, dependencies, or sequencing need to be locked in
-
-## Do Not Use When
-
-- the task is still ambiguous enough for `$deep-interview`
-- the change is a trivial single-file fix
-- the user explicitly wants direct execution and the risk is low
-
-## Execution Policy
-
-- gather repo facts before asking about internals
-- plans are prompts for execution, not prose for humans only
-- every slice must fit in one focused context window
-- every slice must have explicit verification
-- prefer a small number of high-quality slices over a long TODO dump
-
-## Plan Anatomy
-
-Each slice should answer:
-
-- what files are likely to change
-- what the slice must do
-- how to verify it
-- what counts as done
-- what it depends on
-
-## Workflow
-
-1. Read current intent artifacts:
-   - `.enact/operator/plans/*-requirements.md`
-   - `.enact/operator/plans/brownfield-map.md`
-   - `.enact/operator/research/summary.md`
-2. Derive the must-haves from the goal backward:
-   - what must be true when this is done?
-   - what artifacts and connections are required for those truths?
-3. Split the work into waves and slices:
-   - interface or contracts first
-   - implementation second
-   - verification and wiring last
-4. Write or refine:
-   - active phase plan
-   - verification map
-   - any required task queue items
-5. If Ultrawork is active, link the plan id into session state:
-   - MCP: `operator_ultrawork_link_plan`
-   - CLI fallback: `enact-operator ultrawork link-plan <planId>`
-
-## Quality Bar
-
-- no vague acceptance criteria
-- no "make it work" tasks
-- no giant slice that hides three subsystems
-- no verify step that depends on hope
-
-## Deliverables
-
-- `.enact/operator/plans/<phase>.md`
-- `.enact/operator/plans/<phase>-verification.md`
-- updated brownfield map or research summary when needed
-
-## 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.