From 7d8703cc84a42df18fdd7380a8959eec76e88b86 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 12:02:33 -0700 Subject: [PATCH 1/4] docs(quest): plan /quest-afk and the rules agents kept needing from a moq transcript audit Rewrite afk.md as a /quest-afk skill that skips every decision, add the guide-rules and complete-loop quests, and fold the ready-at-hand-back fix into start.md and the merge method and merged-PR refusal into pr-states.md. Co-Authored-By: Claude Opus 5.5 --- quest/m0/helpers/README.md | 15 +++++++-- quest/m0/helpers/afk.md | 56 +++++++++++++++++++++---------- quest/m0/helpers/complete-loop.md | 31 +++++++++++++++++ quest/m0/helpers/guide-rules.md | 53 +++++++++++++++++++++++++++++ quest/m0/helpers/pr-states.md | 18 ++++++---- quest/m0/helpers/start.md | 7 ++++ 6 files changed, 153 insertions(+), 27 deletions(-) create mode 100644 quest/m0/helpers/complete-loop.md create mode 100644 quest/m0/helpers/guide-rules.md diff --git a/quest/m0/helpers/README.md b/quest/m0/helpers/README.md index 1fff2916..03e518b1 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. @@ -46,15 +47,25 @@ 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: ready at hand-back into + [quest start](/quest/m0/helpers/start.md), and the merge method and the + merged-PR refusal into [PR state commands](/quest/m0/helpers/pr-states.md). ## Required +- [Unattended work](/quest/m0/helpers/afk.md) - `/quest-afk` skips every decision and keeps starting agreed work; every skill ends with a summary +- [Guide rules](/quest/m0/helpers/guide-rules.md) - pushing, briefs, follow-ups, whose review counts, and user-owned choices - [PR status](/quest/m0/helpers/status.md) - one call for head, checks, merge state, reviews by head, and unresolved threads - [Move and delete quests](/quest/m0/helpers/move.md) - `quest mv` and `quest rm` keep every root-absolute link valid - [CI checks in wait](/quest/m0/helpers/wait-checks.md) - `quest wait` wakes on required check results for the head - [quest start](/quest/m0/helpers/start.md) - claim a quest with a draft PR, the `## Decisions needed` hand-back, `quest unblocked --unclaimed`, and CI on ready PRs only - [PR state commands](/quest/m0/helpers/pr-states.md) - `quest iterate`, `ready`, `merge`, and `release` label the one owner of a PR -- [Unattended triage](/quest/m0/helpers/afk.md) - an `afk` argument that only asks about merges and deletes +- [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 index a8adb98a..c746fece 100644 --- a/quest/m0/helpers/afk.md +++ b/quest/m0/helpers/afk.md @@ -1,24 +1,44 @@ -# [XS] Triage unattended with an afk argument +# [S] Keep working unattended with /quest-afk ## Goal -`/quest-complete afk` and `/quest-spawn afk` act on their recommendations -without asking, except merges and deletes. This replaces the prompt the -user keeps typing before stepping away: "skip/iterate any that you -recommend, and prompt for any that you recommend I merge... relatively -simple decisions only". +`/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-19 (user): one shared `afk` argument for both skills, not - a new default and not limited to `/quest-complete`. -- In afk mode, dispatch recommended skip, `/quest-iterate`, and - `/quest-ready` picks without asking. Still ask about every merge and - delete, as one simple question each with the recommendation first. -- A decision that is not simple becomes a skip with a note in the summary - rather than a question. Suggested `/quest-plan` follow-ups wait for the - summary, since planning is an interview. -- The rest of the argument still filters the PRs or quests in scope, as - today. -- Edit `assets/skills/complete.md` and `assets/skills/spawn.md`, following - `PROMPTING.md`. +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: + +- A skill of its own, `/quest-afk`, not an argument on two skills. The old + global `/afk` (kixelated/dotfiles), kixelated/skills' `afk`, and the + `/recommended` links in moq-dev/moq and moq-dev/moq.pro were deleted the + same day, ahead of this quest, so the user types those instructions by hand + until it lands. +- 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`. 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..accbe286 --- /dev/null +++ b/quest/m0/helpers/guide-rules.md @@ -0,0 +1,53 @@ +# [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, +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, and confirm the PR is still open before every push, because a push + after the merge brings the deleted branch back. +- 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. +- 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. A review by the PR's + author, or an AI-attributed comment posted from the maintainer's account, + does not count. +- 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 + +- [quest start](/quest/m0/helpers/start.md) - carries the ready-at-hand-back fix from the same audit +- [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 92df7638..7a5a84a8 100644 --- a/quest/m0/helpers/pr-states.md +++ b/quest/m0/helpers/pr-states.md @@ -50,11 +50,15 @@ 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. A repository's root instructions may name another + method or queue per base, and `--land` follows them. 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,8 +71,8 @@ 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 a + repository whose root instructions name another method. ## Required diff --git a/quest/m0/helpers/start.md b/quest/m0/helpers/start.md index 0985d531..2bd72d15 100644 --- a/quest/m0/helpers/start.md +++ b/quest/m0/helpers/start.md @@ -47,6 +47,13 @@ each other"); none came from two quests touching the same files. idle and waits on the maintainer; - the [PR state commands](/quest/m0/helpers/pr-states.md) label a PR whenever another session takes it. +- Decided 2026-10-21 (user), from a month of moq maintainer transcripts + where "should I mark it ready?" came up in about 18 sessions: 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 it a draft. Drop the `start` skill's "the user has settled + every decision, including choices you made without asking" gate, which + already disagrees with the guide's Execution section. - A draft without the heading that looks stale is offered to the user for takeover, showing how long ago its last push or comment was. The user judges; there is no fixed timeout. From b7b9ff6460dd9c4f6a1d26a5736931e39028a5ab Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 12:06:40 -0700 Subject: [PATCH 2/4] docs(quest): link the afk and recommended removals Co-Authored-By: Claude Opus 5.5 --- quest/m0/helpers/afk.md | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/quest/m0/helpers/afk.md b/quest/m0/helpers/afk.md index c746fece..d9ba81b9 100644 --- a/quest/m0/helpers/afk.md +++ b/quest/m0/helpers/afk.md @@ -20,11 +20,14 @@ 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: -- A skill of its own, `/quest-afk`, not an argument on two skills. The old - global `/afk` (kixelated/dotfiles), kixelated/skills' `afk`, and the - `/recommended` links in moq-dev/moq and moq-dev/moq.pro were deleted the - same day, ahead of this quest, so the user types those instructions by hand - until it lands. +- A skill of its own, `/quest-afk`, not an argument on two skills. 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 From 1c654831bf38fc7d68b360684be90eed8b583140 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 12:19:06 -0700 Subject: [PATCH 3/4] docs(quest): exempt claim pushes and make review exclusions defaults Co-Authored-By: Claude Opus 5.5 --- quest/m0/helpers/guide-rules.md | 14 +++++++++----- 1 file changed, 9 insertions(+), 5 deletions(-) diff --git a/quest/m0/helpers/guide-rules.md b/quest/m0/helpers/guide-rules.md index accbe286..48a5389b 100644 --- a/quest/m0/helpers/guide-rules.md +++ b/quest/m0/helpers/guide-rules.md @@ -18,8 +18,10 @@ 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, and confirm the PR is still open before every push, because a push - after the merge brings the deleted branch back. + 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 first claim push, 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. @@ -34,9 +36,11 @@ edits through this plan; follow `PROMPTING.md` (goals over prescriptions). - 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. A review by the PR's - author, or an AI-attributed comment posted from the maintainer's account, - does not count. + 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); From 66e481be6765a38005d12a42d83322ee38516949 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 12:30:21 -0700 Subject: [PATCH 4/4] docs(quest): select the landing method with an explicit flag Co-Authored-By: Claude Opus 5.5 --- quest/m0/helpers/pr-states.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/quest/m0/helpers/pr-states.md b/quest/m0/helpers/pr-states.md index 7a5a84a8..77d965da 100644 --- a/quest/m0/helpers/pr-states.md +++ b/quest/m0/helpers/pr-states.md @@ -53,10 +53,11 @@ repositories ("those are in another repo?"). - 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. A repository's root instructions may name another - method or queue per base, and `--land` follows them. The merge skill named - no method, so an agent squashed a PR into moq-dev/moq's `release`, which - needs a merge commit. + 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 @@ -71,8 +72,8 @@ 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, a refused merged PR, the default merge commit, and a - repository whose root instructions name another method. + leaving the queue, a refused merged PR, the default merge commit, and + `--squash` and `--rebase`. ## Required