Ultrapowers: from install to your first reviewed pull request

This tutorial takes you from nothing to a pull request your coding agent produced from a ticket, with your approvals on the ticket itself. It follows the path that has run live: Claude Code, GitHub, one repository, gated mode. Every other path is marked where it differs.

If you want the reasoning behind the method first, read Introducing Ultrapowers. This page is the runbook.

Prerequisites

A coding agent from the supported list. Claude Code is the one this tutorial shows.
Node 18 or newer. The setup engine and the autopilot engine run on it.
Git, and a project in a git repository.
For steps 4 to 7: a GitHub repository with issues, and the gh CLI signed in. GitLab works the same way through glab, but has not run live yet.

Step 1: Install the plugin on your coding agent

On Claude Code, the repository is its own plugin marketplace:


/plugin marketplace add raoofaltaher/ultrapowers
/plugin install ultrapowers@ultrapowers

The other harnesses each have their own install command. The README has the full list; these are the most common ones:

Harness	Install
GitHub Copilot CLI	`copilot plugin marketplace add raoofaltaher/ultrapowers`, then `copilot plugin install ultrapowers@ultrapowers`
Gemini CLI	`gemini extensions install https://github.com/raoofaltaher/ultrapowers`
Qwen Code	`qwen extensions install raoofaltaher/ultrapowers`
Factory Droid	`droid plugin marketplace add https://github.com/raoofaltaher/ultrapowers`, then `droid plugin install ultrapowers@ultrapowers`
Antigravity	`agy plugin install https://github.com/raoofaltaher/ultrapowers`
Kimi Code	`/plugins install https://github.com/raoofaltaher/ultrapowers`
Pi	`pi install git:github.com/raoofaltaher/ultrapowers`
Hermes Agent	`hermes plugins install raoofaltaher/ultrapowers --enable`
Codex, Cursor, Grok Build	Not in their marketplaces yet: install from a local clone through each tool’s plugin settings.
OpenCode	Ask OpenCode to fetch and follow `.opencode/INSTALL.md` from the repository.

What you should see. Open a fresh session in any project and send Let's make a react todo list. A working install triggers the brainstorming skill before any code is written: the agent asks what you are trying to do instead of opening the editor.

Step 2: Set up the project

In a repository without an Ultrapowers setup, the first session offers it. You can also ask for it:


/ultrapowers:init

The skill asks for the project name, the coding agents your team uses, and where your tickets live: GitHub Issues, GitLab Issues, Odoo tasks or local only. Then it shows a dry run.

What you should see. A list of the files it would write, and the question “Write these files?”. Nothing is written until you say yes. After the yes you have:

AGENTS.md, the one instruction file every agent reads (CLAUDE.md and GEMINI.md import it).
.agents/ultrapowers.json, the one settings file for the project. Commit it.
Ten knowledge-base folders, each with a README that says what belongs in it: tasks/, specs/, plans/, reviews/, evals/, handbooks/, playbooks/, brand-book/, business/, release-notes/.
MCP configuration rendered into each harness’s own format, the team-memory store, and repository hygiene: a gitleaks pre-commit hook and managed .gitignore and .gitattributes blocks.

Init never overwrites a file. Run it again after a plugin update and it switches to upgrade mode, which puts a proposal beside any file that changed and lets you merge what you want.

Step 3: Your first ticket, by hand

Run one ticket manually before you automate anything. You will recognise every stage later when the engine runs them for you.

Open the ticket. With a GitHub source configured, the id names the repository and the issue number:


/ultrapowers:new-task GH-web-7

What you should see. Four folders named by the ticket (tasks/GH-web-7/, specs/GH-web-7/, plans/GH-web-7/, reviews/GH-web-7/), a brief of two short paragraphs in tasks/GH-web-7/GH-web-7.md filled from the issue, a quoted copy of the issue in source.md, and a commit. Without a ticket source, type the brief yourself; any id that matches no configured prefix is a local ticket.

Write the spec.


/ultrapowers:brainstorm-task GH-web-7

What you should see. Before the first question, the agent prints the files it read: the brief, then every file the design depends on. Only then does it ask, one question at a time, propose alternatives, and present the design in sections for your approval. The result is specs/GH-web-7/Spec.md, committed after your review.

Write the plan. The writing-plans skill activates with the approved spec and writes plans/GH-web-7/Plan.md: small tasks, each step one action with a checkable result, with exact file paths, interfaces and test assertions. You review the plan before anything runs.

Build it. You choose between two execution styles:

Subagent-driven: a fresh subagent per task and a review after each one. Most thorough.
Inline: every task in your current session, with one fresh review of the whole branch at the end. Cheapest.

Either way the work runs on a new branch in an isolated worktree, test first: write the failing test, watch it fail, write the minimal code, watch it pass, commit. Code written before its test is deleted.

Check it. Code review runs after each task and once over the whole branch. If the project has a qa block, run the QA specialist (beta); it tests the running app in a real browser and writes one verdict to reviews/GH-web-7/QA-REPORT.md.

Finish it. The finishing skill verifies the tests and offers three choices: merge, open a pull request, or keep the branch.

At any point, /ultrapowers:task GH-web-7 tells you where the ticket stands without changing anything.

Step 4: Turn on autopilot

Autopilot runs the same stages from a GitHub or GitLab ticket, with your decisions on the ticket. Set it up once:


/ultrapowers:init autopilot

The skill asks for the mode (keep gated), the base branch, the tracker logins allowed to approve, the execution style, the harness a watcher would use, two watcher questions (own-account approval and shared credentials), and the six label names. Then it shows a dry run.

What you should see. After your yes, six labels on the repository: up:ready, up:approve, up:changes, up:hold, up:running, up:blocked, and a block like this in .agents/ultrapowers.json:


