wish
wish
Claude Code runs it as
/wish and Codex as $wish. Other agents take its name or a plain request such as "deliver this".What it does
Give wish one decided, bounded task. It comes back with a pull request against your integration branch, or with a refusal that names the route the task needs instead. Merging stays with you: wish never merges.
In Claude Code the delivery is the saved workflow
wish, and every admitted run goes through the same stages:| Stage | What happens |
| Admit | A read-only scout reads the task and the repository and estimates the change. The script checks the estimate against a fixed size band, and a judge that never sees the repository picks the route and freezes the contract: the outcome, the declared files and the acceptance criteria, written before any code exists |
| Work | One executor cuts a worktree on wish/<slug> from the base branch, edits only the declared files and makes one conventional commit |
| Gate | A mechanical check of that commit, described below |
| Review | A different, read-only agent scores the exact commit against the frozen criteria. A diff that leaves the declared files is blocked |
| Repair | While the gate is red or the verdict is FIX-FIRST, and the repair budget holds, a fixer edits the declared files again, and the gate and the review run on the new commit |
| Publish | One agent with an allowlist of commands pushes the branch, opens the pull request and reads the remote back. Without the GitHub CLI it stops before pushing anything |
| Read-back | The script compares the remote head, the pull request's base, head and files, and the checks with what the run set out to deliver |
The task is frozen at the start: no stage asks it again, narrows it or widens it.
The gate at v6.261003.1
At v6.261003.1 the scout reads the repository's root files for its install and check commands. The install is the frozen install for the root lockfile, and there is none without a lockfile. The check is the first of these the repository has: a
check script in package.json, make check, just check, task check, a test script (not the default placeholder that always fails), or make test. A command found in the repository runs only when it is exactly one of those forms; anything else counts as not found. The workflow's check and install args replace them.The executor runs the install in its worktree before its first commit. With a hook system, the gate first needs a live hook: an executable
pre-push or pre-commit in the hooks directory git resolves, which must sit inside the worktree or the repository's git directory. That covers husky, lefthook, the pre-commit framework and core.hooksPath; husky's .husky/_ directory also needs its pre-push. Dead hooks end the run blocked with nothing pushed. Then the gate runs the check once. With no hook system, or no check to find, it runs the validation command frozen in the contract instead, and CI is the authority: merge-ready needs the pull request's checks to pass./wish runs the repository's own install and check commands, so point it only at repositories you trust. The Quickstart lists what the gate asks of your repository.When to use it
- One decided change that should become a green pull request in a single pass.
- A task you can state with the files it touches and the outcome you expect.
- Work bigger than one task, through the plan entry below.
Admission refuses a task that does not fit and names the route it needs, with nothing created:
plan when the task is too big or touches a trust boundary, brainstorm when a product decision is still open, and report when the cause is unknown. The Quickstart lists the trust boundaries at v6.261003.1.What a run returns
| State | Meaning |
merge-ready | The checks pass, the remote head equals the local commit, the pull request's base, head and files match the contract, and the review says SHIP |
pr-open | The pull request exists but its checks had not finished; read them again with gh pr checks |
refused | Admission chose another route; nothing was created |
blocked | Something stopped the run before, during or after publishing; the report names which |
missed | The repair budget ran out or a stage returned nothing; the branch, commit, worktree and any pull request are kept |
After every run the skill runs
genie wish report <runId> --append, which prints the run's tokens and time per stage.To retry after
missed or blocked, run wish again with the same task and slug. It adopts the worktree it left behind when that worktree is clean and nothing has diverged from the remote. wish never deletes a worktree or a branch; after you merge, the report ends with the command that removes both, and that command refuses a branch that is not merged.Plan work bigger than one task
Ask wish for a plan and it skips admission. It writes
.genie/wishes/<slug>/WISH.md from its bundled template: scope in and out, decisions, success criteria, and execution groups, each with its deliverables, acceptance criteria, validation and dependencies. A group that would not fit the admission band becomes a sibling wish. A plan that links a brainstorm design needs that design's SHIP evidence to match its content.Then:
genie wish lintchecks the structure of every plan in the repository and writes nothing.genie task create --title "<group title>" --wish <slug> --group <group-name>adds a card for each group, andgenie context --wish <slug>records the base commit.
Run it
| Agent | How it runs |
| Claude Code | /wish <task> runs the saved workflow wish in the background. /workflows shows its progress. See Workflows |
| Codex | $wish <task> runs the same stages by hand, as subagents, with the same briefs |
| Other agents | Its name, or a plain request such as "deliver this", runs the same stages by hand |
Name an issue number or URL in the request and the scout reads it and the pull request links it. The base branch is
dev unless you name another; main and master are refused. The skill passes the repair budget genie config get budgets.maxEscalationsPerGroup prints, and the workflow caps it.A recorded run
Simulated terminal: a replay of a real /wish run in Claude Code, built from its saved capture and shortened in time. Edited in two places: host details hidden (paths shown as ~/, account plan and quota), and the agent launch line removed.
This is the same run the Quickstart shows as a time-lapsed replay, with its
genie wish report output.Read the transcript: the redacted text of the run's final screen and scrollback, with each cut marked inline.