# Concepts

Omagy is easier to use when you keep the runtime layers separate.

## Antigravity CLI

`agy` is the execution engine. It owns the actual agent session, model calls,
tool use, and Antigravity plugin loading.

Omagy does not replace `agy`. It adds workflows and state around it.

## Omagy CLI

`omagy` is the shell command for setup and runtime support.

Use it for:

- installing and uninstalling the Antigravity plugin
- checking local health with `doctor`
- validating the plugin bundle
- syncing the root plugin source into `plugin/`
- reading and updating `.omagy/` state
- running the tmux-backed team runtime
- exposing MCP servers for state, memory, wiki, and trace tools

The CLI is also what Omagy hooks call after the plugin is installed.

Oh My Antigravity is published as `oh-my-agy` on npm, but the installed command
is `omagy`.

## Omagy Plugin

The repository root is a valid Antigravity plugin source. That supports direct
GitHub URL installs:

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

The npm installer path uses a packaged mirror in `plugin/` so `omagy setup`
can install only the plugin bundle instead of the entire source repository.
Both shapes install to:

```text
~/.gemini/antigravity-cli/plugins/omagy/
```

It contains:

- `plugin.json`
- `hooks/hooks.json`
- `mcp_config.json`
- mirrored skills
- agents
- rules
- user docs
- internal workflow contracts used by skills and verification

The installed hook file is only a launcher. The real behavior is in the Omagy
CLI built from this repository.

## Skills

Root skills live in:

```text
skills/
```

The plugin mirror lives in:

```text
plugin/skills/
```

Users normally trigger skills inside Antigravity CLI with slash commands such
as:

```text
/omagy:plan
/omagy:ultragoal
/omagy:team
/omagy:code-review
```

Skills describe workflow behavior. They are not the same thing as user docs,
even though they are Markdown files.

## Hooks

Omagy installs Antigravity lifecycle hooks for:

- `PreToolUse`
- `PostToolUse`
- `PreInvocation`
- `PostInvocation`
- `Stop`

The hooks help enforce workflow state and capture evidence. For example,
`PostToolUse` can record concise shell verification evidence, while `Stop` can
block completion when a workflow still needs terminal evidence.

## Project State

Project-local Omagy state lives under:

```text
.omagy/
```

Important areas include:

- `.omagy/state/` for active workflow state
- `.omagy/plans/` for PRD and test-spec handoffs
- `.omagy/context/` for captured context artifacts
- `.omagy/ultragoal/` for goal and ledger state
- `.omagy/reports/` for QA and workflow reports

Use Omagy commands or skills to mutate active state. Direct shell edits to
`.omagy/state/` can bypass workflow checks and are blocked by the plugin where
possible.

## Source And Mirror

This repository has a root plugin source and a packaged plugin mirror.

| Source | Mirror |
| --- | --- |
| `plugin.json` | `plugin/plugin.json` |
| `mcp_config.json` | `plugin/mcp_config.json` |
| `hooks/` | `plugin/hooks/` |
| `agents/` | `plugin/agents/` |
| `rules/` | `plugin/rules/` |
| `skills/` | `plugin/skills/` |
| `docs/` | `plugin/docs/` |
| `internal/` | `plugin/internal/` |

`omagy setup` refreshes this mirror before installing the plugin into
Antigravity CLI. For release or CI work, maintainers can refresh and verify the
mirror explicitly:

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

If you need the installed Antigravity plugin to receive local source changes,
run:

```bash
node dist/packages/cli/src/omagy.js setup
```

## Recommended Working Loop

For normal feature work:

1. Clarify only if needed with `/omagy:deep-interview`.
2. Plan with `/omagy:plan` or `/omagy:ralplan`.
3. Execute from an approved handoff with Ultragoal, Ralph, or Team.
4. Verify with tests, command output, or UltraQA.
5. Check workflow state before calling the task done.

The goal is not to use every workflow. The goal is to leave enough structure
that long sessions can resume, verify, and finish cleanly.