@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/enact-factory/skills/workitem-triage/SKILL.md

@@ -0,0 +1,22 @@
+# workitem-triage
+
+## Purpose
+Provide a read-only triage surface for Factory WorkItems. This skill is for assessing queue state and individual WorkItem details without allowing scheduling, mutation, or execution actions.
+
+## Activation Contract
+- Activate with `factory_skill_activate` and `skill="workitem-triage"`.
+- Deactivate with `factory_skill_deactivate` when triage is complete.
+- While active, visible MCP tools must be limited to:
+  - `factory_workitem_list`
+  - `factory_workitem_get`
+
+## Forbidden Operations
+- Do not call scheduler, assignment, lifecycle, watchdog, sync, or closure mutation tools while this skill is active.
+- Do not update WorkItem state, queue entries, assignments, or process state.
+- Do not dispatch agent lanes or terminate processes.
+
+## Output Contract
+- Return concise, factual triage output only.
+- Include WorkItem ids, statuses, and blockers when present.
+- If required data is missing, explicitly state unknowns instead of inferring.
+- Keep recommendations non-mutating unless the operator explicitly switches out of triage mode.

package/extensions/enact-operator/.agents/plugin.json

@@ -0,0 +1,57 @@
+{
+  "name": "enact-operator",
+  "version": "0.1.0",
+  "description": "First-party Enact Operator plugin surfaces for skills, commands, agents, MCP, and runtime hook registrations.",
+  "author": {
+    "name": "amsterdamdatalabs"
+  },
+  "homepage": "https://amsterdamdatalabs.com",
+  "repository": "https://dev.azure.com/amsterdamdatalabs/Enact/_git/enact-operator",
+  "license": "UNLICENSED",
+  "keywords": [
+    "enact",
+    "operator",
+    "orchestration",
+    "workflow"
+  ],
+  "targets": [
+    "claude",
+    "codex",
+    "cursor"
+  ],
+  "skills": "./skills/",
+  "agents": "./agents/",
+  "commands": "./commands/",
+  "mcpServers": "./.mcp.json",
+  "apps": "./.app.json",
+  "interface": {
+    "displayName": "Enact Operator",
+    "shortDescription": "Installable surfaces for Enact Operator workflows.",
+    "longDescription": "Bundles the operator-owned Enact catalog. enact-extensions owns install, registration, hook wiring, enable/disable, status, and uninstall. Hook registrations call stable enact-operator runtime commands such as enact-operator hook user-prompt-submit; hook implementations stay in the enact-operator package.",
+    "developerName": "enact-operator",
+    "category": "Developer Tools",
+    "composerIcon": "./assets/icon.png",
+    "logo": "./assets/logo.png",
+    "capabilities": [
+      "skills",
+      "slash commands",
+      "operator workflows",
+      "team orchestration",
+      "operator setup",
+      "doctor and readiness audits",
+      "plan and execution workflows",
+      "review and QA workflows",
+      "federated context and memory workflows"
+    ]
+  },
+  "operator": {
+    "firstParty": true,
+    "bundledMcpProviders": [
+      "enact-factory",
+      "enact-context",
+      "enact-wiki"
+    ],
+    "operatorScope": "project"
+  },
+  "hooks": "./hooks/hooks.json"
+}

package/extensions/enact-operator/.app.json

@@ -0,0 +1,3 @@
+{
+  "apps": {}
+}

package/extensions/enact-operator/.mcp.json

@@ -0,0 +1,10 @@
+{
+  "mcpServers": {
+    "enact-operator": {
+      "command": "enact-operator",
+      "args": [
+        "mcp"
+      ]
+    }
+  }
+}

package/extensions/enact-operator/_taxonomy.md

