@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/enact-operator/skills/remove-deadcode/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: remove-deadcode
+description: "LSP-verified symbol deletion with entry-point guards and candidate-parallel execution."
+---
+
+# Remove Deadcode
+
+## Purpose
+
+Use `$remove-deadcode` to remove provably unused code symbols without damaging runtime entry points.
+
+## Preconditions
+
+- collect candidate symbols before any deletion
+- load optional entry-point guard list from `.enact/operator/remove-deadcode/entry-points.txt`
+
+## Required Safety Contract
+
+For each candidate symbol, the deletion gate is strict:
+
+1. If symbol is listed in the entry-point guard file, skip deletion unconditionally.
+2. Otherwise call `lsp_find_references` (via enact-context).
+3. If references are non-empty, abort deletion for that symbol and emit an explanatory message.
+4. Only delete when references are exactly zero and the symbol is not guarded.
+
+## Execution Model
+
+- batching is explicit: enumerate all candidates first
+- then dispatch parallel `executor` subagents, one candidate per subagent
+- each subagent must apply the same guard-list and `lsp_find_references` checks
+
+## Behavioral Constraints
+
+- no heuristic-only deletion
+- no bypass of entry-point guard list
+- no GitHub-specific assumptions or workflows in deletion decisions
+
+## Verification Expectations
+
+- unit test: non-empty `lsp_find_references` result must refuse deletion
+- unit test: guard-listed symbol must be skipped even when reference count is zero
+
+## 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/research/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: research
+description: "Evidence-first research mode for current patterns, implementation risks, and decision support."
+---
+
+# Research
+
+## Purpose
+
+Use `$research` when the correct implementation depends on facts you do not yet have, either from the repo or from current external sources.
+
+## Execution Policy
+
+- start with brownfield evidence from the repo
+- use primary sources for technical questions
+- end with a decision-ready recommendation, not a wall of notes
+- persist findings so the next pass does not repeat the work
+
+## Workflow
+
+1. Identify the actual unknowns.
+2. Separate:
+   - repo truth
+   - external truth
+   - assumptions
+3. Gather only the evidence needed to decide.
+4. Write the result into `.enact/operator/research/summary.md`.
+5. Update any linked ultrawork or task state if the research is part of an active execution lane.
+
+## Parallel Sweep
+
+Run concurrent research agents for independent evidence lanes. The floor is 2 concurrent agents whenever there are both repo-truth and external-truth unknowns.
+
+- minimum concurrent-agent floor: 2
+- recommended split: one agent for internal repo evidence and one agent for external primary sources
+- increase concurrency only when unknowns are independent and synthesis cost remains manageable
+
+Anti-stop rule: do not stop at the first result. Continue each lane until at least one corroborating source is collected per lane, or until an explicit blocker is documented.
+
+## Runtime Clarification
+
+- `$research` is an evidence pass, not a currently exposed closure-owning
+  runtime lane.
+- If research output is being used to support closure on a live task, rely
+  on the real Operator proof surfaces rather than treating research notes as
+  equivalent to parity evidence:
+  - `operator_contract_parity_run`
+  - `operator_workflow_reconcile`
+  - `operator_operator_snapshot`
+
+## Deliverables
+
+- current pattern or contract summary
+- risk list
+- recommendation with concrete tradeoffs
+- open questions that still block planning or execution
+
+### Internal Evidence
+
+- repo paths inspected
+- commands or tools used
+- concrete findings tied to files, code, or runtime state
+- unresolved internal gaps
+
+### External Evidence
+
+- primary sources consulted
+- dated facts and version-sensitive constraints
+- corroboration across at least one additional source
+- unresolved external gaps
+
+## 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/review/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: review
+description: "Findings-first pre-landing review against code, plan completion, verification evidence, and durable runtime state."
+---
+
+# Review
+
+## Purpose
+
+Use `$review` to answer one question: is this actually ready to land? Review is not a summary pass. It is a bug, regression, coverage, and state-integrity pass.
+
+## Execution Policy
+
+- findings first, summary second
+- prefer evidence over author claims
+- check the code, the tests, the plan, and the runtime artifacts
+- if the current context authored the change, prefer a separate reviewer role for approval
+
+## Review Order
+
+1. Read the changed code.
+2. Read the active plan and verification map.
+3. Check what was supposed to happen vs what actually landed.
+4. Verify:
+   - tests and typechecks
+   - docs drift
+   - `.enact/operator/` state drift
+   - task, review, inbox, and ledger accuracy
+5. Produce a verdict:
+   - approved
+   - changes requested
+   - blocked
+
+## Mandatory Checks
+
+- missing or fake verification
+- uncovered changed paths
+- stale docs or setup instructions
+- task marked done but still pending review evidence
+- runtime claiming health while inbox or review queue says otherwise
+
+## Recommended State Reads
+
+- `operator_reviews_list`
+- `operator_inbox_list`
+- `operator_ledger_recent`
+- `operator_hud`
+
+## Output Standard
+
+- findings ordered by severity
+- file references and why they matter
+- residual risk
+- final verdict and next action
+
+## 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/security-research/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: security-research
+description: "Multi-agent security research with hunter/PoC split and optional critical bug auto-creation in Azure DevOps."
+---
+
+# Security Research
+
+## Purpose
+
+Use `$security-research` to run a focused vulnerability hunt, produce ranked findings, and optionally create Azure DevOps Bug work items for critical issues.
+
+## Parameters
+
+- `autoCreateBugs: boolean` (default `true`)
+- when `false`, no `factory_workitem_sync_once` call is allowed regardless of severity
+
+## Team Topology
+
+- 3 hunter agents:
+- hunter 1: CWE classification
+- hunter 2: CVSS v4 scoring
+- hunter 3: OWASP category mapping
+- 2 PoC engineer agents:
+- PoC 1 and PoC 2: exploitability proof and reproduction quality
+
+## Required Workflow
+
+1. Launch hunters to identify and classify potential vulnerabilities.
+2. Launch PoC engineers on top-ranked findings to validate exploitability.
+3. Merge outputs into a single findings report.
+4. Write report to `.enact/operator/security/<sessionId>/findings.md`.
+5. Rank findings in the report by CVSS v4 severity.
+6. For each finding with CVSS v4 `>= 9.0`, if `autoCreateBugs=true`, call `factory_workitem_sync_once` to create a `Bug` work item.
+7. If `autoCreateBugs=false`, skip all bug auto-creation calls.
+
+## Azure DevOps-Only Contract
+
+- use factory MCP work-item surfaces for bug creation
+- no GitHub Security Advisories, GitHub issue creation, or GitHub-specific security automation assumptions
+
+## Behavioral Constraints
+
+- CVSS scoring must be v4, not v3 fallback
+- critical auto-bug creation threshold is fixed at `>= 9.0`
+- findings must include at least one of: CWE, CVSS v4 vector/score, OWASP mapping
+
+## Verification Expectations
+
+- integration test: findings report includes at least one CWE classification entry
+- integration test: with `autoCreateBugs=false`, verify no `factory_workitem_sync_once` call is made
+
+## 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/setup/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: enact-operator-setup
+description: "Initialize the Enact Operator control-plane: install the enact-operator CLI if needed, then install hooks and agents and verify the runtime is healthy."
+---
+
+# Enact Operator Setup
+
+## Runtime Prerequisite
+
+Before running the workflow, make sure the `enact-operator` CLI exists:
+
+```bash
+which enact-operator || bash scripts/install.sh
+```
+
+## Purpose
+Bootstraps a project to use Enact Operator by laying out the `.enact/operator/` directory tree and installing Operator hooks and agents. Plugin installation and host registry ownership belongs to enact-extensions.
+
+## Use When
+- First-time installation of enact-operator in a project
+- Reinstalling after a version bump or broken hook state
+- Validating that an existing installation is coherent before running team or staged review workflows
+
+## 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 running setup/readiness checks
+- drive setup through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- keep state current as you go — confirm each step before advancing
+
+## Workflow
+1. Run the top-level installer:
+   - MCP: `operator_setup`
+   - CLI: `enact-operator setup`
+2. Install Claude Code hooks (pre/post tool hooks that integrate with the operator runtime):
+   - No MCP tool for hooks install — use CLI: `enact-operator hooks install`
+3. Check hook registration status:
+   - MCP: `operator_hooks_status`
+   - CLI: `enact-operator hooks status`
+4. Install the Core 7 Codex agent roster into the project:
+   - MCP: `operator_agents_pack_install`
+   - CLI: `enact-operator agents install-pack`
+5. Validate the plugin bundle source is coherent (skills, hooks, agents all present):
+   - MCP: `operator_plugin_validate`
+   - CLI: `enact-operator plugins validate`
+6. Check the install registry for operator-owned hooks and agents:
+   - MCP: `operator_install_registry`
+   - CLI: (no direct equivalent — use `operator_install_registry`)
+7. Run the doctor to confirm runtime health:
+   - MCP: `operator_doctor`
+   - CLI: `enact-operator doctor`
+8. Check replacement-readiness to confirm Operator is ready to take over provider roles:
+   - MCP: `operator_audit_replacement_readiness`
+   - CLI: `enact-operator audit replacement-readiness`
+
+## State Contract
+- Reads: project root, existing `.claude/settings.json`, existing hook files
+- Writes: `.enact/operator/` directory tree (`cache`, `jobs`, `logs`, `memory`, `plans`, `reports`, `research`, `sessions`, `state`, `team`, `ultragoal`, `metrics.json`), hook entries in `.claude/settings.json`
+
+## MCP Tools
+
+- `operator_setup` — run the top-level installer
+- `operator_hooks_status` — verify hook registration state
+- `operator_agents_install` — install individual agent templates
+- `operator_agents_pack_install` — install the full Core 7 Codex agent roster
+- `operator_plugin_validate` — check plugin bundle source coherence
+- `operator_install_registry` — read the install registry
+- `operator_doctor` — confirm runtime health
+- `operator_audit_replacement_readiness` — confirm Operator is ready to take over provider roles
+
+Note: hooks install has no MCP equivalent — use `enact-operator hooks install` via CLI.
+
+## Commands
+```
+enact-operator setup
+enact-operator hooks install
+enact-operator hooks status
+enact-operator agents install-pack
+enact-operator plugins validate
+enact-operator doctor
+enact-operator audit replacement-readiness
+```
+
+## 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_doctor` (or `enact-operator doctor`) reports no errors
+- `operator_plugin_validate` reports the enact-operator source bundle is valid
+- `operator_hooks_status` shows all required hooks registered
+- `.enact/operator/` directory exists with expected subdirectories

