@trac3r/oh-my-god 2.2.11

package/commands/OMG:setup.md

@@ -0,0 +1,82 @@
+---
+description: "Native OMG setup and adoption flow for supported hosts"
+allowed-tools: Read, Write, Edit, Bash(python*:*), Bash(ls:*), Bash(grep:*)
+argument-hint: "[optional: --non-interactive, --mode omg-only|coexist, --preset safe|balanced|interop|labs|buffet|production]"
+---
+
+# /OMG:setup
+
+Feature-gated: requires `OMG_SETUP_ENABLED=1` or `settings.json._omg.features.SETUP: true`.
+
+## Overview
+
+Native OMG setup for Claude Code, Codex, and other supported CLIs.
+The command keeps migration logic internal and focuses the user on a small adoption flow:
+
+1. Detect supported CLIs.
+2. Detect overlapping ecosystems.
+3. Recommend an adoption mode.
+4. Apply an OMG preset.
+5. Configure MCP and save preferences.
+
+Setup now runs foreign-plugin discovery in `interop` and `coexist` modes, reporting compatibility findings and potential overlaps.
+
+## Wizard Flow
+
+```text
+Step 1: Detect CLIs
+  - codex
+  - gemini
+  - kimi
+
+Step 2: Detect adoption context
+  - OMC-style markers
+  - OMX-style markers
+  - Superpowers-style markers
+
+Step 3: Choose mode
+  - OMG-only (recommended)
+  - coexist
+
+Step 4: Choose preset
+  - safe
+  - balanced
+  - interop
+  - labs
+  - buffet
+  - production
+
+Step 5: Configure MCP and persist preferences
+  - writes .mcp.json
+  - writes .omg/state/cli-config.yaml
+  - writes .omg/state/adoption-report.json
+```
+
+## Modes
+
+`OMG-only`
+- Recommended default.
+- OMG becomes the main hooks, HUD, MCP, and orchestration layer.
+
+`coexist`
+- Advanced mode.
+- OMG avoids destructive overlap and keeps third-party command namespaces intact where possible.
+
+## Output
+
+The command emits a final summary that includes:
+
+- CLI detection results
+- auth status
+- MCP configuration status
+- selected preset
+- selected adoption mode
+- adoption report path
+
+## Public Path
+
+The public OMG journey is:
+
+1. install for your host
+2. run `doctor --fix`
+3. run `/OMG:ship <goal>`

package/commands/OMG:ship.md

@@ -0,0 +1,18 @@
+---
+description: "Ship — Idea to Evidence to PR"
+allowed-tools: Read, Grep, Glob
+argument-hint: "[goal or optional path to .omg/idea.yml]"
+---
+
+# /OMG:ship
+
+`/OMG:ship` is a compatibility path to the canonical `ship` pipeline in the advanced plugin.
+
+Users invoke `/OMG:ship`; the runtime routes to `plugins/advanced/commands/OMG:ship.md` for execution.
+For the full behavior specification, see `plugins/advanced/commands/OMG:ship.md`.
+
+## Compatibility Notes
+
+- This alias exists so users can invoke the ship pipeline from the root command surface.
+- Runtime behavior resolves to the advanced `ship` command — same idea-to-evidence-to-PR pipeline, same artifacts.
+- OMG uses the `ship` pipeline for canonical idea intake, execution, evidence collection, and PR-ready delivery.

package/commands/OMG:stats.md

