@trac3r/oh-my-god 2.2.11

package/plugins/advanced/commands/OMG:code-review.md

@@ -0,0 +1,114 @@
+---
+description: Deep code review — reads file completely, checks line-by-line for issues, then analyzes whole-file structure. Enforces code hygiene.
+allowed-tools: Read, Bash(cat:*), Bash(grep:*), Bash(wc:*), Bash(head:*), Bash(find:*), Bash(rg:*), Grep, Glob
+argument-hint: "[file path or 'recent' for git-changed files]"
+---
+
+# /OMG:code-review — Line-by-Line + Structural Review
+
+## Philosophy
+Two passes: LINE-BY-LINE precision, then WHOLE-FILE understanding.
+Don't just scan — READ and UNDERSTAND every line.
+
+## Step 1: Determine Scope
+
+- If file specified: review that file
+- If "recent" or no argument: review uncommitted changes
+  ```bash
+  git diff --name-only HEAD 2>/dev/null
+  git diff --cached --name-only 2>/dev/null
+  ```
+
+## Step 2: Read the FULL File First
+
+Read the ENTIRE file. Not just the changed part. Not just a function.
+Understanding comes from seeing the whole context.
+
+Note:
+- What does this file DO? (its purpose in the system)
+- What are its DEPENDENCIES? (imports, calls)
+- What does it EXPORT? (public API)
+
+## Step 3: Line-by-Line Scan
+
+For each line, check:
+
+**Correctness:**
+- Logic errors (off-by-one, null checks, type mismatches)
+- Missing error handling (unhandled promises, bare except, no null check)
+- Race conditions (shared state, async without await, unchecked concurrent access)
+
+**Security (if auth/payment/database):**
+- Hardcoded secrets → CRITICAL
+- SQL injection (string concatenation in queries) → CRITICAL
+- XSS (innerHTML, dangerouslySetInnerHTML) → HIGH
+- Missing input validation → MEDIUM
+- Overly permissive CORS/cookies → MEDIUM
+
+**Hygiene:**
+- Dead code (unused imports, variables, unreachable branches)
+- Noise comments ("increment i", "return result", "constructor")
+- console.log/print left in production code
+- TODO/FIXME/HACK without tracking
+- Overly complex functions (>40 lines → suggest extract)
+- Duplicated logic (same pattern in 2+ places → suggest DRY)
+
+## Step 4: Whole-File Structure Analysis
+
+After line-by-line:
+- Does the file do ONE thing well, or is it a dumping ground?
+- Are functions ordered logically? (public first, helpers after, or lifecycle order)
+- Is naming consistent? (camelCase throughout? PascalCase for classes?)
+- Does it follow the project's domain pattern? (check .omg/knowledge/domain-patterns/)
+- Any circular dependencies?
+- Is error handling consistent across all functions?
+
+## Step 5: Report
+
+```
+Code Review — [file]
+━━━━━━━━━━━━━━━━━━━━
+
+Structure: [CLEAN | NEEDS_WORK | MESSY]
+Security:  [SAFE | REVIEW_NEEDED | CRITICAL]
+Hygiene:   [CLEAN | NEEDS_CLEANUP]
+
+Issues:
+  [line:col] CRITICAL: [description]
+  [line:col] HIGH: [description]
+  [line:col] MEDIUM: [description]
+  [line:col] LOW: [description]
+
+Dead Code:
+  [line] unused import: [name]
+  [line] unreachable after return
+
+Noise Comments (remove these):
+  [line] "// increment counter"
+  [line] "// return the value"
+
+Structural:
+  - [function] is [N] lines — consider extracting [suggestion]
+  - [pattern] duplicated at lines [X] and [Y]
+
+Recommendation: [summary of what to fix, in priority order]
+```
+
+## Step 6: For Security-Critical Files
+
+If the file touches auth, payment, or database:
+```
+/OMG:escalate codex "Line-by-line security review of [file]. Check:
+1. Every input validation point
+2. Every database query for injection
+3. Every auth check for bypass
+4. Every secret reference for hardcoding
+Report: line numbers + severity + fix suggestion"
+```
+
+## Anti-patterns
+- DON'T skim and say "looks good" — read every line
+- DON'T only check the diff — read the full file for context
+- DON'T ignore test files — they can have real issues too
+- DON'T add more noise comments as "fixes" — remove them instead
+- DON'T suggest unnecessary code as improvements

package/plugins/advanced/commands/OMG:deep-plan.md

