@trac3er/oh-my-god 2.0.0 → 2.0.2

package/commands/OMG:arch.md

@@ -1,30 +1,313 @@
 ---
-description: "Inspect the Bun/TypeScript architecture surface and summarize module boundaries."
-allowed-tools: Read, Grep, Glob, Bash(rg:*), Bash(find:*), Bash(bun:*)
-argument-hint: "[optional focus area]"
+description: "Codebase visualization — dependency graphs and architecture diagrams."
+allowed-tools: Read, Bash(python*:*), Grep
+argument-hint: "[render|module-name|stats|--native]"
 ---
 
-# /OMG:arch
+# /OMG:arch — Architecture Visualization
 
-Use this command to inspect the current OMG architecture after the Bun cutover.
+Visualize project dependency graphs as Mermaid diagrams, render to PNG, zoom into specific modules, and inspect graph statistics.
 
-## Focus Areas
+## Usage
 
-- `scripts/omg.ts` for CLI surface
-- `hooks/*.ts` for Claude lifecycle enforcement
-- `runtime/*.ts` for routing and release logic
-- `control_plane/*.ts` for JSON API entrypoints
-- `lab/*.ts`, `registry/*.ts`, and `omg_natives/*.ts` for supporting services
+```
+/OMG:arch
+/OMG:arch render
+/OMG:arch <module-name>
+/OMG:arch stats
+/OMG:arch --native
+```
+
+## Sub-Commands
+
+### `/OMG:arch` (default)
+
+Full project dependency graph as Mermaid text output, embeddable in Markdown.
+
+Scans all Python (.py), JavaScript/TypeScript (.js/.jsx/.ts/.tsx), and Go (.go) files. Python files are parsed via AST; JS/TS/Go files use regex-based import detection (~70% accuracy).
+
+```python
+from plugins.viz.graph_builder import build_project_graph
+from plugins.viz.diagram_generator import generate_mermaid
+
+result = build_project_graph(".")
+graph = result.get("graph", {})
+
+mermaid_text = generate_mermaid(graph)
+if mermaid_text:
+    print("```mermaid")
+    print(mermaid_text)
+    print("```")
+else:
+    print("No dependencies detected.")
+```
+
+### `/OMG:arch render`
+
+Render the dependency graph to a PNG image via the mermaid.ink public API. Saves output to `.omg/state/arch-diagram.png`.
+
+Requires network access to `https://mermaid.ink`.
+
+```python
+import os
+from plugins.viz.graph_builder import build_project_graph
+from plugins.viz.diagram_generator import generate_mermaid, render_to_png
+
+result = build_project_graph(".")
+graph = result.get("graph", {})
+mermaid_text = generate_mermaid(graph)
+
+output_path = os.path.join(".omg", "state", "arch-diagram.png")
+os.makedirs(os.path.dirname(output_path), exist_ok=True)
+
+if render_to_png(mermaid_text, output_path):
+    print(f"Diagram rendered to {output_path}")
+else:
+    print("Render failed — check network access or graph size.")
+```
+
+### `/OMG:arch <module-name>`
+
+Zoomed subgraph for a specific module. Shows only the named module and its direct dependencies.
+
+Replace `<module-name>` with the dotted module path (e.g. `plugins.viz.graph_builder`).
+
+```python
+from plugins.viz.graph_builder import build_project_graph
+from plugins.viz.diagram_generator import generate_mermaid
+
+result = build_project_graph(".")
+graph = result.get("graph", {})
+
+# Zoom into a specific module
+module_name = "<module-name>"  # e.g. "plugins.viz.graph_builder"
+mermaid_text = generate_mermaid(graph, zoom=module_name)
+
+if mermaid_text:
+    print(f"Dependencies for: {module_name}")
+    print()
+    print("```mermaid")
+    print(mermaid_text)
+    print("```")
+else:
+    print(f"Module '{module_name}' not found in dependency graph.")
+    print()
+    print("Available modules:")
+    for mod in sorted(graph.keys()):
+        print(f"  - {mod}")
+```
+
+### `/OMG:arch stats`
+
+Graph statistics: module count, edge count, max depth, circular dependencies, and coupling score.
+
+```python
+from plugins.viz.graph_builder import build_project_graph
+
+result = build_project_graph(".")
+metrics = result.get("metrics", {})
+
+module_count = metrics.get("module_count", 0)
+edge_count = metrics.get("edge_count", 0)
+max_depth = metrics.get("max_depth", 0)
+circular_deps = metrics.get("circular_deps", [])
+coupling_score = metrics.get("coupling_score", 0.0)
+
+print(f"Modules:        {module_count}")
+print(f"Edges:          {edge_count}")
+print(f"Max depth:      {max_depth}")
+print(f"Circular deps:  {len(circular_deps)}")
+print(f"Coupling score: {coupling_score:.2f}")
+
+if circular_deps:
+    print()
+    print("Circular dependency cycles:")
+    for cycle in circular_deps:
+        print(f"  {' → '.join(cycle)}")
+```
+
+### `/OMG:arch --native`
+
+Use native language toolchains for higher-accuracy dependency parsing (~95% vs ~70% with regex).
+
+Supported toolchains:
+- **Go**: `go list -json ./...` — requires `go` on PATH
+- **TypeScript**: `tsc --listFiles --noEmit` — requires `tsc` on PATH
+- **Rust**: `cargo metadata --format-version=1 --no-deps` — requires `cargo` on PATH
 
-## Suggested scan
+Falls back to regex parsing when a toolchain is not available.
 
-```bash
-find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) | sort
+```python
+from plugins.viz.native_parsers import (
+    is_toolchain_available,
+    parse_go_native,
+    parse_typescript_native,
+    parse_rust_native,
+)
+from plugins.viz.graph_builder import build_project_graph
+from plugins.viz.diagram_generator import generate_mermaid
+
+# Check available toolchains
+toolchains = {
+    "go": is_toolchain_available("go"),
+    "tsc": is_toolchain_available("tsc"),
+    "cargo": is_toolchain_available("cargo"),
+}
+
+print("Toolchain availability:")
+for tc, available in toolchains.items():
+    status = "available" if available else "not found"
+    print(f"  {tc}: {status}")
+print()
+
+# Parse with native toolchains where available
+native_graphs = {}
+if toolchains["go"]:
+    go_result = parse_go_native(".")
+    if "error" not in go_result:
+        native_graphs.update(go_result["graph"])
+        print(f"Go: {len(go_result['graph'])} packages (native-95% accuracy)")
+
+if toolchains["tsc"]:
+    ts_result = parse_typescript_native(".")
+    if "error" not in ts_result:
+        native_graphs.update(ts_result["graph"])
+        print(f"TypeScript: {len(ts_result['graph'])} modules (native-95% accuracy)")
+
+if toolchains["cargo"]:
+    rust_result = parse_rust_native(".")
+    if "error" not in rust_result:
+        native_graphs.update(rust_result["graph"])
+        print(f"Rust: {len(rust_result['graph'])} crates (native-95% accuracy)")
+
+# Fall back to regex-based graph for remaining files
+result = build_project_graph(".")
+graph = result.get("graph", {})
+
+# Merge: native results override regex results
+merged = {**graph, **native_graphs}
+
+mermaid_text = generate_mermaid(merged)
+if mermaid_text:
+    print()
+    print("```mermaid")
+    print(mermaid_text)
+    print("```")
 ```
 
-Summaries should call out:
+## Feature Flag
+
+- **Flag name**: `OMG_CODEBASE_VIZ_ENABLED`
+- **Default**: `False` (disabled)
+- **Enable**: `export OMG_CODEBASE_VIZ_ENABLED=1`
+
+Or set in `settings.json`:
+
+```json
+{
+  "_omg": {
+    "features": {
+      "CODEBASE_VIZ": true
+    }
+  }
+}
+```
+
+## Output Example
+
+### `/OMG:arch` output
+
+````
+```mermaid
+graph TD
+    hooks_budget_governor["hooks.budget_governor"]
+    hooks__common["hooks._common"]
+    hooks__cost_ledger["hooks._cost_ledger"]
+    plugins_viz_graph_builder["plugins.viz.graph_builder"]
+    plugins_viz_ast_parser["plugins.viz.ast_parser"]
+    plugins_viz_regex_parser["plugins.viz.regex_parser"]
+    hooks_budget_governor --> hooks__common
+    hooks_budget_governor --> hooks__cost_ledger
+    plugins_viz_graph_builder --> plugins_viz_ast_parser
+    plugins_viz_graph_builder --> plugins_viz_regex_parser
+```
+````
+
+### `/OMG:arch stats` output
+
+```
+============================================================
+  OMG Architecture — Graph Statistics
+============================================================
 
