diff --git a/README.md b/README.md index fcf08299..b5a59f7c 100644 --- a/README.md +++ b/README.md @@ -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 diff --git a/assets/AGENTS.md b/assets/AGENTS.md index b1e791be..1f27e487 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -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. @@ -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. @@ -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 refs/heads/:refs/heads/`. -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. @@ -176,7 +150,6 @@ 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 ` 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. @@ -184,56 +157,6 @@ Drafts handed back before `## Waiting` replaced it use `## Decisions needed`, wh 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 /`: 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 /...` prints the same as `git diff /...`. -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 @@ -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 `, 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. diff --git a/assets/CONTEXT.md b/assets/CONTEXT.md index 05044852..4eff6b30 100644 --- a/assets/CONTEXT.md +++ b/assets/CONTEXT.md @@ -50,6 +50,118 @@ Engineering rules for every task. The repository's own instructions add to them - Name by role, not today's implementation. - Document every export in one plain line, the way you'd say it out loud. +## 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 `, 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. + +## 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. + +## Pull requests + +Push with an explicit refspec: `git push refs/heads/:refs/heads/`. +A bare branch name can push to the base branch instead, for example under `push.default=upstream` when the branch tracks it. +Never rebase or force-push, even a branch only you hold; merge the base instead, and fix any merge conflicts. +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. +Run the repository's checks locally while the PR is a draft; CI may run only on PRs ready for review. + +## 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 /`: 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 /...` prints the same as `git diff /...`. +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. + +## Quests + +When the repository has a `quest/` directory, it plans work as quests: Markdown files there, each completed in one PR. + +- Before creating, editing, claiming, or finishing a quest, run `quest guide` and follow it. The `/quest-*` skills already do. +- A follow-up becomes a quest only through `/quest-plan`, never a GitHub issue or an agent-session task. Suggest follow-ups in the PR body. + ## Prompting Follow this when writing instructions for other agents: `AGENTS.md`, `CONTRIBUTING.md`, skills, memory, plans, reviews, and delegation briefs. diff --git a/assets/skills/afk.md b/assets/skills/afk.md index d33a1c4c..8715fd3e 100644 --- a/assets/skills/afk.md +++ b/assets/skills/afk.md @@ -14,7 +14,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. - Dispatch the `/quest-iterate` that `/quest-complete` runs without asking, for a PR with no decision for the user. Pick no skip, `/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. -- Dispatch `/quest-review` for a draft whose reviewer outage has cleared, as the guide's Reviews section describes; it needs no decision. A reset still ahead is no reason to keep running: give its time in the summary. +- Dispatch `/quest-review` for a draft whose reviewer outage has cleared, as `quest context`'s Reviews section describes; it needs no decision. A reset still ahead is no reason to keep running: give its time in the summary. - Answer no decision an agent reports. Its PR stays a draft whose `## Waiting` section lists the decision with a recommendation. - Hold `/quest-plan` sessions, stale claims, and suggested follow-ups for the user. diff --git a/assets/skills/complete.md b/assets/skills/complete.md index 7e9030d1..bd243064 100644 --- a/assets/skills/complete.md +++ b/assets/skills/complete.md @@ -11,13 +11,13 @@ List those with how long ago each was last active, and offer to take over only o Do not ask about a draft whose `## Waiting` section, or the older `## Decisions needed`, lists no decision for the user, only outside conditions or actions someone must take: list each once in your summary with what it waits on, and point to `/quest-unblock`. The skill argument can be used to filter the PRs in scope. Run each `/quest-merge` inline in this session; it queues a landable head, or hands the PR to `/quest-iterate`. -Run each `/quest-review` and `/quest-iterate` in parallel in a sub-agent, following the guide's Reviews section for the shared design checkpoint across review rounds. +Run each `/quest-review` and `/quest-iterate` in parallel in a sub-agent, following `quest context`'s Reviews section for the shared design checkpoint across review rounds. `/quest-iterate` is the default for a PR that needs work: dispatch it without asking when the PR has no decision for the user, such as for a merge conflict, failing checks, unaddressed review findings, or no counted review of the head. It fixes the PR, reviews it, and marks it ready; ask about the PR again when it reports. A PR with open decisions, such as those its `## Waiting` section lists or a significant issue you would solve differently, goes to the user instead: settle its decisions with the grill skill's rounds, then dispatch `/quest-iterate` with the answers in its brief. -Ask about every other PR 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: +Ask about every other PR synchronously with one question per PR, never grouping PRs into one question (a prompt may hold a few questions), following `quest context`'s Questions section and including your recommendation: - `/quest-merge`: Are landable as `/quest-merge` defines it. - skip: Are not ready to be merged yet. - `/quest-delete`: Should be deleted. @@ -31,7 +31,7 @@ A blanket answer, such as "accept all" or "use your recommendations", picks your A skip or hold stands until the user lifts it: do not ask about that PR again on a refresh, and state the hold in every sub-agent brief for it. GitHub auto-merge is that pick: enabling it takes write access, and GitHub disables it when anyone without write access pushes. Do not ask about a PR with auto-merge enabled; leave it to land. -A `/quest-merge` pick covers the PR until it lands or needs the user: when `/quest-merge` hands the PR to `/quest-iterate`, dispatch it without asking, and run `/quest-merge` again once it finishes; when it stops for the user instead, as `/quest-merge` describes, take that to the user. When a push draws new review findings, send it back the same way. Each re-dispatch resumes the branch's `quest review` session, whose rounds the guide's design checkpoint counts, so it fires across them. +A `/quest-merge` pick covers the PR until it lands or needs the user: when `/quest-merge` hands the PR to `/quest-iterate`, dispatch it without asking, and run `/quest-merge` again once it finishes; when it stops for the user instead, as `/quest-merge` describes, take that to the user. When a push draws new review findings, send it back the same way. Each re-dispatch resumes the branch's `quest review` session, whose rounds `quest context`'s design checkpoint counts, so it fires across them. When a `/quest-iterate` that no `/quest-merge` pick covers reports, ask about the PR again. 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. diff --git a/assets/skills/grill.md b/assets/skills/grill.md index dbecb7e1..7ec4aa28 100644 --- a/assets/skills/grill.md +++ b/assets/skills/grill.md @@ -10,7 +10,7 @@ A background agent that cannot prompt never picks an answer: it puts each open d Work the tree in **rounds**. The **frontier** is every decision whose prerequisites are already settled. -Ask the whole frontier in one synchronous round, following the guide's Questions section. +Ask the whole frontier in one synchronous round, following `quest context`'s Questions section. Open each question with the context it needs, including the settled answers it builds on, since a later round's question often hangs off a decision made rounds earlier. Mark one answer per question as (recommended) and wait for the user's answers (never guess) before the next round. diff --git a/assets/skills/iterate.md b/assets/skills/iterate.md index 1dd7534d..bb67769b 100644 --- a/assets/skills/iterate.md +++ b/assets/skills/iterate.md @@ -13,7 +13,7 @@ If you cannot push to the PR's branch, stop and report. Read the PR, its linked issues and quest, the reviews and comments posted on it, and the surrounding code. `quest status ` reports its checks, reviews by head, and unresolved threads in one call. Judge the approach before touching anything: would you take a different one? -Follow the guide's Reviews section for the shared design checkpoint across review rounds. +Follow `quest context`'s Reviews section for the shared design checkpoint across review rounds. Settle every decision this PR needs with the grill skill's interview, starting from the user's feedback: those its `## Waiting` section lists, those your judgment of the approach or the review findings raise, and any you find along the way. Record the settled decisions in this PR's description as the paper trail, then implement them. @@ -23,7 +23,7 @@ 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. +Before pushing to a PR that is ready for review, review the new head locally as `quest context`'s Reviews section describes. If `quest status ` shows auto-merge enabled, disable it with `gh pr merge --disable-auto` before any push: GitHub keeps it across a writer's push and would land the new head unreviewed. Push your changes to the PR and update its summary. Summarize the changes made. diff --git a/assets/skills/merge.md b/assets/skills/merge.md index 4ac4b44e..19f9c58c 100644 --- a/assets/skills/merge.md +++ b/assets/skills/merge.md @@ -16,7 +16,7 @@ Read the PR's head, checks, merge state, reviews by head, unresolved threads, an If a `hold` record shows another session holds the PR, stop and report it; taking over a stale hold is the user's choice. The head is landable when: -- a `## Review` record the guide counts names it, or the guide's review exemptions cover the changes since the one it names; +- a `## Review` record `quest context` counts names it, or its review exemptions cover the changes since the one it names; - every review finding posted on it, including automated reviewers' such as CodeRabbit or Codex, is fixed on the head or answered with a refutation, and no decision is open; - its required checks passed, other than the gate's own `quest land` check, which never reports on a head, and it does not conflict with its base. diff --git a/assets/skills/plan.md b/assets/skills/plan.md index c7afc94c..5bc58038 100644 --- a/assets/skills/plan.md +++ b/assets/skills/plan.md @@ -27,4 +27,4 @@ Record each settled decision and its reason in the quest's Plan, so later sessio New work joins the milestone the user picked, at its rank; an epic groups related quests, and its README holds the work no child owns (the end-to-end test, the docs page). When done, commit, open the PR as a draft, and run `/quest-review` on it, which reviews the branch, records the `## Review` section, and marks the PR ready. -Quests planned as follow-ups of an open PR may be committed to that PR instead, whose next push is reviewed as the guide's Reviews section describes. +Quests planned as follow-ups of an open PR may be committed to that PR instead, whose next push is reviewed as `quest context`'s Reviews section describes. diff --git a/assets/skills/review.md b/assets/skills/review.md index dca71640..27ea987b 100644 --- a/assets/skills/review.md +++ b/assets/skills/review.md @@ -13,12 +13,12 @@ A draft you started in this session has no `## Waiting` section, nor the older ` Work in a checkout of the PR's head branch, checking out the head first when someone else opened it. When another worktree holds that branch, work in a detached checkout of its head instead, and pass `--branch ` to each `quest review` so its rounds continue the branch's session. -Commit everything, then run the repository's local checks, unless the guide's Reviews section says to run no code from the head, and fix any failure the branch causes; record one that reproduces on the base as that section describes. +Commit everything, then run the repository's local checks, unless `quest context`'s Reviews section says to run no code from the head, and fix any failure the branch causes; record one that reproduces on the base as that section describes. -If a `## Review` record the guide counts names the committed head, or the guide's review exemptions cover the changes since the head it names, and it leaves no finding unrefuted, run no new round and go on to pushing and marking it ready below. -Otherwise, review the committed branch with `quest review`, as the guide's Reviews section describes; `quest review --help` explains the round. +If a `## Review` record `quest context` counts names the committed head, or its review exemptions cover the changes since the head it names, and it leaves no finding unrefuted, run no new round and go on to pushing and marking it ready below. +Otherwise, review the committed branch with `quest review`, as `quest context`'s Reviews section describes; `quest review --help` explains the round. Run it in the foreground; a round takes minutes. -If a round fails because the reviewer is out of quota or logged out, stop reviewing: keep the PR a draft with the `## Waiting` item the guide's Reviews section describes, hand it back, and report the outage. +If a round fails because the reviewer is out of quota or logged out, stop reviewing: keep the PR a draft with the `## Waiting` item `quest context`'s Reviews section describes, hand it back, and report the outage. Fix each finding you agree with, or refute it with evidence the reviewer can check. Commit the fixes, rerun the checks, and run the next round with `--responses`, one response per finding, written in the checkout's `.tmp/`. Repeat until a round of the head reports no finding you have not refuted with evidence. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index 888510a5..85093db6 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -19,7 +19,7 @@ Start every quest you would recommend starting, without asking: well planned, wi Print each quest you skip and why, suggesting `/quest-plan` for any with significant design issues. Ask only when unsure, such as a quest that may not be worth implementing or may not be worth doing now. -Present those one at a time: a short paragraph explaining the problem, the quest's goal, and your recommendation, then one synchronous question following the guide's Questions section, offering: +Present those one at a time: a short paragraph explaining the problem, the quest's goal, and your recommendation, then one synchronous question following `quest context`'s Questions section, offering: - `/quest-start`: If the quest should start now. - skip: If the quest should not be started yet. diff --git a/cloudflare/src/github/setup.ts b/cloudflare/src/github/setup.ts index a3f6f0ff..0938c722 100644 --- a/cloudflare/src/github/setup.ts +++ b/cloudflare/src/github/setup.ts @@ -125,7 +125,7 @@ function purpose(change: InitChange): string { if (path === "quest/README.md") return "the quest tree's root, with the project's goal"; if (path === ".gitattributes") return "routes `quest/**` through the `quest` merge driver"; if (path === ".claude/settings.json") return "Claude Code's worktree hooks, which run `quest worktree hook`"; - return "points agents at `quest context` and `quest guide`"; + return "points agents at `quest context`"; } /** The setup pull request's title and body for `changes`. */ diff --git a/src/core/init.ts b/src/core/init.ts index 1b1e17e6..98996f24 100644 --- a/src/core/init.ts +++ b/src/core/init.ts @@ -18,10 +18,13 @@ export const PREFIX = "quest-"; export const REFERENCE_MARKER = "Quests: "; /** Appended to the root agent instructions when Quest is installed. */ -export const REFERENCE_LINE = "Quests: before starting work, run `quest context` and `quest guide`, and follow both."; +export const REFERENCE_LINE = "Quests: before any work, run `quest context` and follow it."; /** Earlier releases' default reference lines, which init upgrades in place; a reworded line stays. */ -const OLD_REFERENCE_LINES: readonly string[] = ["Quests: before starting work, run `quest guide` and follow it."]; +const OLD_REFERENCE_LINES: readonly string[] = [ + "Quests: before starting work, run `quest guide` and follow it.", + "Quests: before starting work, run `quest context` and `quest guide`, and follow both.", +]; /** The skill directories Claude Code and Codex read; new installs use real directories. */ export const SKILL_DIRS = [".claude/skills", ".agents/skills"] as const;