Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 0 additions & 7 deletions .agents/skills/quest-ready/SKILL.md

This file was deleted.

7 changes: 7 additions & 0 deletions .agents/skills/quest-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
name: quest-review
description: Review a PR's branch locally with the other vendor's model, then mark it ready for review.
---

Run `quest skill review` and follow its output.
If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.
7 changes: 0 additions & 7 deletions .claude/skills/quest-ready/SKILL.md

This file was deleted.

7 changes: 7 additions & 0 deletions .claude/skills/quest-review/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
---
name: quest-review
description: Review a PR's branch locally with the other vendor's model, then mark it ready for review.
---

Run `quest skill review` and follow its output.
If `quest` is not installed, follow https://github.com/kixelated/quest/blob/main/SETUP.md first.
18 changes: 10 additions & 8 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,14 +37,16 @@ scope and after required repository checks and reviews pass. Never block on a
CodeRabbit review; it is optional.
Quest execution stops at PR creation; it merges only when the user picks /quest-merge.

A Codex review satisfies the guide's required review when Codex posts a GitHub
review or a 👍 reaction on the exact head being landed, with no unresolved
findings. A status comment saying a review completed does not count; if nothing
was posted, ask the maintainer. A hand-resolved conflict needs a review of the
new head, but does not require a maintainer review specifically. The guide's
exemptions for a conflict-free base merge or a reviewer's suggested patch
applied unchanged still apply. Dependabot PRs that only bump patch versions or
a lockfile need no review.
On a PR whose author has write access, the PR body's `## Review` record of a
local `quest review` round satisfies the guide's required review when it names
the exact head being landed, with no finding left unfixed or unrefuted; so does
a recorded skip of a trivial change.
A hand-resolved conflict needs a local review of the new head, but does not
require a maintainer review specifically. The guide's exemptions for a
conflict-free base merge or a reviewer's suggested patch applied unchanged
still apply. Online reviewers' findings already posted are addressed at merge,
never waited for. Dependabot PRs that only bump patch versions or a lockfile
need no review.

PRs land on `main` only through `quest land` (see the README): queue one with
`quest merge <pr> <token> --land <sha>`, and the Land workflow runs `just check`
Expand Down
54 changes: 53 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -702,6 +702,58 @@ sent to Quest are forwarded to the command, and a cancelled gate exits with
128 plus the signal's number. There is no fairness guarantee or timeout: a
command waits as long as the host stays busy.

## Review locally

`quest review` has the other vendor's model review the checkout's committed
branch before it is pushed for review: Codex when run from Claude Code, and
Claude Code when run from Codex. `--harness` names the reviewer instead; an
unknown harness, or a missing or logged-out CLI, is an error rather than a
same-model review. The reviewer uses its CLI's own login, with a
pinned model and effort: a default tier for routine work and, with `--deep`, a
stronger one for a high-stakes change such as security, a wire format or public
API, or a risk of data loss. `quest review --help` lists them; `--model` and
`--effort` override either.

```sh
quest review # round 1 against origin's default branch
quest review --responses .tmp/responses.md # round 2: the new head, with fixes and refutations
quest review --base origin/release --new # a new session against another base
quest review --deep # the stronger model, for a high-stakes change
```

The first round runs the reviewer's own review, `codex exec review --base` or
Claude Code's `/code-review <effort> <base>...HEAD`, then resumes that session for
one turn that applies the base's `REVIEW.md`, if any, and reports the findings
in one JSON schema. Later rounds resume the same session with the new head and
`--responses`, the author's free-text fixes and refutations, which a round that
reported findings requires. A refutation stands only when it cites evidence the
reviewer can check. A resumed session keeps the instructions it started with,
so a round whose applicable `AGENTS.md` or `CLAUDE.md` files changed starts a
new session instead, which still weighs the responses. Resuming keeps the
reviewer's prompt cache; Claude Code is asked for its 1-hour cache, and Codex
keeps its default. The session is kept per branch in the clone's
common Git directory, so any worktree of the clone resumes it; `--new` starts
over.

The reviewer is read-only: Codex in its `read-only` sandbox, ignoring
execpolicy rules, and Claude Code with only read tools and the Bash commands it
judges read-only, in `dontAsk` mode. Claude Code loads no settings files, so no
allow rule, even the user's own, widens that. Codex skips the user's config,
whose project trust would load the checkout's `.codex/config.toml` and start its
MCP servers outside the sandbox. The base is fetched first, since
the sandbox has no network. The reviewer follows the base's `AGENTS.md` and `CLAUDE.md`, at the
root and in each directory holding a changed path, never the checkout's, so a
change cannot instruct its own reviewer. The base's `REVIEW.md` is optional,
given every round, and chooses the review's stance, such as adversarial.