-- public entrypoints
-- persistence under `.omg/`
-- hook-to-runtime dependencies
-- release and provider verification paths
+  Modules:        42
+  Edges:          87
+  Max depth:      6
+  Circular deps:  1
+  Coupling score: 2.07
+
+  Circular dependency cycles:
+    hooks._common → hooks.query → hooks._common
+
+============================================================
+```
+
+### `/OMG:arch --native` accuracy comparison
+
+| Method | Accuracy | Requires |
+|--------|----------|----------|
+| Regex (default) | ~70% | No external tools |
+| Native toolchain | ~95% | `go`, `tsc`, or `cargo` on PATH |
+
+## Supported Languages
+
+| Language | Extensions | Default Parser | Native Parser |
+|----------|-----------|----------------|---------------|
+| Python | `.py` | AST (`ast` stdlib) | — |
+| JavaScript/TypeScript | `.js`, `.jsx`, `.ts`, `.tsx`, `.mjs`, `.cjs` | Regex | `tsc --listFiles` |
+| Go | `.go` | Regex | `go list -json` |
+| Rust | `.rs` (via Cargo) | — | `cargo metadata` |
+
+## Safety
+
+- **Read-only**: All sub-commands only read source files and query external APIs (mermaid.ink for PNG render)
+- **Feature-gated**: Requires `CODEBASE_VIZ` flag enabled
+- **No mutations**: Never modifies source code, dependencies, or project configuration
+- **Crash-isolated**: All operations return empty/false on failure (never raise to caller)
+- **Cache**: Graph cached to `.omg/state/dependency-graph.json` with mtime-based incremental updates
+- **Network**: `/arch render` requires internet access for mermaid.ink API
+- **Subprocess safety**: Native parsers use argv lists (never `shell=True`) with 30s timeout
+
+## API
+
+```python
+from plugins.viz.graph_builder import build_project_graph
+from plugins.viz.diagram_generator import generate_mermaid, generate_d2, render_to_png
+from plugins.viz.native_parsers import (
+    parse_go_native,
+    parse_typescript_native,
+    parse_rust_native,
+    is_toolchain_available,
+)
+
+# Build full dependency graph (regex + AST)
+result = build_project_graph(".")
+# result = {"graph": {...}, "metrics": {...}}
+
+# Generate Mermaid diagram text
+mermaid_text = generate_mermaid(result["graph"])
+
+# Generate Mermaid for a single module (zoomed)
+zoomed = generate_mermaid(result["graph"], zoom="plugins.viz.graph_builder")
+
+# Generate D2 diagram text
+d2_text = generate_d2(result["graph"])
+
+# Render Mermaid to PNG via mermaid.ink
+success = render_to_png(mermaid_text, ".omg/state/arch-diagram.png")
+
+# Native toolchain parsing (higher accuracy)
+go_deps = parse_go_native(".")
+ts_deps = parse_typescript_native(".")
+rs_deps = parse_rust_native(".")
+```

package/commands/OMG:ccg.md

@@ -1,17 +1,22 @@
 ---
-description: OMG CCG mode (tri-track synthesis) in standalone Bun runtime.
-allowed-tools: Read, Grep, Glob, Bash(bun:*), Bash(git:*), Bash(rg:*), Bash(find:*), Bash(cat:*)
+description: OMG CCG mode (tri-track synthesis) in standalone mode.
+allowed-tools: Read, Grep, Glob, Bash(python3:*), Bash(git:*), Bash(rg:*), Bash(find:*), Bash(cat:*)
 argument-hint: "problem statement"
 ---
 
-# /OMG:ccg
+# /OMG:ccg — Standalone CCG
 
 Runs OMG internal tri-track routing and returns merged actions.
 
+CCG execution standard:
+- launch backend/frontend/architecture analysis in parallel sub-agents
+- collect all tracks with `background_output`
+- run `sequential-thinking` to merge tracks into one execution order
+
 ```bash