@@ -0,0 +1,86 @@
+# Enact Operator Extension Taxonomy
+
+`extensions/` has three extension tiers. Each entry belongs to exactly one tier.
+
+## Pure skills
+
+Pure skills live at `extensions/skills/<name>/SKILL.md`.
+
+- No MCP tool surface
+- No persisted lane state
+- Prompt/context guidance only
+
+Current pure skills:
+
+- `ai-slop-cleaner`
+- `analyze`
+- `ask`
+- `autoresearch-goal`
+- `cancel`
+- `configure-notifications`
+- `deep-interview`
+- `doctor`
+- `hud`
+- `hyperplan`
+- `plan`
+- `remove-deadcode`
+- `research`
+- `review`
+- `security-research`
+- `setup`
+- `skill`
+- `tdd`
+- `trace`
+- `wiki`
+- `work-with-workitem`
+
+## Agents
+
+Codex subagents live at `extensions/agents/*.toml`.
+
+- Stateless worker contracts
+- Dispatched through Codex subagents
+- Installed into the Codex agents directory by setup
+
+The old exact-name collisions `architect`, `executor`, and `reviewer` were removed from `extensions/skills/` once their Codex agent TOMLs existed. The remaining helper surfaces such as `plan`, `review`, `research`, `trace`, and `analyze` are pure skills, not agent files.
+
+## Operator lanes
+
+Operator lanes remain under `extensions/skills/<name>/SKILL.md`, but they are explicitly tagged with:
+
+- `lane: true`
+- `mcpToolPrefix: operator_<lane>_`
+
+Lanes add:
+
+- MCP tool surfaces
+- persisted operator state
+- runtime lifecycle semantics
+
+**Classification rule:** an entry is a **root lane** if and only if it has both (a) a durable operator state file under `.enact/operator/state/` AND (b) an `mcpToolPrefix` field in its `SKILL.md` frontmatter. Any entry that satisfies only one criterion, or neither, is a wrapper or continuity overlay, not a root lane.
+
+### Root lanes
+
+Root lanes are the four autonomous runtime execution lanes that the scheduler assigns tasks to. Each has a durable state file and its own `mcpToolPrefix`.
+
+- `ralph`
+- `ultrawork`
+- `team`
+- `autopilot`
+
+### Continuity overlays
+
+Continuity overlays have an MCP surface and durable state, but serve as multi-session goal artifacts that wrap one or more root lanes rather than acting as independent scheduler candidates.
+
+- `ultragoal`
+
+### Wrappers
+
+Wrappers delegate execution to a root lane (typically ralph) and carry no independent durable state file of their own.
+
+- `ralplan`
+- `ultraqa`
+
+## Disambiguation rule
+
+No entry may straddle tiers. If a surface needs Codex subagent dispatch, it belongs in `extensions/agents/`. If it needs Operator MCP tools and durable state, it is a lane. Everything else is a pure skill.

package/extensions/enact-operator/agents/README.md

@@ -0,0 +1,5 @@
+# Enact Operator Agents
+
+Codex-compatible agent TOMLs live in this directory.
+
+The taxonomy contract is documented in [`../_taxonomy.md`](../_taxonomy.md). During the active migration, the legacy agent-style skill directories in `../skills/` are the source material for the TOML ports that land here.

package/extensions/enact-operator/agents/architect.toml

@@ -0,0 +1,25 @@
+name = "architect"
+description = "Architectural review and GO/NO-GO verdict with evidence pointers"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator architect agent.
+
+Role:
+- Read-only architectural reviewer.
+- Diagnose root causes from code and docs already on disk.
+- Produce a GO or NO-GO verdict with concrete evidence pointers.
+
+Rules:
+- Never edit files.
+- Never speculate when you can read the source.
+- Cite exact file paths and line references for material claims.
+- Call out tradeoffs, not just the favored direction.
+
+Output contract:
+- verdict: GO or NO-GO
+- reasons: concise bullet list
+- evidencePointers: file references
+- tradeoffs: short list
+"""

package/extensions/enact-operator/agents/code-reviewer.toml

@@ -0,0 +1,24 @@
+name = "code-reviewer"
+description = "Binding code review pass enforcing unconditional approval or actionable findings"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator code-reviewer agent.
+
+Role:
+- Perform the binding review pass after an implementation batch.
+- Prioritize correctness, regressions, and missing verification over style.
+
+Rules:
+- Never edit files.
+- Review only from the actual diff and surrounding code.
+- Every finding must cite a file reference and explain impact.
+- If no actionable issues remain, emit the token UNCONDITIONAL_APPROVE.
+- Otherwise, return a blocking verdict with the findings ordered by severity.
+
+Output contract:
+- verdict: UNCONDITIONAL_APPROVE or REQUEST_CHANGES
+- findings: severity-ordered list with evidence
+- residual_risks: optional short list
+"""

package/extensions/enact-operator/agents/critic.toml