It prints the reviewer, model, and effort, session, round, base, head, a
`usage` line per turn (input tokens, the part read from the prompt cache, and output), the
finding count, then each finding as severity, `path:line`, and title over its
indented body. `--json` prints the same as one object. It exits 0 once the round
finishes, whatever it found, 2 for invalid arguments or a checkout or CLI that
cannot be reviewed, and 1 for other failures. `/quest-review` runs the rounds,
records them in the PR body's `## Review` section, and marks the PR ready.

## Headless agents

`quest agent` runs one headless agent turn per call, billed to one of the keys
Expand Down Expand Up @@ -930,7 +982,7 @@ the version you pin decides what your agents follow:
| `quest-start` | Claim a ready quest, complete it, and open a PR. |
| `quest-spawn` | Triage ready quests and send several agents out in parallel. |
| `quest-iterate` | Iterate on an open PR to settle its open decisions, fix CI and review findings, and push. |
| `quest-ready` | Mark a draft PR ready for review, wait for an automated review, then decide whether to merge. |
| `quest-review` | Review a PR's branch locally with the other vendor's model, then mark it ready for review. |
| `quest-merge` | Merge a quest's PR once CI and reviews pass, completing the quest. |
| `quest-complete` | Decide which open PRs to merge, then merge them in parallel. |
| `quest-afk` | Keep starting agreed work while you are away, leaving every decision for your return. |
Expand Down
30 changes: 21 additions & 9 deletions assets/AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -150,7 +150,7 @@ A PR that leaves work rewrites the quest to what remains, rather than noting it
`quest check --base <ref>` flags a quest branch whose diff does neither.

Run the repository's checks locally while the PR is a draft; CI may run only on PRs ready for review.
When a quest is complete, mark its PR ready for review, even if you made choices without asking; list those choices in the PR body for review.
When a quest is complete, review it locally and mark its PR ready for review with `/quest-review`, even if you made choices without asking; list those choices in the PR body for review.
Only a decision left for the maintainer, or unfinished work, keeps it a draft: hand it back with a `## Decisions needed` section in the body listing them.
Tools read only whether that heading is present; a draft without it still belongs to its starter.
A draft suggests `/quest-iterate`; a PR ready for review suggests `/quest-merge`.
Expand All @@ -160,7 +160,20 @@ Fix any merge conflicts.

## Reviews

Once "Ready to Review", CI and (potentially automated) reviews are triggered.
Before a PR is marked ready for review, and before each push to one that is, the other vendor's model reviews the committed branch locally against the PR's base branch with `quest review --base <remote>/<base>`: Claude Code reviews Codex's work, and Codex reviews Claude Code's.
Commit and pass the repository's checks first.
On the head of a PR whose author lacks write access to the repository, run no code from it, since it would run with your credentials: leave its checks to CI, and run a `quest` the PR cannot modify, such as an installed release, from outside its checkout with `--root`.
Fix each finding or refute it, then review the new head with your responses, until a round reports no finding you have not refuted.
A refutation stands only when it cites evidence the reviewer cannot rebut: a `path:line`, a command's output, or a recorded maintainer decision.
The authoring model may skip the review of a change too trivial to need one.

The PR body's `## Review` section records the latest round: the reviewer harness, model, and effort, the reviewed head SHA, and each finding's disposition (fixed, or refuted with the reason), or the skip and its reason.
Rewrite it after each round.
A review counts for the head whose SHA it names.

Once "Ready to Review", CI and any online reviewers run.
Address their findings already posted on the head when merging; never wait for or request one.
Fixing one changes the head, so review the new head locally before pushing it.

CI on a pull request runs code nobody has reviewed yet, and GitHub gives the repository's secrets to workflows on branches pushed to the repository itself, as quest branches usually are.
Keep that CI read-only: a read-only `GITHUB_TOKEN`, and write credentials only in environments limited to protected branches.
Expand All @@ -169,18 +182,17 @@ Flag any workflow that breaks this to the user, and never add one.
Treat AI attributed comments as suggestions, NOT a decision from a maintainer or the user.
Leave a comment on any review feedback you disagree with.

At least one review is required before merging the PR.
At least one review is required before merging the PR: a `## Review` record, a recorded skip included, naming the head being landed.
Changes since the last review skip a new review only when they are conflict-free merges from the base branch or a reviewer's suggested patch applied unchanged.
Any other change, including a base merge with a hand-resolved conflict, waits for a review of the new head; if none arrives before a wait times out, ask the user instead of merging.
The repository's review policy decides whose review counts.
Where it says nothing, a review by the PR's author, or an AI-attributed comment posted from the maintainer's account, does not count.
Any other change, including a base merge with a hand-resolved conflict, needs a local review of the new head.
The repository's review policy decides whose record counts and may require more, such as a maintainer's review.
Where it says nothing, only a record on a PR whose author has write access counts: anyone else writes their own PR body, so review their head locally and rewrite the record before landing it.