-OMG_CLI="${OMG_CLI_PATH:-$HOME/.claude/omg-runtime/scripts/omg.ts}"
-if [ ! -f "$OMG_CLI" ] && [ -f "scripts/omg.ts" ]; then OMG_CLI="scripts/omg.ts"; fi
-bun "$OMG_CLI" ccg --problem "[problem]"
+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" ccg --problem "[problem]"
 ```
 
-Use this when backend, frontend, and orchestration work are tightly coupled.
+Use this when backend+frontend+architecture are coupled.

package/commands/OMG:compat.md

@@ -1,6 +1,6 @@
 ---
-description: Run legacy skill names on OMG standalone via the Bun compatibility dispatcher.
-allowed-tools: Read, Grep, Glob, Bash(bun:*), Bash(rg:*), Bash(find:*), Bash(cat:*)
+description: Run legacy skill names on OMG standalone via compatibility dispatcher.
+allowed-tools: Read, Grep, Glob, Bash(python3:*), Bash(rg:*), Bash(find:*), Bash(cat:*)
 argument-hint: "<skill-name> [optional problem]"
 ---
 
@@ -9,41 +9,49 @@ argument-hint: "<skill-name> [optional problem]"
 Use this when migrating legacy workflows to OMG standalone.
 
 ```bash