@@ -0,0 +1,30 @@
+name = "critic"
+description = "Adversarial debate participant for hyperplan and high-risk decision review"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator critic agent.
+
+Role:
+- Attack weak assumptions in plans, proposals, and risky implementation choices.
+- Operate as an adversarial reviewer, not a collaborator trying to be agreeable.
+
+Rules:
+- Never edit files.
+- Surface the strongest counterargument first.
+- Prefer concrete failure modes over vague concern language.
+- When a decision looks sound, say that plainly instead of inventing objections.
+
+Round protocol:
+1. Independent critique.
+2. Cross-attack on the competing argument.
+3. Defend, refine, or concede.
+
+Output contract:
+- position
+- strongest_objections
+- failure_modes
+- concessions
+- final_recommendation
+"""

package/extensions/enact-operator/agents/executor.toml

@@ -0,0 +1,24 @@
+name = "executor"
+description = "Focused implementation worker for small, reviewable diffs with verification"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator executor agent.
+
+Role:
+- Implement the requested change with the smallest viable diff.
+- Run focused verification before claiming completion.
+
+Rules:
+- Stay inside the stated scope.
+- Match existing code patterns.
+- Do not add abstractions unless the code clearly needs them.
+- Do not stop at code changes; include the verification result.
+- If blocked after repeated failed attempts, report the blocker clearly.
+
+Output contract:
+- changes_made
+- verification
+- blockers_or_followups
+"""

package/extensions/enact-operator/agents/explore.toml

@@ -0,0 +1,23 @@
+name = "explore"
+description = "Codebase sweep agent for absolute-path findings and quote-friendly evidence"
+model = "gpt-5.3-codex-spark"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator explore agent.
+
+Role:
+- Find relevant files, symbols, and relationships quickly.
+- Return enough context for another agent to act without repeating the search.
+
+Rules:
+- Never edit files.
+- Use absolute paths in results.
+- Prefer breadth first: search multiple relevant areas before narrowing.
+- Explain how the files connect instead of returning a raw list.
+
+Output contract:
+- findings
+- relationships
+- recommended_next_step
+"""

package/extensions/enact-operator/agents/planner.toml

@@ -0,0 +1,24 @@
+name = "planner"
+description = "Structured implementation planner that never writes production code"
+model = "gpt-5.3-codex-spark"
+model_reasoning_effort = "medium"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator planner agent.
+
+Role:
+- Turn a goal into a small, reviewable execution plan with clear acceptance criteria.
+- You do not implement code.
+
+Rules:
+- Never write production code.
+- Prefer 3 to 6 concrete steps.
+- Include dependencies, risks, and verification expectations.
+- Escalate unresolved product-direction choices instead of guessing.
+
+Output contract:
+- plan_summary
+- steps
+- acceptance_criteria
+- risks_and_open_questions
+"""

package/extensions/enact-operator/agents/verifier.toml

@@ -0,0 +1,24 @@
+name = "verifier"
+description = "Evidence-first verifier for real-surface QA and completion claims"
+model = "gpt-5.3-codex"
+model_reasoning_effort = "high"
+sandbox_mode = "danger-full-access"
+developer_instructions = """
+You are the Enact Operator verifier agent.
+
+Role:
+- Check whether completion claims are supported by fresh evidence.
+- Focus on commands run, outputs observed, and uncovered gaps.
+
+Rules:
+- Never edit files.
+- Do not trust prior claims without rerunning or directly reading evidence.
+- Mark each requirement VERIFIED, PARTIAL, or MISSING.
+- Separate missing evidence from failing behavior.
+
+Output contract:
+- verdict: PASS, FAIL, or INCOMPLETE
+- evidence: commands and observed results
+- requirement_matrix
+- remaining_gaps
+"""

package/extensions/enact-operator/commands/doctor.md

@@ -0,0 +1,39 @@
+---
+name: doctor
+description: Health-check Enact Operator install, hooks, plugins, and runtime readiness
+argument-hint: [focus-area]
+---
+
+# Doctor
+
+Run the Enact Operator **doctor** workflow for this workspace. User focus (optional): `$ARGUMENTS`
+
+## Policy
+
+- Start from repo truth (`.enact/operator/`, hook files, source plugin bundle), not chat memory.
+- If `operator_*` MCP tools are not visible, load the **enact-operator** MCP server first, then prefer MCP over CLI.
+- Report **healthy**, **degraded**, and **broken** with an exact fix per finding.
+
+## Steps
+
+1. Primary health surface:
+   - MCP: `operator_doctor`
+   - CLI: `enact-operator doctor`
+2. If plugins are in scope, inspect source bundle validity:
+   - MCP: `operator_plugin_list`, `operator_plugin_validate`
+   - CLI: `enact-operator plugins validate`
+3. If hooks are in scope (or user mentioned hooks):
+   - MCP: `operator_hooks_status`
+   - CLI: `enact-operator hooks status`
+4. If sessions/team/runtime are in scope:
+   - MCP: `operator_session_status`, `operator_team_status`, `operator_hud`
+5. Summarize findings and the shortest remediation path for each issue.
+
+## Output
+
+- What is healthy
+- What is degraded
+- What is broken
+- Exact command, file path, or config change to fix each item
+
+For deeper operator guidance, follow the `doctor` skill in this plugin's `skills/doctor/SKILL.md`.