package/extensions/enact-operator/skills/setup/scripts/install.sh

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PACKAGE_NAME="@amsterdamdatalabs/enact-operator"
+BIN_NAME="enact-operator"
+
+already_installed() {
+    command -v "${BIN_NAME}" >/dev/null 2>&1
+}
+
+require_npm() {
+    if command -v npm >/dev/null 2>&1; then
+        return 0
+    fi
+
+    echo "ERROR: npm is required to install ${PACKAGE_NAME}." >&2
+    echo "Install Node.js + npm from https://nodejs.org/ and rerun this script." >&2
+    exit 1
+}
+
+install_cli() {
+    echo "Installing ${PACKAGE_NAME} via npm..."
+    npm install -g "${PACKAGE_NAME}"
+}
+
+main() {
+    if already_installed; then
+        local current
+        current="$(${BIN_NAME} --version 2>/dev/null | head -1 || echo 'unknown')"
+        echo "${BIN_NAME} already installed: ${current}"
+        echo "Run '${BIN_NAME} setup' in your repo to initialize Operator state."
+        exit 0
+    fi
+
+    require_npm
+    install_cli
+
+    if ! already_installed; then
+        echo "ERROR: ${BIN_NAME} was installed but is not on PATH." >&2
+        echo "Open a new shell or update your npm global bin PATH, then rerun '${BIN_NAME} --version'." >&2
+        exit 1
+    fi
+
+    local current
+    current="$(${BIN_NAME} --version 2>/dev/null | head -1 || echo 'unknown')"
+    echo "${BIN_NAME} installed: ${current}"
+    echo "Next step: run '${BIN_NAME} setup' in the target workspace."
+}
+
+main "$@"

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