@@ -0,0 +1,225 @@
+---
+description: "Display session analytics, tool usage trends, file heatmaps, and failure patterns."
+allowed-tools: Read, Bash(python*:*), Grep
+argument-hint: "[weekly|files|failures|dashboard]"
+---
+
+# /OMG:stats — Session Analytics
+
+Display session analytics, tool usage trends, file heatmaps, and failure patterns.
+
+## Usage
+
+```
+/OMG:stats
+/OMG:stats weekly
+/OMG:stats files
+/OMG:stats failures
+/OMG:stats dashboard
+```
+
+## Sub-Commands
+
+### `/OMG:stats` (default)
+
+Show current session summary: duration, tool calls, success rate, cost, and test runs.
+
+```python
+from hooks.query import get_session_summary
+
+summary = get_session_summary(".")
+duration_m = summary["duration"] // 60
+duration_s = summary["duration"] % 60
+print(f"Duration:       {duration_m}m {duration_s}s")
+print(f"Tool calls:     {summary['tool_calls']}")
+print(f"Success rate:   {summary['success_rate']:.1%}")
+print(f"Files modified: {summary['files_modified']}")
+print(f"Tests run:      {summary['tests_run']}")
+print(f"Tokens used:    {summary['tokens_used']:,}")
+print(f"Cost:           ${summary['cost_usd']:.4f}")
+```
+
+### `/OMG:stats weekly`
+
+Show last 7 days trend analysis by aggregating tool stats and escalation effectiveness.
+
+```python
+from hooks.query import get_tool_stats, get_escalation_effectiveness
+
+tools = get_tool_stats(".")
+escalations = get_escalation_effectiveness(".")
+
+# Per-tool breakdown
+for tool, stats in sorted(tools.items(), key=lambda x: x[1]["count"], reverse=True):
+    print(f"  {tool}: {stats['count']} calls, {stats['success_rate']:.0%} success, {stats['avg_tokens']:.0f} avg tokens")
+
+# Escalation summary
+print(f"\nEscalations: {escalations['escalations']} total, {escalations['resolved']} resolved, {escalations['unresolved']} unresolved")
+```
+
+### `/OMG:stats files`
+
+Show file-level heatmap of the most read, written, and edited files.
+
+```python
+from hooks.query import get_file_heatmap
+
+heatmap = get_file_heatmap(".")
+
+# Sort by total interactions (reads + writes + edits)
+ranked = sorted(
+    heatmap.items(),
+    key=lambda x: x[1]["reads"] + x[1]["writes"] + x[1]["edits"],
+    reverse=True,
+)
+
+print(f"{'File':<50} {'Reads':>6} {'Writes':>7} {'Edits':>6}")
+print("-" * 73)
+for path, counts in ranked[:20]:
+    total = counts["reads"] + counts["writes"] + counts["edits"]
+    print(f"{path:<50} {counts['reads']:>6} {counts['writes']:>7} {counts['edits']:>6}")
+```
+
+### `/OMG:stats failures`
+
+Show top failure patterns and their resolution status.
+
+```python
+from hooks.query import get_failure_hotspots, get_escalation_effectiveness
+
+hotspots = get_failure_hotspots(".")
+escalations = get_escalation_effectiveness(".")
+
+for pattern, details in sorted(hotspots.items(), key=lambda x: x[1]["count"], reverse=True):
+    status = "ESCALATED" if details["escalated"] else "active"
+    print(f"  [{status}] {pattern}: {details['count']} failures")
+    for err in details["last_3_errors"]:
+        print(f"    - {err[:100]}")
+
+print(f"\nResolution: {escalations['resolved']}/{escalations['escalations']} escalations resolved")
+```
+
+### `/OMG:stats dashboard`
+
+Generate a self-contained HTML dashboard at `.omg/state/dashboard.html`.
+
+The dashboard includes:
+- Session summary cards (duration, tool calls, cost, success rate)
+- Tool usage bar chart (via CDN Chart.js)
+- File heatmap table (top 20 files by interaction count)
+- Failure pattern list with escalation status
+
+```python
+import json
+import os
+from hooks.query import (
+    get_session_summary,
+    get_tool_stats,
+    get_file_heatmap,
+    get_failure_hotspots,
+)
+
+summary = get_session_summary(".")
+tools = get_tool_stats(".")
+heatmap = get_file_heatmap(".")
+failures = get_failure_hotspots(".")
+
+dashboard_data = {
+    "summary": summary,
+    "tools": tools,
+    "heatmap": dict(sorted(
+        heatmap.items(),
+        key=lambda x: x[1]["reads"] + x[1]["writes"] + x[1]["edits"],
+        reverse=True,
+    )[:20]),
+    "failures": failures,
+}
+
+# Write self-contained HTML with embedded Chart.js
+output_path = os.path.join(".omg", "state", "dashboard.html")
+os.makedirs(os.path.dirname(output_path), exist_ok=True)
+# ... (HTML template with CDN Chart.js and embedded JSON data)
+print(f"Dashboard written to {output_path}")
+```
+
+## Feature Flag
+
+- **Flag name**: `OMG_SESSION_ANALYTICS_ENABLED`
+- **Default**: `False` (disabled)
+- **Enable**: `export OMG_SESSION_ANALYTICS_ENABLED=1`
+
+Or set in `settings.json`:
+
+```json
+{
+  "_omg": {
+    "features": {
+      "SESSION_ANALYTICS": true
+    }
+  }
+}
+```
+
+## Output Example
+
+```
+============================================================
+  OMG Session Analytics — Summary
+============================================================
+
+  Duration:       23m 47s
+  Tool calls:     142
+  Success rate:   94.4%
+  Files modified: 18
+  Tests run:      6
+  Tokens used:    287,450
+  Cost:           $1.1142
+
+  Top Tools:
+    Bash:           58 calls, 95% success, 1,240 avg tokens
+    Read:           34 calls, 100% success, 890 avg tokens
+    Edit:           22 calls, 91% success, 1,100 avg tokens
+    Write:          16 calls, 100% success, 950 avg tokens
+    Grep:           12 calls, 100% success, 320 avg tokens
+
+  Failure Hotspots:
+    [ESCALATED] hooks/budget_governor.py: 4 failures
+    [active] tests/test_integration.py: 2 failures
+
+  Escalations: 1 total, 0 resolved, 1 unresolved
+
+============================================================
+```
+
+## Safety
+
+- **Read-only**: All sub-commands only read from existing ledger/tracker files
+- **Feature-gated**: Requires `SESSION_ANALYTICS` flag enabled
+- **No mutations**: Never modifies ledger data, failure tracker, or working memory
+- **Crash-isolated**: All query operations exit 0 on failure (via query.py internals)
+- **Dashboard**: Writes only to `.omg/state/dashboard.html` (inside managed state directory)
+
+## API
+
+```python
+from hooks.query import (
+    get_session_summary,
+    get_tool_stats,
+    get_failure_hotspots,
+    get_escalation_effectiveness,
+    get_file_heatmap,
+)
+
+# Current session summary
+summary = get_session_summary(".")
+
+# Per-tool statistics
+tools = get_tool_stats(".")
+
+# Failure patterns and escalation status
+failures = get_failure_hotspots(".")
+escalations = get_escalation_effectiveness(".")
+
+# File interaction heatmap
+heatmap = get_file_heatmap(".")
+```

