@trac3er/oh-my-god 2.0.0 → 2.0.2

package/commands/OMG:init.md

@@ -1,26 +1,134 @@
 ---
-description: "Initialize project metadata for OMG on a Bun-first repository."
-allowed-tools: Read, Write, Edit, Grep, Glob, Bash(rg:*), Bash(find:*), Bash(bun:*), Bash(git:*)
-argument-hint: "[optional project goal]"
+description: "Unified initializer — auto-detects: project setup (if no .omg/state), domain scaffolding (if argument given), or health check."
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(mkdir:*), Bash(cat:*), Bash(find:*), Bash(ls:*), Bash(head:*), Bash(grep:*), Bash(tree:*), Bash(node:*), Bash(python*:*), Bash(tee:*), Grep, Glob
+argument-hint: "[optional: domain name like 'payment', or 'check' for health check]"
 ---
 
-# /OMG:init
+# /OMG:init — Unified Project & Domain Initializer
 
-Use this to sketch initial project metadata and likely verification commands.
+## Auto-Detection Logic
 
-## Suggested defaults
+```
+if argument is a domain name (e.g. "payment", "user-profile"):
+  → DOMAIN INIT (create new domain from existing patterns)
+elif .omg/state directory does not exist:
+  → PROJECT INIT (first-time project setup)
+elif .omg/state/profile.yaml exists:
+  → HEALTH CHECK (verify everything works, offer upgrades)
+```
+
+---
+
+## MODE A: PROJECT INIT (no .omg/state found)
+
+### Step 1: Create .omg/state/profile.yaml (MOST IMPORTANT)
+Detect from code. Ask user for anything undetectable.
 
 ```yaml
-project:
-  goal: "[describe the product or migration target]"
-  test_cmd: "[detect: bun test/npm test/cargo test]"
-  typecheck_cmd: "[detect: bunx tsc --noEmit or equivalent]"
-  build_cmd: "[detect: bun run build or null]"
+# .omg/state/profile.yaml — injected every session (keep under 20 lines)
+name: "[from package.json/Cargo.toml/pyproject.toml]"
+description: "[1 sentence]"
+repo: "[from git remote -v]"
+
+language: "[detect]"
+framework: "[detect]"
+database: "[detect or ask]"
+infra: "[detect from Dockerfile/terraform/etc]"
+key_deps: "[top 5]"
+
+conventions:
+  naming: "[detect: camelCase/snake_case]"
+  test_cmd: "[detect: npm test/pytest/cargo test]"
+  lint_cmd: "[detect: eslint/ruff/clippy]"
+
+ai_behavior:
+  communication: "[ask user: language preference]"
+  when_stuck: "Ask user after 2 failed attempts"
+  testing: "User-journey focused, not boilerplate"
 ```
 
-## Useful inventory command
+### Step 2: Create knowledge structure + OMG v1 contract dirs
+```
+mkdir -p .omg/state/ledger .omg/knowledge/decisions .omg/knowledge/patterns .omg/knowledge/rules
+mkdir -p .omg/trust .omg/evidence .omg/shadow .omg/migrations
+```
+
+Copy OMG v1 templates when missing:
+- `.omg/idea.yml`
+- `.omg/policy.yaml`
+- `.omg/runtime.yaml`
+
+### Step 3: Auto-detect quality gate
+```json
+// .omg/state/quality-gate.json — only include commands that exist
+{
+  "format": "[detect: prettier/black/gofmt or null]",
+  "lint": "[detect: eslint/ruff/clippy or null]",
+  "typecheck": "[detect: tsc/mypy or null]",
+  "test": "[detect: npm test/pytest/cargo test or null]"
+}
+```
+
+### Step 4: Copy relevant contextual rules
+Based on detected project type, copy relevant rules from templates:
+- Web project → security-domains.md, code-hygiene.md
+- Backend → infra-safety.md, dependency-safety.md
+- DDD project → ddd-sdd.md, outside-in.md
+
+### Step 5: Verify
+Run `/OMG:health-check` to confirm setup.
+
+---
+
+## MODE B: DOMAIN INIT (argument = domain name)
+
+### Step 1: Find Reference Pattern
+```bash
+find . -type f -name "*.ts" -o -name "*.py" | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -10
+```
+Read the most complete existing domain. Extract:
+- Directory structure (routes, services, models, tests)
+- Naming conventions, error handling, data flow patterns
+
+### Step 2: Define the New Domain
+Ask the user:
+- "What entities does [domain] have?"
+- "What actions can be performed?"
+- "What external services does it talk to?"
+- "What are the business rules?"
+
+### Step 3: Generate Domain Structure
+Match the reference pattern EXACTLY. Create:
+```
+src/[domain]/
+  ├── [domain].model.ts
+  ├── [domain].service.ts
+  ├── [domain].repository.ts
+  ├── [domain].controller.ts (or routes)
+  ├── [domain].types.ts
+  └── __tests__/
+      └── [domain].service.test.ts
+```
+
+### Step 4: Document the Pattern
+Save to `.omg/knowledge/patterns/[domain]-pattern.md`
+
+---
+
+## MODE C: HEALTH CHECK (already initialized)
+
+Run `/OMG:health-check` and additionally:
+- Verify profile.yaml is up-to-date with current project state
+- Check if new contextual rules should be added
+- Offer to update quality-gate.json if tools changed
+
+---
 
