@trac3r/oh-my-god 2.2.11

package/QUICK-REFERENCE.md

@@ -0,0 +1,58 @@
+<!-- GENERATED: DO NOT EDIT MANUALLY -->
+# OMG CLI Adapter Quick Reference
+
+## 🎯 Core Integration Points
+
+### Canonical Hosts
+
+<!-- OMG:GENERATED:quick-reference-hosts -->
+### Host Targets
+
+| host | role | config |
+| :--- | :--- | :--- |
+| claude | canonical | `.mcp.json` |
+| codex | canonical | `~/.codex/config.toml` |
+| gemini | canonical | `~/.gemini/settings.json` |
+| kimi | canonical | `~/.kimi/mcp.json` |
+| opencode | compatibility | `~/.config/opencode/opencode.json` |
+
+<!-- /OMG:GENERATED:quick-reference-hosts -->
+
+| Host | Config File |
+| :--- | :--- |
+| claude | `.mcp.json` |
+| codex | `~/.codex/config.toml` |
+| gemini | `~/.gemini/settings.json` |
+| kimi | `~/.kimi/mcp.json` |
+
+### Release Channels
+
+- `public`
+- `enterprise`
+
+### Preset Quick Reference
+
+| Preset | Key Features |
+| :--- | :--- |
+| safe | None |
+| balanced | SETUP, SETUP_WIZARD, MEMORY_AUTOSTART, SESSION_ANALYTICS, CONTEXT_MANAGER... |
+| interop | SETUP, SETUP_WIZARD, MEMORY_AUTOSTART, SESSION_ANALYTICS, CONTEXT_MANAGER... |
+| labs | SETUP, SETUP_WIZARD, MEMORY_AUTOSTART, SESSION_ANALYTICS, CONTEXT_MANAGER... |
+| buffet | SETUP, SETUP_WIZARD, MEMORY_AUTOSTART, SESSION_ANALYTICS, CONTEXT_MANAGER... |
+| production | SETUP, SETUP_WIZARD, MEMORY_AUTOSTART, SESSION_ANALYTICS, CONTEXT_MANAGER... |
+
+### Quick Commands
+
+| Task | Command |
+| :--- | :--- |
+| Install (preview) | `npx omg install --plan` |
+| Install (apply) | `npx omg install --apply` |
+| Diagnostics | `npx omg doctor` |
+| Environment check | `npx omg env doctor` |
+| Ship | `npx omg ship` |
+| Release audit | `npx omg release audit --artifact` |
+| Proof dashboard | `npx omg proof open --html` |
+| Explain run | `npx omg explain run --run-id <id>` |
+| Blocked inspection | `npx omg blocked --last` |
+| Validate | `npx omg validate` |
+| Contract validate | `npx omg contract validate` |

package/README.md