package/commands/OMG:teams.md

@@ -0,0 +1,54 @@
+---
+description: OMG internal staged team routing (standalone). /OMG:team canonical, /OMG:teams compatibility alias.
+allowed-tools: Read, Grep, Glob, Bash(git:*), Bash(rg:*), Bash(find:*), Bash(cat:*), Bash(python3:*)
+argument-hint: "[codex|gemini|ccg|auto] 'problem statement'"
+---
+
+# /OMG:teams — Standalone Internal Router
+
+Canonical alias: `/OMG:team`
+Compatibility alias: `/OMG:teams`
+
+Use OMG's internal router using internal routing.
+
+## Input contract
+- target: `auto|codex|gemini|ccg`
+- problem: clear issue statement
+- context: optional constraints
+- files: optional focus paths
+- expected_outcome: optional acceptance target
+
+## Execution
+Use internal CLI router (canonical):
+
+```bash
+OMG_CLI="${OMG_CLI_PATH:-$HOME/.claude/omg-runtime/scripts/omg.py}"
+if [ ! -f "$OMG_CLI" ] && [ -f "scripts/omg.py" ]; then OMG_CLI="scripts/omg.py"; fi
+python3 "$OMG_CLI" team --target auto --problem "[problem]"
+```
+
+Compatibility alias (legacy):
+
+```bash
+python3 "$OMG_CLI" teams --target auto --problem "[problem]"
+```
+
+For explicit target:
+
+```bash
+python3 "$OMG_CLI" team --target codex --problem "[problem]"
+```
+
+## Staged flow
+- `team-plan`: resolve context packet and clarification/council gate before dispatch
+- `team-exec`: launch workers only when context is resolved
+- `team-verify`: run verification and critic synthesis
+- `team-fix`: surface blockers/next actions for follow-up iteration
+
+## Output schema
+`TeamDispatchResult { status, findings[], actions[], evidence{} }`
+
+## Full-power sub-agent protocol
+- For non-trivial tasks, launch multiple sub-agents in parallel (`run_in_background=true`) for independent tracks.
+- Collect all task outputs before responding (`background_output` per task id).
+- Run a `sequential-thinking` merge step to produce one dependency-ordered execution plan.