+## File Write Method
+Use `Write` tool first. If it fails (file exists), fall back to:
 ```bash
-find . -type f \( -name "*.ts" -o -name "*.tsx" -o -name "*.js" -o -name "*.jsx" \) \
-  | sed 's|/[^/]*$||' | sort | uniq -c | sort -rn | head -10
+cat > .omg/state/profile.yaml << 'EOF'
+[content]
+EOF
 ```
+Always READ the file after writing to confirm.

package/commands/OMG:project-init.md

@@ -1,6 +1,6 @@
 ---
 description: "Alias for /OMG:init (project setup mode). Use /OMG:init instead."
-allowed-tools: Read, Write, Edit, MultiEdit, Bash(mkdir:*), Bash(cat:*), Bash(find:*), Bash(ls:*), Bash(head:*), Bash(grep:*), Bash(tree:*), Bash(bun:*), Bash(tee:*), Grep, Glob
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(mkdir:*), Bash(cat:*), Bash(find:*), Bash(ls:*), Bash(head:*), Bash(grep:*), Bash(tree:*), Bash(node:*), Bash(python*:*), Bash(tee:*), Grep, Glob
 argument-hint: "[optional: project description]"
 ---
 

package/commands/OMG:session-branch.md

@@ -1,18 +1,85 @@
 ---
-description: "Create or switch OMG state branches."
-allowed-tools: Read, Write, Edit, Bash(bun:*)
+description: "Create or manage OMG state branches for experimental workflows."
+allowed-tools: Read, Write, Edit, Bash
 argument-hint: "--name <branch-name> [--from <snapshot_id>]"
 ---
 
-# /OMG:session-branch
+# /OMG:session-branch — Branch OMG State
 
-OMG state branches are stored under `.omg/state/session-snapshots/`.
+Create a named branch of the current OMG state for experimentation or parallel exploration.
 
-## Examples
+## Important
 
+Branching is **OMG state only** — it captures and restores `.omg/state/` directory contents. It does **not** fork the conversation, context window, or Claude session. Think of it as a checkpoint you can name and switch between.
+
+## Usage
+
+```
+/OMG:session-branch --name "experiment"
+/OMG:session-branch --name "refactor-v2" --from 20260302_143000_baseline
+```
+
+## What It Does
+
+1. Creates a snapshot of the current `.omg/state/` directory (or restores a specified snapshot)
+2. Writes branch metadata to `.omg/state/branches/<name>.json`
+3. Updates `.omg/state/current_branch.json` to track the active branch
+
+## Branch Metadata
+
+Each branch stores:
+
+| Field | Description |
+|-------|-------------|
+| `name` | Branch name |
+| `snapshot_id` | Associated snapshot ID |
+| `created_at` | ISO timestamp of creation |
+| `parent_branch` | Branch that was active when this branch was created |
+| `status` | Branch status (`active`) |
+
+## Managing Branches
+
+```
+# List all branches
+python3 tools/session_snapshot.py branches
+
+# Switch to a branch (restores its snapshot)
+python3 tools/session_snapshot.py switch experiment
+
+# Create branch from specific snapshot
+python3 tools/session_snapshot.py branch my-branch --from 20260302_143000_baseline
+```
+
+## Feature Flag
+
+Branching is gated behind `OMG_BRANCHING_ENABLED` (default: `False`).
+
+Enable via environment variable:
 ```bash
-bun tools/session_snapshot.ts branches
-bun tools/session_snapshot.ts switch experiment
-bun tools/session_snapshot.ts branch my-branch --from 20260302_143000_baseline
-bun tools/session_snapshot.ts switch baseline
+export OMG_BRANCHING_ENABLED=true
+```
+
+Or in `settings.json`:
+```json
+{
+  "_omg": {
+    "features": {
+      "BRANCHING": true
+    }
+  }
+}
+```
+
+## Example Workflow
+
+```
+# 1. Create a baseline branch
+/OMG:session-branch --name "baseline"
+
+# 2. Do some experimental work...
+# 3. Create experiment branch to save progress
+/OMG:session-branch --name "experiment-auth"
+
+# 4. Switch back to baseline if experiment didn't work
+python3 tools/session_snapshot.py switch baseline
 ```

