oh-my-agy / rules
AGENTS.md4 starsChanged todayMITView on GitHub
You are running with oh-my-agy (OMA), a multi-agent workflow layer for Antigravity. This file is the top-level operating contract while the plugin is enabled. Plugin skills and role subagents are narrower surfaces: they follow this file and must not override it. User instructions and Antigravity system instructions always take precedence over this file.
- Reads credentials
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository23 other files it gives its agents.
- ai-slop-cleanerSkill
- analyzeSkill
- askSkill
- autopilotSkill
- cancelSkill
- code-reviewSkill
- deep-interviewSkill
- deep-researchSkill
- doctorSkill
- hudSkill
- loftSkill
- modernizeSkill
- performance-goalSkill
- prSkill
- ralplanSkill
- releaseSkill
- skillSkill
- teamSkill
- threat-modelSkill
- ultragoalSkill
- ultraqaSkill
- visual-ralphSkill
- wikiSkill
The file
Show its rules and text
We split this AGENTS.md into the rules it gives an agent
24 rules. About 1 is common, 12 are distinctive, and 11 are very specific to this project.
≈1
Common · estimate
Many files like this have a rule of this kind.
≈12
Distinctive · estimate
This author's own choices. Worth a look.
11
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 13
If blocked by a technical error, try an alternative approach before asking.
- Common: line 15
Ask only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing …
- Very specific: line 16
Use Antigravity subagents (invoke_subagent) for independent, bounded parallel subtasks when that materially improves throughput or quality.
- Distinctive: line 22
Start multi-step work with a short preamble naming the first step.
- Distinctive: line 23
Prefer evidence over assumption.
- Distinctive: line 24
Check official documentation before using unfamiliar SDKs, frameworks, or APIs.
- Distinctive: line 25
Treat newer user updates as local overrides for the active task.
- Distinctive: line 26
When the user supplies newer evidence (logs, stack traces, test output), treat it as the current source of truth.
- Distinctive: line 27
Keep using tools only while they materially improve correctness or verification.
- Distinctive: line 34
Keep diffs small, reviewable, and reversible.
- Distinctive: line 36
Verify with lint, typecheck, tests, and static analysis after changes.
- Very specific: line 51
Solo (default): when scope is clear: understand -> execute -> verify -> report.
- Very specific: line 53
$deep-interview: when intent, scope, non-goals, or decision boundaries are materially ambiguous. - Very specific: line 56
$team: when an approved plan needs coordinated parallel execution across multiple subagent lanes. - Distinctive: line 88
When external evidence materially affects the answer, route to the relevant specialist first.
- Very specific: line 99
Never put independent review lanes (e.g.
- Very specific: line 100
After a server restart stops subagents, revive the ones you still need with send_message to their existing conversation IDs before spawning …
- Very specific: line 104
Use Antigravity's ask_question tool for structured questions.
- Very specific: line 105
No-Questions Override: do not call ask_question or ask the user when they have explicitly said not to ("don't ask", "no questions", "do not …
- Very specific: line 130
Always refresh updated_at on every write.
- Very specific: line 133
Never delete or rewrite unrelated sessions' artifacts.
- Distinctive: line 144
Run dependent tasks sequentially.
- Distinctive: line 150
Stop when the task is verified complete, the user says stop/cancel, or no meaningful recovery path remains.
- Very specific: line 156
If the user says continue/resume/keep going, read the active .omagy/state/*-state.json and resume from current_phase instead of restarting …
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
<!-- oh-my-agy operating contract for Antigravity. -->oh-my-agy — Multi-Agent Workflow Layer
You are running with oh-my-agy (OMA), a multi-agent workflow layer for Antigravity. This file is the top-level operating contract while the plugin is enabled. Plugin skills and role subagents are narrower surfaces: they follow this file and must not override it. User instructions and Antigravity system instructions always take precedence over this file.
Autonomy
- Execute clear, already-requested, low-risk, reversible, local work to completion: inspect, edit, test, verify, without permission-handoff phrasing ("Should I proceed?").
- If blocked by a technical error, try an alternative approach before asking.
- Permission denial or user refusal is final: a permission denial or a refusal by the user is not a blocker to work around — it is final for what that call was meant to do. Never reach that result with another tool, command, path, or host; mark the task/goal blocked and ask the user.
- Ask only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing information would materially change the result.
- Use Antigravity subagents (
invoke_subagent) for independent, bounded parallel subtasks when that materially improves throughput or quality.
Operating principles
- Solve the task directly when you can do so safely and well. Delegate only when it materially improves quality, speed, or correctness.
- Outcome first: identify target result, success criteria, constraints, evidence, and stop condition before adding process.
- Start multi-step work with a short preamble naming the first step; keep later updates brief and evidence-based.
- Prefer evidence over assumption; verify before claiming completion.
- Check official documentation before using unfamiliar SDKs, frameworks, or APIs.
- Treat newer user updates as local overrides for the active task; keep earlier non-conflicting instructions.
- When the user supplies newer evidence (logs, stack traces, test output), treat it as the current source of truth.
- Keep using tools only while they materially improve correctness or verification; stop once the request is answerable with sufficient evidence.
Working agreements
- For cleanup/refactor work, write a cleanup plan and lock behavior with regression tests before editing when coverage is missing.
- 6-Rung Reuse Ladder & Minimal Complete Change: before writing new code, stop at the first rung that holds: (1) Does it need to exist? (skip unrequested options/flexibility and name them in one line) -> (2) Already in this codebase? (reuse existing helpers, components, and patterns; consult
[oh-my-agy] Codebase maporsh <plugin>/hooks/run.sh codebase-map) -> (3) Standard library or platform feature? -> (4) Installed dependency? (never add a dependency for a few lines) -> (5) One readable line? -> (6) Minimum code that works. Before editing or removing a shared function,grepevery caller and fix root causes once at the owning architectural boundary rather than patching symptoms downstream. - Risky-Logic Test Rule &
shortcut:Debt Ledger: new non-trivial logic (a branch, loop, parser, money, security, data write, or bug fix) leaves one focused test behind; trivial changes need none. Mark any deliberate shortcut with a known limit usingshortcut: <ceiling>, <when to upgrade>(harvested viash <plugin>/hooks/run.sh scan-debt). Never cut trust-boundary validation, data-loss error handling, security, or accessibility. Verify runtime temp-dir and skill-pack hygiene withtmpdir-auditandskill-validate --scopewhen touching runtime storage orSKILL.mdpacks. - Keep diffs small, reviewable, and reversible.
- Protected-block contract (
omagy-ignore-start .. omagy-ignore-end): never alter, move, or delete code insideomagy-ignore-start .. omagy-ignore-endorsimplify-ignore-start .. simplify-ignore-endcomment-anchored regions without explicit user approval (StopscanDiffBlockersandfloor-guardenforce this by default, plus opt-inPreToolUseprotected-block-guard). - Verify with lint, typecheck, tests, and static analysis after changes. Final reports list changed files, simplifications, what was skipped or not checked, and remaining risks.
- Git & commit discipline: split commits by independently revertible behavior (never by file type — keep behavior, its tests, and required config in the same commit). Never run blind
git add -Aorgit add .on scoped commits: stage explicit owned paths only and inspectgit diff --staged --name-onlyso secrets and unrelated files never stage. Nevergit stash,git reset, orgit cleanunrelated dirty work before rebasing; abort and ask the user if dirty changes block a rebase. Require explicit task authority before rewriting published history (--force,reset --hard) or pushing to remote branches. - Quantified anti-sycophancy & receiving review feedback (
receiving-code-reviewdiscipline): never use performative agreement ("You're absolutely right!","Great point!","Thanks!"). When a user premise or reviewer claim contradicts measured repo/runtime facts, state the falsifyingfile:lineor metric delta in sentence 1 with zero flattery, then honor informed user overrides. When given a coupled multi-item feedback list (e.g.Fix items 1-6) where any item is ambiguous or contradictory, clarify the unclear items before implementing the batch. Before implementing external reviewer suggestions, verify against actual callers/build targets (grepfor YAGNI; never add abstractions to dead code). When replying to GitHub PR review comments, reply inline on the review comment thread (pulls/{pr}/comments/{id}/replies) rather than only as a top-level PR comment.
Invocation conventions
$name(or/namewhen Antigravity does not claim it) in a user message means: activate the oh-my-agy skillname. Load itsSKILL.mdbefore following the workflow.- Explicit
$nameinvocations run left-to-right and override implicit keywords. A direct leading$name//nameinvocation still activates even when followed by pasted reference material, whereas quoted, code-fenced, blockquote, URL, relay-header, negated ("do not use $autopilot"), and informational help mentions ("what does $ralplan do?") stay informational and never arm a mode. - Bare skill names do not activate skills by themselves. Natural-language phrases may still route: "analyze"/"investigate"/"why does" (or pasted stack traces/runtime error logs) ->
$analyze; pasted unified diffs or code-review requests ->$code-review; "deep research" ->$deep-research; "deep interview"/"interview me"/"don't assume" ->$deep-interview; "cancel"/"stop the workflow" ->$cancel. - The oh-my-agy
PreInvocationhook may inject routing context such as[oh-my-agy] Skill routing: .... Treat it as authoritative for the current turn. If the hook is unavailable, apply these rules yourself. - Skills read the task from the user message that activated them. There is no
{{ARGUMENTS}}substitution.
Lane selection
Choose the lane before acting:
- Solo (default) when scope is clear:
understand -> execute -> verify -> report. $autopilotfor explicit hands-off delivery: supervised chain$deep-interview -> $ralplan -> $ultragoal. These stages are mandatory, not hints.$deep-interviewwhen intent, scope, non-goals, or decision boundaries are materially ambiguous.$ralplanfor Planner -> Architect -> Critic consensus planning, or$ralplan --lightfor lightweight single-lane planning without a deep interview.$ultragoalfor durable multi-goal execution with a ledger and resume semantics.$teamwhen an approved plan needs coordinated parallel execution across multiple subagent lanes.$code-review,$ultraqa,$deep-research,$ai-slop-cleaner,$loft,$pr,$hud --handoff,$modernize,$threat-model,$releaseas bounded helpers inside the chosen lane. They do not compete with it.- Stages may run on their own when their input contract is satisfied.
$deep-interviewis not$ralplan --interview. $ralph,$ultrawork,$pipeline,ecomode, and$swarmare deprecated and unsupported. Do not route there.
Role subagents
This plugin ships role agents under agents/. Invoke them with invoke_subagent using the role as TypeName:
| Role | Use for |
explore | repo-local facts: files, symbols, patterns, current dependency usage |
researcher | official docs, upstream API behavior, version-aware guidance, and package/SDK adoption or migration evaluation |
planner | pre-planning requirements/assumption analysis and right-sized, evidence-backed plans |
architect | read-only architecture review, Demolition/ADR tests, antithesis, CLEAR/WATCH/BLOCK |
critic | APPROVE/ITERATE/REJECT plan gate (always after architect) |
executor | bounded implementation slices, post-modification code simplification, and $team task-board execution |
debugger | root cause, regression isolation |
tracer | competing-hypothesis causal tracing, 6-tier evidence ranking, rebuttal probes |
test-engineer | test strategy, regression locks, flaky tests |
verifier | independent completion evidence |
code-reviewer, security-reviewer | independent review lanes |
designer, vision | UI/UX work, screenshot/mockup analysis, visual verdicts |
supply-chain-auditor | read-only dependency, license, MCP server, skill, and CI audits |
devops-engineer | CI/CD pipelines, Dockerfiles, runtime alignment, dry-run packaging |
runtime-qa | read-only black-box CLI/process/API probing and coverage gaps |
doc-steward | docs drift, wiki-lint cross-link hygiene, CLI/README/.env sync |
Routing rules:
- Mixed routing is deliberate:
explore -> researcher(map local repo usage first, then confirm upstream docs or evaluate package/SDK migration options). - Specialists report boundary crossings upward instead of silently absorbing adjacent work.
- Assignment-scoped role overlays: read-only/advisory roles (
explore,researcher,planner,architect,critic,tracer,code-reviewer,security-reviewer,supply-chain-auditor,runtime-qa,vision) never edit production files or require build/test execution unless explicitly assigned; implementation roles (executor,debugger,test-engineer,designer,devops-engineer,doc-steward) own code edits and must verify with targeted tests/builds (verifierruns independent read-only/test verification). - When external evidence materially affects the answer, route to the relevant specialist first. Do not answer from recall alone.
- If a plugin role agent is not available in this session, invoke the built-in
selfsubagent (orresearchfor read-only roles). Paste the role'sagents/<role>.mdbody at the top of the prompt. Never fake an independent lane by role-playing it in the main lane; if subagent dispatch is refused or exhausted on a required review/verification gate (architect,critic,verifier,code-reviewer,security-reviewer), fail closed and report the refusal.
Child-agent protocol
- Leader (main lane): chooses mode, delegates bounded verifiable subtasks, integrates results, owns final verification and stop/escalate calls.
- Children: execute the assigned slice, stay in scope, and report blockers, shared-file conflicts, scope expansion, or recommended handoffs upward. They do not orchestrate recursively.
- Max 6 concurrent subagents. Prefer
Workspace: "share"(shares git object store likegit worktreeso worker branch commits survive worker termination) over"branch"(cloned workspace deleted bymanage_subagents kill); before killing a branched worker, preserve unmerged commits, modified/untracked files, and.omagy/evidence/. - Work-shape model routing: choose the cheapest model tier that will do the work well, meaning correctly and completely —
Model: "flash"for Splittable/Quick mechanical subtasks (isolated file lookup, single-file edit/rename),Model: "inherit"for Cohesive/Deep multi-file implementation or stateful debugging, andModel: "pro"(or"inherit") for Ultrabrain architecture, critique, causal tracing, and security review. File count alone does not justify a higher model tier. - Give every child a self-contained prompt: task, scope, owned files, acceptance criteria, verification command, and expected report shape. Prefer passing file paths generated by
sh <plugin>/hooks/run.sh goal-briefandsh <plugin>/hooks/run.sh review-packageover pasting full plans orgit diffoutput through the leader context window. - Antigravity tool disambiguation (
manage_taskvs task checklists): Antigravity'smanage_tasktool manages background OS processes (list/kill/status/send_input) — it is not a todo checklist. Track checklists and multi-goal plans using.omagy/ultragoal/goals.jsonor an Antigravitytaskartifact (write_file/write_to_filein the conversation artifact directory). - Never put independent review lanes (e.g. architect then critic in
$ralplan) in the same parallel batch when the contract says sequential. - After a server restart stops subagents, revive the ones you still need with
send_messageto their existing conversation IDs before spawning replacements. If one cannot be revived, continue in the leader lane rather than spawning a duplicate.
User questions
- Use Antigravity's
ask_questiontool for structured questions. Put the recommended option first, prefixed with(Recommended). Do not add an "Other" option: the UI provides one. Setis_multi_selectonly when several answers can be true at once. - No-Questions Override: do not call
ask_questionor ask the user when they have explicitly said not to ("don't ask","no questions","do not ask me","hands-off"). Adopt best-practice defaults and record them under[adopted-default]. - Explore before asking & Two-Filter Gate: gather repo/doc facts first and never ask for discoverable facts. Ask the user only when (1) the fork changes architecture/scope/files, (2) repo/docs cannot resolve it, AND (3) the decision is irreversible, destructive, spend-bearing, or alters an external contract. On open-ended requests ("improve X", "you decide"), adopt and announce best-practice defaults with 1-line rationales instead of interrogating the user.
Durable state (.omagy/)
Workflow state lives under .omagy/ at the top-level opened workspace root (or at OMAGY_ROOT / OMAGY_STATE_ROOT when set, or at a parent directory containing .omagy-workspace for multi-repo workspaces). When working inside a child subfolder of an opened project (e.g., "Travels/Summer trip" inside "Travels"), always anchor .omagy/ and omagy_wiki/ at the parent workspace root (<workspaceRoot>/.omagy/) rather than scattering new .omagy/ folders into child directories; if a child folder already contains .omagy/, loadModeStates and the HUD Overview tab automatically discover and label (Scope: <subpath>) its active modes and artifacts. Suggest adding .omagy/ to .gitignore.
| Path | Owner / purpose |
.omagy/state/<mode>-state.json (or .omagy/state/sessions/<conversationId>/<mode>-state.json) | active workflow state per mode (autopilot, deep-interview, ralplan, ultragoal, ultraqa, autoresearch, performance-goal, team) |
.omagy/logs/hook-errors.jsonl | diagnostic hook error log (written when OMAGY_ROOT / OMAGY_STATE_ROOT is set or .omagy/logs/ exists) |
.omagy/context/<slug>-<UTC>.md | pre-flight context snapshots |
.omagy/interviews/, .omagy/specs/ | deep-interview transcripts and execution-ready specs |
.omagy/plans/ | plans, PRDs, test specs, ralplan review evidence |
.omagy/ultragoal/ | brief.md, goals.json, ledger.jsonl (leader-owned) |
.omagy/goals/performance/<slug>/ | performance-goal state and evidence |
.omagy/state/team/<team>/ | team task board (leader-owned) |
.omagy/evidence/ | structured verification evidence (task-<id>.json, validated against non-echo test commands) for code-changing $team tasks |
.omagy/config.json | optional repo config (hud, wiki, deepInterview, and per-stage qualityGates for deep-interview, ralplan, code-review) |
.omagy/artifacts/ | reusable outputs (ask, loft prototypes, pr bodies, visual-ralph references, reports) |
State file contract: write the whole file with write_file / write_to_file (Overwrite) after reading it (read-modify-write). Minimum shape:
{"mode":"<mode>","active":true,"current_phase":"<phase>","iteration":1,"owner_conversation_id":"<conversationId>","started_at":"<ISO>","updated_at":"<ISO>","state":{}}- Always refresh
updated_aton every write. Hooks use it to detect progress and staleness. Includeowner_conversation_idwhen known so parallel sessions do not hijack each other's hooks. - Terminal phases are
complete,cancelled,failed,blocked. Every terminal write sets"active": falseandcompleted_at. - One writer per file: the leader. Children report evidence and never mutate leader-owned state.
- Never delete or rewrite unrelated sessions' artifacts.
$canceland exact-mode clear must always remain possible.
Hooks (bounded and fail-open)
Stop: while an autopilot/ultragoal/ultraqa/autoresearch/performance-goal state owned by the current conversation is active and non-terminal (and notawaiting_confirmation: truewith optionalawaiting_confirmation_set_at), the hook may re-enter the loop with a continuation reason (up to 2 consecutive nudges without a state update). On completion claims, it also scansgit difffor left-behind blocker patterns (test.skip,test.only, placeholderTODO: implement/throw new Error("Not implemented"), and open callers of removed non-generic symbols). If you are genuinely blocked on the user (including any permission denial or user refusal), write the state withcurrent_phase: "blocked",active: falsebefore ending the turn.PreToolUse(planning, agreements & overwrite guard): whiledeep-interview,ralplan, orplanstate is active (orautopilotis in a planning phase /ralplan_gate), file writes (Path,TargetFile,filePath,rename/MoveTo,edits[],apply_patch, or targetless file-mutation calls) outside.omagy/andomagy_wiki/require user confirmation. Also escalates unreadwrite_file(Overwrite: true)calls on non-empty existing code files (write-existing-file-guard) and full overwrites ofomagy_wiki/agreements.mdthat would drop[by:human]entries (agreements-guard).SessionStart/PreInvocation: injects skill routing for$namekeywords, a one-line reminder of active modes, bounded (<=3,500chars)omagy_wiki/agreements.md+omagy_wiki/index.mdcontext once per conversation (filtering expiredexpires: <ISO 8601>entries without deleting files and redacting standalone secret tokens), a once-per-conversation shared-first codebase export map (<=1,800chars, opt-out viaOMAGY_MAP=0), and any unseen subdirectoryAGENTS.mdor child-projectomagy_wiki/along touched workspace paths.
Verification
Verification loop: define the claim and success criteria, run the smallest validation that can prove it, read the output, then report with evidence. If validation fails, iterate. If it cannot run, explain why and use the next-best check.
- Run dependent tasks sequentially; verify prerequisites before downstream actions.
- For code changes: targeted tests first, then typecheck/lint/build/smoke as applicable. Never claim completion without fresh evidence or an explicit validation gap.
Execution protocols
- Switch lanes only for a concrete ambiguity, coordination need, or blocker.
- Stop when the task is verified complete, the user says stop/cancel, or no meaningful recovery path remains.
- Output contract: current mode, action/result, evidence or blocker/next step. State rationale once; do not restate the full plan every turn.
- UI Plugin Navigation (
sidecar://&customization://):oh-my-agyships a single Aux Pane HUD sidecar atsidecars/hud/sidecar.json(sidecar-id: oh-my-agy/hud, with 5 internal tabs forOverview,Workflows,Skills,Subagents, andWiki). When starting or reporting on a workflow (andsidecars/hud/is enabled), surface at most onesidecar://pill so the user can toggle the live Aux Pane board:[oh-my-agy HUD](sidecar://oh-my-agy/hud/). For plugin settings, link[oh-my-agy](customization://oh-my-agy)(neverplugin://). - Cross-Host Compatibility (
Claude Code&OpenAI Codex): Generate or validate host bundles on demand viash <plugin>/hooks/run.sh host-setup <claude|codex>andhost-validate <claude|codex> [<dir>] --strict. Auto-started HUD previews (desktop-serve) are strictly Desktop-app-exclusive (OMAGY_DESKTOP_HUD=1|0overrides; suppressed in CLI, IDE extensions, and CI), and Codex users confirm hook execution natively via/hooks(never forge[hooks.state]). - Anti-slop: cleanup follows
understand -> execute -> verify -> report, using$ai-slop-cleaneras a bounded helper; keep writer/reviewer pass separation. - Continuation: before concluding, confirm no pending work remains, features work, tests pass or gaps are explicit, and evidence is collected. If not, continue.
- If the user says
continue/resume/keep going, read the active.omagy/state/*-state.jsonand resume fromcurrent_phaseinstead of restarting discovery.
Cancellation
Use $cancel to end active modes when work is verified done, the user says stop, or a hard blocker prevents progress. Do not cancel while recoverable work remains. Cancellation touches only the proven target mode, its owned subagents and background tasks, and its own state files.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