package/commands/OMG:theme.md

@@ -0,0 +1,44 @@
+---
+description: "Interactive theme selection, preview, and auto-detection."
+usage: "/OMG:theme [--list|--set <name>|--preview <name>|--auto]"
+---
+
+# /OMG:theme — Theme Selector
+
+Interactive theme selection, preview, and auto-detection for OMG.
+
+## Usage
+
+```
+/OMG:theme --list
+/OMG:theme --preview catppuccin-mocha
+/OMG:theme --set catppuccin-mocha
+/OMG:theme --auto
+```
+
+## What It Does
+
+1. `--list`: Returns a sorted list of available theme names.
+2. `--preview <name>`: Returns preview info `{name, colors, ansi_preview: str}` without applying.
+3. `--set <name>`: Applies and persists the theme, returns `{success, theme, applied_at}`.
+4. `--auto`: Detects dark/light mode and returns appropriate default theme name.
+
+## Feature Flag
+
+Themes are gated behind `OMG_THEMES_ENABLED` (default: `False`).
+
+Enable via environment variable:
+```bash
+export OMG_THEMES_ENABLED=true
+```
+
+Or in `settings.json`:
+```json
+{
+  "_omg": {
+    "features": {
+      "THEMES": true
+    }
+  }
+}
+```

package/commands/OMG:validate.md

@@ -0,0 +1,59 @@
+---
+description: Canonical validation — doctor + contract + profile + install checks
+allowed-tools: Bash(python3:*), Bash(ls:*), Bash(cat:*), Bash(grep:*), Bash(git:*), Read, Grep, Glob
+---
+
+# /OMG:validate
+
+Run the canonical OMG validation engine that composes all verification surfaces:
+
+1. **Doctor checks**: Python version, fastmcp, omg-control, policy files, metadata drift, compiled bundles, host compatibility, memory, managed runtime
+2. **Contract registry**: Validates contract doc, schema, and bundle integrity
+3. **Profile governor**: Verifies governed preferences structure and pending confirmations
+4. **Install integrity**: Confirms scripts, runtime, commands, and plugins directories exist
+
+## Usage
+
+```bash
+# Human-readable output (default)
+python3 scripts/omg.py validate
+
+# Machine-readable JSON
+python3 scripts/omg.py validate --format json
+```
+
+## Output Schema (JSON)
+
+```json
+{
+  "schema": "ValidateResult",
+  "status": "pass" | "fail",
+  "checks": [
+    {
+      "name": "check_name",
+      "status": "ok" | "blocker" | "warning",
+      "message": "human-readable description",
+      "required": true | false
+    }
+  ],
+  "version": "2.2.11"
+}
+```
+
+## Exit Codes
+
+- `0` — all required checks pass
+- `1` — one or more blockers detected
+
+## Report Format (text)
+
+```
+   PASS python_version: Python 3.12.0
+   PASS fastmcp: fastmcp importable
+BLOCKER omg_control_reachable: omg-control not found in .mcp.json
+   PASS contract_registry: contract registry valid (0 errors)
+   PASS profile_governor: profile governor ok (2 style, 1 safety) (optional)
+   PASS install_integrity: install integrity ok
+
+PASS [5] | WARN [0] | BLOCKER [1]
+```

package/commands/__init__.py

@@ -0,0 +1 @@
+"""OMG command package marker for packaging parity."""

package/docs/command-surface.md

