@amsterdamdatalabs/enact-extensions 0.1.12 → 0.1.25

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

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

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

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

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

@@ -1,41 +0,0 @@
----
-name: wiki
-description: "Wiki-style reference lookup delegated to the enact-wiki provider. Use when the operator wants durable project documentation or knowledge retrieval."
----
-
-# Wiki
-
-## Purpose
-Provides access to the project's durable wiki and knowledge base by delegating to the enact-wiki provider. Operator orchestrates the request and receives the result; it does not re-implement wiki storage or retrieval. Operator-side artifacts produced by research or analysis can be persisted to the wiki via this skill.
-
-## Use When
-- The operator wants to look up a documented decision, design, or reference
-- Research findings from `$autoresearch-goal` should be persisted as a durable wiki entry
-- The operator asks "does the wiki have anything on X?"
-
-## Workflow
-1. Identify the query or document to persist.
-2. Delegate the operation to the enact-wiki provider using its wiki MCP tools.
-   - For a lookup: invoke the enact-wiki wiki query tool with the search term.
-   - For a write: invoke the enact-wiki wiki add tool with the content and title.
-   - For a list: invoke the enact-wiki wiki list tool.
-   - For a read of a specific entry: invoke the enact-wiki wiki read tool with the entry identifier.
-3. If the operation returns content, present it directly to the operator without reformatting.
-4. If persisting a Operator research artifact (e.g., `.enact/operator/research/<goalId>.md`), read the file first, then pass the content to the enact-wiki wiki add tool.
-5. Operator does not store wiki state locally. The enact-wiki provider is the canonical store.
-
-## State Contract
-- Reads: enact-wiki wiki store (via MCP tool calls), `.enact/operator/research/` files when persisting
-- Writes: enact-wiki wiki store (via MCP tool calls); no local `.enact/operator/` files written by this skill
-
-## Dependencies
-- Requires enact-wiki MCP server to be connected. If it is not available, report that to the operator and stop.
-
-## 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
-- The query returned a result or a clear "not found" from enact-wiki
-- For writes, the enact-wiki tool confirmed the entry was saved
-- No wiki content was stored locally in `.enact/operator/` as a substitute for the enact-wiki store
-- If enact-wiki was unavailable, the operator was notified explicitly

package/extensions/enact-operator/skills/work-with-workitem/SKILL.md

@@ -1,51 +0,0 @@
----
-name: work-with-workitem
-description: "Lightweight Azure DevOps work-item delivery lane: implement and hand off; factory owns tracking and closure."
----
-
-# Work With Workitem
-
-## Purpose
-
-Use `$work-with-workitem` for operator-domain delivery tied to a single Azure DevOps work item.
-
-## Domain Boundary
-
-- operator scope is intentionally lightweight: load, isolate, implement, PR, handoff, cleanup
-- enact-factory owns CI heartbeat tracking, branch policy waits, auto-merge, and lifecycle advance to `Closed`
-- this skill must not add CI polling loops or unbounded branch-policy waiting
-
-## Azure DevOps-Only Contract
-
-- use `factory_workitem_get` and `factory_assignment_record` for work-item reads and closing notes
-- use `az repos pr create --work-items <id>` to link the PR to the work item
-- do not assume or reference GitHub APIs, GitHub Actions, GitHub checks, or GitHub branch protection primitives
-
-## Required Sequence
-
-1. `factory_workitem_get` loads the target work item and confirms readiness.
-2. `EnterWorktree` isolates the implementation workspace.
-3. Execute implementation with `$ultrawork` (or `$ralph` for simple tasks).
-4. Create atomic commits with clear work-item-linked intent.
-5. Run `az repos pr create --work-items <id>` and capture the PR URL.
-6. Call `factory_assignment_record` with a closing note that includes PR URL and commit SHA.
-7. `ExitWorktree` cleans up the isolated workspace.
-
-## Behavioral Constraints
-
-- no CI poll loop in this skill; CI heartbeat belongs to `factory_watchdog_status`
-- no merge waiting or policy-wait ownership in this skill
-- no lifecycle mutation to `Closed` from this skill
-- if PR creation fails, record failure context and exit through normal cleanup
-
-## Verification Expectations
-
-- integration target is a work item tagged `test-fixture`
-- verify PR link uses `--work-items <id>`
-- verify `factory_assignment_record` includes PR URL and commit SHA
-- verify `ExitWorktree` cleanup is executed
-- do not verify CI completion or merge here
-
-## 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.