package/commands/OMG:session-fork.md

@@ -1,16 +1,53 @@
 ---
 description: "Fork OMG state from a specific snapshot checkpoint."
-allowed-tools: Read, Write, Edit, Bash(bun:*)
+allowed-tools: Read, Write, Edit, Bash
 argument-hint: "--from <snapshot_id> --name <fork-name>"
 ---
 
-# /OMG:session-fork
+# /OMG:session-fork — Fork OMG State from Checkpoint
 
-Forking is OMG state only. It restores `.omg/state/` snapshot data and starts a new named branch from that checkpoint.
+Create a new branch from a specific snapshot checkpoint. This is a convenience wrapper around `/OMG:session-branch` that always requires a source snapshot.
+
+## Important
+
+Forking is **OMG state only** — it restores a previous `.omg/state/` snapshot and creates a new named branch from it. It does **not** fork the conversation or create a parallel Claude session.
+
+## Usage
+
+```
+/OMG:session-fork --from 20260302_143000_baseline --name "alt-approach"
+```
+
+## What It Does
+
+1. Looks up the specified snapshot by ID
+2. Restores that snapshot to `.omg/state/`
+3. Creates a new branch with the given name pointing to that snapshot
+4. Updates `.omg/state/current_branch.json`
+
+## When to Use Fork vs Branch
+
+| Action | Use Case |
+|--------|----------|
+| `/OMG:session-branch --name X` | Save current state as a named branch |
+| `/OMG:session-fork --from S --name X` | Go back to snapshot S and start a new exploration path |
 
 ## Example
 
-```bash
-bun tools/session_snapshot.ts list
+```
+# List available snapshots to find a good fork point
+python3 tools/session_snapshot.py list
+
+# Fork from a previous checkpoint
 /OMG:session-fork --from 20260302_100000_pre-refactor --name "approach-b"
+
+# Continue working from that earlier state...
+```
+
+## Feature Flag
+
+Forking shares the `OMG_BRANCHING_ENABLED` feature flag with `/OMG:session-branch` (default: `False`).
+
+```bash
+export OMG_BRANCHING_ENABLED=true
 ```

package/commands/OMG:session-merge.md

@@ -1,18 +1,134 @@
 ---
 description: "Merge OMG state branches together with conflict detection."
-allowed-tools: Read, Write, Edit, Bash(bun:*)
+allowed-tools: Read, Write, Edit, Bash
 argument-hint: "--from <source-branch> [--into <target-branch>] [--preview]"
 ---
 
-# /OMG:session-merge
+# /OMG:session-merge — Merge OMG State Branches
 
-Merge one OMG state branch into another with preview support.
+Merge one OMG state branch into another with automatic conflict detection.
 
-## Examples
+## Important
 
+Merging is **OMG state only** — it merges branch metadata (`.omg/state/branches/<name>.json`). It does **not** merge conversations, context windows, or file system state. Think of it as combining the tracked state from two named branches.
+
+## Usage
+
+```
+/OMG:session-merge --from "experiment"
+/OMG:session-merge --from "experiment" --into "main"
+/OMG:session-merge --from "experiment" --preview
+```
+
+## What It Does
+
+1. Loads the source and target branch metadata as flat JSON dicts
+2. Detects conflicts (keys present in both branches with different values)
+3. If `--preview`: returns conflict report without applying changes
+4. If no conflicts: applies source changes on top of target (last-write-wins)
+5. Marks the source branch as `status: "merged"` in its metadata file
+6. Updates `.omg/state/current_branch.json` to the target branch
+
+## Conflict Detection
+
+A **value_conflict** occurs when both branches have the same key but different values. When conflicts are found, the merge is **aborted** — you must resolve conflicts manually before merging.
+
+Conflict report format:
+
+```json
+{
+  "key": "snapshot_id",
+  "source_value": "20260302_150000_experiment",
+  "target_value": "20260302_140000_main",
+  "conflict_type": "value_conflict"
+}
+```
+
+## Preview Mode
+
+Use `--preview` to see what a merge would do without applying changes:
+
+```
+python3 tools/session_snapshot.py merge-preview experiment --into main
+```
+
+Returns:
+
+```json
+{
+  "source": "experiment",
+  "target": "main",
+  "conflicts": [],
+  "changes": 2,
+  "preview": true
+}
+```
+
+## CLI Commands
+
+```
+# Merge source into target
+python3 tools/session_snapshot.py merge experiment --into main
+
+# Preview merge without applying
+python3 tools/session_snapshot.py merge-preview experiment --into main
+
+# Merge into default target (main)
+python3 tools/session_snapshot.py merge experiment
+```
+
+## Feature Flag
+
+Merging is gated behind `OMG_MERGE_ENABLED` (default: `False`).
+
+Enable via environment variable:
 ```bash