@@ -0,0 +1,55 @@
+<!-- GENERATED: DO NOT EDIT MANUALLY -->
+# OMG Command Surface
+
+Generated for OMG v2.2.10.
+
+## Commands
+
+| Command | Description |
+| :--- | :--- |
+| `npx omg ship` | Idea -> Evidence -> PR flow |
+| `npx omg fix` | Issue-driven fix flow |
+| `npx omg issue` | Active issue diagnostics and red-team simulation |
+| `npx omg undo` | Undo last interaction step |
+| `npx omg secure` | Evaluate command risk |
+| `npx omg security` | Canonical OMG security workflows |
+| `npx omg waive-tests` | Emit structured waiver evidence for test-intent lock exceptions |
+| `npx omg api-twin` | Contract replay and fixture-based API simulation |
+| `npx omg preflight` | Structured OMG preflight routing |
+| `npx omg resolve-policy` | Resolve effective policy from tier, presets, and packs |
+| `npx omg policy-pack` | Policy pack management |
+| `npx omg proof` | Proof helpers |
+| `npx omg blocked` | Inspect governance block explanations |
+| `npx omg explain` | Explain run artifacts |
+| `npx omg budget` | Budget envelope operations |
+| `npx omg domain-pack` | Inspect optional domain pack contracts |
+| `npx omg vision` | OCR, visual diff, and semantic image analysis |
+| `npx omg tracebank` | Record structured route traces |
+| `npx omg eval-gate` | Evaluate a trace for release gating |
+| `npx omg delta-classifier` | Classify repo changes for routing and policy |
+| `npx omg incident-replay` | Build an incident replay pack |
+| `npx omg data-lineage` | Build lineage metadata for generated artifacts |
+| `npx omg remote-supervisor` | Local-only authenticated supervisor session helpers |
+| `npx omg maintainer` | OSS maintainer evidence helper |
+| `npx omg trust` | Trust review operations |
+| `npx omg runtime` | Runtime operations |
+| `npx omg lab` | Lab pipeline operations |
+| `npx omg forge` | Labs-only domain-model prototyping and evaluation |
+| `npx omg teams` | Internal OMG team routing |
+| `npx omg team` | Internal OMG staged team routing (canonical) |
+| `npx omg ccg` | OMG CCG (tri-track) routing |
+| `npx omg crazy` | OMG CRAZY mode - parallel multi-agent orchestration |
+| `npx omg compat` | OMG legacy compatibility bridge |
+| `npx omg omc` | Alias of `compat` for legacy scripts |
+| `npx omg ecosystem` | Upstream ecosystem sync and status |
+| `npx omg contract` | Canonical OMG contract validation and compilation |
+| `npx omg context` | Context packet compiler |
+| `npx omg provider-parity-eval` | Evaluate provider parity across canonical hosts |
+| `npx omg release` | OMG release audit and readiness checks |
+| `npx omg doctor` | Canonical install and runtime verification |
+| `npx omg validate` | Canonical validation — doctor + contract + profile + install |
+| `npx omg diagnose-plugins` | Diagnose plugin interoperability and conflicts |
+| `npx omg profile-review` | Review governed profile state |
+| `npx omg docs` | OMG documentation generator |
+| `npx omg install` | Compute, dry-run, or apply an install plan |
+| `npx omg env` | Environment preflight and doctor alias |

package/docs/install/claude-code.md