@@ -0,0 +1,266 @@
+---
+description: Deep strategic planning — understands user direction, asks smart questions, creates comprehensive plan with domain awareness
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(find:*), Bash(cat:*), Bash(git:*), Bash(wc:*), Bash(tree:*), Bash(mkdir:*), Bash(tee:*), Grep, Glob
+argument-hint: "[feature or goal to plan]"
+---
+
+# /OMG:deep-plan — Strategic Planning with Direction Understanding
+
+## Philosophy
+Regular planning = "what steps to take."
+Deep planning = "understand WHY the user wants this, WHAT direction they're heading, and HOW it fits the bigger picture."
+
+This command is the public compatibility path to the canonical `plan-council` bundle.
+Users invoke `/OMG:deep-plan`; the runtime routes to `plan-council` for execution.
+
+## Step 1: Direction Discovery (MANDATORY)
+
+Do not assume goals, constraints, or context. Extract direction from:
+- user prompt
+- `.omg/state/handoff.md`
+- `.omg/state/ledger/failure-tracker.json`
+- current repo structure and patterns
+
+Before planning anything, understand:
+1. **User's real goal** — Often the stated request is one step toward something bigger. Ask: "What's the end state you're imagining?"
+2. **User's constraints** — Time, budget, existing code, team preferences, tech stack decisions already made.
+3. **User's domain knowledge** — Are they expert in this domain (follow their lead) or exploring (guide them)?
+4. **What they've already tried** — Check .omg/state/handoff.md, failure-tracker.json, git log.
+
+If direction is still ambiguous after repo exploration, ask only minimal focused questions.
+
+Examples of BAD questions: "What framework do you want?" "What's your deadline?"
+Examples of GOOD questions:
+- "I see you have a Stripe integration started in /src/payment/. Are you building on that, or replacing it?"
+- "Your auth uses JWT in cookies. Should the new feature respect that pattern, or are you migrating to sessions?"
+- "The DB schema has 3 user types. Does this feature apply to all of them or just one?"
+
+## Step 2: Map the Domain
+
+Read the codebase to understand the CURRENT state:
+```bash
+# Directory structure
+find . -type f -name "*.ts" -o -name "*.py" -o -name "*.go" | head -50
+
+# Key architectural patterns
+grep -rn "export class\|export function\|def \|func \|struct " src/ --include="*.{ts,py,go}" | head -30
+
+# Existing domain boundaries
+ls -la src/*/  # or app/*/ or packages/*/
+
+# Data flow
+grep -rn "import.*from\|require(" src/ --include="*.{ts,js}" | head -20
+```
+
+If DDD reference patterns exist (see .omg/knowledge/ or existing domain modules):
+- Read the reference domain FIRST
+- Plan the new feature to MATCH the pattern
+- Note any intentional deviations with WHY
+
+## Step 3: Create the Deep Plan (Plan Council Artifacts)
+
+Generate the canonical `plan-council` artifacts. Use Bash heredoc to write these files.
+Required artifacts: `.omg/plans/deep-plan.md`, `.omg/plans/deep-plan.json`, `.omg/plans/dissent.json`, `.omg/evidence/plan-council.json`.
+
+### Artifact 1: `.omg/plans/deep-plan.md` (Human-readable)
+```markdown
+# Deep Plan: [Feature Name]
+Created: [date]
+CHANGE_BUDGET=[small|medium|large]
+
+## Direction
+[1-2 sentences: what the user is building toward, not just this task]
+
+## Domain Context
+Reference pattern: [file/module that sets the pattern]
+Bounded contexts affected: [list]
+Key interfaces: [list the interfaces/types this touches]
+
+## Architecture Decisions
+- [Decision]: [chosen approach] because [reason]
+  Alternatives considered: [what was rejected and why]
+
+## Implementation Plan
+
+### Phase 1: Foundation [N files, ~M lines]
+1. [ ] [specific action] — [file] — [what and why]
+2. [ ] [specific action] — [file]
+
+### Phase 2: Core Logic [N files, ~M lines]
+3. [ ] [specific action]
+4. [ ] [specific action]
+
+### Phase 3: Integration + Verification [N files, ~M lines]
+5. [ ] [specific action]
+6. [ ] Verification: /OMG:security-check [affected files]
+
+### Phase 4: Verification
+7. [ ] Tests: [what to test, how]
+8. [ ] Edge cases: [list]
+9. [ ] Manual verification: [steps]
+
+## Risk Map
+- [Risk]: [mitigation]
+- [Risk]: [mitigation]
+
+## What NOT to Do
+- [Anti-pattern specific to this feature]
+- [Approach that looks tempting but will fail because...]
+
+## Files to Read Before Starting
+1. [file] — [why: contains the reference pattern]
+2. [file] — [why: defines the interface this must implement]
+
+## Plan Council Requirements
+### Assumptions
+List your assumptions below:
+- [Assumption 1]
+- [Assumption 2]
+
+### Objections and Dissent
+Record any objections or dissent:
+- [Dissent 1]
+- [Dissent 2]
+
+### Rollback Plan
+Define the rollback plan:
+- [Step 1 to revert]
+- [Step 2 to revert]
+
+### Verification Commands
+List the verification commands:
+- [Command 1]
+- [Command 2]
+
+### Evidence Requirements
+Define the evidence requirements:
+- [Requirement 1]
+- [Requirement 2]
+
+### What would falsify this plan?
+Define what would falsify this plan:
+- [Condition 1]
+- [Condition 2]
+```
+
+### Artifact 2: `.omg/plans/deep-plan.json` (Machine-readable)
+Include the full task plan, workflow stages, and metadata.
+
+### Artifact 3: `.omg/plans/dissent.json` (Dissent log)
+Record all objections, risks, and counter-arguments raised during planning.
+
+### Artifact 4: `.omg/evidence/plan-council.json` (Planning evidence)
+Record the planning process evidence, including tool outputs and validation results.
+
+## Step 4: Present and Iterate
+
+Show the plan to the user. Ask:
+- "Does this match the direction you're thinking?"
+- "Anything I'm missing about your goals?"
+- "Should I adjust the scope or priority?"
+
+Update the plan based on feedback BEFORE starting implementation.
+
+## Step 4.5: Codex Plan Validation (MANDATORY)
+
+Before implementation, run a dedicated Codex validation pass on the final plan.
+
+Checklist for Codex validation:
+- ordering and dependency correctness
+- hidden edge cases and rollback gaps
+- security/performance blind spots
+- missing verification steps
+
+Only after applying those corrections, continue to execution.
+
+## Step 4.6: Multi-Agent Bootstrap (MANDATORY)
+
+After validation, launch exactly 5 planning tracks with mixed-model intent using OMG-native routing (same planning discipline as OMG):
+
+1. Architect track (Claude)
+2. Backend track (GPT/Codex)
+3. Frontend track (Gemini)
+4. Security track (GPT/Codex)
+5. Verification track (Claude)
+
+Dispatch pattern is mandatory: all 5 tracks launch in parallel as background sub-agents.
+
+```python
+task(subagent_type="explore", run_in_background=true, load_skills=[], description="Architect planning track", prompt="...")
+task(subagent_type="explore", run_in_background=true, load_skills=[], description="Backend planning track", prompt="...")
+task(subagent_type="explore", run_in_background=true, load_skills=[], description="Frontend planning track", prompt="...")
+task(subagent_type="explore", run_in_background=true, load_skills=[], description="Security planning track", prompt="...")
+task(subagent_type="explore", run_in_background=true, load_skills=[], description="Verification planning track", prompt="...")
+```
+
+Collection and merge protocol:
+- collect every track using `background_output(task_id="...")`
+- run a `sequential-thinking` merge pass to resolve conflicts and ordering
+- emit one final executable checklist only after the merge pass
+
+Each track must return:
+- concrete plan steps
+- risk notes
+- verification commands
+
+Then merge outputs into a single execution checklist before implementation.
+
+## Step 5: Generate Checklist
+
+Convert the plan into `.omg/state/_checklist.md` with concrete steps.
+Each step should be completable in ONE tool interaction (not "implement the feature").
+
+## Step 5.5: Business Workflow Contract (MANDATORY)
+
+Deep-plan owns the business-style delivery workflow and task-plan contract.
+
+Always generate a normalized workflow path and task plan directly from user instructions:
+
+- canonical stages: `plan -> implement -> qa -> simulate -> final_test -> production`
+- accepted user path keys: `workflow`, `path`, `delivery_path`, `workflow_path`
+- accepted stage aliases:
+  - `planning -> plan`
+  - `implementation|build -> implement`
+  - `quality|quality_assurance -> qa`
+  - `testing|test -> final_test`
+  - `prod|deploy -> production`
+
+Rules:
+1. If user provides a partial path, keep user order and append missing canonical stages.
+2. If user provides no path, use the full canonical path.
+3. Build tasks from:
+   - `user_instructions[]` (source of truth for requested workflow)
+   - `constraints[]` (delivery boundaries)
+   - `acceptance[]` (final test criteria)
+4. Include stage readiness for production handoff:
+   - `production=ready` only when QA/simulation/final_test gates pass.
+
+Persist this contract into planning artifacts:
+- `.omg/plans/deep-plan.md` (human-readable plan)
+- `.omg/plans/deep-plan.json` (machine-readable plan)
+- include structured task metadata in the plan output (`stage`, `title`, `detail`, `source`).
+
+## Integration with DDD
+
+If this is a new domain:
+1. Ask the user to write (or help write) the first domain reference
+2. Extract the pattern: naming convention, data flow, error handling style
+3. Document the pattern in .omg/knowledge/domain-patterns/[name].md
+4. Use the pattern for ALL subsequent domains
+
+## Idea-as-Code Contract (required)
+
+Before leaving planning, ensure `.omg/idea.yml` exists with:
+- `goal`
+- `constraints[]`
+- `acceptance[]`
+- `risk.security[]|risk.performance[]|risk.compatibility[]`
+- `evidence_required.tests[]|security_scans[]|reproducibility[]`
+
+If missing, scaffold from template and fill from the conversation.
+
+## Anti-patterns
+- Don't plan in your head and dump a wall of text — INTERACT with the user
+- Don't make architecture decisions without checking existing patterns
+- Don't create a plan with vague steps like "implement feature" — be specific
+- Don't skip the Direction step — it's the difference between useful and useless

