# Ultrapowers > Use when the user runs "/ultrapowers ", asks to "execute this plan", "go ultra", or wants an approved plan built autonomously in parallel waves — on the exe.dev fleet, never on this machine. Also use when the user runs "/ultrapowers setup", asks whether they have a fleet yet, or asks to build one. - Skill: `popmechanic/ultrapowers` (Agent Skill, multi-file: 22 files) - Install (CLI): `npx skillmds@latest add popmechanic/ultrapowers` - Raw SKILL.md: https://api.skillmd.com/api/skills/popmechanic/ultrapowers/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: popmechanic (https://skillmd.com/u/popmechanic) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/popmechanic/ultrapowers --- # Ultrapowers This skill is the CLIENT only. Since 0.3.0 there is no LLM engine session: on the sandbox, a boot unit spawns the deterministic driver (`node fleet/run-main.mjs` → `fleet/run-engine.mjs`), which compiles the plan, dispatches judgment agents, folds each wave with the kernel, gates, and approves — code, not prose. Nothing in this skill runs a plan locally, and `ultra_run.py` refuses to (its `fleet-run` stage). The argument decides the mode. A plan path is the client below; the bare word `setup` is the guided first run. The client falls into setup by itself when the doctor is not `ready`, so setup is a path through this file and not a separate errand. ## Setup The doctor is the only thing that knows which pieces of the fleet are already there. Every row it returns is a read: running it twice is the same as running it once, and nothing in setup creates a VM. The setup agent uses AskUserQuestion wherever a question can be posed as choices. The agent runs every command in this section itself. Only three things need a human — a browser signup, a browser approval, and one copied code — and each of those is followed by an AskUserQuestion whose recommended option is the next step, so the agent waits on an answer instead of on a guess. If a command fails in the agent's own shell, the agent reports the failure and the exact command and offers, with AskUserQuestion, to hand that one command over; that fallback exists only after the agent-run form has already failed. The first command, run from the plugin cache: ```bash node /fleet/doctor.mjs --json ``` `` is two directories above this skill's base directory. The harness prints `Base directory for this skill:` when it loads this file; the cache path itself differs by version and by host, so derive it rather than naming it. The doctor answers with one row per piece, and its row ids are `exe-dev`, `capacity`, `claude`, `accounts`, `github`, `integrations`, `verb-drift`, `render`, in that order. Each row carries a `status` of `ok` or `missing`, a human `detail`, and a `fix` naming the `## ` section of `references/first-run.md` that repairs it. Read the rows back to the user as a short list before touching anything. Configuration lives in `~/.ultrapowers/fleet.json`; the doctor takes `--config ` to read it from somewhere else, and `--target /` to include that repository's own integration object in the answer. Then take the red rows in the doctor's order. Open the row's `fix` section in `references/first-run.md` for the detail — the walk is not restated here — and say one line about what is happening before each repair. `exe-dev` — the account. The human signs up at exe.dev and adds an ssh key in the browser; that is the first consent and the agent cannot do it for them. AskUserQuestion: **Done in the browser?** — `Yes, the account and key are in place (Recommended)` / `Not yet, wait for me`. Then the agent asks, again with AskUserQuestion, which key file `~/.ssh/config` should point at — `~/.ssh/id_ed25519` (Recommended) or another path the user names — and writes the `Host *.exe.xyz exe.dev` stanza itself. `capacity` — the pool the account's plan allows. When the detail names keys nothing reads, the agent rewrites the file with cpu and memory only, keeping any size it already carried, and re-runs the doctor — no question is asked. The agent reads the doctor's `detail` for the pool it found and asks with AskUserQuestion: **Lower the run size, or upgrade the plan?** — `Lower it to {"cpu":"4","memory":"8GB"} (Recommended)` / `Upgrade the plan instead`. On the first the agent writes the smaller size into `~/.ultrapowers/fleet.json` itself; on the second the human upgrades the plan in the browser and the agent re-runs the doctor after them. `claude` — the token. The agent runs `node /fleet/claude-token.mjs login --code-from-clipboard` in the background; it opens claude.ai and waits for the code to land on the clipboard. The human approves there and copies the code — the third consent, and the only secret that ever moves by hand. AskUserQuestion: **Done in the browser?** — `Yes, the code is copied (Recommended)` / `Not yet, still approving`. On the answer the agent reads the command's result and says in one line whether the token landed. `github` — the GitHub integration. The agent runs `ssh exe.dev integrations setup github` and shows the user what it prints; the human approves the GitHub app install in the browser, which is the second consent. AskUserQuestion: **Done in the browser?** — `Yes, the install is approved (Recommended)` / `Not yet, wait for me`. Keep that integration personal: `--act-as-user` is unavailable on team integrations, so a team account's PRs are authored by the installation bot rather than by the user. `integrations` — every object a run needs, on the fleet's policy. The agent runs `node /fleet/target.mjs /` for the repository being built, which creates the one object that repository needs on the attachment policy `tag:fleet`; the command is idempotent, so an object already there is left alone, its policy read and replaced only when it is not `tag:fleet`. When the doctor reports another object — `claude-max`, or the renderer's — as off that policy, the agent asks with AskUserQuestion: **Put `` on the fleet policy?** — `Yes, set its policy to tag:fleet (Recommended)` / `No, leave it and I will look`, and on yes it runs `ssh exe.dev "integrations policy get --json"`, reads the `revision` it prints, then runs `ssh exe.dev "integrations policy set 'tag:fleet' --permanent --if-revision="` with that revision. (exe.dev refuses `integrations attach`/`detach` and `new --integration` since 2026-09-11; the policy is the only grant.) The agent re-runs the doctor after each fix, and the row that turned `ok` is read back to the user in one line before the next red row is touched. A row that comes back `missing` twice is reported with the doctor's `detail` and its walk section, and the agent keeps going down the list rather than starting over. When the doctor's verdict is `ready` the fleet is complete, and the launch in `## Client` below runs in the same turn — setup is a repair, not a destination. ## Client Selecting ultrapowers at the planning handoff, or invoking `/ultrapowers` on an approved plan, **is** the authorization to execute — no further approval pause. 1. **Derive the target from this checkout.** The target is the repository this skill is run in: `repo` is `gh repo view --json nameWithOwner -q .nameWithOwner`, and `baseSha` is the checkout's current commit. There is nothing per-project to configure — the pair travels in the launch, and each sandbox clones `repo` and branches from `baseSha`. That sha has to be one GitHub already has, so compare it against the upstream tip: when they differ, say the base is not on GitHub yet and ask the operator to push it before the launch. When the plan is for a repository other than this checkout, the launcher still needs a clone of that target with it as `origin`: clone it somewhere disposable and add `--repo ` to the launch line; `--target` alone is refused. The launcher compiles the plan from inside that clone, so the plan path on the launch line resolves relative to it: copy the plan and its `.gate-verdicts.json` into the clone (an untracked `docs/superpowers/plans/` there is fine) and name that relative path. Then run `node /fleet/doctor.mjs --target ` once. A verdict of `ready` goes straight to step 2. Any other verdict is repaired here: run the `## Setup` path inline, in this same turn, and launch when the doctor comes back `ready`. 2. **Launch.** One line: ```bash node /fleet/launch.mjs --target --base ``` It prints the run id, the VM name, the status URL and the assignment comment. Tell the user all four: the run is `run-`, the VM is `fleet-r-…`, and its status page is `https://.exe.xyz/status.json`. Nothing else needs staging — the launcher commits the plan to the target's `ultra/plan-run-` branch, then creates the VM in one lobby call with `--tag fleet` (the tag every fleet integration's policy grants), the assignment as its comment, and a setup script that starts the run's unit. No ssh, no second step. Add `--hold` to that line when the PR should stay open for a person — a measurement run; the sandbox then publishes and does not merge. 3. **Walk away.** The run outlives this session; there is nothing to tail. Its state is `status.json`, written at every transition: `booting` → `running` → `publishing` → `done`, or `parked` or `failed`. When the user asks how the run is doing, read `status.json` by tag: a finished run's record is `ultra/evidence/run-`, the one spelling that keeps working after the VM is reaped and after the run's branches are gone. ```bash gh api 'repos//contents/.ultrapowers/runs//status.json?ref=ultra/evidence/run-' --jq .content | base64 -d ``` While the run is in flight that tag is not written yet and the same bytes are on its `ultra/evidence-run-` branch, a working surface that goes at publish. The page at https://.exe.xyz/status.json is the operator's own: a browser logged in to exe.dev reads it, this agent does not. 4. **The PR is the gate.** There is no approval command. When the engine is done and the branch is ahead of base, the sandbox pushes it and opens the PR itself, through the target's integration attached at launch. The run's code is the `ultra/integration-run-` branch, which is the PR head; its evidence is under `.ultrapowers/runs//`, on the `ultra/evidence-run-` branch while the run is in flight and at the tag `ultra/evidence/run-` once it ends, never merged and linked from the PR body. Gate-green → a ready PR and `done`. Parked → a draft PR carrying the gate receipt and `parked`. `pr` and `prAuthor` in `status.json` are the PR's URL and who GitHub says opened it — read both back to the user, and say so when the author is the installation bot rather than them (their GitHub account is not yet linked on exe.dev's Integrations page). A ready PR merges itself on the run's own evidence: the sandbox asks GitHub for no check runs, it merges once its own gate is green and main has not moved off the tip it folded onto — `status.json`'s `merged` cell is the squash commit — and `--hold` on the launch line keeps it open for the operator; a draft PR is the operator's to merge or close. That self-merge sentence is a gate-green run's only: after a park the sandbox has exited and merges nothing, so a parked run is acknowledged by the operator, by hand — mark the draft ready, `gh pr update-branch ` when it is behind main (GitHub's strict rule refuses a behind merge; this is a GitHub merge, not the kernel's fold), then `gh pr merge --squash ` — or re-driven as a narrower plan. A parked run with nothing to publish opens no PR; its record is still pushed and still tagged `ultra/evidence/run-`. The laptop never fetches a run branch. 5. **Reap.** `node /fleet/janitor.mjs` removes the VMs of runs that finished over an hour ago, and reports the stale ones rather than removing them. The launcher runs it before every launch; nothing schedules it, and the agent runs it by hand when this machine has been asleep. No scheduled job or timer on this machine runs the janitor, and none is to be added: a run merges its own PR from the sandbox and the launcher runs the reap (#660), so a local process on a timer would only be a second writer, and one that dies when the laptop sleeps. ## Resources - `fleet/run-engine.mjs` — the engine (waves, judgments, fold, gate) as code; `fleet/roles/*.md` — the judgment prompts, one file per role. - `references/first-run.md` — one section per doctor row: what it means and the command that builds it. - `references/design-rationale.md` — why each surviving guard exists. - `references/dependency-analysis.md`, `references/plan-markers.md` — plan → waves. - `references/report-format.md`, `references/finishing-notes.md` — report schema; finishing checks. - `kernel/FOLD_LOG.md` — the fold-log schema (contended-wave state a parked run's evidence carries). - `scripts/ultra_run.py`, `scripts/ultra_gate.py`, `scripts/finalize_report.py`, `scripts/gate_check.py`, `scripts/compile_plan.py`.