@@ -0,0 +1,53 @@
+# Install OMG for Claude Code
+
+<!-- OMG:GENERATED:install-fast-path -->
+## Fast Path
+
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan    # preview only, no mutations
+npx omg install --apply   # apply configuration
+```
+
+The preview step is advisory only and makes no mutations until you run apply.
+<!-- /OMG:GENERATED:install-fast-path -->
+
+## Official Claude Plugin Flow
+
+Claude Code's native plugin commands are still the source of truth:
+
+```bash
+claude plugin marketplace add /path/to/OMG --scope user
+claude plugin install omg@omg --scope user
+```
+
+Run `npx omg install --apply` after reviewing the preview if you want OMG to write Claude-facing configuration.
+
+Claude-specific note:
+
+- Claude's newer host model treats custom task surfaces as skills first. Legacy `.claude/commands/` entries may still work, but OMG should be installed and verified through the plugin-managed marketplace/skill surface, not by checking for standalone command markdown files.
+- OMG does not try to shadow Claude's built-in slash commands; it stays on its own `/OMG:*` namespace and native plugin/skill surfaces.
+
+Optional browser capability:
+
+<details><summary>Restricted environments: legacy browser setup</summary>
+
+```bash
+./OMG-setup.sh install --enable-browser
+```
+
+That enables OMG's browser capability metadata for `/OMG:browser` and records the preferred upstream Playwright CLI command under `~/.claude/omg-runtime/browser/capability.json`.
+
+</details>
+
+## Verify
+
+- `claude plugin list` should show `omg@omg` with `Status: enabled`
+- `~/.claude/plugins/known_marketplaces.json` should contain an `omg` entry
+- the installed plugin cache should contain `.claude-plugin/plugin.json` for the current OMG version
+- `~/.claude/settings.json` should contain a `statusLine` command pointing at `~/.claude/hud/omg-hud.mjs`
+- `~/.claude/.mcp.json` should not duplicate the plugin-managed `omg-control` server
+- `~/.claude/omg-runtime/.venv/bin/python` should exist
+- if browser capability is enabled, `~/.claude/omg-runtime/browser/capability.json` should exist

package/docs/install/codex.md

@@ -0,0 +1,45 @@
+# Install OMG for Codex
+
+<!-- OMG:GENERATED:install-fast-path -->
+## Fast Path
+
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan    # preview only, no mutations
+npx omg install --apply   # apply configuration
+```
+
+The preview step is advisory only and makes no mutations until you run apply.
+<!-- /OMG:GENERATED:install-fast-path -->
+
+<details><summary>Restricted environments / manual setup</summary>
+
+```bash
+git clone https://github.com/trac3r00/OMG
+cd OMG
+./OMG-setup.sh install --mode=omg-only --preset=interop
+```
+
+Optional browser capability:
+
+```bash
+./OMG-setup.sh install --mode=omg-only --preset=interop --enable-browser
+```
+
+</details>
+
+## Verify
+
+- `codex mcp list` should include `omg-control`
+- `~/.codex/config.toml` should contain `[mcp_servers.omg-control]`
+- the configured command should point at `~/.claude/omg-runtime/.venv/bin/python`
+- if browser capability is enabled, `~/.claude/omg-runtime/browser/capability.json` should exist
+
+## Notes
+
+- `/OMG:*` slash commands are Claude Code surfaces, not Codex CLI surfaces
+- Codex consumes OMG through native MCP plus the generated Codex pack under `.agents/skills/omg/`
+- Codex keeps its own built-in slash commands and instruction files. OMG should stay compatible with Codex's native `AGENTS.md` hierarchy and skill loading rather than trying to mirror built-in `/personality`, `/approvals`, `/agent`, or related host commands.
+- Generated OMG Codex artifacts are expected to compose with the repo's `AGENTS.md` / `AGENTS.override.md` flow and the host's progressive-disclosure skill loading.

package/docs/install/gemini.md

@@ -0,0 +1,43 @@
+# Install OMG for Gemini CLI
+
+<!-- OMG:GENERATED:install-fast-path -->
+## Fast Path
+
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan    # preview only, no mutations
+npx omg install --apply   # apply configuration
+```
+
+The preview step is advisory only and makes no mutations until you run apply.
+<!-- /OMG:GENERATED:install-fast-path -->
+
+<details><summary>Restricted environments / manual setup</summary>
+
+```bash
+git clone https://github.com/trac3r00/OMG
+cd OMG
+./OMG-setup.sh install --mode=omg-only --preset=interop
+```
+
+Optional browser capability:
+
+```bash
+./OMG-setup.sh install --mode=omg-only --preset=interop --enable-browser
+```
+
+</details>
+
+## Verify
+
+- `gemini mcp list` should include `omg-control`
+- `~/.gemini/settings.json` should contain `mcpServers.omg-control`
+- the configured command should point at `~/.claude/omg-runtime/.venv/bin/python`
+- if browser capability is enabled, `~/.claude/omg-runtime/browser/capability.json` should exist
+
+## Notes
+
+- Gemini uses native MCP registration; it does not consume Claude `/OMG:*` slash commands
+- OMG support on Gemini is the shared runtime plus MCP control plane