oh-my-agent 20.0.1 → 20.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.md +521 -199
  2. package/bin/cli-main.js +1017 -1017
  3. package/package.json +2 -2
package/README.md CHANGED
@@ -1,60 +1,435 @@
1
- # oh-my-agent: The Multi-Agent Harness That Checks the Work
1
+ # oh-my-agent: A Specialist Team for the Coding Agent You Already Use
2
2
 
3
3
  [![npm version](https://img.shields.io/npm/v/oh-my-agent?color=cb3837&logo=npm)](https://www.npmjs.com/package/oh-my-agent) [![npm downloads](https://img.shields.io/npm/dm/oh-my-agent?color=cb3837&logo=npm)](https://www.npmjs.com/package/oh-my-agent) [![GitHub stars](https://img.shields.io/github/stars/first-fluke/oh-my-agent?style=flat&logo=github)](https://github.com/first-fluke/oh-my-agent) [![License](https://img.shields.io/github/license/first-fluke/oh-my-agent)](https://github.com/first-fluke/oh-my-agent/blob/main/LICENSE) [![Last Updated](https://img.shields.io/github/last-commit/first-fluke/oh-my-agent?label=updated&logo=git)](https://github.com/first-fluke/oh-my-agent/commits/main)
4
4
 
5
5
  [한국어](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.ko.md) | [中文](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.zh.md) | [Português](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.pt.md) | [日本語](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.ja.md) | [Français](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.fr.md) | [Español](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.es.md) | [Nederlands](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.nl.md) | [Polski](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.pl.md) | [Русский](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.ru.md) | [Deutsch](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.de.md) | [Tiếng Việt](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.vi.md) | [ภาษาไทย](https://github.com/first-fluke/oh-my-agent/blob/main/docs/README.th.md)
6
6
 
7
- **Agents narrate success. oh-my-agent checks the artifacts.**
7
+ **oh-my-agent (`oma`) adds a team of specialists to the coding agent you already use: Claude Code, Codex CLI, Cursor, and 11 more.** A planner breaks the work down, engineers build in parallel, a reviewer checks the result, and a debugger fixes root causes. It also does cited research, slide decks, videos and images. Most steps leave a file you can open, and in the long-running workflows a gate can send the agent back to work until your own `test`, `lint` or `typecheck` script passes.
8
8
 
9
- Spawning parallel agents is the easy part. The hard part is knowing whether they actually did the work. "Tests pass, all criteria met" costs an agent nothing to say, and nothing inside that same session can contradict it.
9
+ Run this from your project root:
10
10
 
11
- oh-my-agent makes the claim falsifiable. A Stop hook refuses to end your session until your project's own `typecheck` / `test` / `lint` script exits 0. A gate command decides whether a workflow really ran by looking for the artifacts it must have left behind — and its JSON verdict, not the agent's summary, is the result. In `/ralph`, the workflow prompt dispatches a judge, briefed on the criteria only, that re-verifies every criterion each round, including the ones that already passed. Gate decisions are appended to a per-session event log that you can read afterwards with `oma state`. Then it runs that same discipline across a dozen agent runtimes from one portable `.agents/` directory.
11
+ ```bash
12
+ curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash
13
+ ```
12
14
 
13
- Follow [Quick Start](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/getting-started/quick-start.md) to choose a skill preset, run `oma doctor`, and ask a named skill for one scoped change. Record the file, check command, and exit status.
15
+ Then run `oma doctor` and type `/plan add user accounts with a settings page` in your agent. [Your first 5 minutes](#your-first-5-minutes) walks through it.
14
16
 
15
17
  ![oh-my-agent explainer](https://github.com/first-fluke/oh-my-agent/raw/main/docs/assets/video/oh-my-agent-explainer.gif)
16
18
 
17
19
  [Watch the full video (35s)](https://github.com/first-fluke/oh-my-agent/blob/main/docs/assets/video/oh-my-agent-explainer.mp4)
18
20
 
19
- ## Quick Start
21
+ ## What you get
20
22
 
21
- Run the OMA installer and choose a skill preset for your project.
23
+ **Workflows** are what you type (or just say). They call in **roles**, the specialists. **Skills** are the know-how: each role carries its own, and your agent loads the rest whenever a task needs them.
22
24
 
23
- The install scripts auto-install bun, uv, and serena if they're missing.
25
+ | | What it gives you | Try it |
26
+ |---|---|---|
27
+ | **12 specialist roles** | PM, architect, backend, frontend, mobile, database and infra engineers, QA reviewer, debugger, refactorer, docs curator, researcher ([meet them](#meet-the-team)) | `/orchestrate build a TODO app with login` |
28
+ | **21 workflows** | Slash commands from `/brainstorm` and `/plan` to `/review`, `/debug` and `/scm`. Most also start from a plain request (keyword banks in up to 11 languages) | "review this PR" |
29
+ | **33 skills** | Domain know-how that loads only when a task needs it: UI, APIs, schemas, Terraform, CI, security, git, observability | loads by itself, e.g. "add a Terraform S3 bucket" |
30
+ | **Files you can open** | Plans, design docs, API contracts, ADRs, bug notes, per-agent results, security evidence, HTML explainers, recaps | `ls .agents/results` |
31
+ | **Checks that don't take the agent's word** | In a long-running workflow, your own `test`, `lint` or `typecheck` script must pass before the agent may stop; `oma ralph verify` checks that a `/ralph` run left its plan, QA and refactor files | `/ultrawork …`, then `oma goal set --gate test` |
32
+ | **Research and content** | Cited search, market research, papers, slide decks, MP4 videos, images, local voice, PDF/HWP to Markdown | `/video`, `/convert` |
33
+ | **One folder, 14 runtimes** | One portable `.agents/` directory, written into each runtime's own config files | `oma link cursor` |
24
34
 
25
- ```bash
26
- # macOS / Linux — auto-installs bun, uv & serena if missing
27
- curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh | bash
28
- ```
35
+ **[Install](#install)** · **[First 5 minutes](#your-first-5-minutes)** · **[The team](#meet-the-team)** · **[Which workflow?](#how-the-team-works-together)** · **[Everything in the box](#everything-in-the-box)** · **[Works with](#works-with)** · **[Verification](#verification-not-narration)** · **[FAQ](#faq)** · **[Docs](https://first-fluke.github.io/oh-my-agent/)**
36
+
37
+ ## Install
38
+
39
+ The script installs [bun](https://bun.sh) if it is missing, installs the `oma` command globally (`bun install --global oh-my-agent`, skipped when `oma` is already on your PATH), then starts the interactive setup. The global command matters: the hooks (keyword detection, the Stop gate) and several workflows call `oma`, and the hooks silently do nothing when they cannot find it. If you skip the script, install it yourself with `bun install --global oh-my-agent` (`npm install --global oh-my-agent` or `brew install oh-my-agent` also work).
40
+
41
+ <details>
42
+ <summary>Windows, or without the install script</summary>
29
43
 
30
44
  ```powershell
31
- # Windows (PowerShell) — auto-installs bun, uv & serena if missing
45
+ # Windows (PowerShell)
32
46
  irm https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.ps1 | iex
33
47
  ```
34
48
 
35
49
  ```bash
36
- # Or manual (any OS, requires bun + uv + serena)
37
- bunx oh-my-agent@latest
50
+ # Any OS with bun installed: the same setup, plus the global `oma` command
51
+ bun install --global oh-my-agent
52
+ oma
38
53
  ```
39
54
 
40
- Pick a preset and you're ready:
55
+ On Windows the installer hides Antigravity, Hermes, and Kimi, and the hook wrapper is a bash script. The default Aside browser MCP installs through `bash`, so deselect it if you have no bash.
56
+
57
+ </details>
58
+
59
+ The setup asks for your response language, which agent runtimes to wire up, capability providers, a browser MCP, a model preset, and a skill preset. **Pick `All` for the skill preset if you are unsure**: workflows are always installed, and several of them (`/orchestrate`, `/work`, `/ultrawork`, `/ralph`, `/docs`, `/security`) need skills that only `All` includes.
60
+
61
+ <details>
62
+ <summary>What the installer also does by default</summary>
63
+
64
+ - Installs **bun** (required). Tries **uv**, **Serena** (`uv tool install`), and **CUE** (`brew install cue` or `winget`), and continues with a warning if any of them fails.
65
+ - Pre-selects the **Aside** browser MCP in the interactive setup, and installs it with `curl -fsSL https://releases.aside.com/install.sh | bash` only if you keep it selected. Deselect it in the browser MCP step, or change it later with `oma update mcp`.
66
+ - Uses **AgentMemory** for semantic memory, which runs `bun install -g @agentmemory/agentmemory` and registers it as a login service (launchd, systemd user unit, or Windows scheduled task). Choose provider `none` or set `OMA_NO_AGENTMEMORY=1` to skip it.
67
+ - Asks before linking skills into home-directory vendor folders (Antigravity, Hermes, Kimi). In `$HOME` without `--global` it asks for confirmation.
68
+ - Writes some files outside the project without asking: `~/.claude.json` (marks the project as a trusted Claude Code workspace), `~/.serena/` (OMA context, answer-size floor, project registration), `~/.cursor/cli-config.json` (turns off Cursor's commit attribution), `~/.grok/config.toml` (telemetry), and `~/.gemini/antigravity-cli/` (HUD), each only for a vendor you selected.
69
+ - Writes **telemetry opt-outs** into vendor settings (Claude `DISABLE_TELEMETRY=1`, which also turns off Claude Code Remote Control; Gemini, Qwen, Codex, and Grok usage stats). Set `telemetry: true` to keep vendor defaults.
70
+ - Adds unset Claude Code settings to `.claude/settings.json`, including `skipDangerousModePermissionPrompt: true`, `effortLevel: high`, `cleanupPeriodDays: 180`, and env flags that turn off auto memory, adaptive thinking, error reporting, and built-in git instructions. Values you already set are kept.
71
+ - Adds a **co-author trailer**: Claude Code's commit attribution becomes `Co-Authored-By: First Fluke <our.first.fluke@gmail.com>` and PRs get a "Generated with oh-my-agent" line. Set `scm.co_author.enabled: false` to turn this off.
72
+ - Installs a **commit-msg guard** in `.githooks/` that rejects unlisted `Co-authored-by` addresses, and sets `git config --local core.hooksPath .githooks` when no other hooks are active. Set `scm.co_author.enforce_hook: false` to opt out.
73
+ - `oma update` updates the `oma` CLI in the background (`auto_update_cli: false` or `OMA_SKIP_VERSION_CHECK=1` to stop it) and runs `uv tool upgrade serena-agent --prerelease=allow` (`serena.auto_update: false`).
74
+ - With Serena in the default `bridge` mode, the first agent session that starts a shared Serena server registers a **cleanup timer** that stops idle shared Serena servers every 5 minutes (launchd `dev.oma.serena-daemon-gc`, systemd user timer `oma-serena-daemon-gc.timer`, or Windows scheduled task `OMA Serena Daemon GC`). Set `serena.mode: stdio` to skip the shared server and its timer. `oma uninstall` does not remove the timer.
75
+ - Non-interactive runs (`-y`, `OMA_YES=1`, `CI=true`) use the `All` skill preset, `model_preset: auto`, and Python as the backend language. They select no browser MCP (and skip the Aside install script) unless `mcp.devtools_browsers` already lists one.
76
+
77
+ </details>
78
+
79
+ <details>
80
+ <summary>Skill presets</summary>
81
+
82
+ | Preset | Skills |
83
+ |--------|--------|
84
+ | **All** | **All 33 skills** (recommended) |
85
+ | Fullstack | architecture, backend, brainstorm, db, debug, design, dev-workflow, frontend, mobile, pm, qa, scm, tf-infra |
86
+ | Fullstack Web | Fullstack without mobile and tf-infra |
87
+ | Fullstack Mobile | Fullstack without frontend and tf-infra |
88
+ | Frontend | architecture, brainstorm, debug, design, frontend, pm, qa, scm |
89
+ | Backend | architecture, backend, brainstorm, db, debug, dev-workflow, pm, qa, scm |
90
+ | Mobile | architecture, brainstorm, debug, mobile, pm, qa, scm |
91
+ | DevOps | architecture, brainstorm, debug, dev-workflow, observability, pm, qa, scm, tf-infra |
92
+ | Research | academic-writing, hwp, market, pdf, scholar, scm, search, translation |
93
+ | Content | academic-writing, design, image, scm, translation, voice |
94
+ | Custom | Pick skills one by one |
95
+
96
+ Of the named presets, only `All` includes coordination, orchestration, docs, security, refactor, explanation, recap, video, slide, and skill-creation (or pick them under `Custom`). Research and Content lack the skills behind `/plan`, `/review`, `/debug`, `/architecture`, and `/brainstorm`. See [Workflows that need skills outside a preset](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/getting-started/installation.md#workflows-that-need-skills-outside-a-preset).
97
+
98
+ </details>
99
+
100
+ ## Your first 5 minutes
101
+
102
+ 1. **Install** with the command above.
103
+ 2. **Check the install:**
104
+
105
+ ```bash
106
+ oma doctor
107
+ ```
108
+
109
+ You should see `CLI Status` (which agent CLIs are installed and signed in) and `Skills Status` (for example `Skills (33/33 installed, 33 complete)`). If `oma` is not found, open a new terminal (the installer may have just added `~/.bun/bin` to your PATH) or run `bun install --global oh-my-agent`.
110
+ 3. **Open your agent in the project and ask for a plan:**
111
+
112
+ ```text
113
+ /plan add user accounts with a settings page
114
+ ```
41
115
 
42
- | Preset | What You Get |
43
- |--------|-------------|
44
- | **All** | **Every agent and skill** |
45
- | Backend | architecture + backend + brainstorm + db + debug + dev-workflow + pm + qa + scm |
46
- | Content | academic-writer + design + image + scm + translator + voice |
47
- | DevOps | architecture + brainstorm + debug + dev-workflow + observability + pm + qa + scm + tf-infra |
48
- | Frontend | architecture + brainstorm + debug + design + frontend + pm + qa + scm |
49
- | Fullstack | architecture + backend + brainstorm + db + debug + design + dev-workflow + frontend + mobile + pm + qa + scm + tf-infra |
50
- | Fullstack Mobile | architecture + backend + brainstorm + db + debug + design + dev-workflow + mobile + pm + qa + scm |
51
- | Fullstack Web | architecture + backend + brainstorm + db + debug + design + dev-workflow + frontend + pm + qa + scm |
52
- | Mobile | architecture + brainstorm + debug + mobile + pm + qa + scm |
53
- | Research | academic-writer + hwp + market + pdf + scholar + scm + search + translator |
116
+ Or just write "plan user accounts with a settings page": on runtimes with a prompt hook, the keyword starts the same workflow.
117
+ 4. **Check what you got.** `/plan` runs in the current session. For work that spans several areas, like this one, it writes `.agents/results/plan-<session-id>.json` and a tracker at `docs/plans/work/<NNN>-<name>.md`. A small, single-area request gets a direct recommendation instead of a plan file.
54
118
 
55
- ## Agent Integrations
119
+ Stop there. You will know whether this is for you. When you want more, run `/work` or `/orchestrate` on the plan.
56
120
 
57
- `oh-my-agent` uses `.agents/` as the shared source for agent skills, workflows, rules, and verification gates.
121
+ ## Meet the team
122
+
123
+ Your own agent leads the team. In `/work`, `/orchestrate` and `/ultrawork` it hands each job to the right specialist, which runs as its own subagent. `/plan`, `/architecture` and `/docs` run in your current session with that role's skill, and `/review` and `/debug` call in their specialist for large scopes. When a role is on another vendor's CLI, `oma agent spawn` runs it there.
124
+
125
+ | Your specialist | Carries | Call them with | Leaves behind |
126
+ |---|---|---|---|
127
+ | **Product manager** (`pm-planner`) | oma-pm | `/plan`, or "plan the payment feature" | A plan JSON and a tracker in `docs/plans/work/` for Medium and Complex work (Simple requests get a direct recommendation) |
128
+ | **Architect** (`architecture-reviewer`) | oma-architecture | `/architecture` | An ADR or recommendation in `.agents/results/architecture/` |
129
+ | **Backend, frontend, mobile, database and infra engineers** | oma-backend, oma-frontend + oma-design, oma-mobile, oma-db, oma-tf-infra | `/work`, `/orchestrate` | Code, tests, and a `result-<agent>` file per task |
130
+ | **QA reviewer** (`qa-reviewer`) | oma-qa | `/review`, or "review this PR" | Findings ranked CRITICAL to LOW, each with file:line and fix code |
131
+ | **Debugger** (`debug-investigator`) | oma-debug | `/debug`, or "fix this bug" | A minimal fix, a regression test, and a bug note in `.agents/results/bugs/` when one is warranted |
132
+
133
+ <details>
134
+ <summary>The other three roles, and the skills without a role</summary>
135
+
136
+ | Your specialist | Carries | Call them with | Leaves behind |
137
+ |---|---|---|---|
138
+ | **Refactorer** (`refactor-engineer`) | oma-refactor | `/ultrawork`'s REFINE phase | Behavior-preserving `refactor:` commits and a `result-refactor-<session>.md` report |
139
+ | **Docs curator** (`docs-curator`) | oma-docs | `/docs`, or "verify docs" | `docs/generated/doc-refs.json` and the doc patches you approve |
140
+ | **Researcher** (`research-explorer`) | oma-search, oma-market, oma-scholar | a research request | Cited sources with trust labels; market briefs in `.agents/results/market/` |
141
+
142
+ The infra engineer (`tf-infra-engineer`) is told to ask before any destructive or production `apply` or `destroy`. The remaining skills (brainstorm, security, scm, dev-workflow, observability, explanation, recap, translation, coordination, orchestration, skill-creation, content and media) have no dedicated role. Your agent loads them itself, and for most of them the skill injector suggests the right one from your prompt.
143
+
144
+ </details>
145
+
146
+ ## How the team works together
147
+
148
+ ```text
149
+ THINK /brainstorm ......................... docs/plans/designs/<NNN>-<feature>.md
150
+ PLAN /plan · /architecture ............... plan JSON, API contracts, ADR
151
+ DESIGN /design ............................. DESIGN.md + tokens
152
+ BUILD /work · /orchestrate · /ultrawork ... code + result-<agent> files, engineers in parallel
153
+ CHECK /review · /security · /debug ........ findings, security evidence, regression test
154
+ SHIP /scm · /docs ........................ Conventional Commits, doc fixes
155
+ ```
156
+
157
+ Each step hands a file to the next. `/brainstorm` saves a design that `/plan` reads, and `/plan` writes a plan in which every task has an agent, dependencies, acceptance criteria and a check command. `/orchestrate` runs that plan (it loads the most recent `plan-*.json`, or writes one). `/work` and `/ultrawork` start by having the PM write their own plan. Skip any stage you don't need; every stage also works on its own.
158
+
159
+ **Which workflow should run the team?**
160
+
161
+ | You want | Run | How it ends |
162
+ |---|---|---|
163
+ | Just a plan | `/plan` | A plan file for multi-area work, or a direct recommendation for small work |
164
+ | A PM-led build you follow step by step | `/work` | PM, then engineers tier by tier, then QA. CRITICAL and HIGH findings go into a fix loop (up to 5 cycles) |
165
+ | A hands-off parallel build | `/orchestrate` | Only tasks whose checks pass count as done; each task gets up to 3 attempts, then is marked partial or failed |
166
+ | Maximum care | `/ultrawork` | Five gated phases (PLAN, IMPL, VERIFY, REFINE, SHIP); every review runs in a fresh reviewer session |
167
+ | "Don't stop until it's really done" | `/ralph` | Repeats `/ultrawork` with a separately spawned, fresh-context judge until every criterion passes; stops with a partial report when criteria are blocked or after 5 iterations |
168
+ | The team on a timer | `oma schedule create qa-reviewer "review open PRs" --every 2h` | One Markdown log per run in `~/.oma/schedule/runs/<id>/` |
169
+
170
+ You don't need slash commands. On runtimes with a prompt hook, plain requests (keyword banks in up to 11 languages) can start most workflows: "review this PR" starts `/review`. Describing a whole app ("Build a TODO app with user authentication") suggests `/orchestrate`, and your agent decides whether to run it. Keywords inside code blocks are ignored.
171
+
172
+ `/orchestrate`, `/work`, `/ultrawork` and `/ralph` are **persistent** when you invoke them by name, as a slash command or in plain text ("ultrawork: add rate limiting"). The agent is then sent back to work when it tries to stop early (up to 5 times or 2 hours) until you say **"workflow done"**. A loosely matching request only suggests them.
173
+
174
+ **Measured, with caveats.** In the [benchmark](https://github.com/first-fluke/oh-my-agent/blob/main/benchmarks/README.md) (one prompt, Claude Code with five different add-on setups including plain, `claude-opus-4-6`, one build each), oma scored 80.6 against 70.7 for plain Claude Code, at 1.7x the cost ($4.04 vs $2.37) and 1.8x the time.
175
+
176
+ <details>
177
+ <summary>All 21 workflows</summary>
178
+
179
+ | Command | What it does |
180
+ |---------|--------------|
181
+ | `/architecture` | Weighs design tradeoffs and produces a recommendation, review, or ADR |
182
+ | `/brainstorm` | Explores ideas and constraints and produces an approved design before planning |
183
+ | `/convert` | Converts PDF/HWP to Markdown, or transcodes images, video, and audio with ffmpeg |
184
+ | `/debug` | Reproduces a bug, fixes the root cause, writes a regression test, and scans for similar patterns |
185
+ | `/deepinit` | Maps an existing codebase into AGENTS.md, ARCHITECTURE.md, and a docs/ knowledge base |
186
+ | `/design` | Builds a design system, DESIGN.md, and tokens with accessibility checks |
187
+ | `/docs` | Finds broken doc references and proposes patches for docs a diff touched |
188
+ | `/explain` | Turns a diff, PR, branch, or topic into a self-contained interactive HTML explainer |
189
+ | `/orchestrate` | Runs agents in parallel, coordinates them through file state, and verifies the result (persistent) |
190
+ | `/plan` | Breaks a feature into prioritized tasks with API contracts |
191
+ | `/ralph` | Repeats `/ultrawork` with a separately spawned judge, up to 5 iterations (persistent) |
192
+ | `/recap` | Summarizes your AI conversation history for a day or period |
193
+ | `/review` | Reviews security (OWASP Top 10), performance, accessibility (WCAG 2.2 AA), and code quality |
194
+ | `/schedule` | Registers an agent job that runs on a recurring interval |
195
+ | `/scm` | Handles branches, merges, conflicts, worktrees, and Conventional Commits |
196
+ | `/security` | Scans source, agent skills, and MCP components, validates findings, and sets up CI gates |
197
+ | `/stack-set` | Detects your tech stack and generates stack-specific references for domain skills |
198
+ | `/tools` | Lists, enables, and disables MCP tools in plain language |
199
+ | `/ultrawork` | Five phases (PLAN, IMPL, VERIFY, REFINE, SHIP), each review in a fresh reviewer session (persistent) |
200
+ | `/video` | Turns a brief into a finished MP4 through a key-optional pipeline |
201
+ | `/work` | Coordinates several agents on a multi-domain project with PM planning and QA review (persistent) |
202
+
203
+ Trigger accuracy is measured, not assumed: `oma verify triggers` scores the detector against a labeled English and Korean corpus of 212 prompts, and CI fails above 10% false fires or 20% missed fires. Last measured: **0% missed-fire, 5.3% false-fire**. Full reference: [Workflows](https://first-fluke.github.io/oh-my-agent/docs/core-concepts/workflows/).
204
+
205
+ </details>
206
+
207
+ ## See it work
208
+
209
+ An illustrative `/ultrawork` session. The `[OMA PERSISTENT MODE: ULTRAWORK]` block is the exact format the Stop hook prints; the other lines are paraphrased:
210
+
211
+ ```text
212
+ you /ultrawork add rate limiting to POST /login
213
+ agent runs `oma goal set --gate test`
214
+ agent PLAN writes .agents/results/plan-<run-id>.json
215
+ agent IMPL -> VERIFY -> REFINE -> SHIP (each review runs in a fresh reviewer session)
216
+ agent "Rate limiting added. All tests pass."
217
+ oma [OMA PERSISTENT MODE: ULTRAWORK]
218
+ Stop gate 'test' FAILED (reinforcement 1/5).
219
+ Fix the failures below, then finish the workflow — the stop is allowed only when the gate passes.
220
+ --- gate output (tail) ---
221
+ FAIL src/auth/login.test.ts > returns 429 after 5 attempts
222
+ To abandon instead: delete .agents/state/ultrawork-state-<host-session>.json or say "workflow done".
223
+ agent fixes the limiter and stops again
224
+ oma `test` exits 0: stop allowed, gate.passed appended to the session log
225
+ ```
226
+
227
+ Afterwards, `oma state list` finds the session and `oma state get <oma-sid>` (the ID `state list` prints) shows every gate event. Under `/ralph`, `oma ralph verify --json` also checks that the phases left their files behind (output trimmed):
228
+
229
+ ```json
230
+ { "ok": false,
231
+ "missing": [{ "id": "A3", "description": "a distinct QA agent ran (VERIFY phase)",
232
+ "pattern": ".agents/state/memories/result-qa*.md or .agents/results/result-qa*.md",
233
+ "status": "missing" }] }
234
+ ```
235
+
236
+ ## Everything in the box
237
+
238
+ <details>
239
+ <summary><strong>Plan and design</strong>: <code>/brainstorm</code>, <code>/plan</code>, <code>/architecture</code>, <code>/design</code></summary>
240
+
241
+ | Command | What it does | Writes |
242
+ |---|---|---|
243
+ | `/brainstorm` | Asks one clarifying question at a time and proposes 2-3 approaches that work differently, then hands off to `/plan`. Writes no code | `docs/plans/designs/<NNN>-<feature>.md` |
244
+ | `/plan` | Sizes the work as Simple, Medium or Complex; for Medium and Complex work, splits it into tasks, each with an agent, dependencies, acceptance criteria and a check command, and defines API contracts when the work crosses a boundary | `.agents/results/plan-<sid>.json`, `docs/plans/work/<NNN>-<name>.md`, contracts in `.agents/results/api-contracts/` when needed |
245
+ | `/architecture` | Reads earlier decisions first, compares at least 2 options, and marks replaced ADRs as superseded | An ADR or recommendation in `.agents/results/architecture/` |
246
+ | `/design` | Proposes 2-3 directions, then writes `DESIGN.md` with tokens and audits responsive layout and accessibility | `DESIGN.md`, CSS/Tailwind/shadcn tokens |
247
+
248
+ </details>
249
+
250
+ <details>
251
+ <summary><strong>Build</strong>: 7 domain skills, plus <code>/stack-set</code> to fit them to your stack</summary>
252
+
253
+ | Skill | Builds |
254
+ |---|---|
255
+ | oma-frontend | React/Next.js or Angular UI that follows your tokens, i18n and accessibility rules |
256
+ | oma-backend | APIs, auth and data access, layered router → service → repository |
257
+ | oma-mobile | Flutter, React Native or Swift apps |
258
+ | oma-db | Schemas, migrations, query tuning, vector/RAG retrieval plans |
259
+ | oma-tf-infra | Terraform for any cloud, with drift, destructive-change and cost risks called out |
260
+ | oma-dev-workflow | mise tasks, lint/format/typecheck, commitlint, git hooks, CI/CD and releases |
261
+ | oma-observability | OpenTelemetry, SLOs, alerting and incident forensics |
262
+
263
+ `/stack-set` reads your manifests and writes stack-specific references for the backend, frontend and mobile skills. In a monorepo, frontend, backend and mobile engineers are pointed at their workspace (pnpm, npm/yarn/bun workspaces, lerna, nx, turbo, `mise.toml`).
264
+
265
+ </details>
266
+
267
+ <details>
268
+ <summary><strong>Review, fix and ship</strong>: <code>/review</code>, <code>/security</code>, <code>/debug</code>, refactor, <code>/scm</code></summary>
269
+
270
+ | Command or skill | What it does | Writes |
271
+ |---|---|---|
272
+ | `/review` | A dependency audit, then OWASP Top 10, performance, WCAG 2.2 AA and code quality. Every finding gets file:line and fix code | The report in chat plus a memory record; no report file |
273
+ | `/security` | Scans your source, agent skills and MCP servers (Deepsec, Cisco Skill and MCP Scanner) and, given a scoped test deployment, runs ARTEX pen tests. The workflow requires an engine that failed to run to be reported as failed, not as clean | `.agents/results/security/<run-id>/` |
274
+ | `/debug` | Reproduces the failure, fixes the root cause with a minimal change, adds a regression test, and scans for the same pattern elsewhere | The fix and test; a bug note in `.agents/results/bugs/` when one is warranted |
275
+ | oma-refactor | Changes structure without changing behavior: characterization tests first, then refactor-only commits | `.agents/results/refactor/` |
276
+ | `/scm` | Conventional Commits split by logical change; branches, merges, rebases and worktrees | Commits and branches |
277
+
278
+ </details>
279
+
280
+ <details>
281
+ <summary><strong>Docs and knowledge</strong>: <code>/deepinit</code>, <code>/docs</code>, <code>/explain</code>, <code>/recap</code>, translation</summary>
282
+
283
+ | Command or skill | What it does | Writes |
284
+ |---|---|---|
285
+ | `/deepinit` | Turns an existing repo into an agent-ready knowledge base | `AGENTS.md`, `ARCHITECTURE.md`, `docs/` |
286
+ | `/docs` | Finds broken references, patches the docs a diff touched (only the patches you approve), and finds stale translations | `docs/generated/doc-refs.json`, patched docs |
287
+ | `/explain` | Turns a PR, branch or staged change into an HTML walkthrough with a 5-question quiz, or a topic into a one-page visual explainer | `.agents/results/explain/<date>-<slug>.html` |
288
+ | `/recap` | Summarizes your AI conversations across tools for a day or a period | `.agents/results/recap/<date>.md` |
289
+ | oma-translation | Translation that reads natively; placeholders, code and locale keys stay unchanged | Translated text |
290
+
291
+ </details>
292
+
293
+ <details>
294
+ <summary><strong>Research</strong>: search, market, papers, academic writing</summary>
295
+
296
+ | Skill | What it does | Writes |
297
+ |---|---|---|
298
+ | oma-search | Docs, web and code search, with a trust label on each source | Cited results |
299
+ | oma-market | Pain points, trends and competitors from community signals, framed with SWOT, Porter's 5 Forces and PESTEL | `.agents/results/market/<topic>-<date>.md` |
300
+ | oma-scholar | Paper search that reads a compact claims file (Knows format, about 700 tokens) instead of the full PDF (about 10K tokens) | `<paper>.knows.yaml` |
301
+ | oma-academic-writing | Drafts and audits academic prose against a rubric | Your file |
302
+
303
+ </details>
304
+
305
+ <details>
306
+ <summary><strong>Content and media</strong>: <code>/video</code>, <code>/convert</code>, slides, images, voice</summary>
307
+
308
+ | Command or skill | What it makes | Writes |
309
+ |---|---|---|
310
+ | `/video` | Shorts, explainers or demos as a finished MP4; keyed providers have key-free fallbacks | `.agents/results/videos/<run>/` with a manifest |
311
+ | oma-slide | 1920×1080 HTML decks, exported to PDF, PNG or PPTX | `.agents/results/slides/<session>/` |
312
+ | oma-image | Images through the vendor CLIs you're signed into, compared side by side | `.agents/results/images/<run>/` |
313
+ | oma-voice | Local text-to-speech and transcription through the Voicebox app | `.agents/results/voice/<run>/` |
314
+ | `/convert` | PDF or HWP to Markdown; image, video and audio conversion through ffmpeg | Next to the input file |
315
+
316
+ These pipelines report a missing source or vendor key instead of silently returning a thinner result.
317
+
318
+ </details>
319
+
320
+ <details>
321
+ <summary><strong>Hooks that run without being asked</strong></summary>
322
+
323
+ | Hook | What it does | Off switch / limit |
324
+ |---|---|---|
325
+ | Keyword start | Starts the matching workflow from a plain request | Questions, pasted text and code blocks are skipped |
326
+ | Skill injector | Points your agent at the right skills for the prompt | Paused while a persistent workflow is active |
327
+ | Stop gate | Sends a persistent workflow back to work; with `oma goal set --gate test`, the stop is allowed when that script exits 0 within 25 s | Say "workflow done"; it also releases after 5 blocks or 2 hours |
328
+ | Refactor guard | At stop, flags edited files over 500 lines for `refactor-engineer` | Opt-in: `refactor_guard.enabled` |
329
+ | Secret guard | Blocks `git add` of `*.env`, `*.pem`, `id_rsa*`, `*.tfstate` and similar files | Prefix that one command with `OMA_SCM_ALLOW_SECRETS=1` |
330
+ | Code-search guard | Blocks native recursive search in the project so the agent uses Serena or Gortex | `providers.code_intelligence_guard: off` |
331
+ | Test filter | Keeps only failures and summaries from test output, so fewer tokens are spent | `OMA_TEST_FILTER=0` |
332
+ | Session memory | When you switch or resume a session (or after compaction), re-injects the active session's recent events plus AgentMemory recall | Memory provider `none` or `OMA_NO_AGENTMEMORY=1` turns off the recall; the local event snapshot stays |
333
+
334
+ `oma hook probe` checks that oma's prompt hooks accept each runtime's hook input (it does not launch the runtime). Which hooks each runtime wires is in [Host differences](#host-differences).
335
+
336
+ </details>
337
+
338
+ <details>
339
+ <summary><strong>Parallel agents, sessions and dashboards</strong></summary>
340
+
341
+ - `oma agent spawn <role> "<task>" <sid>` runs a role on Antigravity, Claude, Codex, Cursor, OpenCode, Qwen, Grok or Pi, with `--isolation worktree` and `--fallback-vendors`. `oma agent parallel` runs several at once.
342
+ - `oma state list --all-projects` and `oma state get <sid>`: sessions and every recorded event.
343
+ - `oma dashboard terminal` / `oma dashboard web`: live agent status (the web dashboard listens on `127.0.0.1` only). [Dashboard guide](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/guide/dashboard-monitoring.md).
344
+ - `oma stats get` (productivity metrics), `oma retro` (a git retrospective), `oma recap --window 7d` (what you did across AI tools).
345
+ - `oma visualize --affected <paths>`: which skills, workflows, agents and checks depend on the `.agents/` files you changed.
346
+
347
+ </details>
348
+
349
+ <details>
350
+ <summary><strong>Code intelligence, memory and MCP</strong></summary>
351
+
352
+ | Slot | Default | Alternatives |
353
+ |---|---|---|
354
+ | Docs | Context7 | — |
355
+ | Code intelligence | Serena, one shared server per project | Gortex (experimental) |
356
+ | Semantic memory | AgentMemory | Honcho (experimental), none |
357
+ | Browser MCP | Aside | Chrome DevTools, Firefox DevTools |
358
+
359
+ Agents coordinate through plain files in `.agents/state/`, with no outside service. `/tools` turns MCP tools on or off in plain language. Details: [Capability Providers](https://github.com/first-fluke/oh-my-agent/blob/main/docs/capability-providers.md).
360
+
361
+ </details>
362
+
363
+ <details>
364
+ <summary><strong>Getting better over time</strong></summary>
365
+
366
+ - `oma skill eval` measures a skill's lift over a baseline on held-out tasks. `oma skill optimize` proposes edits that raise it, and `--apply` keeps them ([skill-eval guide](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/guide/skill-eval.md)).
367
+ - `oma harness evolution enable --max-dispatches <n>` schedules a nightly cycle that turns failed runs into regression fixtures and applies skill improvements that pass evaluation as project overlays. Add `--mode propose` to only record them.
368
+ - `oma emit` exports the `.agents/` source as an Agent Skills package, an Agent Plugins package, a Claude Code plugin marketplace, or `AGENTS.md`.
369
+
370
+ </details>
371
+
372
+ <details>
373
+ <summary><strong>Config and safety rails</strong></summary>
374
+
375
+ - One user-owned `.agents/oma-config.yaml` survives updates (only `oma update --force` resets it); private `.local.yaml` or `.local.cue` overlays can sit on top of it. `language` sets the response language.
376
+ - 13 project rules (backend, commit, database, debug, design, and more) load as native rules in Claude Code and Cursor, and are indexed in the managed `AGENTS.md` block written for Codex, Qwen Code and Pi.
377
+ - Updates keep config and migration backups in `.agents/backup/`; shipped skills and workflows are replaced in place, so keep local changes outside them. `oma uninstall --dry-run` shows what would be removed. `first-fluke/oma-update-action@v1` runs `oma update` in CI and opens a PR.
378
+
379
+ </details>
380
+
381
+ <details>
382
+ <summary><strong>All 33 skills</strong></summary>
383
+
384
+ | Skill | What it does |
385
+ |---|---|
386
+ | **oma-academic-writing** | Drafts, revises, and audits academic prose. |
387
+ | **oma-architecture** | Weighs architecture tradeoffs and draws module boundaries, with ADR/ATAM/CBAM analysis. |
388
+ | **oma-backend** | Builds APIs, authentication, and data access in Python, Node.js, or Rust. |
389
+ | **oma-brainstorm** | Explores ideas with you before you commit to building. |
390
+ | **oma-coordination** | Guides manual, step-by-step coordination of PM, frontend, backend, mobile, and QA agents. |
391
+ | **oma-db** | Designs schemas, migrations, indexes, and vector stores. |
392
+ | **oma-debug** | Finds the root cause, fixes the bug, and writes a regression test. |
393
+ | **oma-design** | Builds design systems with tokens, accessibility, and responsive layouts. |
394
+ | **oma-dev-workflow** | Automates CI/CD, releases, and monorepo tasks. |
395
+ | **oma-docs** | Checks docs for broken references, syncs them with code changes, and flags translation drift. |
396
+ | **oma-explanation** | Turns a diff, PR, branch, or topic into a self-contained HTML explainer, with a quiz for code changes. |
397
+ | **oma-frontend** | Builds UI in React/Next.js or Angular. |
398
+ | **oma-hwp** | Converts HWP, HWPX, and HWPML files to Markdown. |
399
+ | **oma-image** | Generates images and reference-guided variations, and can compare AI vendors side by side. |
400
+ | **oma-market** | Researches your market from community signals and frames it with SWOT, 5F, and PESTEL. |
401
+ | **oma-mobile** | Builds mobile apps with Flutter, React Native, or native Swift. |
402
+ | **oma-observability** | Routes observability work across metrics, logs, traces, SLOs, and incident forensics. |
403
+ | **oma-orchestration** | Runs multiple agents in parallel from the CLI. |
404
+ | **oma-pdf** | Converts PDF files to Markdown. |
405
+ | **oma-pm** | Plans tasks, breaks down requirements, and defines API contracts. |
406
+ | **oma-qa** | Reviews changes for correctness, OWASP security, performance, and accessibility. |
407
+ | **oma-recap** | Recaps your conversation history into themed work summaries. |
408
+ | **oma-refactor** | Refactors without changing behavior, using hotspot targeting, characterization tests, and refactor-only commits. |
409
+ | **oma-scholar** | Searches academic literature and builds Knows paper sidecars for claims, evidence, and peer review. |
410
+ | **oma-scm** | Manages branches, merges, worktrees, and Conventional Commits. |
411
+ | **oma-search** | Routes each query to the best source and scores how much you can trust the result. |
412
+ | **oma-security** | Scans source, agent skills, and MCP components; tests deployed web apps and validates findings. |
413
+ | **oma-skill-creation** | Writes and audits new OMA skills. |
414
+ | **oma-slide** | Generates HTML presentation decks and exports them to PDF/PNG/PPTX. |
415
+ | **oma-tf-infra** | Provisions multi-cloud infrastructure with Terraform. |
416
+ | **oma-translation** | Translates so the result reads like a native speaker wrote it. |
417
+ | **oma-video** | Generates short-form, explainer, and demo videos through a key-optional HyperFrames pipeline. |
418
+ | **oma-voice** | Generates voiceovers and transcribes audio on-device. |
419
+
420
+ </details>
421
+
422
+ ## Works with
423
+
424
+ 14 installer targets: Claude Code, Codex CLI, Cursor, Antigravity, Qwen Code, Grok, Kiro, Kimi, OpenCode, Pi, GitHub Copilot, Hermes, CommandCode, and ZCode. Wire a runtime you skipped with `oma link <vendor>`. Runtimes differ in which hooks they offer; the full matrix is in [Supported Agents](https://github.com/first-fluke/oh-my-agent/blob/main/docs/SUPPORTED_AGENTS.md).
425
+
426
+ - **Orca IDE:** [OMA for Orca](https://github.com/first-fluke/oh-my-agent/blob/main/integrations/orca/README.md) adds a sidebar panel and command-palette actions (Orca 1.4.197+ with experimental plugins).
427
+ - **DeepSeek Harness:** [OMA for DeepSeek Harness](https://github.com/first-fluke/oh-my-agent/blob/main/integrations/dsh/README.md) connects OMA checks through a Cordis plugin. It needs `oma` on your `PATH`.
428
+
429
+ <details>
430
+ <summary>Runtime logos (installer targets plus Amp and DeepSeek Harness)</summary>
431
+
432
+ native = oma writes the runtime's own config files; adapter = oma also adds hook or agent shims. Amp reads `.agents/skills/` by itself and is not an installer target.
58
433
 
59
434
  <table>
60
435
  <colgroup>
@@ -106,7 +481,7 @@ Pick a preset and you're ready:
106
481
  <td align="center">
107
482
  <a href="https://ampcode.com"><img src="https://github.com/first-fluke/oh-my-agent/raw/main/docs/assets/agents/amp.png" alt="Amp" width="48" height="48" /></a><br/>
108
483
  <strong>Amp</strong><br/>
109
- <sub>native-compatible</sub>
484
+ <sub>reads .agents/skills</sub>
110
485
  </td>
111
486
  <td align="center">
112
487
  <a href="https://github.com/features/copilot"><img src="https://github.com/github.png?size=120" alt="GitHub Copilot" width="48" height="48" /></a><br/>
@@ -128,215 +503,158 @@ Pick a preset and you're ready:
128
503
 
129
504
  <p align="center"><sub><a href="https://github.com/first-fluke/oh-my-agent/blob/main/docs/SUPPORTED_AGENTS.md">& more</a></sub></p>
130
505
 
131
- ## Your Engineering Team
506
+ </details>
132
507
 
133
- Instead of one AI doing everything (and getting confused halfway through), oh-my-agent splits work across specialized agents. Each one knows its domain deeply, has its own tools and checklists, and stays in its lane.
508
+ <a id="host-differences"></a>
509
+ <details>
510
+ <summary>Host differences: which runtimes get keyword detection and the Stop gate</summary>
511
+
512
+ | Runtime | Keyword detection | Stop gate |
513
+ |---|---|---|
514
+ | Claude Code, Codex CLI, Qwen Code, Grok, Kimi | yes | yes |
515
+ | Cursor | yes | yes (re-enters as a follow-up message) |
516
+ | Antigravity | yes | yes (runs handlers through bun, not the `oma` wrapper) |
517
+ | OpenCode, Pi | yes | best-effort (Pi needs a build with `agent_settled`) |
518
+ | Kiro | yes | no: Kiro ignores Stop hook output |
519
+ | CommandCode | no prompt hook | yes |
520
+ | GitHub Copilot, Hermes, ZCode | no hooks | no hooks |
134
521
 
135
- | Agent | What They Do |
136
- |-------|-------------|
137
- | **oma-architecture** | Weighs architecture tradeoffs and draws module boundaries, with ADR/ATAM/CBAM analysis. |
138
- | **oma-backend** | Builds and secures your APIs in Python, Node.js, or Rust. |
139
- | **oma-brainstorm** | Explores ideas with you before you commit to building. |
140
- | **oma-db** | Designs your schema, migrations, indexes, and vector stores. |
141
- | **oma-debug** | Finds the root cause, fixes the bug, and writes a regression test. |
142
- | **oma-design** | Builds design systems with tokens, accessibility, and responsive layouts. |
143
- | **oma-dev-workflow** | Automates your CI/CD, releases, and monorepo tasks. |
144
- | **oma-docs** | Checks your docs for broken references and flags ones a code change touched. |
145
- | **oma-explanation** | Turns a diff, PR, or branch into a self-contained interactive HTML explainer with a quiz. |
146
- | **oma-frontend** | Builds your UI with React/Next.js, TypeScript, Tailwind CSS v4, and shadcn/ui. |
147
- | **oma-mobile** | Builds cross-platform mobile apps with Flutter. |
148
- | **oma-observability** | Routes observability work across metrics, logs, traces, SLOs, and incident forensics. |
149
- | **oma-orchestration** | Runs multiple agents in parallel from the CLI. |
150
- | **oma-pm** | Plans tasks, breaks down requirements, and defines API contracts. |
151
- | **oma-qa** | Reviews your code for OWASP security, performance, and accessibility issues. |
152
- | **oma-refactor** | Refactors code without changing its behavior, using hotspot targeting, characterization-test safety nets, and refactor-only commits. |
153
- | **oma-scm** | Manages your branches, merges, worktrees, and Conventional Commits. |
154
- | **oma-security** | Scans source, agent skills, and MCP components; tests deployed web apps and validates findings. |
155
- | **oma-search** | Routes each query to the best source and scores how much you can trust the result. |
156
- | **oma-tf-infra** | Provisions multi-cloud infrastructure with Terraform. |
522
+ </details>
157
523
 
524
+ <a id="per-agent-models"></a>
158
525
  <details>
159
- <summary>Internal &amp; meta tools</summary>
526
+ <summary>Per-agent models</summary>
527
+
528
+ `model_preset` in `.agents/oma-config.yaml` chooses which model each agent role uses. The default, `auto`, follows the running runtime's own agent and model settings.
160
529
 
161
- | Agent | What They Do |
162
- |-------|-------------|
163
- | **oma-coordination** | Guides manual step-by-step coordination of PM, frontend, backend, mobile, and QA agents. |
164
- | **oma-skill-creation** | Writes and audits new OMA skills in the SSL-lite format. |
530
+ ```yaml
531
+ language: en
532
+ model_preset: auto # auto | free | antigravity | claude | codex | cursor | kiro | mixed | qwen | <custom_presets key>
533
+
534
+ # Optional per-agent overrides; they win over the preset
535
+ agents:
536
+ backend: { model: openai/gpt-5.5, effort: high }
537
+ ```
538
+
539
+ - `mixed` uses Claude for orchestrator, architecture, QA, PM, and docs, and Codex `gpt-5.5` for implementation roles, so it needs both Claude Code and Codex CLI.
540
+ - `free` routes through a FreeLLMAPI gateway and needs `FREELLM_API_KEY` plus a running server.
541
+ - `kiro` is not in the installer menu; set it in the config file.
542
+ - `oma doctor --profile` prints the resolved model for each role.
543
+ - Full guide: [Per-agent models](https://first-fluke.github.io/oh-my-agent/docs/guide/per-agent-models/)
165
544
 
166
545
  </details>
167
546
 
168
- ## Beyond Code: Content & Research Pipelines
547
+ ## Verification, Not Narration
169
548
 
170
- Separate from the engineering team, oma ships content and research pipelines built to the same engineering discipline: deterministic replay from fixtures, manifests for reproducibility, and honest degradation reporting when a source or vendor key is unavailable rather than a silently thinner result.
549
+ Agents narrate success. oh-my-agent checks the artifacts. [See it work](#see-it-work) shows the Stop gate in action; here is every check oma runs, and what each one proves.
171
550
 
172
- | Agent | What They Do |
173
- |-------|-------------|
174
- | **oma-academic-writing** | Drafts, revises, and audits academic prose to publication quality. |
175
- | **oma-hwp** | Converts HWP, HWPX, and HWPML files to Markdown. |
176
- | **oma-image** | Generates images through several AI providers at once. |
177
- | **oma-market** | Researches your market from community signals and frames it with SWOT, 5F, and PESTEL. |
178
- | **oma-pdf** | Converts PDF files to Markdown. |
179
- | **oma-recap** | Recaps your conversation history into themed work summaries. |
180
- | **oma-scholar** | Searches academic literature and helps you run peer review. |
181
- | **oma-slide** | Generates distinctive, animation-rich HTML presentation decks and exports to PDF/PNG/PPTX. |
182
- | **oma-translation** | Translates between languages so it reads like a native wrote it. |
183
- | **oma-video** | Generates short-form, explainer, and demo videos through a key-optional HyperFrames pipeline. |
184
- | **oma-voice** | Generates voiceovers and transcribes audio on-device, no cloud needed. |
551
+ Every mechanism below except the prompted judge is mechanical: a command exits 0 or it doesn't, a file is on disk or it isn't. None of those asks an LLM whether the work "looks correct."
185
552
 
186
- ### Orca IDE
553
+ | Mechanism | What it checks | Source |
554
+ |-----------|----------------|--------|
555
+ | **Stop-hook gate** | During a persistent workflow, `oma goal set --gate test` (or `lint`, `typecheck`) allows the stop only when that package.json script exits 0 within 25 s. | [`persistent-mode.ts`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/hooks/core/persistent-mode.ts) |
556
+ | **Artifact gate** | `oma ralph verify --json` checks for the phase records, the plan JSON, and result files from a **distinct QA agent** and a **distinct refactor agent**, each bound to recorded agent runs. | [`ralph.md`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/workflows/ralph.md) |
557
+ | **Prompted judge** | Not mechanical: the `/ralph` prompt tells the orchestrator to spawn a fresh-context judge that re-checks **every** criterion each iteration. Nothing checks that the spawn happened. | [`judge-protocol.md`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/workflows/ralph/resources/judge-protocol.md) |
558
+ | **Event log** | In an OMA session, gate passes, gate failures, and decisions append one JSON line each to the session's `events.jsonl`. | [`state-core.ts`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/hooks/core/state-core.ts) · [`event-spec.md`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/skills/_shared/runtime/event-spec.md) |
559
+ | **Per-agent checks** | `oma verify agent <type>` runs Scope Check, Charter Preflight, Hardcoded Secrets, TODO/FIXME Comments, Declared outputs, and TDD Evidence, plus per-type checks such as TypeScript, Any Types, SQL Injection, and tests. | `oma verify agent --help` |
187
560
 
188
- [OMA for Orca](https://github.com/first-fluke/oh-my-agent/blob/main/integrations/orca/README.md) adds a sidebar panel and command-palette
189
- actions for project setup, review, debugging, verification, and local results.
190
- It uses your existing Orca agent terminal and project OMA installation. Requires
191
- Orca 1.4.197+ with experimental plugins enabled.
561
+ > **No session, no trail.** The Stop hook records gate events under the OMA session opened when the persistent workflow started. Event writes are best-effort. If that session could not be created (stderr shows `[oma] L1 session activation failed`), a failing gate still blocks the stop, but no `gate.failed` line is written. Before you rely on the trail, or demo it, check that `oma state list` shows an active session; `oma state get <sid>` then shows its events.
192
562
 
193
- ### DeepSeek Harness
563
+ <details>
564
+ <summary>Limits, details, and how the Stop hook decides</summary>
194
565
 
195
- [OMA for DeepSeek Harness](https://github.com/first-fluke/oh-my-agent/blob/main/integrations/dsh/README.md) connects project OMA checks
196
- to DSH tool execution and turn completion through a Cordis plugin. DSH discovers
197
- the existing `.agents/skills` directly. The plugin ships executable JavaScript
198
- and requires no build. See the integration guide for installation, tested versions,
199
- and the supported hook events.
566
+ **Limits to know:**
200
567
 
201
- ## How It Works
568
+ - The Stop gate applies only to the persistent workflows (`/orchestrate`, `/work`, `/ultrawork`, `/ralph`). Without `oma goal set --gate`, it only re-prompts the agent to continue. `/ultrawork` tells the agent to set a gate when the project has a cheap check, but nothing enforces it. Run `oma goal set --gate test` yourself if you want to be sure; the other persistent workflows never set one.
569
+ - Only the `typecheck`, `test`, and `lint` keywords are accepted, and they run the package.json script of that name. No package.json, or no script with that name, means the gate is not run. Non-JS projects need a package.json wrapper script.
570
+ - The block is released and logged as failed after 5 reinforcements, after 2 hours, or when `--budget-minutes` runs out, so a permanently red gate cannot trap you.
571
+ - Budgets: `session.quota_cap` caps tokens, spawn count, and per-vendor tokens; the orchestrator refuses the next spawn when a dimension is exceeded.
202
572
 
203
- Just chat. Describe what you want and oh-my-agent figures out which agents to use.
573
+ **Artifact gate.** A missing artifact means the phase did not run, whatever the narration says. The refactor check also passes as `skip-recorded` when the session log records a REFINE skip reason.
204
574
 
205
- ```
206
- You: "Build a TODO app with user authentication"
207
- → PM plans the work
208
- → Backend builds auth API
209
- → Frontend builds React UI
210
- → DB designs schema
211
- → QA reviews everything
212
- → Done: coordinated, reviewed code
575
+ **Prompted judge.** The `/ralph` workflow prompt tells the orchestrator to spawn the judge as a separate agent with fresh context, briefed on the criteria only (never on what the implementer claims it fixed), and to re-verify **every** criterion each iteration, including earlier PASSes, because fixing C2 is how C1 silently regresses. Nothing checks that the spawn happened: `oma ralph verify` gates the EXEC artifacts, not the judge, and a runtime that cannot spawn subagents is told to judge inline and record `ralph.judge-inline-fallback`. `/ralph` stops after 5 iterations with a partial report.
576
+
577
+ **Event log.** Find the session with `oma state list` and read it with `oma state get <sid>`. Each event is stamped with vendor and runtime session id. The file's location depends on `OMA_HOME`, `OMA_STATE_HOME`, `OMA_PROFILE`, and older project-local session folders, so don't hard-code it.
578
+
579
+ **Per-agent checks.** Types: `backend`, `frontend`, `mobile`, `qa`, `debug`, `pm`. The command exits 1 when any check fails; TODO/FIXME Comments and Inline Styles only warn.
580
+
581
+ - `backend`: `<Language> Syntax`, `SQL Injection` (raw SQL patterns), and `<Language> Tests`, from the commands in `stack/stack.yaml`. Without that file (generate it with `/stack-set`) they are skipped.
582
+ - `frontend`: the `stack/stack.yaml` syntax and test commands (under `oma-frontend`, or `angular-developer` when that skill is installed), or TypeScript (`tsc --noEmit`) and Frontend Tests (Vitest). Inline Styles and Any Types always run.
583
+ - `mobile`: the `stack/stack.yaml` syntax and test commands, or Flutter/Dart Analysis and Flutter Tests.
584
+ - `debug`: Python Tests (pytest through uv) or Frontend Tests (Vitest).
585
+ - `pm`: PM Plan (the plan file is valid JSON).
586
+ - `qa`: no mechanical checks.
587
+
588
+ ```mermaid
589
+ flowchart TD
590
+ S[Agent tries to stop] --> P{Persistent workflow active?}
591
+ P -- no --> A[Stop allowed]
592
+ P -- yes --> D{User or agent said workflow done?}
593
+ D -- yes --> A
594
+ D -- no --> R{Budget spent, state older than 2 h, or 5 blocks reached?}
595
+ R -- yes --> F[Stop allowed, logged as gate.failed]
596
+ R -- no --> G{Gate set and package.json script exists?}
597
+ G -- no --> B1[Blocked: workflow still active]
598
+ G -- yes --> X{Script exits 0 within 25 s?}
599
+ X -- yes --> OK[Stop allowed, logged as gate.passed]
600
+ X -- no --> B2[Blocked with output tail, logged as gate.failed]
213
601
  ```
214
602
 
215
- Or use slash commands for structured workflows:
603
+ </details>
216
604
 
217
- | Step | Command | What It Does |
218
- |------|---------|-------------|
219
- | 0 | `/deepinit` | Maps your existing codebase into AGENTS.md, ARCHITECTURE.md, and docs |
220
- | 1 | `/brainstorm` | Explores ideas with you before you commit to building |
221
- | 2 | `/architecture` | Weighs your design tradeoffs and draws clean module boundaries |
222
- | 2 | `/design` | Builds your design system with tokens, accessibility, and responsive layouts |
223
- | 2 | `/plan` | Breaks your feature down into prioritized tasks |
224
- | 3 | `/work` | Builds your feature step by step across multiple agents |
225
- | 3 | `/orchestrate` | Runs multiple agents in parallel to build your feature faster |
226
- | 3 | `/ultrawork` | Builds your feature through five gated quality phases; every review runs in a fresh, isolated reviewer session (cross-context review) |
227
- | 3 | `/ralph` | Repeats `/ultrawork` until its judge passes every criterion |
228
- | 4 | `/review` | Reviews your code for security, performance, and accessibility issues |
229
- | 4 | `/security` | Scans security targets, validates findings, and applies CI gates |
230
- | 5 | `/debug` | Finds the root cause, fixes the bug, and writes a regression test |
231
- | 5 | `/docs` | Checks your docs for broken references and patches the ones your code changes touched |
232
- | 6 | `/scm` | Manages your branches, merges, and Conventional Commits |
233
- | - | `/schedule` | Schedules an agent job to run on a recurring interval |
605
+ ## FAQ
234
606
 
235
- **Auto-detection**: You don't even need slash commands — keywords like "architecture", "plan", "review", and "debug" in your message (in 11 languages!) auto-activate the right workflow. Detection accuracy is measured, not assumed: `oma verify triggers` scores the detector against a labeled English and Korean prompt corpus, and CI fails if false fires exceed 10% or missed fires exceed 20% (re-measured 2026-10-13: **0% missed-fire**, 5.3% false-fire).
607
+ <details>
608
+ <summary><strong>Do I need every skill?</strong></summary>
236
609
 
237
- ### Per-Agent Models
610
+ No. See [Skill presets](#install); `All` is the safe default.
238
611
 
239
- Set `model_preset` in `.agents/oma-config.yaml` to choose which AI models each agent uses:
612
+ </details>
240
613
 
241
- ```yaml
242
- language: en
243
- model_preset: mixed # antigravity | claude | codex | cursor | kiro | mixed | qwen
614
+ <details>
615
+ <summary><strong>How do I know it is working?</strong></summary>
244
616
 
245
- # Optional per-agent overrides
246
- agents:
247
- backend: { model: openai/gpt-5.5, effort: high }
248
- ```
617
+ `oma doctor` shows installed skills and warns when hooks can't find `oma`. During a persistent workflow, `oma state list` shows the active session and `oma state get <sid>` shows its gate events.
249
618
 
250
- - `oma doctor --profile` — prints the per-role resolved model matrix
251
- - Full guide: [`web/docs/guide/per-agent-models.md`](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/guide/per-agent-models.md)
619
+ </details>
252
620
 
253
- ## Verification, Not Narration
621
+ <details>
622
+ <summary><strong>Does it cost more tokens?</strong></summary>
254
623
 
255
- Every mechanism below except the prompted judge is mechanical: a command exits 0 or it doesn't, a file is on disk or it isn't. None of those asks an LLM whether the work "looks correct."
624
+ Usually, yes. Skills load only when a task needs them, but multi-agent workflows and fresh-context reviews spend more. In the [one-prompt benchmark](https://github.com/first-fluke/oh-my-agent/blob/main/benchmarks/README.md), oma cost 1.7x plain Claude Code.
256
625
 
257
- | Mechanism | What it mechanically checks | Where it lives |
258
- |-----------|------------------------------|----------------|
259
- | **Stop-hook gate** | Blocks session termination while a persistent workflow is active, and runs the configured gate script before allowing a stop. Only `typecheck`, `test`, and `lint` are executable — an agent that writes anything else into the state file gets it ignored, never run. Capped at 5 reinforcements so a permanently red gate can't trap you. | [`.agents/hooks/core/persistent-mode.ts`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/hooks/core/persistent-mode.ts) |
260
- | **Anti-Circumvention Gate** | `oma ralph verify --json` checks four artifacts a shortcut can't fake: ultrawork's phase records, the plan JSON, a **distinct QA agent's** result file, and a **distinct refactor agent's** result file. Missing artifacts mean the phase did not run, whatever the narration says. | [`.agents/workflows/ralph.md`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/workflows/ralph.md) |
261
- | **Prompted judge** | Not mechanical: the `/ralph` workflow prompt tells the orchestrator to spawn the judge as a separate agent with fresh context, briefed on the criteria only — never on what the implementer claims it fixed — and to re-verify **every** criterion each iteration, including prior PASSes, because fixing C2 is how C1 silently regresses. Nothing checks that the spawn happened: `oma ralph verify` gates the EXEC artifacts, not the judge, and a runtime that cannot spawn subagents is told to judge inline and record `ralph.judge-inline-fallback`. | [`judge-protocol.md`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/workflows/ralph/resources/judge-protocol.md) |
262
- | **Event-sourced state** | In an OMA session, every gate pass, gate failure, and decision appends one JSON line to the session's `events.jsonl`, stamped with vendor and runtime session id. Append-only, cross-vendor, auditable after the run. Find the session with `oma state list` and read its events with `oma state get <sid>`; the file's location depends on `OMA_HOME`, `OMA_STATE_HOME`, `OMA_PROFILE`, and older project-local session folders, so don't hard-code it. | [`state-core.ts`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/hooks/core/state-core.ts) · [`event-spec.md`](https://github.com/first-fluke/oh-my-agent/blob/main/.agents/skills/_shared/runtime/event-spec.md) |
263
- | **Per-agent check battery** | `oma verify <agent>` runs a shared core (scope violation, charter alignment, hardcoded secrets, TODO scan, declared outputs) plus type-specific checks (TypeScript strict, tests, raw SQL, Flutter analyze, inline styles). | `oma verify <agent>` |
264
- | **Skill eval harness** | `oma skill eval` measures utility lift on held-out tasks — treatment vs. baseline — instead of assuming a skill helps. `oma skill optimize` keeps only edits that improve the measured lift. | [skill-eval guide](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/guide/skill-eval.md) |
626
+ </details>
265
627
 
266
- > **No session, no trail.** The Stop hook records gate events under the OMA session opened when the persistent workflow started. If that session could not be created (stderr shows `[oma] L1 session activation failed`), a failing gate still blocks the stop, but no `gate.failed` line is written. Before you rely on the trail, or demo it, check that `oma state list` shows an active session.
628
+ <details>
629
+ <summary><strong>The Stop hook keeps blocking. How do I get out?</strong></summary>
267
630
 
268
- Budgets are enforced the same way. `session.quota_cap` caps tokens, spawn count, and per-vendor spend; the orchestrator refuses the next spawn when a dimension is exceeded. When the wall-clock budget runs out, the Stop hook stops honestly with partial status recorded on the event log, rather than pretending completion.
631
+ Say "workflow done" (or "workflow complete" / "workflow finished", or the equivalent in the other supported languages), or delete `.agents/state/<workflow>-state-<sid>.json`. If you do neither, it releases on its own after 5 blocks or 2 hours.
269
632
 
270
- ### Control Boundary
633
+ </details>
271
634
 
272
- oh-my-agent leaves open-ended planning and next-action selection to the host LLM. It does not replace that judgment with a universal workflow graph or policy engine. Instead, it externalizes the invariants that must hold regardless of the model: tool guardrails, permissions, budgets, retry and stop limits, durable events, and mechanically verified completion. Structured events record decisions and gate outcomes; they do not act as a second planner.
635
+ <details>
636
+ <summary><strong>How do I update or uninstall?</strong></summary>
273
637
 
274
- Deterministic SLM execution is therefore a separate, optional product direction rather than missing infrastructure in the current harness.
638
+ `oma update` refreshes skills, workflows, and hooks and keeps your config (`--with-new-skills` adds skills new in the release; `oma update mcp` re-chooses the browser MCP). `oma uninstall --dry-run` shows what would be removed; `oma uninstall` removes it and keeps `oma-config.yaml`, `mcp.json`, and skills you wrote. More fixes: [Troubleshooting](https://first-fluke.github.io/oh-my-agent/docs/guide/troubleshooting/).
275
639
 
276
- ## Why oh-my-agent?
640
+ </details>
277
641
 
278
- - **Role-based** — agents modeled like a real engineering team, not a pile of prompts
279
- - **Conditional context** — dispatch loads the owning skill and defers supporting references until the task needs them. File-size scenarios and runtime loading are reported separately ([measurement guidance](https://github.com/first-fluke/oh-my-agent/blob/main/web/docs/core-concepts/skills.md#token-savings-math)).
280
- - **Recoverable** — after 2 failed retries, `orchestrate` spawns hypothesis variants in parallel and keeps the highest-scoring result instead of retrying a wrong approach forever
281
- - **Monorepo-aware** — `detectWorkspace` reads pnpm / nx / turbo / lerna and routes each agent to its workspace
282
- - **Multi-vendor** — mix Antigravity, Claude, Codex, Cursor, Kiro, and Qwen per agent type
283
- - **Observable** — terminal and web dashboards for real-time monitoring
642
+ <details>
643
+ <summary><strong>What does oh-my-agent leave to the model?</strong></summary>
284
644
 
285
- ## Architecture
645
+ Planning and choosing the next step stay with your agent's model; oma has no fixed workflow graph. What oma enforces outside the model: tool guardrails (secret and search guards), budgets, retry and stop limits, an event log, and, when you set a gate, a stop that waits for your own checks to pass.
286
646
 
287
- ```mermaid
288
- flowchart TD
289
- subgraph Workflows["Workflows"]
290
- direction TB
291
- W0["/brainstorm"]
292
- W1["/work"]
293
- W1b["/ultrawork"]
294
- W2["/orchestrate"]
295
- W3["/architecture"]
296
- W4["/plan"]
297
- W5["/review"]
298
- W6["/debug"]
299
- W7["/deepinit"]
300
- W8["/design"]
301
- end
302
-
303
- subgraph Orchestration["Orchestration"]
304
- direction TB
305
- PM[oma-pm]
306
- ORC[oma-orchestration]
307
- end
308
-
309
- subgraph Domain["Domain Agents"]
310
- direction TB
311
- ARC[oma-architecture]
312
- FE[oma-frontend]
313
- BE[oma-backend]
314
- DB[oma-db]
315
- MB[oma-mobile]
316
- DES[oma-design]
317
- TF[oma-tf-infra]
318
- end
319
-
320
- subgraph Quality["Quality"]
321
- direction TB
322
- QA[oma-qa]
323
- DBG[oma-debug]
324
- end
325
-
326
- Workflows --> Orchestration
327
- Orchestration --> Domain
328
- Domain --> Quality
329
- Quality --> SCM([oma-scm])
330
- ```
647
+ </details>
331
648
 
332
649
  ## Learn More
333
650
 
334
- - **[Detailed Documentation](https://github.com/first-fluke/oh-my-agent/blob/main/docs/AGENTS_SPEC.md)** — Full technical spec and architecture
335
- - **[Supported Agents](https://github.com/first-fluke/oh-my-agent/blob/main/docs/SUPPORTED_AGENTS.md)** — Agent support matrix across IDEs
336
- - **[Capability Providers](https://github.com/first-fluke/oh-my-agent/blob/main/docs/capability-providers.md)** — Experimental Gortex and Honcho configuration, routing, and limits
337
- - **[Skill Compatibility Matrix](https://github.com/first-fluke/oh-my-agent/blob/main/docs/skills-matrix.md)** — Check native skill content, references, and response contracts in Claude and Codex
338
- - **[Benchmark Report](https://github.com/first-fluke/oh-my-agent/blob/main/benchmarks/README.md)** — Method, scores, screenshots, and caveats
339
- - **[Web Docs](https://first-fluke.github.io/oh-my-agent/)** — Guides, tutorials, and CLI reference
651
+ - **[Docs site](https://first-fluke.github.io/oh-my-agent/)**: guides, tutorials, and CLI reference. Start with [Quick Start](https://first-fluke.github.io/oh-my-agent/docs/getting-started/quick-start/) and [Installation](https://first-fluke.github.io/oh-my-agent/docs/getting-started/installation/).
652
+ - **[Why oh-my-agent](https://first-fluke.github.io/oh-my-agent/docs/getting-started/why-oh-my-agent/)**: when to choose it and the trade-offs
653
+ - **[Benchmark Report](https://github.com/first-fluke/oh-my-agent/blob/main/benchmarks/README.md)**: how it compares with superpowers, ECC, and oh-my-claudecode on one prompt, with method, scores, screenshots, and caveats
654
+ - **[Supported Agents](https://github.com/first-fluke/oh-my-agent/blob/main/docs/SUPPORTED_AGENTS.md)**: support matrix across runtimes
655
+ - **[Detailed Documentation](https://github.com/first-fluke/oh-my-agent/blob/main/docs/AGENTS_SPEC.md)**: technical spec and architecture
656
+ - **[Capability Providers](https://github.com/first-fluke/oh-my-agent/blob/main/docs/capability-providers.md)**: experimental Gortex and Honcho configuration, routing, and limits
657
+ - **[Skill Compatibility Matrix](https://github.com/first-fluke/oh-my-agent/blob/main/docs/skills-matrix.md)**: native skill content, references, and response contracts in Claude and Codex
340
658
 
341
659
  > **Like this project?** Give it a star!
342
660
  >
@@ -352,6 +670,9 @@ flowchart TD
352
670
 
353
671
  ## References
354
672
 
673
+ <details>
674
+ <summary>Research this builds on (7 papers)</summary>
675
+
355
676
  - Li, X., Liu, Y., Chen, W., You, B., Di, Z., He, Y., Zheng, S., Choe, K. W., Sun, J., Wang, S., Tao, C., Li, B., Zhao, X., Geng, H., Wu, X., Zhou, J., Chen, X., Xing, H., Li, Y., … Song, D. (2026). *SkillsBench: Benchmarking how well agent skills work across diverse tasks* (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2602.12670
356
677
  - Yu, G., & Wang, X. (2026). *Knows: Agent-native structured research representations* (Version 1) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.17309
357
678
  - Liang, Q., Wang, H., Liang, Z., & Liu, Y. (2026). *From skill text to skill structure: The scheduling-structural-logical representation for agent skills* (Version 4) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2604.24026
@@ -360,6 +681,7 @@ flowchart TD
360
681
  - Huang, Z., Xu, J., Yang, Y., Gong, Z., Yang, Q., Tian, M., Wang, X., Lv, C., Gao, X., Dai, Q., Liu, B., Qiu, K., Yang, X., Chen, D., Zheng, X., & Luo, C. (2026). *From raw experience to skill consumption: A systematic study of model-generated agent skills* [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2605.23899
361
682
  - Hong, D. B., Imani, A., & Ahmed, I. (2026). *From anatomy to smells: An empirical study of SKILL.md in agent skills* (Version 2) [Preprint]. arXiv. https://doi.org/10.48550/arXiv.2607.01456
362
683
 
684
+ </details>
363
685
 
364
686
  ## License
365
687