-bun tools/session_snapshot.ts merge-preview experiment --into main
-bun tools/session_snapshot.ts merge experiment --into main
-bun tools/session_snapshot.ts merge experiment
-bun tools/session_snapshot.ts branches
+export OMG_MERGE_ENABLED=true
+```
+
+Or in `settings.json`:
+```json
+{
+  "_omg": {
+    "features": {
+      "MERGE": true
+    }
+  }
+}
+```
+
+## Merge Behavior
+
+| Scenario | Result |
+|----------|--------|
+| No conflicts | Source state overlaid on target (last-write-wins) |
+| Conflicts found | Merge aborted, conflicts returned |
+| Source branch missing | Error returned |
+| Target branch missing | Error returned |
+| Feature flag disabled | `{"skipped": true}` |
+
+## After Merge
+
+- The **target** branch is updated with merged state
+- The **source** branch status changes to `"merged"` (not deleted)
+- `current_branch.json` is updated to the target branch
+- Source branch remains accessible for reference
+
+## Example Workflow
+
+```
+# 1. Create branches
+/OMG:session-branch --name "main"
+/OMG:session-branch --name "experiment"
+
+# 2. Do experimental work on "experiment" branch...
+
+# 3. Preview the merge
+/OMG:session-merge --from "experiment" --preview
+
+# 4. If no conflicts, apply the merge
+/OMG:session-merge --from "experiment" --into "main"
+
+# 5. Verify merge
+python3 tools/session_snapshot.py branches
 ```

package/commands/OMG:setup.md

@@ -1,22 +1,79 @@
 ---
-description: "Interactive setup for the Bun runtime, provider status, and Claude hook installation."
-allowed-tools: Read, Write, Edit, Bash(bun:*), Bash(ls:*), Bash(grep:*)
-argument-hint: "[optional: --non-interactive for CI mode]"
+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]"
 ---
 
 # /OMG:setup
 
-Guided setup for the Bun runtime.
+Feature-gated: requires `OMG_SETUP_ENABLED=1` or `settings.json._omg.features.SETUP: true`.
 
-## Covers
+## Overview
 
-- Bun availability and version
-- provider detection and status via `runtime/provider_bootstrap.ts`
-- standalone install or plugin install through `OMG-setup.sh`
-- settings merge and hook registration
+Native OMG setup for Claude Code, Codex, OpenCode, and other supported CLIs.
+The command keeps migration logic internal and focuses the user on a small adoption flow:
 
-## Non-interactive mode
+1. Detect supported CLIs.
+2. Detect overlapping ecosystems.
+3. Recommend an adoption mode.
+4. Apply an OMG preset.
+5. Configure MCP and save preferences.
 
-```bash
-./OMG-setup.sh install --non-interactive
+## Wizard Flow
+
+```text
+Step 1: Detect CLIs
+  - codex
+  - gemini
+  - opencode
+  - 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
+
+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 `/OMG:setup`
+3. run `/OMG:crazy <goal>`