diff --git a/.agents/skills/quest-complete/SKILL.md b/.agents/skills/quest-complete/SKILL.md index 4e2b239e..59f863c3 100644 --- a/.agents/skills/quest-complete/SKILL.md +++ b/.agents/skills/quest-complete/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-complete -description: Decide which open PRs to merge, then merge them in parallel. +description: Decide which open PRs to merge, then queue them. --- Run `quest skill complete` and follow its output. diff --git a/.agents/skills/quest-merge/SKILL.md b/.agents/skills/quest-merge/SKILL.md index 581f04a6..c03a0d84 100644 --- a/.agents/skills/quest-merge/SKILL.md +++ b/.agents/skills/quest-merge/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-merge -description: Merge a quest once reviews and CI pass. +description: Queue a reviewed PR to land, or send it to /quest-iterate. --- Run `quest skill merge` and follow its output. diff --git a/.claude/skills/quest-complete/SKILL.md b/.claude/skills/quest-complete/SKILL.md index 4e2b239e..59f863c3 100644 --- a/.claude/skills/quest-complete/SKILL.md +++ b/.claude/skills/quest-complete/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-complete -description: Decide which open PRs to merge, then merge them in parallel. +description: Decide which open PRs to merge, then queue them. --- Run `quest skill complete` and follow its output. diff --git a/.claude/skills/quest-merge/SKILL.md b/.claude/skills/quest-merge/SKILL.md index 581f04a6..c03a0d84 100644 --- a/.claude/skills/quest-merge/SKILL.md +++ b/.claude/skills/quest-merge/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-merge -description: Merge a quest once reviews and CI pass. +description: Queue a reviewed PR to land, or send it to /quest-iterate. --- Run `quest skill merge` and follow its output. diff --git a/README.md b/README.md index 50551b18..30e73236 100644 --- a/README.md +++ b/README.md @@ -992,8 +992,8 @@ the version you pin decides what your agents follow: | `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-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-merge` | Queue a reviewed PR to land, or send it to `quest-iterate`. | +| `quest-complete` | Decide which open PRs to merge, then queue them. | | `quest-afk` | Keep starting agreed work while you are away, leaving every decision for your return. | | `quest-delete` | Abandon a quest, deleting it in its own PR. | diff --git a/assets/AGENTS.md b/assets/AGENTS.md index da44ea94..069afade 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -95,6 +95,8 @@ Search the tree and git history first before making a new quest. Split independently completable work into separate quests. A suggested follow-up becomes a quest only through `/quest-plan`, never as an agent-session task or a GitHub issue. +Plan recommended follow-ups without offering first: run `/quest-plan` on each one in turn, one follow-up per run. +A background agent that cannot prompt reports them for its caller to plan. Group related quests in an epic; its README holds the work no child owns. A release or pin bump that unblocks work is its own quest. @@ -154,7 +156,7 @@ When a quest is complete, review it locally and mark its PR ready for review wit 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`. -Include a summary of the changes made and suggest follow-up quests based on issues encountered; `/quest-merge` decides which to plan. +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. diff --git a/assets/skills/complete.md b/assets/skills/complete.md index f8dbc8fe..a3f92fd7 100644 --- a/assets/skills/complete.md +++ b/assets/skills/complete.md @@ -1,5 +1,5 @@ --- -description: Decide which open PRs to merge, then merge them in parallel. +description: Decide which open PRs to merge, then queue them. --- Before starting, run `quest guide`, `quest skill review`, `quest skill merge`, and `quest skill plan`. @@ -9,12 +9,13 @@ For a draft, summarize the open decisions its body lists. Read each PR with `quest status` and skip one another session holds, using its `hold` and `starter-hold` records instead of a separate label read. A `hold` names the label, acquisition token/time, event URL, and age. A `starter-hold` identifies a draft without a `## Decisions needed` section and reports when it was last active; that is not an acquisition time. List those with how long ago each was last active, and offer to take over only one that looks stale. 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. +Run each `/quest-merge` inline in this session; it only queues a reviewed head or recommends `/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. 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-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. +- `/quest-merge`: Are ready for review, with a review the guide counts on the head and no outstanding issues. +- `/quest-iterate`: Have issues, need decisions, or have no counted review of the head. - skip: Are not ready to be merged yet. - `/quest-delete`: Should be deleted. @@ -23,26 +24,25 @@ Act on a PR only after the user picks its action in this session, including PRs A blanket answer, such as "accept all" or "use your recommendations", picks your recommendation for every PR in scope, `/quest-merge` included, except a PR whose recommendation settles a decision you have not yet shown; ask about those. 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, and dispatch `/quest-merge` only when a conflict, failing check, or review finding stalls it. -A pick covers the PR until it lands or needs the user: when its push draws new review findings, send the agent back without asking; the merge skill's design checkpoint counts rounds from the PR, so it fires across those re-dispatches. +Do not ask about a PR with auto-merge enabled; leave it to land. +A pick covers the PR until it lands or needs the user: when `/quest-merge` recommends `/quest-iterate` for a picked PR, dispatch it without asking, and run `/quest-merge` again when it reports; when a push draws new review findings, send it back the same way. The guide's design checkpoint counts rounds from the PR, so it fires across those re-dispatches. 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-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. +Run each `/quest-review` or `/quest-iterate` in its own sub-agent with its own isolated worktree. +Each sub-agent reports back only when done or blocked, and never waits on GitHub CI, reviews, or merges. -Merge sub-agents report once their PR is landing; do not watch the queue or wait for merges. +Do not watch the queue or wait for merges. An open PR that left the queue unmerged shows why under `landing-stopped` in `quest status `. -After `merge_conflict` or `failed_checks`, its pick still holds, even from an earlier session: dispatch `/quest-merge` again without asking. +After `merge_conflict` or `failed_checks`, its pick still holds, even from an earlier session: dispatch `/quest-iterate` without asking, then run `/quest-merge` when it reports. +After `checks_pending`, or a pick `/quest-merge` left for pending checks, run `/quest-merge` again on a later refresh once they pass. Any other reason, such as a person removing it, is the user's call, so ask about the PR again. Keep going until all PRs have been decided, then wait for all spawned sub-agents to finish. Refresh the open PR list whenever a sub-agent reports, and once more before finishing; ask about each new PR in scope the same way. As each sub-agent reports, include a summary and interactively prompt the user for any outstanding decisions. -Collect each merged PR's suggested follow-ups, and once every sub-agent has finished, run `/quest-plan` on them without asking first; its interview lets the user drop any. +Collect each queued PR's suggested follow-ups, and once every sub-agent has finished, plan them as the guide describes; each interview lets the user drop its follow-up. Dispatch already selected actions before asking the next question; background work can continue while the foreground waits. Once every sub-agent has finished, remove local worktrees and branches whose tip is the head of a merged PR; squash merges leave that tip off the base branch. diff --git a/assets/skills/merge.md b/assets/skills/merge.md index 4387c03d..6d5f90e9 100644 --- a/assets/skills/merge.md +++ b/assets/skills/merge.md @@ -1,60 +1,38 @@ --- -description: Merge a quest once reviews and CI pass. +description: Queue a reviewed PR to land, or send it to /quest-iterate. --- Before you begin, run `quest guide` and read its output completely. +This skill runs inline in the session that picked it, never in its own sub-agent: it only decides whether the PR's head can land as is, and queues it. +It never fixes the PR, pushes, or waits on GitHub; `/quest-iterate` does the fixing, and the merge gate handles conflicts and failures after queueing. + Parse the arguments to determine the PR number, otherwise resolve it from the current context/branch. If a draft, stop and offer `/quest-review` instead. Take the PR with `quest merge ` before acting, passing a token you already hold from another state to swap it, and keep the hold token it prints; `quest merge --help` explains holds. If it refuses because another session holds the PR, stop and report what it printed; taking over a stale hold is the user's choice. -Hand it back with `quest release ` whenever you stop before it lands, including to ask. - -Read the PR's head, checks, merge state, reviews by head, and unresolved threads with `quest status `, including after each `quest wait` wakes, instead of chaining `gh` queries. -Fix any mechanical issues with the PR, such as merge conflicts and failing CI checks. -Address the review findings already posted on the head, fixing those you agree with and leaving a comment on any you disagree with. -Never wait for or request a review, including an `@codex review` comment or toggling a ready PR to draft and back. -Before pushing any change, review the new head locally, following the guide's Reviews section, including its design checkpoint across rounds. - -Abort the merge if there is a significant decision to be made. -Interactively prompt the user with your recommendation and any alternatives. -Suggested follow-ups do not hold the merge; once the PR merges, run `/quest-plan` on them without asking first. - -A background agent that cannot prompt lists its decisions and suggested follow-ups in its report instead. - -When waiting for CI, run -`quest wait --timeout 3300` as one blocking command instead of polling -GitHub in a loop; it also reports the head's required checks as `checks:failed` -or `checks:passed`, so no separate check watcher is needed. -Inspect the events and decide whether they satisfy the wait. If activity is -irrelevant (including bot notices and reviews), call it again with `--since` -set to the last field of its last line. Exit 3 means the deadline passed with -no activity; re-run with `--since` set to the printed cursor, so nothing during -the first wait is missed. -Other failures must be reported rather than treated as activity. -Run each wait so its exit wakes you, such as a background task that notifies on -exit, and end your turn until then. Never poll its output or rerun it under a -foreground time limit; each wake rereads your whole context. The hour bound -keeps that reread cached; a wake after the prompt cache expires rewrites it all. -A headless process ends when its turn ends, killing its background commands: -run each wait in the foreground instead, bounded by the shell's own time limit, -and apply the timeout rule above. - -Merge the PR *only* after all outstanding decisions have been confirmed. -Before landing it, fetch the PR's base branch and head, check out the head, and run `quest --root check --base / --branch `. -Run a `quest` the PR cannot modify, such as an installed release or a build from the base, from a directory outside the head checkout: the head's files, including runtime config such as `bunfig.toml`, are untrusted. -A stale local base can predate the quest and skip the check. -On a finding, fix the branch: delete the finished quest with `quest rm`, or rewrite it to the remainder the PR body names. -Then push, re-check, and continue; ask the user only when what remains is unclear. -Land only a head named by a `## Review` record the guide counts, or one the guide's review exemptions cover. -Leave a summary of the changes and decisions made, then land the head you checked with `quest merge --land `. +Hand it back with `quest release ` whenever you stop without queueing it, including to recommend `/quest-iterate` or to ask. + +Read the PR's head, checks, merge state, reviews by head, and unresolved threads with one `quest status `. +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; +- no review finding posted on it still needs a change, 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. + +Otherwise recommend `/quest-iterate`, saying what it needs: a review of the head, fixes, or decisions. +While its required checks are only pending, report that the pick stands until they pass; do not wait for them. + +Before queueing, fetch the PR's base branch and its exact head, check out the head outside your checkout, such as a detached worktree in `.tmp/`, and run `quest --root check --base / --branch ` with a `quest` the PR cannot modify, from a directory outside the head checkout: the head's files are untrusted, and a stale local base can skip the check. +A finding means the PR leaves its quest inaccurate: recommend `/quest-iterate`. + +Queue the head with `quest merge --land `. It makes a merge commit; add `--squash` or `--rebase` when the repository's root instructions name that method for the PR's base. -On a base that requires the `quest land` check, it queues the PR for `quest land`, whose chain merges and tests against the current base; do not merge the base or rerun checks per PR just to queue it. -On an ungated base, the command refuses a head that does not contain the current base. Merge the base locally (never rebase), rerun the repository's checks, push, and land the new head after satisfying the guide's review rule for those changes. +On a base that requires the `quest land` check, it queues the PR for `quest land`, whose chain merges and tests against the current base. +On an ungated base, it refuses a head that does not contain the current base: recommend `/quest-iterate` to merge the base. The `quest:merge` label stays on while the PR is queued or auto-merging. -Report once it is landing; do not wait for it to merge, since the queue re-checks it without you. -A PR that left the queue unmerged or lost auto-merge shows why under `landing-stopped` in `quest status `. -After `merge_conflict` or `failed_checks`, the pick still holds: fix it and land it again. -After `checks_pending`, wait for its required checks to pass and land it again. -Any other reason, such as a person removing it, is the user's call, so report why instead of landing it again. + +Report once it is queued, and do not wait for it to merge. +Plan the PR's suggested follow-ups as soon as it is queued, as if it lands, rather than waiting for the merge, unless a coordinator such as `/quest-complete` called this skill and batches them. +A PR that left the queue unmerged shows why under `landing-stopped` in `quest status `; it needs the user's pick again. Never close a PR to unstick it, and never work around a refused merge; ask instead. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index e97c2170..9f572a75 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -36,15 +36,16 @@ Report each sub-agent's final status, staying silent on interim notifications, b As each agent reports, explain its result in a few lines, then ask about its PR in the same way, offering: - `/quest-review`: If the PR is a draft ready for review. -- `/quest-merge`: If the PR is ready for review with no significant issues. -- `/quest-iterate`: If the PR has significant issues or needs decisions. +- `/quest-merge`: If the PR is ready for review, with a review the guide counts on its head and no significant issues. +- `/quest-iterate`: If the PR has significant issues, needs decisions, or has no counted review of its head. - skip: If the PR should not be merged yet. - `/quest-delete`: If the quest should be deleted. -Once every sub-agent has finished, run `/quest-plan` without asking first on the suggested follow-ups that merged PRs' `/quest-merge` sub-agents reported. +Once every sub-agent has finished, plan the suggested follow-ups of the PRs `/quest-merge` queued, as the guide describes. Include quest context, as many quests are concurrently in flight. -Run each selected `/quest-review`, `/quest-merge`, or `/quest-iterate` in a background sub-agent with its own isolated worktree, as for `/quest-start`. +Run each selected `/quest-merge` inline, as `/quest-complete` does, including its re-dispatch of `/quest-iterate` for a picked PR. +Run each selected `/quest-review` or `/quest-iterate` in a background sub-agent with its own isolated worktree, as for `/quest-start`. Run selected `/quest-plan` sessions in the foreground. Once every sub-agent has finished, remove local worktrees and branches whose tip is the head of a merged PR; squash merges leave that tip off the base branch. diff --git a/docs/getting-started.md b/docs/getting-started.md index 17d5cf47..3c3adb3d 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -59,7 +59,7 @@ job whose runner goes offline; check it for a live runner lock before starting. You review each change: `/quest-review` has the other vendor's model review a draft locally and marks it ready, and `/quest-merge` (`$quest-merge` in Codex) -merges it once checks and reviews pass. +queues it to land once a review covers its head and checks pass. The quest is complete, its plan leaves the tree, and the quests that required it can become ready. diff --git a/quest/m0/host-land/README.md b/quest/m0/host-land/README.md index 5ce0d351..4ce65fc3 100644 --- a/quest/m0/host-land/README.md +++ b/quest/m0/host-land/README.md @@ -80,7 +80,6 @@ can hand off instead. ## Required -- [Inline merge](/quest/m0/host-land/inline-merge.md) - `/quest-merge` queues inline or recommends `/quest-iterate`; no per-PR merge sub-agents - [moq-bot's App key](/quest/m0/host-land/bot-key.md) - condition: the maintainer places the key on the gate host - [Host daemon](/quest/m0/host-land/daemon.md) - `quest land serve` lands batches and ejects without bisecting - [Codex fixer](/quest/m0/host-land/fixer.md) - ejected batches get one mechanical fix attempt and healthy PRs are requeued diff --git a/quest/m0/host-land/inline-merge.md b/quest/m0/host-land/inline-merge.md deleted file mode 100644 index 7ad6acea..00000000 --- a/quest/m0/host-land/inline-merge.md +++ /dev/null @@ -1,30 +0,0 @@ -# [S] Merge inline from the coordinator - -## Goal - -`/quest-complete` and `/quest-spawn` merge a picked PR inline, without a -sub-agent. `/quest-merge` reads the PR with `quest status`, and when a -`## Review` record the guide counts names the head (a recorded skip for a -trivial change included), it queues that head with `quest merge --land` and -reports. Otherwise it recommends `/quest-iterate`, which runs the review and -any changes, and queues afterwards. `/quest-spawn` and `/quest-complete` -recommend `/quest-iterate` for every PR whose head has no counted review. - -## Plan - -Decided 2026-10-30 (user, /quest-plan); see the -[epic](/quest/m0/host-land/README.md). - -- `/quest-merge` no longer fixes conflicts, failing checks, or review - findings, and no longer runs `quest check --base` or waits: the gate's - check covers `quest check`, and its fixer owns conflicts and failures. - Posted review findings that need changes make it recommend - `/quest-iterate` instead of queueing. -- Drop the skills' re-dispatch of `/quest-merge` after a `merge_conflict` or - `failed_checks` ejection; the fixer requeues those or hands them back, - and a handed-back PR is asked about again. -- This works on today's land.yml gate too, so it can land before the host - gate. -- Reconcile with [moq-dev/quest#288](https://github.com/moq-dev/quest/pull/288) - and [moq-dev/quest#276](https://github.com/moq-dev/quest/pull/276), which - also rewrite these skills, whichever lands first.