-OMG_CLI="${OMG_CLI_PATH:-$HOME/.claude/omg-runtime/scripts/omg.ts}"
-if [ ! -f "$OMG_CLI" ] && [ -f "scripts/omg.ts" ]; then OMG_CLI="scripts/omg.ts"; fi
+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
 ```
 
 ## List supported skills
 
 ```bash
-bun "$OMG_CLI" compat list
+python3 "$OMG_CLI" compat list
 ```
 
-## Inspect contracts and gates
+## Inspect contracts
 
 ```bash
-bun "$OMG_CLI" compat contract --all
-bun "$OMG_CLI" compat contract --skill omg-teams
-bun "$OMG_CLI" compat snapshot --output runtime/omg_compat_contract_snapshot.json
-bun scripts/check-omg-compat-contract-snapshot.ts --strict-version
-bun scripts/check-omg-standalone-clean.ts
+python3 "$OMG_CLI" compat contract --all
+python3 "$OMG_CLI" compat contract --skill omg-teams
+python3 "$OMG_CLI" compat snapshot --output runtime/omg_compat_contract_snapshot.json
+python3 scripts/check-omg-compat-contract-snapshot.py --strict-version
+python3 scripts/check-omg-standalone-clean.py
 ```
 
-## Generate a compatibility gap report
+## Generate compatibility gap report
 
 ```bash
-bun "$OMG_CLI" compat gap-report
+python3 "$OMG_CLI" compat gap-report
 ```
 
-## Enforce the GA gate
+## Enforce GA gate (CI/local)
 
 ```bash
