# Oh My Antigravity

Oh My Antigravity (`omagy`) is a workflow layer for Antigravity CLI (`agy`).

Antigravity CLI still does the agent work. Omagy adds the surrounding system
that makes longer coding sessions easier to run: workflow skills, lifecycle
hooks, file-backed state, team helpers, diagnostics, memory, and verification
commands.

Use Omagy when you want Antigravity CLI to feel less like a single prompt box
and more like a repeatable engineering workflow.

## What You Get

- A local Antigravity plugin named `omagy`
- In-session skills for planning, review, execution, QA, memory, and team work
- Shell commands for setup, doctor checks, workflow state, and tmux-backed
  teams
- Project state under `.omagy/` so plans, handoffs, goals, QA evidence, and
  runtime status survive across turns
- Hooks that capture useful evidence and prevent unsafe direct edits to Omagy
  runtime state

Omagy is intentionally Antigravity-native. It is not a generic cross-runtime
agent framework, and it does not replace `agy`.

## Requirements

- Node.js 20+
- Antigravity CLI available as `agy`
- A shell that can run Node scripts
- `tmux` if you want the recommended durable team runtime

Oh My Antigravity is published as `oh-my-agy` on npm. It installs the `omagy`
CLI and the `omagy` Antigravity plugin.

## Quick Start

Recommended full install:

```bash
npm install -g oh-my-agy
omagy setup
omagy doctor
```

Plugin-first install is also supported when you want Antigravity CLI to import
the repository directly:

```bash
npm install -g oh-my-agy
agy plugin install https://github.com/shayne-snap/oh-my-antigravity
omagy doctor
```

The GitHub install path makes this repository itself the plugin source. The
global `omagy` CLI is still required because hooks, MCP servers, diagnostics,
and state commands run through that command.

After setup, verify the active shape:

```bash
omagy doctor
```

Then open Antigravity CLI and use the Omagy skills from inside the session.

## First Workflow

For a feature or bug fix, start with planning instead of jumping straight into
execution:

```text
/omagy:plan "clarify and plan the change"
```

After the plan is approved, choose the execution path:

- Use `omagy team from-plan --json` when the approved plan should launch a
  coordinated team run.
- Use the Ultragoal skill when the work should become durable goals with
  checkpoint evidence.
- Use Ralph when one persistent owner should keep pushing until completion.

The important habit is the same across all paths: plan first, execute from an
approved handoff, then finish with verification evidence.

## Two Surfaces

Omagy has two user surfaces. Keep them separate.

### Terminal CLI

Run these from your shell:

```bash
omagy setup
omagy workflow status --json
omagy plan status --json
omagy team from-plan --json
omagy team status <team-name> --json
omagy doctor
```

The CLI is for setup, diagnostics, file-backed state, hooks, and the external
team runtime.

### Antigravity Skills

Use these inside an Antigravity CLI session after the plugin is installed:

```text
/omagy:deep-interview
/omagy:plan
/omagy:ralplan
/omagy:ultrawork
/omagy:ultragoal
/omagy:ultraqa
/omagy:ralph
/omagy:team
/omagy:code-review
/omagy:memory
/omagy:wiki
/omagy:hud
/omagy:cancel
```

Skills are the normal user-facing workflow path. They may call the Omagy CLI
under the hood, but users should think of them as in-session workflows, not as
shell commands.

## Mental Model

```text
agy                 actual agent runtime
omagy CLI           setup, doctor, state, hooks, team runtime
repo root           Antigravity plugin source for GitHub URL installs
plugin/             packaged plugin mirror used by omagy setup
skills/             plugin skills edited in this repo
.omagy/             project-local workflow state and artifacts
```

`omagy setup` refreshes the packaged plugin mirror before installing it, so it
is the normal local refresh path. Maintainers can also refresh and verify the
mirror explicitly:

```bash
npm run sync-plugin
npm run build
npm run verify-plugin
```

## Project State

Omagy writes durable project state under `.omagy/`, including:

- workflow status in `.omagy/state/`
- PRD and test-spec handoffs in `.omagy/plans/`
- contextual artifacts in `.omagy/context/`
- Ultragoal ledgers in `.omagy/ultragoal/`
- wiki and memory artifacts used by Omagy skills and MCP servers

Do not edit `.omagy/state/` directly during active runs. Use `omagy workflow`,
`omagy state`, `omagy team api`, or the relevant skill.

## Documentation

- [Getting Started](docs/getting-started.md)
- [Concepts](docs/concepts.md)

The current docs are intentionally small. Add new pages only when a user needs
a separate guide, not just because another command exists.

## Development

For local development from this checkout:

```bash
npm install
npm run build
npm run verify-plugin
node dist/packages/cli/src/omagy.js setup
```

Common local commands:

```bash
npm run build
npm run typecheck
npm test
npm run doctor
npm run verify-plugin
npm run sync-plugin
```

`npm test` is broad. For documentation-only changes, `npm run build` and
`npm run verify-plugin` are usually the right minimum checks. Run
`npm run sync-plugin` explicitly when you need to inspect or commit the packaged
plugin mirror before setup/prepack refreshes it.