oh-my-codex-pennix 0.18.13

package/skills/autoresearch/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: autoresearch
+description: Stateful validator-gated research loop with native-hook persistence
+---
+
+# Autoresearch
+
+Autoresearch is the skill-first replacement for the deprecated `omx autoresearch` command.
+It keeps the useful measured-research loop, but it now runs as a native-hook stateful workflow instead of a direct CLI or tmux launch surface.
+
+## Boundary with planning research
+
+Use `$autoresearch` when the research output itself is a bounded deliverable that must pass an explicit validator. Do not recommend it for ordinary pre-planning docs lookup or general best-practice checks; use `$best-practice-research` for that. If `$autoresearch` is intentionally run before architecture planning, its approved artifact should feed evidence into `$ralplan`; it should not become a final architecture/component unless the user explicitly asks for ongoing research automation.
+
+## Use when
+- You want a Ralph-ish persistent research loop
+- The task should keep nudging until explicit validation evidence exists
+- You want init-time choice between script validation and prompt+architect validation
+
+## Do not use when
+- You want the old `omx autoresearch` command surface (hard-deprecated)
+- You want detached tmux or split-pane launch parity
+- You have not decided the validation regime yet
+
+## Core contract
+1. **Init chooses validation mode.** Pick exactly one:
+   - `mission-validator-script`
+   - `prompt-architect-artifact`
+2. **Persist mode state** in `.omx/state/.../autoresearch-state.json` including:
+   - `validation_mode`
+   - `completion_artifact_path`
+   - `mission_validator_command` **or** `validator_prompt`
+   - optional `output_artifact_path`
+3. **Completion is artifact-gated.** The loop does not stop because the model says “done”, because a stop hook fired once, or because several turns were no-ops.
+4. **Direct CLI launch is gone.** Use `$deep-interview --autoresearch` for intake and `$autoresearch` for execution.
+
+## Completion artifact contract
+
+### `mission-validator-script`
+The completion artifact must exist and record a passing validator result, for example:
+
+```json
+{
+  "status": "passed",
+  "passed": true,
+  "summary": "metric improved beyond baseline"
+}
+```
+
+### `prompt-architect-artifact`
+The completion artifact must include both an architect approval verdict and an output artifact path, for example:
+
+```json
+{
+  "validator_prompt": "Review the research output against the mission.",
+  "architect_review": { "verdict": "approved" },
+  "output_artifact_path": ".omx/specs/autoresearch-demo/report.md"
+}
+```
+
+## Recommended flow
+1. Run `$deep-interview --autoresearch` to clarify mission + evaluator.
+2. Materialize `.omx/specs/autoresearch-{slug}/mission.md`, `sandbox.md`, and `result.json`.
+3. Start `$autoresearch` with the chosen validation mode stored in mode state.
+4. Let stop-hook / auto-nudge continue until the completion artifact satisfies the chosen validation mode.
+5. Finish only after the validator artifact is complete.
+
+## Migration note
+- `omx autoresearch` is hard-deprecated.
+- No direct CLI launch.
+- No tmux split-pane launch.
+- No noop-count completion gate.