@@ -0,0 +1,207 @@
+# OMG
+
+[![Compat Gate](https://github.com/trac3r00/OMG/actions/workflows/omg-compat-gate.yml/badge.svg)](https://github.com/trac3r00/OMG/actions/workflows/omg-compat-gate.yml)
+[![npm version](https://img.shields.io/npm/v/%40trac3r%2Foh-my-god)](https://www.npmjs.com/package/@trac3r/oh-my-god)
+[![License](https://img.shields.io/github/license/trac3r00/OMG)](LICENSE)
+
+OMG upgrades your agent host instead of replacing it. It gives Claude Code, Codex, and other supported CLIs a tighter setup flow, stronger orchestration, native adoption from older plugin stacks, and proof-backed verification.
+
+## The Problem
+
+Agent hosts like Claude Code and Codex are powerful but lack governance, mutation safety, and evidence-backed verification. They often operate in a "trust me" mode where changes happen without a clear audit trail or safety gates. This leads to risky mutations, lack of interoperability between different agent stacks, and difficulty in verifying that a task was actually completed correctly.
+
+## The Solution
+
+OMG (Oh My God) provides a governance and orchestration layer that sits on top of existing agent hosts. It introduces:
+
+- **Hooks**: Pre-tool and post-tool execution gates for security and validation.
+- **Governance Payload**: Structured metadata for every action.
+- **Mutation Gate**: Prevents or warns about risky file system changes.
+- **Session Health**: Monitors the state of the session and requires review for risky states.
+- **Forge**: A modular orchestration engine for complex tasks.
+- **Memory**: A secure, namespaced, and encrypted state store.
+- **Evidence-Backed Verification**: Machine-generated proof for every claim.
+
+## Real-World Example
+
+Imagine an agent trying to delete a critical configuration file. Without OMG, the agent might just do it. With OMG's **Mutation Gate**, the action is intercepted, a warning is generated, and the user is prompted for approval. Or, when an agent claims a feature is "done", OMG's **Claim Judge** and **Proof Gate** require actual test results and build logs as evidence before the claim is accepted.
+
+## Architecture
+
+OMG operates as a middleware layer between the agent host and the underlying tools.
+
+```mermaid
+graph TD
+    Host[Agent Host: Claude Code / Codex] -->|Tool Call| Hooks[OMG Hooks]
+    Hooks -->|Security Check| Security[Security Guard / Firewall]
+    Hooks -->|Governance| ControlPlane[OMG Control Plane]
+    ControlPlane -->|State| Memory[OMG Memory]
+    ControlPlane -->|Verification| Proof[Proof Gate / Claim Judge]
+    ControlPlane -->|Orchestration| Forge[OMG Forge]
+    Hooks -->|Execution| Tool[Actual Tool Execution]
+    Tool -->|Result| Hooks
+    Hooks -->|Evidence| Proof
+```
+
+## Comparison
+
+| Feature | Raw Claude Code | Superpowers | OMG |
+| :--- | :---: | :---: | :---: |
+| **Governance** | Minimal | Plugin-based | Native Control Plane |
+| **Mutation Safety** | Basic | None | Hard Gates + Warnings |
+| **Verification** | Manual | None | Evidence-Backed Proof |
+| **Interoperability** | Single Host | Multi-Host | Universal MCP + Registry |
+| **State Management** | Volatile | Local Files | Encrypted + Namespaced |
+| **Orchestration** | Linear | Scripted | Modular Forge |
+
+## Limitations
+
+- **Not a Base Model**: OMG does not train or provide its own LLMs; it orchestrates existing ones.
+- **Local-Only**: Designed for same-machine production; no cloud-sync for state by design.
+- **Advisory-First**: In v1, many gates are advisory (warnings) rather than hard-blocking to avoid breaking workflows.
+- **Host Dependent**: Capabilities are limited by what the underlying agent host supports.
+
+- Brand: `OMG`
+- Repo: `https://github.com/trac3r00/OMG`
+- npm: `@trac3r/oh-my-god`
+- Plugin id: `omg`
+- Marketplace id: `omg`
+
+## Why OMG
+
+<!-- OMG:GENERATED:why-omg -->
+OMG keeps the host you already use, then adds governed install, proof, and release surfaces on top.
+
+- Canonical host parity targets are Claude, Codex, Gemini, and Kimi.
+- OpenCode remains a supported compatibility host for teams that need it.
+- Install and verification stay explicit: doctor first, preview second, apply last.
+
+> Legacy Claude compatibility commands such as `/OMG:setup` and `/OMG:crazy <goal>` remain documented as footnotes only.
+<!-- /OMG:GENERATED:why-omg -->
+
+- Claude front door: run `npx omg env doctor`, then `npx omg install --plan`, then `npx omg install --apply`.
+- Browser front door: run `/OMG:browser <goal>` for browser automation and verification, with `/OMG:playwright` kept as a compatibility alias and the upstream Playwright CLI handling browser execution.
+- Multi-host support: Claude Code, Codex, Gemini CLI, and Kimi CLI are canonical behavior-parity hosts; OpenCode is compatibility-only.
+- Compiled planning: advanced planning is now compiled into the `plan-council` bundle for deterministic execution.
+- Native adoption: setup detects OMC, OMX, and Superpowers-style environments without exposing copycat public migration commands.
+- Proof-first delivery: verification, provider coverage, HUD artifacts, and transcripts are published instead of implied.
+
+## Canonical Contract
+
+OMG now ships a production control-plane contract and generated host artifacts. Same-machine production support is anchored by the stdio-first `omg-control` MCP. HTTP control-plane exposure is intended for development and local HUD use only.
+
+- Normative spec: `OMG_COMPAT_CONTRACT.md`
+- Executable registry: `registry/omg-capability.schema.json` and `registry/bundles/*.yaml`
+- Generated Codex pack: `.agents/skills/omg/`
+- Validation: `npx omg contract validate`
+- Compilation: `npx omg contract compile --host claude --host codex --host gemini --host kimi --channel public`
+- Release gate: `npx omg release readiness --channel dual`
+
+![OMG HUD](docs/assets/omg-hud.svg)
+
+## Quickstart
+
+<!-- OMG:GENERATED:install-intro -->
+> **Prerequisites**: macOS or Linux, Node >=18, Python >=3.10
+
+```bash
+npx omg env doctor
+npx omg install --plan
+# confirm preview output before applying
+npx omg install --apply
+npx omg ship
+```
+
+Local package-manager installs only link `omg` into `node_modules/.bin/`; they do not mutate configuration.
+
+The package postinstall runs `npx omg install --plan` as a preview, so it makes no mutations until you explicitly run `npx omg install --apply`.
+<!-- /OMG:GENERATED:install-intro -->
+
+On non-Claude hosts, verify native MCP registration after `npx omg install --apply`:
+
+- `codex mcp list`
+- `gemini mcp list`
+- `kimi mcp list`
+
+Success looks like:
+
+- supported hosts are detected
+- Claude Code sees `omg@omg` as enabled instead of `failed to load`
+- Claude Code's plugin bundle owns `omg-control` via `.claude-plugin/mcp.json`; project or user `.mcp.json` entries can keep `filesystem` without collisions
+- `~/.claude/settings.json` has a `statusLine` command for `~/.claude/hud/omg-hud.mjs`
+- `~/.codex/config.toml`, `~/.gemini/settings.json`, and `~/.kimi/mcp.json` receive `omg-control` after `npx omg install --apply` when those CLIs are on `PATH`
+- additional MCP servers are added when a broader preset is selected (`balanced` adds `context7`; `interop` adds `websearch` and `omg-memory`; `labs` adds browser automation)
+- `.omg/state/adoption-report.json` is written when another ecosystem is present
+- OMG reports the selected preset and next step
+- narrowed defaults keep the required control plane small while optional capabilities such as browser automation remain opt-in
+
+> Restricted environments / air-gapped fallback only: clone-and-setup flows plus Claude slash commands such as `/OMG:setup` and `/OMG:crazy <goal>` remain available when launcher-first install cannot modify the host directly.
+
+## Install Guides
+
+- Claude Code: [docs/install/claude-code.md](docs/install/claude-code.md)
+- Codex: [docs/install/codex.md](docs/install/codex.md)
+- OpenCode: [docs/install/opencode.md](docs/install/opencode.md)
+- Gemini: [docs/install/gemini.md](docs/install/gemini.md)
+- Kimi: [docs/install/kimi.md](docs/install/kimi.md)
+## Native Adoption
+
+OMG uses native setup language instead of public migration commands.
+
+- `OMG-only`: recommended. OMG becomes the primary hooks, HUD, MCP, and orchestration layer.
+- `coexist`: advanced. OMG preserves non-conflicting third-party surfaces and records overlap instead of overwriting it.
+- Modes: `chill`, `focused`, `exploratory`. `focused` is the production default.
+- Presets: `safe`, `balanced`, `interop`, `labs`, `production` (all governed flags on).
+
+## Security Notes
+
+- The shipped `safe` preset now registers pre-tool security hooks before the planning helper.
+- `Bash` requests are screened by `firewall.py`, and file reads or edits are screened by `secret-guard.py`.
+- Raw environment dumps, interpreters, and permission-changing commands such as `env`, `node`, `python`, `python3`, `chmod`, and `chown` now require approval instead of being silently allowed.
+
+Compatibility references to OMC, OMX, and Superpowers are documented here: [docs/migration/native-adoption.md](docs/migration/native-adoption.md)
+
+## Proof
+
+Current local verification for this release: See `.omg/evidence/` for machine-generated verification artifacts.
+
+- Truth bundles: `claim-judge`, `test-intent-lock`, `proof-gate`
+- Execution Kernel: `exec-kernel` facade with `worker-watchdog` stall detection and `merge-writer` provenance
+- Governed Tool Fabric: Lane-based tool governance with signed approval and ledgering
+- Budget Envelopes: Multi-dimensional resource tracking (CPU, memory, wall time, tokens, network)
+- Host Parity: Semantic host parity normalization across canonical providers
+- Issue Surface: Active red-team and diagnostic surface via `/OMG:issue`
+- Certification Lane 1 and permanent flagship gate: Music OMR daily verification for deterministic OMR and live transposition under the hardest real-time domain constraints in the stack
+- Evidence profiles: `browser-flow`, `forge-cybersecurity`, `interop-diagnosis`, `install-validation`, `buffet`
+- Verification and provider matrix: [docs/proof.md](docs/proof.md)
+- Sample setup transcript: [docs/transcripts/setup.md](docs/transcripts/setup.md)
+- Sample crazy transcript: [docs/transcripts/crazy.md](docs/transcripts/crazy.md)
+- Release process: [docs/release-checklist.md](docs/release-checklist.md)
+
+## Command Surface
+
+Primary launcher entry points:
+
+- `npx omg env doctor`
+- `npx omg install --plan`
+- `npx omg install --apply`
+- `npx omg ship`
+- `npx omg proof open --html`
+- `npx omg blocked --last`
+
+> **Legacy/advanced aliases**: `/OMG:setup`, `/OMG:browser`, `/OMG:crazy`, `/OMG:deep-plan`
+> (compatibility path to `plan-council`),
+> `/OMG:playwright`, `/OMG:security-check`, `/OMG:api-twin`, `/OMG:preflight`, `/OMG:teams`,
+> `/OMG:ccg`, `/OMG:compat`, `/OMG:ship`
+
+## Contributing
+
+Public contributions are welcome.
+
+- Contribution guide: [CONTRIBUTING.md](CONTRIBUTING.md)
+- Security reporting: [SECURITY.md](SECURITY.md)
+- Changelog: [CHANGELOG.md](CHANGELOG.md)
+
+## Positioning
+
+OMG is a plugin and orchestration layer for supported CLIs. It is not a base-model training project. The goal is to make frontier agent hosts tighter, safer, more interoperable, and more verifiable than the default experience.

package/agents/__init__.py

@@ -0,0 +1 @@
+"""OMG agents module."""

package/agents/_model_roles.yaml

@@ -0,0 +1,26 @@
+roles:
+  default:
+    model: "claude-opus-4-5"
+    temperature: 1.0
+    max_tokens: 8192
+    description: "Default balanced model for general tasks"
+  smol:
+    model: "claude-haiku-4-5"
+    temperature: 0.7
+    max_tokens: 4096
+    description: "Fast cheap model for simple/trivial tasks"
+  slow:
+    model: "claude-opus-4-5"
+    temperature: 0.5
+    max_tokens: 16384
+    description: "Careful deliberate model for complex reasoning"
+  plan:
+    model: "claude-sonnet-4-5"
+    temperature: 0.8
+    max_tokens: 8192
+    description: "Planning and architecture model"
+  commit:
+    model: "claude-haiku-4-5"
+    temperature: 0.3
+    max_tokens: 2048
+    description: "Concise model for git commits and short summaries"

package/agents/designer.md

@@ -0,0 +1,67 @@
+---
+name: designer
+description: UI/UX design agent — component design, layout, accessibility, responsive design
+model: claude-opus-4-5
+tools: Read, Grep, Glob, Bash, Write, Edit
+bundled: true
+---
+
+# Agent: Designer
+
+## Role
+
+Frontend-focused UI/UX design agent. Designs and implements components, layouts, and visual systems with accessibility and responsiveness as first-class concerns.
+
+## Model
+
+`default` (claude-opus-4-5) — balanced capability for design reasoning and implementation.
+
+## Capabilities
+
+- Component design and implementation (React, Vue, HTML/CSS)
+- Layout systems (flexbox, grid, responsive breakpoints)
+- Accessibility (ARIA, keyboard navigation, color contrast, screen readers)
+- Responsive design (mobile-first, breakpoint strategy)
+- CSS and Tailwind utility class usage
+- Design system adherence and token usage
+- Animation and micro-interaction design
+- Visual hierarchy and typography
+
+## Instructions
+
+You are a frontend design agent. You design and build UI components.
+
+**Core rules:**
+- MUST NOT modify backend/API code (routes, controllers, database)
+- MUST check accessibility on every component (ARIA labels, keyboard nav, contrast)
+- MUST verify responsive behavior at 375px, 768px, and 1280px
+- MUST NOT introduce inline styles when a design system or utility classes exist
+- ALWAYS run the frontend linter/build before claiming completion
+
+**Design process:**
+1. Understand the user need — what problem does this UI solve?
+2. Check existing design system tokens, components, and patterns
+3. Design the component structure (props, state, layout)
+4. Implement with accessibility built in from the start
+5. Verify at all breakpoints
+6. Run linter and build
+
+**Accessibility checklist (every component):**
+- [ ] Semantic HTML elements used correctly
+- [ ] ARIA labels on interactive elements without visible text
+- [ ] Keyboard navigation works (Tab, Enter, Escape, Arrow keys)
+- [ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for UI)
+- [ ] Focus indicators visible
+
+**When to defer:**
+- Backend data fetching logic → `omg-backend-engineer`
+- Complex state management → coordinate with backend agent
+- Security-sensitive forms → recommend `/OMG:escalate codex`
+
+## Example Prompts
+
+- "Design a responsive navigation component with mobile hamburger menu"
+- "Build an accessible modal dialog with focus trap"
+- "Create a data table component with sorting and pagination"
+- "Improve the color contrast on the dashboard cards"
+- "Design a multi-step form wizard with progress indicator"

package/agents/explore.md

@@ -0,0 +1,60 @@
+---
+name: explore
+description: Fast codebase search agent — grep, glob, file reading, pattern matching
+model: claude-haiku-4-5
+tools: Read, Grep, Glob
+bundled: true
+---
+
+# Agent: Explore
+
+## Role
+
+Fast, read-only codebase search agent. Finds code, files, and patterns without modifying anything.
+
+## Model
+
+`smol` (claude-haiku-4-5) — speed-optimized for quick lookups and pattern matching.
+
+## Capabilities
+
+- Grep for patterns across files and directories
+- Glob to find files by name or extension
+- Read file contents and extract relevant sections
+- Pattern matching across multiple files simultaneously
+- Symbol and reference discovery
+- Dependency tracing (imports, requires, includes)
+- Find all usages of a function, class, or variable
+
+## Instructions
+
+You are a read-only search agent. Your job is to find things, not change them.
+
+**Core rules:**
+- NEVER write, edit, or delete files
+- NEVER run commands that modify state (no git commits, no npm install, no file writes)
+- ALWAYS return file paths with line numbers when reporting findings
+- ALWAYS summarize what you found at the end
+
+**Search strategy:**
+1. Start broad with glob to find candidate files
+2. Narrow with grep to find exact patterns
+3. Read relevant sections for context
+4. Report findings with file:line references
+
+**Output format:**
+- List each finding as `file.ext:LINE — description`
+- Group related findings together
+- End with a summary count: "Found N occurrences in M files"
+
+**When to stop:**
+- Once you've found what was asked for
+- If a pattern doesn't exist, say so clearly — don't keep searching
+
+## Example Prompts
+
+- "Find all usages of `fetchUser` across the codebase"
+- "Which files import from `@/lib/auth`?"
+- "Show me all TODO comments in the src/ directory"
+- "Find every place we call `console.error`"
+- "What files define a `handleSubmit` function?"

package/agents/model_roles.py

@@ -0,0 +1,196 @@
+#!/usr/bin/env python3
+"""Model roles loader — defines role configurations for model selection.
+
+Loads role definitions from _model_roles.yaml and provides utilities for
+role-based model selection, CLI argument parsing, and feature flag control.
+"""
+import os
+import sys
+from pathlib import Path
+from typing import Optional
+
+# Try to import yaml; fall back to json if not available
+try:
+    import yaml
+    HAS_YAML = True
+except ImportError:
+    HAS_YAML = False
+    import json
+
+# Add parent directory to path for importing from hooks
+_AGENTS_DIR = Path(__file__).parent
+_HOOKS_DIR = _AGENTS_DIR.parent / "hooks"
+if str(_HOOKS_DIR) not in sys.path:
+    sys.path.insert(0, str(_HOOKS_DIR))
+
+try:
+    from _common import get_feature_flag, get_project_dir
+except ImportError:
+    # Fallback if _common is not available
+    def get_feature_flag(flag_name, default=True):
+        env_key = f"OMG_{flag_name.upper()}_ENABLED"
+        env_val = os.environ.get(env_key, "").lower()
+        if env_val in ("0", "false", "no"):
+            return False
+        if env_val in ("1", "true", "yes"):
+            return True
+        return default
+
+    def get_project_dir():
+        return os.environ.get("CLAUDE_PROJECT_DIR", os.getcwd())
+
+
+# Global roles dictionary
+ROLES: dict = {}
+
+
+def _load_roles() -> dict:
+    """Load role definitions from _model_roles.yaml.
+    
+    Returns:
+        Dictionary mapping role names to role configurations.
+        Falls back to default roles if YAML cannot be loaded.
+    """
+    roles_file = _AGENTS_DIR / "_model_roles.yaml"
+    
+    if not roles_file.exists():
+        return _get_default_roles()
+    
+    try:
+        if HAS_YAML:
+            with open(roles_file, "r") as f:
+                data = yaml.safe_load(f)
+                if data and "roles" in data:
+                    return data["roles"]
+    except Exception as e:
+        print(f"[OMG] Warning: Failed to load roles from {roles_file}: {e}", file=sys.stderr)
+
+    
+    return _get_default_roles()
+
+
+def _get_default_roles() -> dict:
+    """Return hardcoded default roles if YAML cannot be loaded."""
+    return {
+        "default": {
+            "model": "claude-opus-4-5",
+            "temperature": 1.0,
+            "max_tokens": 8192,
+            "description": "Default balanced model for general tasks"
+        },
+        "smol": {
+            "model": "claude-haiku-4-5",
+            "temperature": 0.7,
+            "max_tokens": 4096,
+            "description": "Fast cheap model for simple/trivial tasks"
+        },
+        "slow": {
+            "model": "claude-opus-4-5",
+            "temperature": 0.5,
+            "max_tokens": 16384,
+            "description": "Careful deliberate model for complex reasoning"
+        },
+        "plan": {
+            "model": "claude-sonnet-4-5",
+            "temperature": 0.8,
+            "max_tokens": 8192,
+            "description": "Planning and architecture model"
+        },
+        "commit": {
+            "model": "claude-haiku-4-5",
+            "temperature": 0.3,
+            "max_tokens": 2048,
+            "description": "Concise model for git commits and short summaries"
+        }
+    }
+
+
+def get_role(name: str) -> dict:
+    """Get role configuration by name.
+    
+    Args:
+        name: Role name (e.g., 'smol', 'slow', 'plan', 'commit', 'default')
+    
+    Returns:
+        Role configuration dictionary. Returns 'default' role if name not found.
+    """
+    if not ROLES:
+        _init_roles()
+    
+    return ROLES.get(name, ROLES.get("default", {}))
+
+
+def list_roles() -> list[str]:
+    """Get list of all available role names.
+    
+    Returns:
+        List of role names in order they appear in configuration.
+    """
+    if not ROLES:
+        _init_roles()
+    
+    return list(ROLES.keys())
+
+
+def parse_role_args(argv: list[str]) -> Optional[str]:
+    """Parse command-line arguments to detect role selection.
+    
+    Detects: --smol, --slow, --plan, --commit
+    
+    Args:
+        argv: Command-line arguments (typically sys.argv[1:])
+    
+    Returns:
+        Role name if detected, None otherwise.
+    """
+    role_map = {
+        "--smol": "smol",
+        "--slow": "slow",
+        "--plan": "plan",
+        "--commit": "commit",
+    }
+    
+    for arg in argv:
+        if arg in role_map:
+            return role_map[arg]
+    
+    return None
+
+
+def _init_roles() -> None:
+    """Initialize the global ROLES dictionary."""
+    global ROLES
+    ROLES = _load_roles()
+
+
+# Initialize on module import
+_init_roles()
+
+
+if __name__ == "__main__":
+    # CLI for testing/inspection
+    import json as json_module
+    
+    if len(sys.argv) > 1:
+        if sys.argv[1] == "list":
+            print("Available roles:")
+            for role_name in list_roles():
+                print(f"  - {role_name}")
+        elif sys.argv[1] == "get":
+            if len(sys.argv) > 2:
+                role_name = sys.argv[2]
+                role = get_role(role_name)
+                print(json_module.dumps(role, indent=2))
+            else:
+                print("Usage: python3 model_roles.py get <role_name>")
+        elif sys.argv[1] == "parse":
+            detected = parse_role_args(sys.argv[2:])
+            if detected:
+                print(f"Detected role: {detected}")
+            else:
+                print("No role detected")
+        else:
+            print("Usage: python3 model_roles.py [list|get <role>|parse <args...>]")
+    else:
+        # Default: print all roles
+        print(json_module.dumps(ROLES, indent=2))

package/agents/omg-api-builder.md

@@ -0,0 +1,23 @@
+---
+name: api-builder
+description: API-builder specialist - API contracts, endpoint design, versioning, and integration boundaries
+model: claude-sonnet-4-5
+tools: Read, Grep, Glob, Bash, Write, Edit
+---
+API-builder specialist. Designs and implements API contracts with stable request/response schemas and explicit validation.
+
+Example tasks: define OpenAPI specs, design REST/GraphQL endpoints, add pagination/filtering conventions, version API changes, and align handlers with contract-first patterns.
+
+## Preferred Tools
+
+- Claude Sonnet (claude-sonnet-4-5): deep API design reasoning and schema correctness
+- Read/Grep: trace endpoint usage and downstream dependencies
+- LSP: map symbol references and validate interface impact
+- Bash: run API tests and contract verification commands
+
+## Guardrails
+
+- Must keep backward compatibility unless version bump is explicit.
+- Must validate input/output schemas at API boundaries.
+- Must include explicit error response shape and status code rationale.
+- Must run relevant API tests before completion claims.