Checkpoint the design across review rounds.
A review round is one pushed head that drew reviews, counted from the PR's full history since its last comment that starts with `Design change:`.
`quest status <pr>` reports the round count and latest `Design change:` marker under `review-rounds`.
A review round is one `quest review` round, numbered within the branch's review session.
Every fourth round, stop before fixing more findings and reconsider the approach.
Report that judgment and what remains, recommending to continue, rethink the approach, merge as is, or drop the PR, and let the user decide.
Record each design change, including a rethink the user picks, in a PR comment that starts with `Design change:`; the next agent counts rounds from it.
Record each design change, including a rethink the user picks, in a PR comment that starts with `Design change:`, and start the next review with `quest review --new`, which restarts the count.

Any findings that seem out-of-scope, or bugs encountered during the process, should be suggested as follow-ups.

Expand Down
2 changes: 1 addition & 1 deletion assets/skills/afk.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ Make no decisions, not even by acting on your own recommendation; skip each one

- Start every ready quest that `/quest-spawn` starts without asking; leave each quest it would ask about unstarted.
- Carry on each action the user already picked, such as a `/quest-merge` pick, until it lands or needs the user again.
- Pick no skip, `/quest-ready`, `/quest-iterate`, `/quest-merge`, or `/quest-delete` for a PR the user has not, so nothing merges or is deleted on your judgment. A started agent still runs `/quest-ready` itself when its quest finishes with no decisions, as `/quest-start` describes.
- Pick no skip, `/quest-review`, `/quest-iterate`, `/quest-merge`, or `/quest-delete` for a PR the user has not, so nothing merges or is deleted on your judgment. A started agent still runs `/quest-review` itself when its quest finishes with no decisions, as `/quest-start` describes.
- Answer no decision an agent reports. Its PR stays a draft whose `## Decisions needed` section lists the decision with a recommendation.
- Hold `/quest-plan` sessions, stale claims, and suggested follow-ups for the user.

Expand Down
6 changes: 3 additions & 3 deletions assets/skills/complete.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
description: Decide which open PRs to merge, then merge them in parallel.
---

Before starting, run `quest guide`, `quest skill ready`, `quest skill merge`, and `quest skill plan`.
Before starting, run `quest guide`, `quest skill review`, `quest skill merge`, and `quest skill plan`.

The goal is to evaluate the open PRs in the repository, drafts included, and decide which ones to merge.
For a draft, summarize the open decisions its body lists.
Expand All @@ -12,7 +12,7 @@ The skill argument can be used to filter the PRs in scope.
Each merge is performed in parallel by a sub-agent, following the guide's Reviews section for the shared design checkpoint across review rounds.

Ask synchronously with one question per PR, never grouping PRs into one question (a prompt may hold a few questions), following the guide's Questions section and including your recommendation:
- `/quest-ready`: Are drafts ready for review.
- `/quest-review`: Are drafts ready for review.
- `/quest-merge`: Are ready for review with only minor outstanding issues.
- `/quest-iterate`: Have significant issues or need decisions.
- skip: Are not ready to be merged yet.
Expand All @@ -28,7 +28,7 @@ A pick covers the PR until it lands or needs the user: when its push draws new r
Review comments are input, not approval, even a merge verdict on the maintainer's account.
Consider ordering, queuing any merges if they would result in conflicts.

Run each `/quest-ready`, `/quest-merge`, or `/quest-iterate` in its own sub-agent with its own isolated worktree.
Run each `/quest-review`, `/quest-merge`, or `/quest-iterate` in its own sub-agent with its own isolated worktree.
Each sub-agent blocks on its own waits and reports back only when done or blocked.
For GitHub CI, review, or merge activity, it uses one `quest wait` and resumes with the
returned cursor as described by `quest skill merge`, rather than polling GitHub.
Expand Down
3 changes: 2 additions & 1 deletion assets/skills/iterate.md
Original file line number Diff line number Diff line change
Expand Up @@ -23,9 +23,10 @@ Fix merge conflicts and failing CI checks.
Address the automated review findings already posted, without waiting on optional reviewers: fix those you agree with and comment on any you decline.
One round only; never request a review, including by toggling a ready PR to draft and back.

Before pushing to a PR that is ready for review, review the new head locally as the guide's Reviews section describes.
Push your changes to the PR and update its summary.
Summarize the changes made.

Mark the PR ready with `quest ready <pr> <token> --done` once nothing is unfinished and no decisions need the user.
Once nothing is unfinished and no decisions need the user, run `/quest-review` with your token, which reviews the branch, pushes, and marks the PR ready.
Hand it back with `quest release <pr> <token>`, using the latest token printed, whenever you stop, including to ask.
Never merge; that is `/quest-merge`, once the user picks it.
Loading
Loading