package/extensions/enact-operator/commands/setup.md

@@ -0,0 +1,51 @@
+---
+name: setup
+description: Bootstrap Enact Operator in this repo — layout, hooks, agents, and readiness checks
+argument-hint: [reinstall|validate-only]
+---
+
+# Setup
+
+Run the Enact Operator **setup** workflow for this workspace. User mode (optional): `$ARGUMENTS`
+
+## Policy
+
+- Start from the project root and existing `.enact/operator/` state, not chat memory.
+- If `operator_*` MCP tools are not visible, load the **enact-operator** MCP server first, then prefer MCP over CLI.
+- Confirm each step before advancing; do not skip verification at the end.
+
+## Workflow
+
+1. Top-level installer:
+   - MCP: `operator_setup`
+   - CLI: `enact-operator setup`
+2. Install hooks (no MCP equivalent):
+   - CLI: `enact-operator hooks install`
+3. Hook registration:
+   - MCP: `operator_hooks_status`
+   - CLI: `enact-operator hooks status`
+4. Agent role-pack:
+   - MCP: `operator_agents_pack_install`
+   - CLI: `enact-operator agents install-pack`
+5. Plugin bundle source coherence:
+   - MCP: `operator_plugin_validate`
+   - CLI: `enact-operator plugins validate`
+6. Install registry:
+   - MCP: `operator_install_registry`
+7. Runtime health:
+   - MCP: `operator_doctor`
+   - CLI: `enact-operator doctor`
+8. Replacement readiness:
+   - MCP: `operator_audit_replacement_readiness`
+   - CLI: `enact-operator audit replacement-readiness`
+
+If the user passed `validate-only`, run steps 3–8 only (skip install mutations).
+
+## Final check
+
+- Doctor reports no blocking errors
+- Plugin validation reports the enact-operator source bundle is valid
+- Hooks status shows required hooks registered
+- `.enact/operator/` exists with expected subdirectories
+
+For full setup contract details, follow the `enact-operator-setup` skill in `skills/setup/SKILL.md`.

package/extensions/enact-operator/hooks/hooks.json

@@ -0,0 +1,146 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook session-start",
+            "statusMessage": "Loading Operator workspace context"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook user-prompt-submit"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-counter reset"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-search-guard reset"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook pre-tool-use",
+            "statusMessage": "Checking Operator shell safety policy"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook post-tool-use",
+            "statusMessage": "Reviewing Operator tool output"
+          }
+        ]
+      },
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-counter",
+            "statusMessage": "Checking Operator tool-call budget"
+          }
+        ]
+      },
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook doom-loop-search-guard",
+            "statusMessage": "Checking Operator search deduplication"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook stop",
+            "timeout": 30
+          }
+        ]
+      }
+    ],
+    "SessionIdle": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook session-idle"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook pre-compact"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook session-end"
+          }
+        ]
+      }
+    ],
+    "SubagentStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook subagent-tracker start"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "enact-operator hook subagent-tracker stop"
+          }
+        ]
+      }
+    ]
+  }
+}

package/extensions/enact-operator/skills/_variants.md

@@ -0,0 +1,44 @@
+# Skill Variant Contract
+
+Each skill directory may ship model-specific peer files alongside the default
+`SKILL.md`.
+
+## File Names
+
+- `SKILL.md` is the default prompt body and the required fallback.
+- `gpt.md` is selected for GPT-family model identities.
+- `gemini.md` is selected for Gemini-family model identities.
+- `kimi.md` is selected for Kimi-family model identities.
+- `opus-4-7.md` is selected for Claude Opus 4.7 model identities.
+
+## Selection Rule
+
+The loader resolves variants in this order:
+
+1. first matching model-specific peer file
+2. `SKILL.md` when no model-specific peer matches or no model identity is available
+
+## Model Identity Header
+
+The model identity is propagated through the `X-Model-Identity` header injected
+by enact-gateway on routed requests. Variant selection reads that identity from
+activation metadata. If the header is absent, the loader must fall back to
+`SKILL.md` instead of guessing.
+
+## Testing Constraint
+
+The default `auto` route does not expose a stable raw model identity for prompt
+selection tests. For live gateway pass-through checks, use the confirmed model
+IDs:
+
+- `kimi-for-coding`
+- `MiniMax-M2.7`
+
+Do not use generic labels like `gpt-4` or `gemini` for integration checks.
+Helper/unit tests should inject the model identity directly instead of depending
+on a live gateway route.
+
+## Current Scope
+
+This helper/documentation slice defines the variant selection contract and the
+Ralph Gemini variant file. Full hook/prompt-loader wiring remains a later step.