Metadata-Version: 2.5
Name: oi-gantry
Version: 0.2.14
Summary: Automate the full SDLC of an OI Nebula project from inside your coding agent
Author: Orion Innovation
License: Proprietary
Keywords: adl,claude,codex,coding-agent,copilot,cursor,gantry,gemini,windsurf
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.9
Description-Content-Type: text/markdown

```
                                    /\
      .______.                     /  \
      |\    /|                    /    \
      |/____\|                   /      \
      |\    /|                  /        \
      |/____\|                  |        |
      |\    /|                  | /---\  |
      |/____\|=================>| |O/_|  |
      |\    /|                  | \---/  |
      |/____\|                  |        |
      |\    /|                  | #####  |
      |/____\|=================>| #####  |
      |\    /|                 /|        |\
      |/____\|                / |        | \
      |      |               /__|________|__\
      '______'
  ________________________________________________

     ____     _     _   _  _____  ____  __   __
    / ___|   / \   | \ | ||_   _||  _ \ \ \ / /
   | |  _   / _ \  |  \| |  | |  | |_) | \ V / 
   | |_| | / ___ \ | |\  |  | |  |  _ <   | |  
    \____|/_/   \_\|_| \_|  |_|  |_| \_\  |_|  
```

# GANTRY

*The harness holds it, checks it, and never flies with it.*

**Automate the full SDLC of an OI Nebula project from inside the coding agent you already use.**

GANTRY installs a set of `/gantry` slash commands into Claude Code, Cursor, Codex, Windsurf, GitHub
Copilot and Gemini CLI. You point it at a project, and it runs the delivery cycle: read the current
state, pick the work that matters, make the change, prove it works, and hand the project back.

The build-run-test work happens on your machine with your real toolchain — **your local Docker**,
your test runner, a real browser — so what gets marked done is what actually ran. The platform's own
containers are never used as a runtime.

---

## 1. Create a project

