diff --git a/quest/m0/helpers/README.md b/quest/m0/helpers/README.md index 9bf1e552..b5006d3a 100644 --- a/quest/m0/helpers/README.md +++ b/quest/m0/helpers/README.md @@ -5,7 +5,8 @@ Agents stop hand-writing `gh`, `jq`, and `sed` loops for routine quest workflow steps, because `quest` commands cover them and the skills point at those commands: CI results while waiting, a one-shot PR status, claiming -quests and PRs, moving and deleting quests, and unattended triage. +quests and PRs, moving and deleting quests, and unattended work. Skill +rules that remove the maintainer's repeated steering belong here too. Only generic helpers belong here. Non-goals: the kix.quest UI, a daemon, and deciding whose review or which result counts; the agent still decides. @@ -45,10 +46,22 @@ commands from Sep-Oct. Session counts in each child come from that window. without that section. - Decided (user): this epic ranks after the worktree and gate quests and before the Kix decision UI. Children rank by sessions affected. +- Decided 2026-10-21 (user), from a month of moq maintainer transcripts: + quests that remove the maintainer's repeated steering join this epic. + `/quest-afk` and the guide rules rank first, since they save the most + maintainer time and change only prose. The complete loop ranks right after + the PR state commands, which also rewrite `complete`. Findings that fit an + existing child went into it: the merge method and the merged-PR refusal + into [PR state commands](/quest/m0/helpers/pr-states.md). Ready at + hand-back went into [Guide rules](/quest/m0/helpers/guide-rules.md), since + quest start landed without it. ## Required +- [Unattended work](/quest/m0/helpers/afk.md) - `/quest-afk` replaces the `afk` argument: it skips every decision and keeps starting agreed work; every skill ends with a summary +- [Guide rules](/quest/m0/helpers/guide-rules.md) - pushing, briefs, ready at hand-back, follow-ups, whose review counts, and user-owned choices - [PR state commands](/quest/m0/helpers/pr-states.md) - `quest iterate`, `ready`, `merge`, and `release` label the one owner of a PR +- [Complete loop](/quest/m0/helpers/complete-loop.md) - `/quest-complete` re-scans PRs, keeps picks and holds, and counts rounds per PR - [Headless agents](/quest/m0/helpers/headless-agents.md) - `/quest-spawn api` launches, resumes, and stops billed agents through one command auto mode allows ## Related diff --git a/quest/m0/helpers/afk.md b/quest/m0/helpers/afk.md new file mode 100644 index 00000000..b7e7ab0d --- /dev/null +++ b/quest/m0/helpers/afk.md @@ -0,0 +1,56 @@ +# [S] Keep working unattended with /quest-afk + +## Goal + +`/quest-afk` keeps quest work moving while the user is away and asks +nothing: it skips every decision instead of choosing one, leaves each skipped +decision on its PR, and keeps starting agents and PRs for work the user +already agreed to. Every quest skill ends with a final summary, so returning +starts with what needs the user. This replaces the steering the user typed in +about 20 moq sessions ("I'm going to bed", "you don't need to decide +everything, only when blocked", "I'm back, what decisions need to be made") +and the one-line global `/afk` and repository `/recommended` skills. + +Non-goals: a wind-down mode that stops dispatching ("just make the PRs then +stop"), and noticing the user's return; the final summary covers it. + +## Plan + +Decided 2026-10-21 (user), replacing the 2026-10-19 `afk` argument on +`/quest-complete` and `/quest-spawn`, from an audit of a month of moq +maintainer transcripts. That argument landed the same day in +[kixelated/quest#166](https://github.com/kixelated/quest/pull/166) as an +`## Unattended` section in `assets/skills/complete.md` and +`assets/skills/spawn.md`, plus a README sentence. It acts on its own +recommendations, answers simple decisions agents report, and still asks about +each merge and delete. This quest replaces it: + +- A skill of its own, `/quest-afk`, not an argument on two skills. Delete + both `## Unattended` sections and the README's `afk` sentence in the same + PR. At the user's request the old skills were removed the same day, ahead + of this quest, so the user types those instructions by hand until it + lands: the global `/afk` link in kixelated/dotfiles, the `afk` skill in + [kixelated/skills#8](https://github.com/kixelated/skills/pull/8), and the + `/recommended` links in + [moq-dev/moq#6200](https://github.com/moq-dev/moq/pull/6200) and + moq-dev/moq.pro. +- It makes no decisions. Every question a quest skill would ask is skipped, + not answered with its recommendation: the PR stays a draft listing the + decision with a recommendation, a quest that would need asking is left + unstarted and listed, and suggested follow-ups wait for `/quest-plan`. + Unlike the landed argument, it picks no skip, `/quest-ready`, or + `/quest-iterate` for a PR the user has not picked, answers no reported + decision, and asks nothing about merges or deletes: it never merges or + deletes on its own judgment. +- It keeps going as far as already agreed work allows: it starts ready + quests that `/quest-spawn` starts without asking, and carries on the actions + the user already picked, until nothing is left that needs no decision. +- Decided (user): every quest skill ends with a final summary in sections, + such as its PRs and their states, the open decisions, and suggested + follow-ups. Don't fix the exact shape. State this once in the guide rather + than in each skill. +- Write `assets/skills/afk.md` following `PROMPTING.md`, reusing the spawn + and complete skills' dispatch rules instead of restating them. Register it + in `src/cli/skills.ts` and the README's skill table; existing + repositories get its `quest-afk` stub by rerunning `quest init`. The user + asked for the skill and guide edits through this plan. diff --git a/quest/m0/helpers/complete-loop.md b/quest/m0/helpers/complete-loop.md new file mode 100644 index 00000000..a63eddfd --- /dev/null +++ b/quest/m0/helpers/complete-loop.md @@ -0,0 +1,31 @@ +# [S] Keep /quest-complete current across rounds + +## Goal + +`/quest-complete` notices new PRs as they appear, keeps the user's picks and +holds for the whole session, and counts review rounds per PR rather than per +sub-agent. The maintainer stops asking "any new PRs?" (8+ times in a month of +moq transcripts) and stops re-stating holds and merge approvals. + +## Plan + +Decided 2026-10-21 (user), from that audit. The user asked for these skill +edits through this plan. + +- Re-scan the open PR list whenever a sub-agent reports or a merge wait + wakes, not only before finishing, and ask about new PRs in scope the same + way. +- An "accept all" or "use your recommendations" answer never covers a + merge; each merge needs its own pick. A skip or hold stands across refreshes + and re-dispatched sub-agents until the user lifts it. +- Fresh sub-agents count review rounds from zero, so the merge skill's design + checkpoint never fires across re-dispatches. Count rounds from the PR's + timeline since its last design change, and apply the same checkpoint in + `iterate`, which has none today. Record a design change somewhere the next + agent can read it back from the PR, such as the comment recording the + decision. + +## Related + +- [PR state commands](/quest/m0/helpers/pr-states.md) - also rewrites how `complete` dispatches and skips held PRs +- [Unattended work](/quest/m0/helpers/afk.md) - carries on picks the user already made diff --git a/quest/m0/helpers/guide-rules.md b/quest/m0/helpers/guide-rules.md new file mode 100644 index 00000000..8aab88fa --- /dev/null +++ b/quest/m0/helpers/guide-rules.md @@ -0,0 +1,66 @@ +# [S] Guide and skill rules agents kept needing + +## Goal + +Agents stop needing the same corrections from the maintainer, because the +guide and skills state them: who may push to a branch, what a brief carries, +when a finished quest's PR is marked ready, where follow-ups go, whose review +counts, which choices are the user's, and searching for duplicates before +planning. Each rule comes from steering the +moq maintainer typed repeatedly over a month of transcripts. + +Non-goals: CLI changes, and restating repository rules; a repository's own +instructions keep owning its merge, review, and decision policy. + +## Plan + +Decided 2026-10-21 (user), from that audit. Each finding was checked against +the skill text on `main` that day. The user asked for these guide and skill +edits through this plan; follow `PROMPTING.md` (goals over prescriptions). + +- Pushing (guide): never rebase or force-push a branch another session may + hold. Before every push to a branch that already has a PR, confirm the PR + is still open, because a push after the merge brings the deleted branch + back. The claim push `quest start` makes, which comes before its draft PR + exists, is exempt. +- Briefs (`spawn`, `complete`): a sub-agent's brief carries the quest or PR, + the user's picks, and the scope, and leaves repository rules to that + repository's own instructions instead of restating them. +- Hand-back (guide, `start`): a complete quest is marked ready even if the + agent made choices without asking; it lists those choices in the PR body + for review. Only a decision left for the maintainer keeps the PR a draft + with `## Decisions needed`. Drop the `start` skill's "the user has settled + every decision, including choices you made without asking" gate, which + disagrees with the guide's Execution section. "Should I mark it ready?" + came up in about 18 moq sessions. Planned for quest start, which landed in + [kixelated/quest#167](https://github.com/kixelated/quest/pull/167) + without it. +- Planning (`plan`): search the quest tree, git history for deleted quests, + and open PRs touching `quest/` before anything else, and show any overlap in + the first round. The maintainer asked "double check we don't already have + it" and "I thought I had a probe quest already?". +- Audit (`audit`): moving a quest between milestones or changing its rank is + always the user's decision, never a factual correction. "Apply factual + corrections" was read as permission to move quests, and the move was + reverted. +- Follow-ups (guide): a follow-up becomes a quest through `/quest-plan`, + never a session task card or a GitHub issue. +- Reviews (guide): "At least one review is required" defers to the + repository's review policy for whose review counts. Where that policy + says nothing, a review by the PR's author, or an AI-attributed comment + posted from the maintainer's account, does not count. This is guidance + for the agent's judgment; the helper commands still never decide whose + review counts, as the epic's non-goal says. +- Decisions (`iterate`): a sub-agent that cannot prompt picks the + recommended option only for decisions the repository's instructions don't + reserve for the maintainer (moq reserves API shape, naming, and scope); + the rest stay open in the PR. +- Dropped (user): filtering CodeRabbit rate-limit and Codex "review started" + notices in `quest wait`. Vendor-specific filters break the core's + independence and the helpers' "the agent decides which result counts" + non-goal; the merge skill already re-waits on bot notices. + +## Related + +- [PR state commands](/quest/m0/helpers/pr-states.md) - refuses a merged PR mechanically and carries the merge method +- [Unattended work](/quest/m0/helpers/afk.md) - the guide's final-summary rule diff --git a/quest/m0/helpers/pr-states.md b/quest/m0/helpers/pr-states.md index ba95c11b..f593dcbb 100644 --- a/quest/m0/helpers/pr-states.md +++ b/quest/m0/helpers/pr-states.md @@ -50,11 +50,16 @@ repositories ("those are in another repo?"). PR is queued or auto-merging, until it merges. If it leaves the queue unmerged, the command that notices removes the label, and the PR is idle and waits on the maintainer's pick again. -- Decided (user): a repository with its own queue, such as moq-dev/moq.pro's - `merge` label from - [moq-dev/moq.pro#2510](https://github.com/moq-dev/moq.pro/pull/2510), says - how to land in its root instructions. The skill follows those instead of - `--land`; the label still means "on its way in". +- Decided 2026-10-21 (user), replacing a carve-out for moq-dev/moq.pro's + `merge` label queue, which the user means to remove: `--land` makes a merge + commit by default (`gh pr merge --merge`), through GitHub's merge queue + when the base has one. `--squash` or `--rebase` selects another method; + the command never reads prose, so the merge skill picks the flag from the + method a repository's root instructions name for that base. The merge + skill named no method, so an agent squashed a PR into moq-dev/moq's + `release`, which needs a merge commit. +- Every command refuses a merged or closed PR, because a push after the merge + brings the deleted branch back. - A merge pick covers the fixes its own agent pushes for conflicts, CI, and review findings. A head moved by anyone else, a design change, or the merge skill's design checkpoint asks the user again, as `complete` already says. @@ -67,5 +72,5 @@ repositories ("those are in another repo?"). - Test a refused draft its starter still holds, a race for one PR, two sessions taking the same state, a release with a stale token, a refused swap, landing on a moved head, a PR - leaving the queue, and a repository whose root instructions override - landing. + leaving the queue, a refused merged PR, the default merge commit, and + `--squash` and `--rebase`.