package/skills/autoresearch-goal/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: autoresearch-goal
+description: Durable professor-critic research workflow over Codex goal mode without reviving deprecated omx autoresearch
+---
+
+# Autoresearch Goal
+
+Use this workflow when a research mission should be bound to Codex goal-mode focus while OMX remains the durable state owner. This is for research projects that need Codex goal-mode management plus professor/critic-style validation; it is not the default answer for ordinary pre-planning best-practice lookup.
+
+## Boundary
+- Do **not** use or revive the deprecated `omx autoresearch` direct launch surface.
+- Do **not** claim shell commands mutate hidden Codex `/goal` state.
+- Do **not** edit upstream `../../codex` or add dependencies.
+- Use `get_goal`, `create_goal`, and `update_goal({status: "complete"})` only through the active Codex thread when those tools are available.
+
+## Artifacts
+`omx autoresearch-goal` writes:
+- `.omx/goals/autoresearch/<slug>/mission.json`
+- `.omx/goals/autoresearch/<slug>/rubric.md`
+- `.omx/goals/autoresearch/<slug>/ledger.jsonl`
+- `.omx/goals/autoresearch/<slug>/completion.json`
+
+## Flow
+1. Create the mission and professor-critic rubric:
+   `omx autoresearch-goal create --topic "..." --rubric "..." --critic-command "..."`
+2. Emit the model-facing handoff:
+   `omx autoresearch-goal handoff --slug <slug>`
+3. In the active Codex thread, call `get_goal`; call `create_goal` only if no active goal exists and the printed payload is the intended objective.
+4. Research iteratively against the rubric. Record every critic outcome:
+   `omx autoresearch-goal verdict --slug <slug> --verdict <pass|fail|blocked> --evidence "..."`
+5. Completion is blocked until professor-critic validation records `verdict=pass`. After the mission audit passes, call `update_goal({status: "complete"})`, call `get_goal` again, then run:
+   `omx autoresearch-goal complete --slug <slug> --codex-goal-json <get_goal-json-or-path>`
+6. Treat the completion command as read-only reconciliation plus durable OMX state update; hooks and shell commands must not mutate Codex goal state.
+
+## Completion gate
+A passing professor-critic artifact and a matching complete Codex `get_goal` snapshot are required. Assistant prose, partial tests, or a failed/blocked verdict are not sufficient.

package/skills/best-practice-research/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: best-practice-research
+description: "[OMX] Bounded best-practice research wrapper using official/upstream evidence first"
+argument-hint: "<technology|decision|practice question>"
+---
+
+# Best-Practice Research
+
+Use this skill when a task depends on current external best practices, version-aware guidance, standards, official recommendations, or upstream behavior. This is a workflow wrapper: it routes evidence gathering and synthesis; it is not a new research authority and it does not replace `researcher`.
+
+## Purpose
+
+Produce a cited, reusable best-practice answer or handoff that separates current external evidence from repo-local facts and dependency-selection decisions. For pre-planning investigation, this is the ordinary first research wrapper: gather official/upstream evidence, then hand it to `$ralplan` or the caller as planning input. Do not present `$best-practice-research` as a final architecture component or as a validator-gated research loop.
+
+## Terminal By Default
+
+This skill is terminal and read-only by default. It gathers evidence and produces a cited recommendation with a handoff, then stops. Do not write or edit files, create or amend commits, run mutating commands, or otherwise modify repository state under this skill — even when the question has clear implementation implications. When implementation is warranted, stop and hand off rather than continuing: name `$ralplan` for planning and `$ultragoal`, `$team`, or `executor` for execution, and resume only after the user explicitly switches to that workflow.
+
+## Activate When
+
+- The user asks for best practices, recommended approach, current guidance, official recommendations, standards, or version-aware external behavior.
+- `$ralplan`, `$deep-interview`, `$team`, or another workflow needs current external evidence before planning or execution can be correct.
+- The task involves an already chosen technology and needs authoritative usage guidance, migration notes, API behavior, lifecycle rules, or current safety guidance.
+
+## Do Not Activate When
+
+- The answer is fully repo-local; use `explore` for codebase facts.
+- The main question is whether to adopt, replace, upgrade, or compare dependencies; use `dependency-expert`.
+- The user only needs implementation against already-grounded requirements; use `executor`, `$ralph`, or `$team` as appropriate.
+- The task can be answered from stable local project conventions without current external lookup.
+
+## Specialist Routing
+
+1. Use `explore` first for brownfield facts: current code usage, local constraints, versions, config, and integration points.
+2. Use `researcher` for official/upstream docs, release notes, standards, migration guides, source-backed examples, and current best-practice evidence for an already chosen technology.
+3. Use `dependency-expert` only for adoption/upgrade/replacement/comparison decisions.
+4. Return to the caller with explicit evidence, uncertainty, and any implementation handoff constraints.
+
+## Source-Quality Rules
+
+- Prefer official documentation, upstream source, release notes, changelogs, standards, and maintainer guidance.
+- Include source URLs for material claims.
+- State date/version context for current best-practice claims.
+- Label third-party summaries as supplemental; do not use them before official/upstream sources.
+- Flag stale, conflicting, undocumented, or version-mismatched evidence.
+- Do not over-fetch: gather the smallest evidence set that can support the decision.
+
+## Workflow
+
+1. Classify the question: conceptual best practice, implementation guidance, migration/version guidance, standards/compliance guidance, or mixed local + external guidance.
+2. Gather repo-local facts with `explore` when local usage or constraints affect the answer.
+3. Gather external evidence with `researcher` when current or version-aware practice affects correctness.
+4. Synthesize a concise answer with source quality, version/date context, caveats, and an implementation or planning handoff.
+5. Stop when the answer is grounded enough for the caller; otherwise report the exact blocker or specialist handoff needed.
+
+## Output Contract
+
+```md
+## Best-Practice Research: <question>
+
+### Direct Recommendation
+<actionable guidance or decision support>
+
+### Evidence Used
+- Official/upstream: <source URL> — <what it establishes>
+- Supplemental, if any: <source URL> — <why it is secondary>
+
+### Version / Date Context
+<versions, dates, release channels, or unknowns>
+
+### Repo-Local Context
+<facts from explore, or "not needed">
+
+### Boundaries / Non-goals
+<what this research does not decide>
+
+### Handoff
+<planning/execution/test implications; name the next workflow — `$ralplan` for planning, `$ultragoal`/`$team`/`executor` for execution — and note that this skill stops here unless the user explicitly switches workflows>
+```
+
+## Stop Rules
+
+- Stop after a source-backed recommendation is reusable by the caller.
+- Stop and route upward if the task becomes dependency comparison, broad architecture, or implementation.
+- Do not continue researching when remaining work would only polish wording rather than change the recommendation.
+- This skill never implements. After delivering the recommendation and handoff, stop; do not modify repo files or repo state. Resume only when the user explicitly switches to a planning or implementation workflow named in the handoff.
+
+Task: {{ARGUMENTS}}

