# Getting Started

This guide takes you from a local checkout to the first Omagy-ready
Antigravity CLI session.

## Before You Start

You need:

- Node.js 20+
- Antigravity CLI available as `agy`
- A shell that can run Node scripts
- `tmux` if you plan to use `omagy team`

Omagy is built around the Antigravity CLI plugin model. The CLI installs and
verifies the plugin, while the day-to-day workflow happens inside Antigravity
through Omagy skills.

## Install Omagy

Recommended full install:

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

`omagy setup` installs or updates the `omagy` plugin in Antigravity CLI.
`omagy doctor` checks that the CLI, plugin, hooks, and project state are usable.

## Install From GitHub

Antigravity CLI can also import the repository as a plugin source:

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

Use this when you specifically want the plugin to come from the GitHub repo.
The npm package is still required for the `omagy` command. Without it, the
plugin can validate and install, but hooks, MCP servers, and workflow commands
will not have their runtime CLI.

## Build Locally

If you are developing Omagy from this repository:

```bash
npm install
npm run build
```

Check that the local Omagy CLI can see the runtime pieces it expects:

```bash
npm run doctor
npm run verify-plugin
```

`doctor` checks the local runtime and project state. `verify-plugin` is a
maintainer check for plugin bundle shape; it does not replace `omagy setup`.

## Install The Plugin From A Checkout

Preview the install first:

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

If the target path and files look correct, install:

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

The plugin is installed as:

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

After install, run the checks again:

```bash
npm run doctor
```

## Start Your First Session

Open Antigravity CLI in the project you want to work on. Then start with a
planning skill:

```text
/omagy:plan "plan the change before implementation"
```

The planning flow creates PRD and test-spec artifacts under `.omagy/plans/`.
Treat those artifacts as the handoff between planning and execution.

## Choose An Execution Path

Use the smallest path that fits the work:

| Need | Use |
| --- | --- |
| Clarify an ambiguous request before planning | `/omagy:deep-interview` |
| Turn a request into an approved PRD/test spec | `/omagy:plan` or `/omagy:ralplan` |
| Execute a planned change with durable goal checkpoints | `/omagy:ultragoal` |
| Keep one agent pushing until done | `/omagy:ralph` |
| Run coordinated parallel work | `/omagy:team` or `omagy team from-plan --json` |
| Stress-test a completed change | `/omagy:ultraqa` |
| Review code before completion | `/omagy:code-review` |

If you are unsure, start with `/omagy:plan`. It leaves a clearer trail than
starting with execution.

## Verify Completion

For most work, completion should include:

- the intended files changed
- a clear plan or handoff artifact when planning was used
- test or command evidence
- clean workflow state, or an explicit reason why a workflow was cancelled

Useful shell checks:

```bash
omagy workflow status --json
omagy plan status --json
omagy hud
```

For team runs, do not trust launcher text alone. Check runtime state:

```bash
omagy team status <team-name> --json
```

## When Something Looks Stale

If you edit root skills, docs, internal contracts, agents, rules, hooks, MCP
config, or plugin metadata, run setup from the fresh build. It refreshes the
packaged plugin mirror before installing it:

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

For release or CI work, maintainers can check the mirror explicitly:

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