:** The 20-point engineering axis rewards architectural decisions, security hardening, and maintainability. oma's lead here indicates it produces production-ready code, not just functional snippets.
- Actionable Intelligence: The benchmark scores correlate directly with reduced technical debt. Teams using orchestrated workflows spend less time fixing agent-induced drift and security issues.
Core Solution
To address fragmentation, drift, and security, oh-my-agent implements a control plane that standardizes agent interaction, enforces security boundaries, and provides observable metrics. The architecture rests on four pillars:
1. Consolidated Configuration and Model Management
Vendor-specific configurations are consolidated into a single oma-config.yaml. This file defines model presets, agent routing, and auto-approval policies. The system includes a model management suite that diffs the local registry against external sources like OpenRouter and Cursor's model list.
Architecture Decision: Centralizing configuration allows for atomic updates and migration safety. Legacy mappings are auto-migrated via versioned migration scripts (e.g., migration 008), ensuring backward compatibility while enforcing modern standards.
Configuration Example:
# oma-config.yaml
version: "2.0"
model_preset: "production-optimized"
agents:
cursor:
vendor: "cursor"
routing: "composer-2"
auto_approve: true
preset: "cursor-only"
codex:
vendor: "codex"
cli_guard: true
arg_terminator: "--"
security:
path_traversal_protection: true
mime_validation: true
nfkc_normalization: true
observability:
auto_update_cli: true
benchmark_rounds: 3
2. Dynamic Skill Registration
Skills are no longer hardcoded. The system scans .agents/skills/ directories at build time, reading frontmatter to auto-register capabilities. This enables modular expansion without touching core logic.
Skill Definition Example:
# .agents/skills/oma-deepsec/skill.yaml
name: "oma-deepsec"
description: "Vercel deepsec driver integration for security auditing"
trigger_keywords:
- "/deepsec"
- "security-audit"
languages:
- typescript
- javascript
- python
execution:
command: "oma run deepsec"
requires_auth: false
3. Security Hardening and Input Validation
The orchestration layer enforces strict input validation:
- NFKC Normalization: Prevents hook bypasses using fullwidth Unicode characters (e.g.,
parallel is normalized to parallel before evaluation).
- Path Traversal Protection: Output and reference paths are validated against traversal patterns.
- Magic-Byte Validation: Reference images are verified via MIME type detection, not just file extensions.
- CLI Invocation Guard: A two-tier guard ensures commands like
claude review this code route to workflows, while claude exec --foo is blocked from unintended execution.
4. Cross-Vendor Routing and Windows Compatibility
Cursor is promoted to a first-class vendor with dedicated routing (composer-2) and auto-approval presets. Windows support is robust, handling junction and hardlink fallbacks when symlinks fail with EPERM. Path separators are normalized across all IO layers, including gitignore handling and doctor diagnostics.
Pitfall Guide
| Pitfall | Explanation | Fix |
|---|
| NFKC Bypass | Attackers use fullwidth Unicode to bypass keyword detectors. E.g., parallel evades regex matching parallel. | Implement NFKC normalization on all input strings before hook evaluation. |
| Path Traversal | Malicious --out or --reference arguments can write files outside the intended directory. | Validate paths against traversal patterns. Use canonical path resolution. |
| Variadic Arg Swallowing | CLI tools like codex exec -i may treat the prompt as a second reference image if arguments are variadic. | Terminate variable arguments with -- before the instruction string. |
| Hardcoded Skill Maps | Maintaining a static list of skills requires code changes for every new capability. | Use frontmatter-based auto-registration in .agents/skills/. |
| Windows Symlink EPERM | Symlinks often fail on Windows due to permission restrictions. | Implement fallback logic to use junctions or hardlinks when symlinks raise EPERM. |
| Single-Shot Benchmarking | Evaluating agents on a single run produces noisy, unreliable metrics. | Use multi-judge averaging across multiple rounds (e.g., 3 rounds, 3 judges). |
| Translation Drift | i18n files diverge across locales, leading to missing or incorrect translations. | Run oma docs i18n to detect drift. Use oma docs lint to flag em-dashes and placeholders. |
Production Bundle
Action Checklist
Decision Matrix
| Scenario | Recommended Approach | Why | Cost Impact |
|---|
| Multi-Vendor Team | Use oma with consolidated config | Standardizes behavior across Cursor, Codex, etc. Reduces drift. | Low setup cost; high ROI on consistency. |
| Security-First Project | Enable oma-deepsec and path validation | Prevents path traversal and input bypasses. | Minimal overhead; critical risk reduction. |
| Benchmarking Agents | Use oma's multi-judge benchmark | Provides reliable, reproducible metrics. | Requires compute for 3 rounds; accurate results. |
| Windows Development | Use install.ps1 and junction fallbacks | Handles symlink limitations gracefully. | No cost; ensures cross-platform compatibility. |
| Rapid Prototyping | Use oma-skill-creator | Generates new skills quickly from templates. | Accelerates development; maintains structure. |
Configuration Template
# oma-config.yaml
# Production-ready configuration template
version: "2.0"
model_preset: "high-fidelity"
agents:
cursor:
vendor: "cursor"
routing: "composer-2"
auto_approve: true
preset: "cursor-only"
codex:
vendor: "codex"
cli_guard: true
arg_terminator: "--"
variadic_fix: true
security:
path_traversal_protection: true
mime_validation: true
nfkc_normalization: true
magic_byte_check: true
observability:
auto_update_cli: true
benchmark_rounds: 3
benchmark_judges: 3
skills:
auto_register: true
directory: ".agents/skills"
docs:
i18n_locales:
- en
- ja
- zh
lint_rules:
- em_dash_cjk
- placeholder_validation
Quick Start Guide
- Install:
# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash
# Windows
irm https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.ps1 | iex
- Initialize:
oma init
- Verify:
oma doctor
- Run Benchmark:
oma benchmark
- Deploy Skill:
mkdir -p .agents/skills/oma-custom
# Add skill.yaml to directory
oma skills list
This orchestration layer transforms fragmented agent usage into a standardized, secure, and measurable workflow. By consolidating configuration, enforcing security boundaries, and providing reliable benchmarks, teams can achieve consistent, production-grade results across all AI coding agents.