package/skills/build-fix/SKILL.md

@@ -0,0 +1,10 @@
+---
+name: build-fix
+description: Build Fix deprecated shim
+---
+
+# Build Fix deprecated
+
+Hard-deprecated. Do not invoke or route this skill. Build failures should be handled by the active execution, debugging, or verification workflow.
+
+Task: {{ARGUMENTS}}

package/skills/cancel/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: cancel
+description: Cancel any active OMX mode (autopilot, ralph, ultrawork, ecomode, ultraqa, swarm, ultrapilot, pipeline, team)
+---
+
+# Cancel Skill
+
+Intelligent cancellation that detects and cancels the active OMX mode.
+
+**The cancel skill is the standard way to complete and exit any OMX mode.**
+When the stop hook detects work is complete, it instructs the LLM to invoke
+this skill for proper state cleanup. If cancel fails or is interrupted,
+retry with `--force` flag, or wait for the 2-hour staleness timeout as
+a last resort.
+
+## What It Does
+
+Automatically detects which mode is active and cancels it:
+- **Autopilot**: Stops workflow, preserves progress for resume
+- **Ralph**: Stops persistence loop, clears linked ultrawork if applicable
+- **Ultrawork**: Stops parallel execution (standalone or linked)
+- **Ecomode**: Stops token-efficient parallel execution (standalone or linked to ralph)
+- **UltraQA**: Stops QA cycling workflow
+- **Swarm**: Stops coordinated agent swarm, releases claimed tasks
+- **Ultrapilot**: Stops parallel autopilot workers
+- **Pipeline**: Stops sequential agent pipeline
+- **Team**: Sends shutdown inbox to all workers, waits for exit, kills tmux session, and clears team state
+
+## Usage
+
+```
+/cancel
+```
+
+Or say: "cancelomc", "stopomc"
+
+## Auto-Detection
+
+`/cancel` follows the session-aware state contract:
+- By default the command inspects the current session via `state_list_active` and `state_get_status`, navigating `.omx/state/sessions/{sessionId}/…` to discover which mode is active.
+- When a session id is provided or already known, that session-scoped path is authoritative. Legacy files in `.omx/state/*.json` are consulted only as a compatibility fallback if the session id is missing or empty.
+- Swarm is a shared SQLite/marker mode (`.omx/state/swarm.db` / `.omx/state/swarm-active.marker`) and is not session-scoped.
+- The default cleanup flow calls `state_clear` with the session id to remove only the matching session files; modes stay bound to their originating session.
+
+## Normative Ralph cancellation post-conditions (MUST)
+
+For Ralph-targeted cancellation (standalone or linked), completion is defined by post-conditions:
+
+1. Target Ralph state is terminalized, not silently removed:
+   - `active=false`
+   - `current_phase='cancelled'`
+   - `completed_at` is set (ISO timestamp)
+2. If Ralph is linked to Ultrawork or Ecomode in the same scope, that linked mode is also terminalized/non-active.
+4. Cancellation MUST remain scope-safe: no mutation of unrelated sessions.
+
+See: `docs/contracts/ralph-cancel-contract.md`.
+
+Active modes are still cancelled in dependency order:
+1. Autopilot (includes linked ultragoal/ultraqa/ecomode cleanup plus explicit legacy Ralph cleanup)
+2. Ralph (cleans its linked ultrawork or ecomode)
+3. Ultrawork (standalone)
+4. Ecomode (standalone)
+5. UltraQA (standalone)
+6. Swarm (standalone)
+7. Ultrapilot (standalone)
+8. Pipeline (standalone)
+9. Team (tmux-based)
+10. Plan Consensus (standalone)
+
+## Normative Ralph post-conditions (MUST)
+
+When cancellation targets Ralph state in a scope, completion requires all of the following:
+
+1. Ralph state is terminal in that same scope: `active=false`, `current_phase='cancelled'` (or linked terminal phase), and `completed_at` is set.
+2. Linked Ultrawork/Ecomode in the same scope is also terminal/non-active.
+4. Unrelated sessions are untouched.
+
+## Force Clear All
+
+Use `--force` or `--all` when you need to erase every session plus legacy artifacts, e.g., to reset the workspace entirely.
+
+```
+/cancel --force
+```
+
+```
+/cancel --all
+```
+
+Steps under the hood:
+1. `state_list_active` enumerates `.omx/state/sessions/{sessionId}/…` to find every known session.
+2. `state_clear` runs once per session to drop that session’s files.
+3. A global `state_clear` without `session_id` removes legacy files under `.omx/state/*.json`, `.omx/state/swarm*.db`, and compatibility artifacts (see list).
+4. Team artifacts (`.omx/state/team/*/`, tmux sessions matching `omx-team-*`) are best-effort cleared as part of the legacy fallback.
+
+Every `state_clear` command honors the `session_id` argument, so even force mode still uses the session-aware paths first before deleting legacy files.
+
+Legacy compatibility list (removed only under `--force`/`--all`):
+- `.omx/state/autopilot-state.json`
+- `.omx/state/ralph-state.json`
+- `.omx/state/ralph-plan-state.json`
+- `.omx/state/ralph-verification.json`
+- `.omx/state/ultrawork-state.json`
+- `.omx/state/ecomode-state.json`
+- `.omx/state/ultraqa-state.json`
+- `.omx/state/swarm.db`
+- `.omx/state/swarm.db-wal`
+- `.omx/state/swarm.db-shm`
+- `.omx/state/swarm-active.marker`
+- `.omx/state/swarm-tasks.db`
+- `.omx/state/ultrapilot-state.json`
+- `.omx/state/ultrapilot-ownership.json`
+- `.omx/state/pipeline-state.json`
+- `.omx/state/plan-consensus.json`
+- `.omx/state/ralplan-state.json`
+- `.omx/state/boulder.json`
+- `.omx/state/hud-state.json`
+- `.omx/state/subagent-tracking.json`
+- `.omx/state/subagent-tracker.lock`
+- `.omx/state/rate-limit-daemon.pid`
+- `.omx/state/rate-limit-daemon.log`
+- `.omx/state/checkpoints/` (directory)
+- `.omx/state/sessions/` (empty directory cleanup after clearing sessions)
+
+## Implementation Steps
+
+When you invoke this skill:
+
+### 1. Parse Arguments
+
+```bash
+# Check for --force or --all flags
+FORCE_MODE=false
+if [[ "$*" == *"--force"* ]] || [[ "$*" == *"--all"* ]]; then
+  FORCE_MODE=true
+fi
+```
+
+### 2. Detect Active Modes
+
+The skill now relies on the session-aware state contract rather than hard-coded file paths:
+1. Call `state_list_active` to enumerate `.omx/state/sessions/{sessionId}/…` and discover every active session.
+2. For each session id, call `state_get_status` to learn which mode is running (`autopilot`, `ralph`, `ultrawork`, etc.) and whether dependent modes exist.
+3. If a `session_id` was supplied to `/cancel`, skip legacy fallback entirely and operate solely within that session path; otherwise, consult legacy files in `.omx/state/*.json` only if the state tools report no active session. Swarm remains a shared SQLite/marker mode outside session scoping.
+4. Any cancellation logic in this doc mirrors the dependency order discovered via state tools (autopilot → ralph → …).
+
+### 3A. Force Mode (if --force or --all)
+
+Use force mode to clear every session plus legacy artifacts via `state_clear`. Direct file removal is reserved for legacy cleanup when the state tools report no active sessions.
+
+### 3B. Smart Cancellation (default)
+
+#### If Team Active (tmux-based)
+
+Teams are detected by checking for config files in `.omx/state/team/`:
+
+```bash
+# Check for active teams
+ls .omx/state/team/*/config.json 2>/dev/null
+```
+
+**Two-pass cancellation protocol:**
+
+**Pass 1: Graceful Shutdown**
+```
+For each team found in .omx/state/team/:
+  1. Read config.json to get team_name and workers list
+  2. For each worker:
+     a. Write shutdown inbox to .omx/state/team/{name}/workers/{worker}/inbox.md
+     b. Send short trigger via tmux send-keys
+     c. Wait up to 15 seconds for worker tmux pane to exit
+     d. If still alive: mark as unresponsive
+```
+
+**Pass 2: Force Kill**
+```
+After graceful pass:
+  1. For each remaining alive worker:
+     a. Send C-c via tmux send-keys
+     b. Wait 2 seconds
+     c. Kill the tmux window if still alive
+  2. Destroy the tmux session: tmux kill-session -t omx-team-{name}
+```
+
+**Cleanup:**
+```
+  1. Strip AGENTS.md team worker overlay (<!-- OMX:TEAM:WORKER:START/END -->)
+  2. Remove team state directory: rm -rf .omx/state/team/{name}/
+  3. Clear team mode state: state_clear(mode="team")
+  4. Emit structured cancel report
+```
+
+**Structured Cancel Report:**
+```
+Team "{team_name}" cancelled:
+  - Workers signaled: N
+  - Graceful exits: M
+  - Force killed: K
+  - tmux session destroyed: yes/no
+  - State cleaned up: yes/no
+```
+
+**Implementation note:** The cancel skill is executed by the LLM, not as a bash script. When you detect an active team:
+1. Check `.omx/state/team/*/config.json` for active teams
+2. For each worker in config.workers, write shutdown inbox and send trigger
+3. Wait briefly for workers to exit (15s timeout)
+4. Force kill remaining workers via tmux
+5. Destroy tmux session: `tmux kill-session -t omx-team-{name}`
+6. Strip AGENTS.md overlay
+7. Remove state: `rm -rf .omx/state/team/{name}/`
+8. `state_clear(mode="team")`
+9. Report structured summary to user
+
+#### If Autopilot Active
+
+Call `cancelAutopilot()` from `src/hooks/autopilot/cancel.ts:27-78`:
+
+```bash
+# Autopilot handles its own cleanup + ralph + ultraqa
+# Just mark autopilot as inactive (preserves state for resume)
+if [[ -f .omx/state/autopilot-state.json ]]; then
+  # Clean up ralph if active
+  if [[ -f .omx/state/ralph-state.json ]]; then
+    RALPH_STATE=$(cat .omx/state/ralph-state.json)
+    LINKED_UW=$(echo "$RALPH_STATE" | jq -r '.linked_ultrawork // false')
+
+    # Clean linked ultrawork first
+    if [[ "$LINKED_UW" == "true" ]] && [[ -f .omx/state/ultrawork-state.json ]]; then
+      rm -f .omx/state/ultrawork-state.json
+      echo "Cleaned up: ultrawork (linked to ralph)"
+    fi
+
+    # Clean ralph
+    rm -f .omx/state/ralph-state.json
+    rm -f .omx/state/ralph-verification.json
+    echo "Cleaned up: ralph"
+  fi
+
+  # Clean up ultraqa if active
+  if [[ -f .omx/state/ultraqa-state.json ]]; then
+    rm -f .omx/state/ultraqa-state.json
+    echo "Cleaned up: ultraqa"
+  fi
+
+  # Mark autopilot inactive but preserve state
+  CURRENT_STATE=$(cat .omx/state/autopilot-state.json)
+  CURRENT_PHASE=$(echo "$CURRENT_STATE" | jq -r '.phase // "unknown"')
+  echo "$CURRENT_STATE" | jq '.active = false' > .omx/state/autopilot-state.json
+
+  echo "Autopilot cancelled at phase: $CURRENT_PHASE. Progress preserved for resume."
+  echo "Run /autopilot to resume."
+fi
+```
+
+#### If Ralph Active (but not Autopilot)
+
+Call `clearRalphState()` + `clearLinkedUltraworkState()` from `src/hooks/ralph-loop/index.ts:147-182`:
+
+```bash
+if [[ -f .omx/state/ralph-state.json ]]; then
+  # Check if ultrawork is linked
+  RALPH_STATE=$(cat .omx/state/ralph-state.json)
+  LINKED_UW=$(echo "$RALPH_STATE" | jq -r '.linked_ultrawork // false')
+
+  # Clean linked ultrawork first
+  if [[ "$LINKED_UW" == "true" ]] && [[ -f .omx/state/ultrawork-state.json ]]; then
+    UW_STATE=$(cat .omx/state/ultrawork-state.json)
+    UW_LINKED=$(echo "$UW_STATE" | jq -r '.linked_to_ralph // false')
+
+    # Only clear if it was linked to ralph
+    if [[ "$UW_LINKED" == "true" ]]; then
+      rm -f .omx/state/ultrawork-state.json
+      echo "Cleaned up: ultrawork (linked to ralph)"
+    fi
+  fi
+
+  # Clean ralph state
+  rm -f .omx/state/ralph-state.json
+  rm -f .omx/state/ralph-plan-state.json
+  rm -f .omx/state/ralph-verification.json
+
+  echo "Ralph cancelled. Persistent mode deactivated."
+fi
+```
+
+#### If Ultrawork Active (standalone, not linked)
+
+Call `deactivateUltrawork()` from `src/hooks/ultrawork/index.ts:150-173`:
+
+```bash
+if [[ -f .omx/state/ultrawork-state.json ]]; then
+  # Check if linked to ralph
+  UW_STATE=$(cat .omx/state/ultrawork-state.json)
+  LINKED=$(echo "$UW_STATE" | jq -r '.linked_to_ralph // false')
+
+  if [[ "$LINKED" == "true" ]]; then
+    echo "Ultrawork is linked to Ralph. Use /cancel to cancel both."
+    exit 1
+  fi
+
+  # Remove local state
+  rm -f .omx/state/ultrawork-state.json
+
+  echo "Ultrawork cancelled. Parallel execution mode deactivated."
+fi
+```
+
+#### If UltraQA Active (standalone)
+
+Call `clearUltraQAState()` from `src/hooks/ultraqa/index.ts:107-120`:
+
+```bash
+if [[ -f .omx/state/ultraqa-state.json ]]; then
+  rm -f .omx/state/ultraqa-state.json
+  echo "UltraQA cancelled. QA cycling workflow stopped."
+fi
+```
+
+#### No Active Modes
+
+```bash
+echo "No active OMX modes detected."
+echo ""
+echo "Checked for:"
+echo "  - Autopilot (.omx/state/autopilot-state.json)"
+echo "  - Ralph (.omx/state/ralph-state.json)"
+echo "  - Ultrawork (.omx/state/ultrawork-state.json)"
+echo "  - UltraQA (.omx/state/ultraqa-state.json)"
+echo ""
+echo "Use --force to clear all state files anyway."
+```
+
+## Implementation Notes
+
+The cancel skill runs as follows:
+1. Parse the `--force` / `--all` flags, tracking whether cleanup should span every session or stay scoped to the current session id.
+2. Use `state_list_active` to enumerate known session ids and `state_get_status` to learn the active mode (`autopilot`, `ralph`, `ultrawork`, etc.) for each session.
+3. When operating in default mode, call `state_clear` with that session_id to remove only the session’s files, then run mode-specific cleanup (autopilot → ralph → …) based on the state tool signals.
+4. In force mode, iterate every active session, call `state_clear` per session, then run a global `state_clear` without `session_id` to drop legacy files (`.omx/state/*.json`, compatibility artifacts) and report success. Swarm remains a shared SQLite/marker mode outside session scoping.
+5. Team artifacts (`.omx/state/team/*/`, tmux sessions matching `omx-team-*`) remain best-effort cleanup items invoked during the legacy/global pass.
+
+State tools always honor the `session_id` argument, so even force mode still clears the session-scoped paths before deleting compatibility-only legacy state.
+
+Mode-specific subsections below describe what extra cleanup each handler performs after the state-wide operations finish.
+## Messages Reference
+
+| Mode | Success Message |
+|------|-----------------|
+| Autopilot | "Autopilot cancelled at phase: {phase}. Progress preserved for resume." |
+| Ralph | "Ralph cancelled. Persistent mode deactivated." |
+| Ultrawork | "Ultrawork cancelled. Parallel execution mode deactivated." |
+| Ecomode | "Ecomode cancelled. Token-efficient execution mode deactivated." |
+| UltraQA | "UltraQA cancelled. QA cycling workflow stopped." |
+| Swarm | "Swarm cancelled. Coordinated agents stopped." |
+| Ultrapilot | "Ultrapilot cancelled. Parallel autopilot workers stopped." |
+| Pipeline | "Pipeline cancelled. Sequential agent chain stopped." |
+| Team | "Team cancelled. Teammates shut down and cleaned up." |
+| Plan Consensus | "Plan Consensus cancelled. Planning session ended." |
+| Force | "All OMX modes cleared. You are free to start fresh." |
+| None | "No active OMX modes detected." |
+
+## What Gets Preserved
+
+| Mode | State Preserved | Resume Command |
+|------|-----------------|----------------|
+| Autopilot | Yes (phase, files, spec, plan, verdicts) | `/autopilot` |
+| Ralph | No | N/A |
+| Ultrawork | No | N/A |
+| UltraQA | No | N/A |
+| Swarm | No | N/A |
+| Ultrapilot | No | N/A |
+| Pipeline | No | N/A |
+| Plan Consensus | Yes (plan file path preserved) | N/A |
+
+## Notes
+
+- **Dependency-aware**: Autopilot cancellation cleans up Ultragoal/UltraQA state and any explicit legacy Ralph state
+- **Link-aware**: Ralph cancellation cleans up linked Ultrawork or Ecomode
+- **Safe**: Only clears linked Ultrawork, preserves standalone Ultrawork
+- **Local-only**: Clears state files in `.omx/state/` directory
+- **Resume-friendly**: Autopilot state is preserved for seamless resume
+- **Team-aware**: Detects tmux-based teams and performs graceful shutdown with force-kill fallback
+
+## Tmux Team Cleanup
+
+When cancelling team mode, the cancel skill should:
+
+1. **Kill all team tmux sessions**: `tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^omx-team-'` and kill each
+2. **Remove team state directories**: `rm -rf .omx/state/team/*/`
+3. **Strip AGENTS.md overlay**: Remove content between `<!-- OMX:TEAM:WORKER:START -->` and `<!-- OMX:TEAM:WORKER:END -->`
+
+### Force Clear Addition
+
+When `--force` is used, also clean up:
+```bash
+rm -rf .omx/state/team/                  # All team state
+# Kill all omx-team-* tmux sessions
+tmux list-sessions -F '#{session_name}' 2>/dev/null | grep '^omx-team-' | while read s; do tmux kill-session -t "$s" 2>/dev/null; done
+```