agentleFS
YomudoglyYomudogly/oh-my-agy/rules/AGENTS.md

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

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
  1. Distinctive:

    If blocked by a technical error, try an alternative approach before asking.

    line 13
  2. Common:

    Ask only for destructive, irreversible, credential-gated, external-production, or materially scope-changing actions, or when missing …

    line 15
  3. Very specific:

    Use Antigravity subagents (invoke_subagent) for independent, bounded parallel subtasks when that materially improves throughput or quality.

    line 16
  4. Distinctive:

    Start multi-step work with a short preamble naming the first step.

    line 22
  5. Distinctive:

    Prefer evidence over assumption.

    line 23
  6. Distinctive:

    Check official documentation before using unfamiliar SDKs, frameworks, or APIs.

    line 24
  7. Distinctive:

    Treat newer user updates as local overrides for the active task.

    line 25
  8. Distinctive:

    When the user supplies newer evidence (logs, stack traces, test output), treat it as the current source of truth.

    line 26
  9. Distinctive:

    Keep using tools only while they materially improve correctness or verification.

    line 27
  10. Distinctive:

    Keep diffs small, reviewable, and reversible.

    line 34
  11. Distinctive:

    Verify with lint, typecheck, tests, and static analysis after changes.

    line 36
  12. Very specific:

    Solo (default): when scope is clear: understand -> execute -> verify -> report.

    line 51
  13. Very specific:

    $deep-interview: when intent, scope, non-goals, or decision boundaries are materially ambiguous.

    line 53
  14. Very specific:

    $team: when an approved plan needs coordinated parallel execution across multiple subagent lanes.

    line 56
  15. Distinctive:

    When external evidence materially affects the answer, route to the relevant specialist first.

    line 88
  16. Very specific:

    Never put independent review lanes (e.g.

    line 99
  17. Very specific:

    After a server restart stops subagents, revive the ones you still need with send_message to their existing conversation IDs before spawning …

    line 100
  18. Very specific:

    Use Antigravity's ask_question tool for structured questions.

    line 104
  19. Very specific:

    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 …

    line 105
  20. Very specific:

    Always refresh updated_at on every write.

    line 130
  21. Very specific:

    Never delete or rewrite unrelated sessions' artifacts.

    line 133
  22. Distinctive:

    Run dependent tasks sequentially.

    line 144
  23. Distinctive:

    Stop when the task is verified complete, the user says stop/cancel, or no meaningful recovery path remains.

    line 150
  24. Very specific:

    If the user says continue/resume/keep going, read the active .omagy/state/*-state.json and resume from current_phase instead of restarting …

    line 156

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
AGENTS.md
<!-- 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 map or sh <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, grep every 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 using shortcut: <ceiling>, <when to upgrade> (harvested via sh <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 with tmpdir-audit and skill-validate --scope when touching runtime storage or SKILL.md packs.
  • Keep diffs small, reviewable, and reversible.
  • Protected-block contract (omagy-ignore-start .. omagy-ignore-end): never alter, move, or delete code inside omagy-ignore-start .. omagy-ignore-end or simplify-ignore-start .. simplify-ignore-end comment-anchored regions without explicit user approval (Stop scanDiffBlockers and floor-guard enforce this by default, plus opt-in PreToolUse protected-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 -A or git add . on scoped commits: stage explicit owned paths only and inspect git diff --staged --name-only so secrets and unrelated files never stage. Never git stash, git reset, or git clean unrelated 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-review discipline): 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 falsifying file:line or 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 (grep for 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 /name when Antigravity does not claim it) in a user message means: activate the oh-my-agy skill name. Load its SKILL.md before following the workflow.
  • Explicit $name invocations run left-to-right and override implicit keywords. A direct leading $name / /name invocation 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 PreInvocation hook 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.
  • $autopilot for explicit hands-off delivery: supervised chain $deep-interview -> $ralplan -> $ultragoal. These stages are mandatory, not hints.
  • $deep-interview when intent, scope, non-goals, or decision boundaries are materially ambiguous.
  • $ralplan for Planner -> Architect -> Critic consensus planning, or $ralplan --light for lightweight single-lane planning without a deep interview.
  • $ultragoal for durable multi-goal execution with a ledger and resume semantics.
  • $team when 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, $release as 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-interview is not $ralplan --interview.
  • $ralph, $ultrawork, $pipeline, ecomode, and $swarm are 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:

RoleUse for
explorerepo-local facts: files, symbols, patterns, current dependency usage
researcherofficial docs, upstream API behavior, version-aware guidance, and package/SDK adoption or migration evaluation
plannerpre-planning requirements/assumption analysis and right-sized, evidence-backed plans
architectread-only architecture review, Demolition/ADR tests, antithesis, CLEAR/WATCH/BLOCK
criticAPPROVE/ITERATE/REJECT plan gate (always after architect)
executorbounded implementation slices, post-modification code simplification, and $team task-board execution
debuggerroot cause, regression isolation
tracercompeting-hypothesis causal tracing, 6-tier evidence ranking, rebuttal probes
test-engineertest strategy, regression locks, flaky tests
verifierindependent completion evidence
code-reviewer, security-reviewerindependent review lanes
designer, visionUI/UX work, screenshot/mockup analysis, visual verdicts
supply-chain-auditorread-only dependency, license, MCP server, skill, and CI audits
devops-engineerCI/CD pipelines, Dockerfiles, runtime alignment, dry-run packaging
runtime-qaread-only black-box CLI/process/API probing and coverage gaps
doc-stewarddocs 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 (verifier runs 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 self subagent (or research for read-only roles). Paste the role's agents/<role>.md body 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 like git worktree so worker branch commits survive worker termination) over "branch" (cloned workspace deleted by manage_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, and Model: "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-brief and sh <plugin>/hooks/run.sh review-package over pasting full plans or git diff output through the leader context window.
  • Antigravity tool disambiguation (manage_task vs task checklists): Antigravity's manage_task tool 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.json or an Antigravity task artifact (write_file / write_to_file in 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_message to 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_question tool for structured questions. Put the recommended option first, prefixed with (Recommended). Do not add an "Other" option: the UI provides one. Set is_multi_select only when several answers can be true at once.
  • 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 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.

PathOwner / 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.jsonldiagnostic hook error log (written when OMAGY_ROOT / OMAGY_STATE_ROOT is set or .omagy/logs/ exists)
.omagy/context/<slug>-<UTC>.mdpre-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.jsonoptional 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_at on every write. Hooks use it to detect progress and staleness. Include owner_conversation_id when known so parallel sessions do not hijack each other's hooks.
  • Terminal phases are complete, cancelled, failed, blocked. Every terminal write sets "active": false and completed_at.
  • One writer per file: the leader. Children report evidence and never mutate leader-owned state.
  • Never delete or rewrite unrelated sessions' artifacts. $cancel and 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 not awaiting_confirmation: true with optional awaiting_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 scans git diff for left-behind blocker patterns (test.skip, test.only, placeholder TODO: 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 with current_phase: "blocked", active: false before ending the turn.
  • PreToolUse (planning, agreements & overwrite guard): while deep-interview, ralplan, or plan state is active (or autopilot is in a planning phase / ralplan_gate), file writes (Path, TargetFile, filePath, rename/MoveTo, edits[], apply_patch, or targetless file-mutation calls) outside .omagy/ and omagy_wiki/ require user confirmation. Also escalates unread write_file(Overwrite: true) calls on non-empty existing code files (write-existing-file-guard) and full overwrites of omagy_wiki/agreements.md that would drop [by:human] entries (agreements-guard).
  • SessionStart / PreInvocation: injects skill routing for $name keywords, a one-line reminder of active modes, bounded (<=3,500 chars) omagy_wiki/agreements.md + omagy_wiki/index.md context once per conversation (filtering expired expires: <ISO 8601> entries without deleting files and redacting standalone secret tokens), a once-per-conversation shared-first codebase export map (<=1,800 chars, opt-out via OMAGY_MAP=0), and any unseen subdirectory AGENTS.md or child-project omagy_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-agy ships a single Aux Pane HUD sidecar at sidecars/hud/sidecar.json (sidecar-id: oh-my-agy/hud, with 5 internal tabs for Overview, Workflows, Skills, Subagents, and Wiki). When starting or reporting on a workflow (and sidecars/hud/ is enabled), surface at most one sidecar:// 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) (never plugin://).
  • Cross-Host Compatibility (Claude Code & OpenAI Codex): Generate or validate host bundles on demand via sh <plugin>/hooks/run.sh host-setup <claude|codex> and host-validate <claude|codex> [<dir>] --strict. Auto-started HUD previews (desktop-serve) are strictly Desktop-app-exclusive (OMAGY_DESKTOP_HUD=1|0 overrides; 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-cleaner as 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.json and resume from current_phase instead 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.