GANTRY drives a project hosted on **[OI Nebula](https://www.orioninnovation.com/services/artificial-intelligence/oi-nebula/)**.
Create one there first, then note three things from the project console:

| | |
|---|---|
| **Project URL** | the host your project is served from |
| **Project ID** | the `proj-…` identifier |
| **API key** | issued from the console; treat it as a secret |

## 2. Install

```bash
pip install oi-gantry
gantry sync            # writes the commands into every coding agent on this machine
```

`gantry sync --target claude` (or `cursor`, `codex`, `windsurf`, `copilot`, `gemini`,
`antigravity`) installs for one agent only. `--scope project --dir <path>` installs into a single project folder instead of your
user config.

### Full automation (on by default)

A GANTRY firing is unattended: every phase from `pull` onwards runs `docker compose`, `git`, the
project's package manager and its test runner. So `sync` also grants the agent unattended
read/write/execute/network access — for Claude Code it merges `permissions.defaultMode:
"bypassPermissions"` into that scope's `settings.json`. Your existing settings are **merged, never
overwritten**, and `gantry sync --no-automation` installs the commands without the grant (expect a
prompt per action, and an unattended `/loop` firing to stall on the first one). `--uninstall`
subtracts exactly the keys the installer added.

The other five agents have no config file this installer can write, so it prints the one-line change
to make in each — Codex `approval_policy = "never"`, Gemini `--yolo`, and the auto-run/Turbo/auto-
approve toggles in Cursor, Windsurf and Copilot.

Install into a scope you are willing to run unattended: `--scope project --dir <path>` confines the
grant to one project folder, while the default `--scope user` applies it everywhere.

## 3. Run it

Open your coding agent and type:

```
/gantry 10m /loop
{
  URL:        https://your-project-host,
  API_KEY:    your-key,
  Project_ID: proj-xxxx
}
```

That runs the delivery cycle on a repeating **10-minute** firing: each pass takes the project, works
as much of the backlog as it can, records what it did, and hands the project back before the next
one starts. Change `10m` to whatever interval suits the work.

The three values are the ones from step 1. They are read once at the start of the session and
verified with a single read-only call before anything is touched.

For a single pass instead of a loop, just type `/gantry`.

---

## Commands

`/gantry` on its own runs the whole cycle. You rarely need the individual commands — they exist so
you can step in at any point, and so the agent can tell you exactly where it is.

### Understand

| Command | What it does |
|---|---|
| `precheck` | Can this machine do the work? Docker daemon, compose v2, git identity, writable workspace, credentials, tool permissions. **Runs first; the work commands refuse without it.** |
| `status` | Cheap read-only health check. Changes nothing. |
| `connect` | Point this session at your project and verify the credentials. |
| `observe` | Read the project's current state and any failures in full. |
| `memory` | Read what the project has already learned — earlier corrections and decisions. |
| `select` | Choose which failure to work on: the one that unblocks the most work. |
| `diagnose` | Establish the true root cause before changing anything. |

### Change

| Command | What it does |
|---|---|
| `acquire` | Reserve the project for this session so two agents never collide. |
| `batch` | Group work that does not conflict into a single cycle instead of one at a time. |
| `fix` | Apply a surgical change. |
| `pull` | Clone the project onto your machine. |
| `take` | Build, run and test on your local Docker with your real toolchain, then push the result back. |
| `sync` | Push locally proven changes back into the project. |
| `verify` | Prove the change works on your local stack, from the outside, not by assertion. |
| `pass` | Close work you have built, run and tested green. |

### Decide and hand back

| Command | What it does |
|---|---|
| `decide` | Turn "I am blocked" into a decision it is authorised to make, and record it. |
| `ask` | Ask the project's humans a question when the answer is not in the code. |
| `hitl` | Answer an approval that is waiting on a person. |
| `escalate` | Raise something that cannot be resolved from inside the session. |
| `report` | Write the session report. |
| `resume` | Hand the project back and release the session. |

### Ways to call it

| You type | What happens |
|---|---|
| `/gantry 10m /loop` | Runs the cycle every 10 minutes until the backlog is empty. |
| `/gantry` | Runs the cycle once. |
| `/gantry why is the checkout task stuck?` | **Answers** from read-only state. Takes nothing, changes nothing. |
| `/gantry finish the payment task` | Runs the cycle, scoped to what you asked. |
| `/gantry should cancel refund before releasing inventory?` | Reaches a human. It will not invent a requirement. |
| `/gantry:status` | Runs one command directly. |

Each loop firing is a **complete session** — it takes the project, works, and releases it. Nothing is
held between firings, so a firing that dies never leaves the project locked for the next one.

Sub-commands are `/gantry:<name>` in Claude Code and Gemini CLI, and `/gantry-<name>` in Cursor,
Codex, Copilot, Windsurf and Antigravity — the difference is how each agent namespaces its commands,
not a difference in behaviour.

**Questions are answered, not executed.** When a request is ambiguous, GANTRY takes the cheaper,
reversible path — reply, or ask — rather than making a change you did not ask for.

---

## Supported agents

Claude Code · Cursor · Codex · Windsurf · GitHub Copilot · Gemini CLI · Antigravity

One package installs all seven. `gantry sync` after every upgrade.

Antigravity reads workflows from a different folder depending on scope — `.agents/workflows/` in a
project, `global_workflows/` under `~/.antigravity` for the user scope — and the installer handles
that for you. Both are taken from the shipped build's own path constants, not inferred.

## Staying current

```bash
gantry selfcheck            # is this copy current?
gantry selfcheck --update   # upgrade and rewrite every agent's commands
```

Sessions check this themselves before they start work, so an out-of-date copy is caught before it
can run a cycle under superseded rules. If the index cannot be reached, the session carries on —
a version check is never allowed to block delivery.

## Requirements

Python 3.9+. No third-party dependencies. **Docker must be installed and runnable on the machine you
run GANTRY from** — it is the only runtime for build, test, migrations and verification, and a
session cannot fall back to the platform's containers. A browser is needed for the e2e steps. Both
use whatever your project already uses.

---

© Orion Innovation. See [CHANGELOG.md](CHANGELOG.md) for what changes between releases.