package/plugins/advanced/commands/OMG:handoff.md

@@ -0,0 +1,115 @@
+---
+description: Intelligent session transfer — captures WHAT was done, HOW it was done, and WHY decisions were made. Works across platforms (Claude Code → Claude.ai).
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(git:*), Bash(cat:*), Bash(wc:*), Bash(find:*), Bash(mkdir:*), Bash(tee:*), Grep, Glob
+argument-hint: "[optional: --portable for cross-platform, or reason for handoff]"
+---
+
+# /OMG:handoff — Intelligent Session Transfer
+
+## Size Budget (CRITICAL)
+- handoff.md: **≤ 60 lines** (briefing, not data dump)
+- handoff-portable.md: **≤ 100 lines** (fits most context windows)
+- If a section grows too long, SUMMARIZE — don't truncate mid-sentence
+
+## Philosophy
+A handoff is NOT a data dump. It's a **briefing** for the next session.
+The next Claude (in ANY platform) should read this and know EXACTLY:
+1. What was the goal
+2. What was accomplished (with evidence)
+3. What decisions were made and WHY
+4. What failed and WHY (so it doesn't repeat)
+5. The single most important next action
+
+## Step 1: Gather Intelligence
+
+Read these (silently, don't dump to user):
+- .omg/state/profile.yaml or project.md (project identity)
+- .omg/state/working-memory.md or _plan.md + _checklist.md (task state)
+- .omg/state/ledger/failure-tracker.json (what failed)
+- .omg/state/ledger/tool-ledger.jsonl (last 20 entries for activity summary)
+- git diff --stat + git log --oneline -5 (what changed)
+
+## Step 2: Synthesize — Write .omg/state/handoff.md
+
+DO NOT copy-paste raw data. SYNTHESIZE into this structure (≤ 60 lines total):
+
+```markdown
+# Handoff — [date]
+
+## Goal
+[1 sentence: what we're trying to achieve]
+
+## What Was Done (with evidence)
+- [action]: [result] (verified: [command, exit code])
+Total: [N] files changed, [M] lines
+
+## Key Decisions (preserve these)
+- Chose [X] over [Y] because [reason]
+
+## What Failed (don't repeat these)
+- [Approach A]: failed because [root cause]
+
+## Current State
+Branch: [name] | Uncommitted: [N files]
+Checklist: [done]/[total] steps
+
+## Exact Next Step
+[Single most important action with specific instructions]
+Read [specific file] first, then [specific action]
+
+## Files to Read on Resume
+1. .omg/state/profile.yaml (project identity)
+2. .omg/state/handoff.md (this file)
+3. [specific file relevant to next step]
+```
+
+## Step 3: Generate Portable Version (≤ 100 lines)
+
+ALWAYS also generate `.omg/state/handoff-portable.md` — a **self-contained** version that works
+when pasted into Claude.ai, ChatGPT, or any AI chat without file access.
+
+Portable version differences:
+- **Include** project identity inline (language, framework, key conventions) — no file references
+- **Include** the relevant code context (key interfaces, schemas, or config) — the next AI can't Read files
+- **Replace** "Read file X" with actual excerpts of the critical parts
+- **Total ≤ 100 lines** (fits in most context windows)
+
+## Step 4: Write Files
+
+**IMPORTANT: File write method — prevents "Error writing file".**
+
+First ensure directory exists:
+```
+mkdir -p .omg/state
+```
+
+Then write with `Write` tool. **If Write fails** (file already exists), use Bash heredoc:
+```bash
+cat > .omg/state/handoff.md << 'HANDOFF_EOF'
+[content here]
+HANDOFF_EOF
+```
+
+Do the same for handoff-portable.md.
+
+## Step 5: Present BOTH Versions
+
+```
+Handoff ready:
+  📁 .omg/state/handoff.md ([N] lines) — for Claude Code sessions
+  📋 .omg/state/handoff-portable.md ([N] lines) — for Claude.ai / other platforms
+
+To continue in Claude Code:
+  "Read .omg/state/profile.yaml and .omg/state/handoff.md, continue where I left off."
+
+To continue in Claude.ai (copy-paste the portable version):
+  [Show the user the full content of handoff-portable.md so they can copy it]
+```
+
+## Anti-patterns
+- Don't dump raw file contents into handoff (synthesize)
+- Don't list every tool call (summarize activity)
+- Don't include full error output (root cause only)
+- Don't make the portable version reference files it can't access
+- Don't exceed 60 lines / 100 lines budget
+- Don't use Write tool alone if the file already exists — fallback to Bash heredoc

package/plugins/advanced/commands/OMG:learn.md

@@ -0,0 +1,110 @@
+---
+description: Create a reusable skill from a pattern you just did. Auto-detects repetitive work and offers to skill-ify it.
+allowed-tools: Read, Write, Edit, MultiEdit, Bash(git:*), Bash(cat:*), Bash(find:*), Bash(ls:*), Bash(mkdir:*), Bash(tee:*), Grep, Glob
+argument-hint: "[skill name] or 'auto' to detect from recent work"
+---
+
+# /OMG:learn — Auto-Skill Creator
+
+## What This Does
+Takes something you just did (test pattern, implementation approach, debugging method)
+and turns it into a reusable Claude Code skill that activates automatically next time.
+
+## Usage
+
+### Manual: /OMG:learn [skill-name]
+Claude asks you what the pattern is and creates a skill.
+
+### Auto: /OMG:learn auto
+Claude analyzes recent tool-ledger entries to detect repetitive patterns.
+
+## Step 1: Detect Pattern
+
+### If "auto":
+Read .omg/state/ledger/tool-ledger.jsonl (last 50 entries).
+Look for:
+- Same file types being created repeatedly (e.g., always creating .test.ts with same structure)
+- Same command sequences repeated (e.g., lint → typecheck → test → format)
+- Same file reading patterns (e.g., always reading ARCHITECTURE_TOC.md before edits)
+- Same error→fix sequences (e.g., import error → add import → retry)
+
+Present findings: "I noticed you repeatedly [pattern]. Want me to make this a skill?"
+
+### If manual:
+Ask: "Describe the pattern you want to save. What triggers it? What should happen?"
+
+## Step 2: Create Skill
+
+Skills live in: ~/.config/omg/skills/ (personal) or .omg/skills/ (project)
+
+```
+~/.config/omg/skills/[skill-name]/
+├── SKILL.md          # Instructions Claude follows
+├── templates/        # Template files (optional)
+└── scripts/          # Helper scripts (optional)
+```
+
+### SKILL.md Format:
+```markdown
+# [Skill Name]
+
+## When to activate
+[Trigger conditions — what keywords, file types, or situations activate this]
+
+## Steps
+1. [Step 1]
+2. [Step 2]
+...
+
+## Templates
+[If the skill creates files, include template content or reference templates/]
+
+## Quality check
+[How to verify the skill worked correctly]
+
+## Examples
+[1-2 examples of good output]
+```
+
+## Step 3: Register
+
+Add skill to .omg/skills-index.json:
+```json
+{
+  "skills": [
+    {
+      "name": "api-test-pattern",
+      "trigger": ["test", "api", "endpoint"],
+      "path": "~/.config/omg/skills/api-test-pattern/SKILL.md",
+      "description": "Creates API endpoint tests with auth, validation, edge cases"
+    }
+  ]
+}
+```
+
+## Step 4: Verify
+- Create a test invocation
+- Confirm the skill produces correct output
+- Tell user: "Skill '[name]' saved. It'll activate when you [trigger condition]."
+
+## Built-in Skill Candidates (suggest these)
+When detecting patterns, especially look for:
+- **Test patterns**: How tests are structured for this project
+- **Component patterns**: How new React/Vue/etc components are created
+- **API patterns**: How new endpoints are added (route + handler + validation + test)
+- **Migration patterns**: How DB migrations are created and verified
+- **PR patterns**: How PRs are structured (description, checklist, labels)
+- **Debug patterns**: Project-specific debugging steps (log locations, common fixes)
+
+## Aggregated Patterns (Auto)
+When you run `/OMG:learn auto`, OMG reads all learning files from `.omg/state/learnings/` and generates `.omg/knowledge/critical-patterns.md` with your top tool and file patterns.
+
+Run: `python3 -c "import sys; sys.path.insert(0,'hooks'); from _learnings import save_critical_patterns; save_critical_patterns('.')"`
+## File Write Fallback
+If `Write` fails (file exists), use `Edit` or Bash heredoc:
+```bash
+cat > path/to/skill.md << 'SKILLEOF'
+[content]
+SKILLEOF
+```
+Always READ the file after writing to verify changes.

package/plugins/advanced/commands/OMG:maintainer.md

@@ -0,0 +1,31 @@
+---
+description: Open-source maintainer workflow — issue triage, release notes, review assistance, impact evidence pack
+allowed-tools: Read, Write, Edit, MultiEdit, Grep, Glob, Bash(git:*), Bash(rg:*), Bash(find:*), Bash(cat:*), Bash(ls:*)
+argument-hint: "[triage|release|review|impact]"
+---
+
+# /OMG:maintainer — OSS Maintainer Kit
+
+## Modes
+1. `triage`: summarize new issues, propose labels/priority/owner.
+2. `release`: draft release notes from recent commits and notable changes.
+3. `review`: review open changes with risk tags and test gaps.
+4. `impact`: generate Ecosystem Impact evidence draft.
+
+## Ecosystem Impact Evidence Pack
+Create `.omg/evidence/oss-impact.json` with:
+- `activity`: commits/reviews/releases in recent window
+- `dependents`: direct/transitive usage indicators (if available)
+- `stability`: test pass/fail trend and security findings
+- `adoption_signals`: downloads/stars/changelog cadence (factual only)
+- `summary_500_words`: draft narrative for application forms
+
+## Integrity Policy
+- Never fabricate stats.
+- Never suggest metric manipulation (stars/download inflation).
+- Mark unknown metrics as `unverified`.
+
+## Output format
+- Findings first
+- Risks and unknowns
+- Actionable next 3 maintainer tasks

package/plugins/advanced/commands/OMG:ralph-start.md

@@ -0,0 +1,43 @@
+---
+description: "Start Ralph autonomous loop — continues working until all tasks complete or max iterations reached."
+allowed-tools: Read, Write, Edit, Bash, Grep, Glob
+argument-hint: "[goal description]"
+---
+
+# /OMG:ralph-start — Start Ralph Autonomous Loop
+
+## Purpose
+Starts a Ralph loop that autonomously continues working until all tasks in the goal are complete or max iterations reached.
+
+## Usage
+```
+/OMG:ralph-start [goal description]
+```
+
+## How it Works
+1. Ask the user for a goal description if not provided
+2. Create `.omg/state/ralph-loop.json` with:
+   - `active: true`
+   - `iteration: 0`
+   - `max_iterations: 50`
+   - `original_prompt: [goal]`
+   - `started_at: [ISO8601 timestamp]`
+   - `checklist_path: ".omg/state/_checklist.md"` (if exists)
+3. Confirm: "Ralph loop started. Will continue working on: [goal]"
+
+## State File Format
+```json
+{
+  "active": true,
+  "iteration": 0,
+  "max_iterations": 50,
+  "original_prompt": "fix all failing tests",
+  "started_at": "2026-02-28T10:00:00Z",
+  "checklist_path": ".omg/state/_checklist.md"
+}
+```
+
+## Stop Condition
+- Reaches max_iterations (50 by default)
+- User runs `/OMG:ralph-stop`
+- User deletes `.omg/state/ralph-loop.json`