"autopilot": {
  "mode": "gated",
  "baseBranch": "main",
  "approvers": [],
  "execution": "inline",
  "harness": "claude-code"
}

Inline execution is what ran live. The default, subagent, dispatches a fresh subagent per plan task and has not yet run inside an autopilot run. An empty approvers list means any member with write access can approve, including you. If the engine ever runs as a bot account, list your human approvers here to keep the bot out.

Step 5: Your first one-command ticket


/ultrapowers:autopilot GH-web-8

What you should see. The run writes the brief, the spec and the plan on a ticket branch cut from your base branch, pushes it, posts a review packet on the issue, and stops. Here is the packet the live run posted on issue 16 of the plugin’s own repository, shortened to its shape:


Autopilot packet for GH-16 — gate 1 of 2 — mode gated
Docs branch GH-16-writing-plans-hand-off-lines-still at 2019507…
  brief   …/tasks/GH-16/GH-16.md
  spec    …/specs/GH-16/Spec.md   changed since last packet: none
  plan    …/plans/GH-16/Plan.md
Repositories in scope
  .   base dev
Assumptions to check (lowest confidence first)
  1. Where does the scenario live? — chosen: tests/task-lifecycle/ (medium)
  2. Does the fix also cover the autopilot-form hand-off? — chosen: no (medium)
  3. Which repositories are in scope? — chosen: . only (high)
Approve: add label up:approve. Changes: comment, then add up:changes. Stop: up:hold.
Packet id 4a6b1f2fa8f1

Read it on the issue. The assumption ledger is the part to check first: every question the agent would have asked you in the manual flow became a row here, lowest confidence at the top.

Step 6: Approve on the ticket

Add the label up:approve to the issue. Then, in the same session, continue the run.

What the engine checks before it accepts the label: who added it, read from the tracker’s own timeline; that they have write access (on GitLab, Maintainer or above) and are in approvers when that list is set; that the label came after the packet; and that the branch is still at the commits the packet named. A new commit voids the approval. The check runs again before implementation starts and before the pull request opens.

What you should see. The engine removes the label, freezes the scope, and the run implements the plan test-first with a review per task, runs QA when the project has a qa block, and moves on to the pull request.

Two other labels steer the run:

up:changes, with a comment saying what to change, sends the run back to the spec and the plan. The next packet shows what changed since the last one.
up:hold pauses the run until you remove it.

Step 7: Review and merge the pull request

What you should see. One pull request per repository in scope, against the base branch, citing the packet id, the approver and the head of the stage log, and a closing comment on the issue. The ticket branch carries tasks/<ID>/autopilot.json and a hash-chained tasks/<ID>/stage-log.jsonl, the record of every stage.

Review it the way you review any pull request, then merge it yourself. In this release neither the agent nor the engine merges.

A recipe for each team

Team	Settings	Flow
Solo developer on GitHub	`mode: gated`, `execution: inline`, `approvers` empty or your own login	Step 5, approve your own ticket, merge. The closest to the live run.
Lead who owns the tickets, developer who runs them	`approvers: ["lead-login"]`	The developer runs the command; the lead reads the packet, adds the label, merges.
Team on several coding agents	`harnesses` lists them all	One `AGENTS.md`, one ticket trail, one team memory in git, whichever agent a developer opens.
GitLab team, several repositories	`topology: nested`, `repos` with `area`, a GitLab source	One merge request per repository. Offline suites only; not yet run live.
Agency running a client’s tickets	The client’s tracker as the source, client leads as `approvers`, `commitTrailer` set	The packet is the client-facing record; the client merges.
Full automation (beta)	The watcher, after the seven-item checklist in `docs/autopilot-watcher.md`	A disposable VM, a bare service user, HTTPS remotes, branch protection, a scoped engine token plus a read-only stage token, `maxConcurrent` 1, and a kill switch everyone knows. Treat it as a pilot.

Do you want me to set this up on your project? Contact me.

Troubleshooting

Symptom	What to do
The brainstorming skill does not trigger in a fresh session	The bootstrap did not load. Reinstall, restart the session, and send the todo-list prompt again.
The run says it is waiting and nothing happens	Open the issue: the packet is there and wants a label.
The approval was ignored	Check who added the label and when. The actor needs write access, must be in `approvers` if set, and the label must come after the packet.
The spec is wrong	Comment what to change, then add `up:changes`.
Someone pushed to the branch after the approval	The new commit voided it. Read the new packet and approve again.
A session misbehaves in some other way	Ask the agent to “figure out what went wrong with ultrapowers in this session”; the diagnosing skill reads the transcript and reports with evidence.

Questions readers ask

Will init overwrite my files? No. It shows a dry run and never overwrites a file.
Do I need GitHub? Not for the manual flow; local tickets work. Autopilot needs a GitHub or GitLab source.
Who can approve? A member with write access, limited to approvers if that list is set, and only after the packet is posted.
Can it merge? No. You merge.
What leaves our network? The plugin itself sends nothing anywhere. Your agent still talks to its model provider, and gh, glab and git reach your tracker with your tokens.
Is the guardrail a sandbox? No. It is a hook that matches patterns and denies pushes, merges and tracker writes during a stage. The credentials a stage holds and the host it runs on are the real boundary.

Next steps

The repository, release notes and the full install list: github.com/raoofaltaher/ultrapowers .
The watcher guide, for teams that want tickets picked up from a label: docs/autopilot-watcher.md in the repository.
Questions and ideas: the repository’s Discussions .

Work with me

Do you want to automate the development workflow of your project with Ultrapowers? Do you want me to set it up on your project, or teach your team how to use it? Contact me.