oma-bootstrap ยท diff
git:20261006.35f12f1 to git:20261102.fa2bdc2
92 added, 45 removed. Audit A to A.
---
name: oma-bootstrap
description: Install or verify the oma CLI and its runtimes (bun, uv, serena) before any oma-* skill, agent, or workflow runs an `oma` command. Use when `oma` is missing from PATH, when a skill says to run `oma ...` and the shell reports "command not found", or on the first task in a fresh Cursor or Grok Bot workspace.
---
- # oma bootstrap
+ # OMA bootstrap
- The oma-* skills in this plugin describe *what* to do. Several of them delegate
- the mechanics to the `oma` CLI (`oma agent spawn`, `oma market run`,
- `oma recap`, `oma hook run`, `oma doctor`), and code search expects the
- Serena MCP binary. Marketplace installs ship the skill text, not the binaries,
- so a fresh workspace may have neither.
+ ## Scheduling
- ## When to run
+ ### Goal
+ Prepare the CLI, required provider tools and project state for the requested
+ OMA task. Marketplace installation supplies instructions, not runtime binaries.
- - A skill instruction contains an `oma ...` command and `command -v oma` is empty.
- - The shell reports `oma: command not found` or `serena: command not found`.
- - The workspace has no `.agents/` directory and a skill needs project state
- (`.agents/state/`, `.agents/results/`, `oma-config.yaml`).
+ ### Intent signature
+ - An OMA task reports `oma: command not found` or a missing provider binary.
+ - A fresh Cursor or Grok Bot workspace lacks required project state.
- Skip this skill when `oma --version` already prints a version.
+ ### When to use
+ An invoked skill needs an `oma` command, a configured provider, or project OMA
+ state that is not ready. Check these requirements independently: a working CLI
+ does not establish that Serena or the project is ready.
- ## Steps
+ ### When NOT to use
+ For instruction-only work that needs no CLI, provider or project state, use the
+ requested skill directly. Do not provision tools just because the plugin loaded.
- Run from the repository root. Every step is idempotent; rerunning is safe.
+ ### Expected inputs
+ The invoked skill, its required tools and the task's actual repository or working
+ directory. Do not use the plugin cache or the Bot's HOME as the project root.
- 1. Check: `command -v oma && oma --version`. If both succeed, stop here.
- 2. Provision the runtimes with the official installer in non-interactive
- mode. It installs bun, uv, serena-agent, and cue when missing, and
- `OMA_INSTALL_NO_RUN=1` skips the interactive setup it would otherwise
- launch at the end:
+ ### Expected outputs
+ Evidence that each required phase is ready, or the specific dependency blocking
+ the original task. Do not equate a successful download with a working runtime.
- ```bash
- curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh \
- | OMA_INSTALL_NO_RUN=1 bash
- export PATH="$HOME/.bun/bin:$HOME/.local/bin:$PATH"
- ```
+ ### Dependencies
+ The official platform bootstrap script and `oma doctor --json`. Linux/macOS
+ commands below apply to hosted Bot computers; native Windows environments use
+ the PowerShell installer with `OMA_INSTALL_NO_RUN=1`.
- Without `curl`, use `wget -qO-` in its place. Each dependency is
- best-effort: the installer warns and continues when one fails.
+ ## Structural Flow
- 3. Install the CLI as a persistent global binary (skills call bare `oma`):
+ ### Transitions
+ - CLI available: skip CLI provisioning, then inspect required providers and state.
+ - Required provider missing: provision that dependency even if the CLI works.
+ - Project state absent: initialize only when the requested task needs it and
+ project setup is authorized. Existing task authorization remains sufficient.
+ - Existing project: diagnose and reuse it; do not automatically reinstall over
+ customized definitions or unrelated work.
+ ### Failure and recovery
+ | Failure | Recovery |
+ |---|---|
+ | Installer succeeds but `oma --version` fails | Inspect `command -v oma` and PATH. Do not create another global install that shadows an existing npm or Homebrew binary. |
+ | Required Serena binary is still missing | If `uv` is available, run `uv tool install -p 3.13 serena-agent@latest --prerelease=allow` once, then `uv tool update-shell`. Report failure if it remains unavailable. |
+ | Existing project has configuration or registration issues | Inspect `oma doctor --json`; apply only the indicated repair covered by the task's authorization and preserve local changes. |
+ | Dependency or setup cannot proceed | Continue independent instruction-only work and report the blocked command. Do not substitute an invented implementation of `oma`. |
+
+ ### Exit
+ Resume the original task when its required CLI, provider and project phases are
+ ready. Keep unresolved phases explicit; plugin import alone does not verify them.
+
+ ## Logical Operations
+
+ ### Canonical command path
+ 1. Determine which phases the invoked skill actually requires. In its task
+ directory, inspect `command -v oma` and, when present, `oma --version`.
+ Check required provider binaries separately and inspect existing `.agents/`
+ state. Do not stop after the CLI check.
+ 2. If the CLI or required bootstrap dependencies are missing on Linux/macOS,
+ run the official installer without launching its interactive setup:
+
```bash
- bun install --global oh-my-agent
+ curl -fsSL https://raw.githubusercontent.com/first-fluke/oh-my-agent/main/cli/install.sh \
+ | OMA_INSTALL_NO_RUN=1 bash
+ export PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin"
```
- 4. Wire the project non-interactively. This creates `.agents/` with the
- default preset and leaves existing files untouched:
+ Without `curl`, use `wget -qO-`. The installer already installs the global
+ CLI when absent and preserves an existing binary; do not follow it with an
+ unconditional `bun install --global`. Optional dependencies can fail while
+ the installer continues, so verify each required tool after it returns.
+ Append the fallback PATH entries to preserve the priority of a working
+ Homebrew or npm CLI during a provider-only repair.
+ 3. Recheck `command -v oma && oma --version` and required provider binaries.
+ Resolve any missing dependency using the recovery table before invoking it.
+ 4. If project state is needed, inspect the project's existing installation.
+ For an absent `.agents/` tree and authorized project setup, run:
```bash
- oma install --yes
+ env -u OMA_YES CI=1 oma install
```
- 5. Verify: `oma doctor`. It reports whether `serena` is on PATH and whether
- the project is registered. Report any warning before continuing with the
- original task.
+ CI mode skips prompts without the affirmative side effects of `--yes`, such
+ as an automatic GitHub star. Installation writes managed skills, workflows,
+ hooks, agents, rules and vendor settings; it does not preserve every existing
+ file. For an existing installation, diagnose first instead of rerunning this
+ command over local changes.
+ 5. Run `oma doctor --json` when provider or project setup was required. Report
+ relevant warnings and complete only the repairs needed for the original task.
- ## Rules
+ ### Resource scope and effects
+ Runtime bootstrap can install global tools and update PATH. Project setup writes
+ the target repository's OMA definitions and vendor settings and may update
+ selected providers' HOME configuration. This skill does not authorize publication,
+ account changes or messages to others.
- - Ask before `oma install --yes` when the repository is not yours or when
- `.agents/` already exists with local changes.
- - Do not fall back to re-implementing an `oma` command by hand. If the CLI
- cannot be installed, say so and complete only the parts of the task that do
- not need it.
- - Do not run the installer without `OMA_INSTALL_NO_RUN=1` in a headless Bot:
- the interactive setup reads from `/dev/tty` and hangs.
- - If `serena` is still missing after step 2, run
- `uv tool install -p 3.13 serena-agent@latest --prerelease=allow` once, then
- `uv tool update-shell`.
+ ### Guardrails
+ - Keep `OMA_INSTALL_NO_RUN=1` in headless bootstrap commands: interactive setup
+ reads from `/dev/tty` and can hang.
+ - Preserve existing installations and local edits. If project setup falls outside
+ the authorized task, request that missing authorization without stopping
+ independent work.
+ - Do not install the project into the plugin checkout or the Bot's HOME.
+
+ ## References
+ - [Linux/macOS bootstrap](../../../cli/install.sh) (dependency provisioning).
+ - [Windows bootstrap](../../../cli/install.ps1) (native Windows environments).