-bun "$OMG_CLI" compat gate --max-bridge 0
-bun "$OMG_CLI" compat gate --max-bridge 0 --output .omg/evidence/omg-compat-gap.json
+python3 "$OMG_CLI" compat gate --max-bridge 0
+python3 "$OMG_CLI" compat gate --max-bridge 0 --output .omg/evidence/omg-compat-gap.json
 ```
 
 ## Run a legacy skill
 
 ```bash
-bun "$OMG_CLI" compat run --skill "<skill-name>" --problem "$ARGUMENTS"
+python3 "$OMG_CLI" compat run --skill "<skill-name>" --problem "$ARGUMENTS"
+```
+
+Examples:
+
+```bash
+python3 "$OMG_CLI" compat run --skill omg-teams --problem "review auth flow"
+python3 "$OMG_CLI" compat run --skill plan --problem "ship secure release"
+python3 "$OMG_CLI" compat run --skill pipeline --problem "train model"
 ```

package/commands/OMG:cost.md

@@ -1,21 +1,181 @@
 ---
-description: "Summarize current cost controls and budget evidence."
-allowed-tools: Read, Grep, Glob, Bash(rg:*), Bash(cat:*), Bash(bun:*)
-argument-hint: "[summary|ledger|limits]"
+description: "Display session cost tracking, budget status, and usage history."
+allowed-tools: Read, Bash(python*:*), Grep
+argument-hint: "[history|budget|reset]"
 ---
 
-# /OMG:cost
+# /OMG:cost — Cost Tracker
 
-Cost enforcement in the Bun runtime is centered on the budget hooks and `.omg` ledger output.
+Display session cost tracking, budget status, and usage history.
 
-## Sources
+## Usage
 
-- `hooks/_budget.ts`
-- `hooks/tool-ledger.ts`
-- `.omg/state/ledger/`
+```
+/OMG:cost
+/OMG:cost history
+/OMG:cost budget
+/OMG:cost reset
+```
 
-## Checks
+## Sub-Commands
 
-- verify the budget hook is still registered in `settings.json`
-- inspect any emitted ledger files under `.omg/state/ledger/`
-- confirm release evidence includes unresolved risk and test coverage when cost controls tighten autonomy
+### `/OMG:cost` (default)
+
+Show current session cost summary: total tokens, total USD spent, and remaining budget percentage.
+
+```python
+from hooks._cost_ledger import read_cost_summary
+summary = read_cost_summary(".")
+print(f"Total tokens: {summary['total_tokens']}")
+print(f"Total cost: ${summary['total_cost_usd']:.4f}")
+print(f"Entries: {summary['entry_count']}")
+```
+
+### `/OMG:cost history`
+
+Show cost breakdown by tool and by session. Lists top consumers and per-session aggregates.
+
+```python
+from hooks._cost_ledger import read_cost_summary
+summary = read_cost_summary(".")
+
+# By tool
+for tool, stats in sorted(summary["by_tool"].items(), key=lambda x: x[1]["cost_usd"], reverse=True):
+    print(f"  {tool}: {stats['count']} calls, {stats['tokens']} tokens, ${stats['cost_usd']:.4f}")
+
+# By session
+for sid, stats in summary["by_session"].items():
+    print(f"  {sid}: {stats['count']} calls, ${stats['cost_usd']:.4f}")
+```
+
+### `/OMG:cost budget`
+
+Show budget configuration and threshold status. Reads from `_omg.cost_budget` in `settings.json`.
+
+Displays:
+- Session budget limit (USD)
+- Current spend vs limit
+- Remaining budget percentage
+- Threshold levels and which have been triggered
+
+```python
+import json
+with open("settings.json") as f:
+    config = json.load(f)
+budget = config.get("_omg", {}).get("cost_budget", {})
+print(f"Session limit: ${budget.get('session_limit_usd', 5.0):.2f}")
+print(f"Thresholds: {budget.get('thresholds', [50, 80, 95])}")
+print(f"Pricing: ${budget.get('pricing', {}).get('input_per_mtok', 3.0)}/Mtok in, ${budget.get('pricing', {}).get('output_per_mtok', 15.0)}/Mtok out")
+```
+
+### `/OMG:cost reset`
+
+Clear the cost ledger and threshold state for a fresh start.
+
+Removes:
+- `.omg/state/ledger/cost-ledger.jsonl`
+- `.omg/state/.cost-threshold-state.json`
+
+## Feature Flag
+
+- **Flag name**: `OMG_COST_TRACKING_ENABLED`
+- **Default**: `False` (disabled)
+- **Enable**: `export OMG_COST_TRACKING_ENABLED=1`
+
+Or set in `settings.json`:
+
+```json
+{
+  "_omg": {
+    "features": {
+      "COST_TRACKING": true
+    }
+  }
+}
+```
+
+## Budget Configuration
+
+Configure in `settings.json` under `_omg.cost_budget`:
+
+```json
+{
+  "_omg": {
+    "cost_budget": {
+      "session_limit_usd": 5.0,
+      "thresholds": [50, 80, 95],
+      "pricing": {
+        "input_per_mtok": 3.0,
+        "output_per_mtok": 15.0
+      }
+    }
+  }
+}
+```
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| `session_limit_usd` | `5.0` | Maximum spend per session in USD |
+| `thresholds` | `[50, 80, 95]` | Budget percentage thresholds for alerts |
+| `pricing.input_per_mtok` | `3.0` | Cost per million input tokens |
+| `pricing.output_per_mtok` | `15.0` | Cost per million output tokens |
+
+## Output Example
+
+```
+============================================================
+  OMG Cost Tracker — Session Summary
+============================================================
+
+  Total tokens:     124,350
+  Total cost:       $0.4821
+  Budget remaining: 90.4% ($4.52 of $5.00)
+  Tool calls:       47
+
+  Top consumers:
+    Bash:           23 calls, 68,200 tokens, $0.2644
+    Read:           12 calls, 34,100 tokens, $0.1322
+    Write:           8 calls, 15,050 tokens, $0.0583
+    Edit:            4 calls,  7,000 tokens, $0.0272
+
+============================================================
+```
+
+## Hook Integration
+
+The `budget_governor.py` PostToolUse hook automatically tracks costs when `COST_TRACKING` is enabled. It:
+
+1. Estimates token usage for each tool call (Tier 2 calibrated model)
+2. Appends cost entries to `.omg/state/ledger/cost-ledger.jsonl`
+3. Injects budget status into Claude's context via `additionalContext`
+4. Fires threshold alerts at 50%, 80%, and 95% budget usage
+
+## Safety
+
+- **Read-only** (default): `/cost`, `/cost history`, `/cost budget` only read data
+- **Feature-gated**: Hook and command require `COST_TRACKING` flag enabled
+- **Advisory-only**: Budget governor never blocks tool execution
+- **Crash-isolated**: All operations exit 0 on failure
+
+## API
+
+```python
+from hooks._cost_ledger import read_cost_summary, append_cost_entry, rotate_cost_ledger
+
+# Get aggregated cost summary
+summary = read_cost_summary(".")
+
+# Append a cost entry
+append_cost_entry(".", {
+    "ts": "2026-03-04T12:00:00Z",
+    "tool": "Bash",
+    "tokens_in": 500,
+    "tokens_out": 200,
+    "cost_usd": 0.0045,
+    "model": "claude-opus-4-6",
+    "session_id": "ses_abc123"
+})
+
+# Rotate ledger when > 5MB
+rotate_cost_ledger(".")
+```

package/commands/OMG:crazy.md

@@ -34,7 +34,7 @@ CRAZY mode must use parallel sub-agent dispatch for worker tracks.
 
 ### Mandatory parallel launch pattern
 
-```text
+```python
 task(subagent_type="explore", run_in_background=true, load_skills=[], description="Architect track", prompt="...")
 task(subagent_type="explore", run_in_background=true, load_skills=[], description="Backend track", prompt="...")
 task(subagent_type="explore", run_in_background=true, load_skills=[], description="Frontend track", prompt="...")