@@ -0,0 +1,82 @@
+---
+name: skill
+description: "Meta-skill: list, discover, and route to available Operator skills. Use when the operator wants to know what skills exist or which skill handles a given task."
+---
+
+# Skill
+
+## Purpose
+Provides a navigable index of all skills available in the enact-operator plugin. When the operator asks "what can Operator do?" or "which skill should I use for X?", this skill answers by listing the catalog and routing to the correct skill. It does not execute work itself.
+
+## Use When
+- The operator wants to see all available Operator skills
+- Choosing between skills for a given task type
+- Checking whether a skill exists before invoking it
+- Auditing the plugin's skill surface for completeness
+
+## Execution Policy
+
+- start from the repo and `.enact/operator/` truth, not chat memory
+- drive discovery through MCP tools when running inside Codex; CLI commands are the equivalent operator surface
+- this skill is read-only — it writes nothing
+
+## Workflow
+1. List all source skills in the operator bundle:
+   - MCP: `operator_plugin_list`
+   - CLI: `ls enact-operator/extensions/skills/`
+
+   Plugin installation and host registry state are owned by enact-extensions.
+
+2. For a raw directory listing of skill names:
+   ```
+   ls enact-operator/extensions/skills/
+   ```
+
+3. To validate that all skill files are well-formed:
+   ```
+   enact-operator plugins validate
+   ```
+
+4. To read a specific skill's playbook, open its `SKILL.md` directly:
+   ```
+   enact-operator/extensions/skills/<skill-name>/SKILL.md
+   ```
+
+5. Route the operator to the correct skill based on their task:
+
+   | Task type | Skill |
+   |-----------|-------|
+   | First-time install or reinstall | `$setup` |
+   | Durable multi-executor implementation flow | `$team` |
+   | Single executor execution lane | `$executor` |
+   | Long-horizon multi-session goal | `$ultragoal` |
+   | QA cycling with hard-stop gates | `$ultraqa` |
+   | Remove TODO/placeholder noise | `$ai-slop-cleaner` |
+   | Read-only investigation | `$analyze` |
+   | Specific factual question | `$ask` |
+   | Research anchored to a goal | `$autoresearch-goal` |
+   | Stop all active modes | `$cancel` |
+   | Findings-first review | `$review` |
+   | Notification preferences | `$configure-notifications` |
+   | Wiki/reference lookup | `$wiki` |
+
+## State Contract
+- Reads: `enact-operator/extensions/skills/` directory, `operator_plugin_list` output
+- Writes: nothing
+
+## MCP Tools
+
+- `operator_plugin_list` — list local operator plugin bundle sources
+
+## Commands
+```
+enact-operator plugins validate
+```
+
+## 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
+- All skills listed in the routing table are present in `enact-operator/extensions/skills/`
+- `enact-operator plugins validate` passes with no errors
+- The operator was routed to a specific skill, not left with a general answer

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.