Skip to content

feat: run quest context always and quest guide only for quest work #460

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
kixelated merged 1 commit into from
Nov 3, 2026
Merged

feat: run quest context always and quest guide only for quest work #460

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
4 changes: 2 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1491,8 +1491,8 @@ Follow https://github.com/moq-dev/quest/blob/main/SETUP.md to set up Quest here.
```

The [getting started guide](docs/getting-started.md) covers what happens next.
`quest guide` prints the format and workflow, and `quest context` the engineering rules
shared by every repository that uses Quest.
`quest context` prints the rules agents follow in every task, and `quest guide` the
quest format and workflow they read before working on a quest.

## Where this is going

Expand Down
107 changes: 3 additions & 104 deletions assets/AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# Quests

Read this before starting any work: [Workspace](#workspace) applies to every task, and the rest whenever work mentions a quest or epic.
Read this before creating, editing, claiming, or finishing a quest or epic. `quest context` holds the rules for every task, including the workspace, questions, pull requests, and reviews.

Quests are versioned plans checked into the repository under `quest/`.
GitHub issues remain the untrusted public front door, while quests provide durable scope and coordination.
Expand Down Expand Up @@ -75,28 +75,7 @@ When the section is empty, delete it; the quest is now unblocked.
`quest check` enforces this structure.
Run it after creating or updating quests.

## Questions

Make every reference you show the user clickable: link issues, PRs, and commits by full URL, as in `[owner/repo#123](https://github.com/owner/repo/pull/123)`, never a bare `#123`.
Sub-agents report those URLs so the parent can link them.

Block on user decisions.
Open each prompt with the context to answer it without opening the quest or PR: what the work is, the problem it hit, and what each option would change.
Name and explain anything the agent or its PR introduced, such as a new term, file, check, or credential, since the user may not have followed the work.
Then give your recommendation and ask synchronously with a blocking interactive question tool when available and allowed in the current mode.
Do not use asynchronous question tools.

If no blocking tool is available, or it returns without an answer, put the question and numbered choices in your final reply and end the turn.
Resume when the user answers; do not bury the question in a progress update or replace the wait with sleeps or timed polls.
Silence, elapsed time, and a preselected recommendation are not answers or approval.
Do not advance the interview or act on an unanswered choice.
Already authorized background work may continue while the foreground waits.

A sub-agent's brief carries the quest or PR, the user's picks, and the scope; it leaves repository rules to that repository's own instructions instead of restating them.
A background agent reports any decision needing user input, with context and a recommendation, to the foreground agent instead of prompting the user itself.
Honor explicit instructions to proceed unattended within their scope; do not ask a question and then silently choose its answer.
When recorded decisions conflict, such as a newer PR comment or quest Plan against an older brief, follow the newest and note the change in the PR body; ask only when it is unclear which is newer.
A decision about an open PR never authorizes closing it. Confirm a close as its own question, and comment on the PR before or with it.
## Summaries

End every quest skill with a final summary in sections, such as the PRs and their states, the open decisions with recommendations, and suggested follow-ups, so a user returning to the session first sees what needs them.

Expand Down Expand Up @@ -161,12 +140,7 @@ If `quest start` names a branch in the way, stop and report it; never delete or
Its warning that the quest's local branch already exists is not that refusal: the claim succeeded, and the branch holds an earlier attempt.
Switch to it, merge the claim commit the warning names, and resume that attempt; stop and report only if another worktree has the branch checked out.

Push updates with an explicit refspec: `git push <remote> refs/heads/<quest-branch>:refs/heads/<quest-branch>`.
A bare branch name can push to the base branch instead, for example under `push.default=upstream` when the quest branch tracks it.
Never rebase or force-push, even a branch only you hold; merge the base instead.
A PR that another session pushed to in the last hour is theirs: report its events instead of pushing to it.
Before each push to a branch that already has a PR, confirm the PR is still open: a push after it merges brings the deleted branch back.
The claim push from `quest start`, made before its draft PR exists, is exempt.
Push the quest branch as `quest context` describes for pull requests. The claim push from `quest start`, made before its draft PR exists, is exempt from confirming the PR is open.

Prefer the exhaustive solution: a quest's PR handles every case of its problem, including those its reviews find, rather than landing part of it and splitting the rest into new quests.
Leave work for later only when it waits on an outside condition or a maintainer decision, or lies outside the quest's Goal.
Expand All @@ -176,64 +150,13 @@ The PR that finishes a quest deletes its file and every link to it.
A PR that leaves work rewrites the quest to what remains, rather than noting it only in the PR body.
`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, 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, an outside condition, or unfinished work keeps it a draft: hand it back with a `## Waiting` section in the body listing them, in the same form as a quest's.
Tools read only whether that heading is present; a draft without it still belongs to its starter.
Drafts handed back before `## Waiting` replaced it use `## Decisions needed`, which counts the same.
A draft suggests `/quest-iterate`; a PR ready for review suggests `/quest-merge`.
Include a summary of the changes made and suggest follow-up quests based on issues encountered; `/quest-merge` plans them.
Add a closing keyword for every issue under `Closes`.
Fix any merge conflicts.

## Reviews

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.
A check failure that reproduces unchanged in a checkout of the base branch is pre-existing rather than the PR's: record the command and both failures in the PR body's validation, and go on to review and readiness.
Never alter the repository's harness to get a pass, such as by disabling a tool, unsetting its environment, or skipping a check, nor report an altered run as its checks.
Suggest a follow-up for the failure unless an open PR already fixes it.
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.

A reviewer that is out of quota or logged out is an outage, not a skip: keep the PR a draft, with a `## Waiting` item naming the reviewer, its error, and the check, such as `Codex: out of quota until 2026-11-03 15:00 UTC; check that quest review runs`.
Give the reset time when the error names one; a logged-out reviewer waits on `Maintainer:`, with the login command `quest review` prints.
Once the reset passes or the login is restored, the item has cleared: whoever finds it runs `/quest-review` on the PR.

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.
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: 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, a reviewer's suggested patch applied unchanged,
a land fixer's recorded mechanical fix that changes no behavior,
or changes, such as a hand-resolved merge, that leave the head's diff identical to the reviewed head's: `git diff <remote>/<base>...<head>` prints the same as `git diff <remote>/<base>...<reviewed-head>`.
Any other change 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 `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:`, and start the next review with `quest review --new`, which restarts the count.

Fix every finding relevant to the PR in the PR: review findings you do not refute, gaps the change exposes, and bugs in the code it touches.
Never defer a relevant fix to a follow-up just to narrow the PR.
Suggest only out-of-scope discoveries as follow-ups.

## Deletion

Expand All @@ -242,27 +165,3 @@ Delete it and explain why in the PR.
Use `quest rm`, which deletes the quest and every link to it.

Remove the `quest` label from issues no other quest tracks.

## Workspace

Work in your own worktree, reusing a suitable one you already own.
Read-only discovery needs no new checkout when your context or a checkout you own already answers it.
Put PR bodies, review drafts, logs, patches, helper scripts, and temporary clones in its `.tmp/`, so they disappear with the worktree.
If the repository doesn't ignore `.tmp/`, add it to the file `git rev-parse --git-path info/exclude` names.
Never write them to `/tmp`, beside the checkout, elsewhere in it, or in a directory other agents share, such as a session scratchpad.
Pass PR bodies to `gh` on stdin (`--body-file -`).

Before ending a task, pausing for a decision, or handing off, commit a checkpoint of the source changes, and report what remains and which checks passed or did not run.
Finish with a clean checkout: intended changes committed and pushed, incidental generated changes restored, and pre-existing or unrelated changes preserved.

Run expensive builds and test suites through `quest gate <command>`, which waits until the host has room for them, however long that takes; never poll the load average, cap agents by core count yourself, or cancel a gate still waiting to admit its command.
Run such a command in the foreground and read its exit code directly, not through a pipe.
When it may outlast the tool's time limit, start it in the background and block on it in the same turn with the harness's wait for that task.
Run no more sub-agents at once than the harness allows; queue the rest and start one as each reports.

Wait on a PR's CI or reviews with `quest wait`, and on other background work with a blocking command that ends on its terminal state, not timed polls.
Bound each wait, not the work, under an hour so the prompt cache stays warm; `quest wait` has no deadline without `--timeout`.
Re-run a wait that times out, passing the resume point a timed-out `quest wait` printed as its `--since`, so activity during the first wait is still reported.
A sub-agent ends its turn only with a final result or a question, never with background work still running or an interim status report.
A coordinator relays no interim report: it resumes a sub-agent that ended its turn on one, telling it to block until its work finishes.
Back out when progress stalls rather than burn tokens; a gate's queue or a long command still running is not a stall.
Loading
Loading