From 2f471eda9f8f97ddd44d1390a0fab9947129c74d Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 22:39:03 -0700 Subject: [PATCH 1/3] chore(quest): claim quest/m0/helpers/guide-rules.md Quest-Claim: dc05236d477422f4 From 51a0acf19db41cd4db8dff00bb6a7a892cd804a6 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 22:44:14 -0700 Subject: [PATCH 2/3] docs(skills): state the guide and skill rules agents kept needing Pushing, sub-agent briefs, ready at hand-back, overlap search before planning, user-owned milestone moves, follow-ups through /quest-plan, whose review counts, and decisions reserved for the maintainer. Co-Authored-By: Claude Opus 5.5 --- assets/AGENTS.md | 10 ++++- assets/skills/audit.md | 2 +- assets/skills/complete.md | 1 + assets/skills/iterate.md | 4 +- assets/skills/plan.md | 3 ++ assets/skills/spawn.md | 1 + assets/skills/start.md | 4 +- quest/m0/helpers/README.md | 5 +-- quest/m0/helpers/guide-rules.md | 66 --------------------------------- 9 files changed, 19 insertions(+), 77 deletions(-) delete mode 100644 quest/m0/helpers/guide-rules.md diff --git a/assets/AGENTS.md b/assets/AGENTS.md index d606cc2d..db0a176a 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -87,6 +87,7 @@ Quests are created in PRs and reviewed. 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. 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. @@ -125,6 +126,9 @@ For example, `quest/m1/foo/bar.md` is branch `quest/m1/foo/bar`. 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 a branch another session may hold. +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. A quest's PR leaves its quest accurate when it merges. The PR that finishes a quest deletes its file and every link to it. @@ -132,8 +136,8 @@ A PR that leaves work rewrites the quest to what remains, rather than noting it `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 with no open decisions, mark its PR ready for review. -Otherwise keep it a draft and hand it back: add a `## Decisions needed` section to the body listing its open decisions, or what remains unfinished. +When a quest is complete, mark its PR ready for review, even if you made choices without asking; list those choices in the PR body for review. +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. @@ -148,6 +152,8 @@ Treat AI attributed comments as suggestions, NOT a decision from a maintainer or Leave a comment on any review feedback you disagree with. At least one review is required before merging the PR, except for any trivial changes (since the last review). +The repository's review policy decides whose review counts. +Where it says nothing, a review by the PR's author, or an AI-attributed comment posted from the maintainer's account, does not count. Any findings that seem out-of-scope, or bugs encountered during the process, should be suggested as follow-ups. diff --git a/assets/skills/audit.md b/assets/skills/audit.md index 6608bda2..755d23c4 100644 --- a/assets/skills/audit.md +++ b/assets/skills/audit.md @@ -15,6 +15,6 @@ Look for: Split the reading across parallel sub-agents, each given a slice of the scope and returning its findings with evidence (a path, line, or commit). -Apply factual corrections and changes the user has already decided. Use `/quest-plan` only for unresolved scope, priority, API, or other consequential choices; recommendations are not decisions. Once those choices are settled, apply them without another approval round. +Apply factual corrections and changes the user has already decided. Moving a quest between milestones or changing its rank is always the user's decision, never a factual correction. Use `/quest-plan` only for unresolved scope, priority, API, or other consequential choices; recommendations are not decisions. Once those choices are settled, apply them without another approval round. Move and delete quests with `quest mv` and `quest rm`, which update the links to them; edit any mentions they report, run `quest check`, and follow the repository's PR workflow within the user's authorized scope. Report the changes with their evidence and any decisions still open. An explicit read-only audit request leaves the tree unchanged. diff --git a/assets/skills/complete.md b/assets/skills/complete.md index 44944eae..fd003fec 100644 --- a/assets/skills/complete.md +++ b/assets/skills/complete.md @@ -23,6 +23,7 @@ Review comments are input, not approval, even a merge verdict on the maintainer' Consider ordering, queuing any merges if they would result in conflicts. Run each `/quest-ready`, `/quest-merge`, or `/quest-iterate` in its own sub-agent with its own isolated worktree. +Each brief carries the quest or PR, the user's picks, and the scope; leave repository rules to that repository's own instructions instead of restating them. 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. diff --git a/assets/skills/iterate.md b/assets/skills/iterate.md index a8b8fcc3..9afe7f85 100644 --- a/assets/skills/iterate.md +++ b/assets/skills/iterate.md @@ -14,8 +14,8 @@ Judge the approach before touching anything: would you take a different one? Scope the changes this PR needs with the plan skill's interview, starting from the user's feedback, your judgment of the approach, and any review findings that need a decision. Skip its quest and PR steps: record the settled decisions in this PR's description as the paper trail, then implement them immediately. -A sub-agent that cannot prompt picks the recommended option for each decision and lists those decisions in the PR description and its report. -It stops to ask only when a choice is truly consequential. +A sub-agent that cannot prompt picks the recommended option only for decisions the repository's instructions don't reserve for the maintainer, and lists those choices in the PR description and its report. +Reserved decisions, and any truly consequential choice, stay open in the PR with a recommendation. 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. diff --git a/assets/skills/plan.md b/assets/skills/plan.md index 1aabc90c..e6b74d2d 100644 --- a/assets/skills/plan.md +++ b/assets/skills/plan.md @@ -4,6 +4,9 @@ description: Scope and create quests through an interactive interview. Use when Before you begin, run `quest guide` and read its output completely. +Before anything else, search for existing work: the quest tree, git history for deleted quests, and open PRs touching `quest/`. +Show any overlap in the first round. + Interview the user until you reach a shared understanding. Every follow-up the user picks goes through this interview, including edits to existing quests and to quests in other repositories. A background agent that cannot prompt puts the problem in its report with a recommendation, so this skill can run in the foreground; it never creates or edits quests itself. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index b7346ee8..1e3fd393 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -26,6 +26,7 @@ Present those one at a time: a short paragraph explaining the problem, the quest - `/quest-delete`: If the quest should be deleted. Start each quest in a background sub-agent with its own isolated worktree, since agents cannot write to a worktree their parent created. +Each brief carries the quest or PR, the user's picks, and the scope; leave repository rules to that repository's own instructions instead of restating them. Each agent reports back only when done or blocked. Limit the number of active agents to the physical CPU core count. diff --git a/assets/skills/start.md b/assets/skills/start.md index 74a5b1e9..0fd078d9 100644 --- a/assets/skills/start.md +++ b/assets/skills/start.md @@ -23,6 +23,6 @@ Record the outcome as a PR comment as a paper-trail. Also offer to `/quest-plan` any suggested follow-ups as a multi-select. -Once the quest is complete and the user has settled every decision, including choices you made without asking, and the PR reflects them, run `/quest-ready` on it. +Once the quest is complete and the PR reflects the user's answers, run `/quest-ready` on it; list choices you made without asking in the PR body rather than waiting on them. -A background agent that cannot prompt lists its decisions and suggested follow-ups in its report instead, running `/quest-ready` only when the quest is complete and it has none. +A background agent that cannot prompt lists its decisions and suggested follow-ups in its report instead, running `/quest-ready` only when the quest is complete and no decision is left for the maintainer. diff --git a/quest/m0/helpers/README.md b/quest/m0/helpers/README.md index 71061094..2ffc5ace 100644 --- a/quest/m0/helpers/README.md +++ b/quest/m0/helpers/README.md @@ -52,14 +52,11 @@ commands from Sep-Oct. Session counts in each child come from that window. 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. + into [PR state commands](/quest/m0/helpers/pr-states.md). ## 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 diff --git a/quest/m0/helpers/guide-rules.md b/quest/m0/helpers/guide-rules.md deleted file mode 100644 index 8aab88fa..00000000 --- a/quest/m0/helpers/guide-rules.md +++ /dev/null @@ -1,66 +0,0 @@ -# [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 From a477407d29013ac3418cf4af0dc8ed8d533eee65 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 23:28:26 -0700 Subject: [PATCH 3/3] docs(guide): move the sub-agent brief rule into the guide Spawn and complete shared it verbatim; shared workflow instructions belong in the guide. Co-Authored-By: Claude Opus 5.5 --- assets/AGENTS.md | 1 + assets/skills/complete.md | 1 - assets/skills/spawn.md | 1 - 3 files changed, 1 insertion(+), 2 deletions(-) diff --git a/assets/AGENTS.md b/assets/AGENTS.md index db0a176a..53fdf31b 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -78,6 +78,7 @@ Silence, elapsed time, and a preselected recommendation are not answers or appro 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. diff --git a/assets/skills/complete.md b/assets/skills/complete.md index fd003fec..44944eae 100644 --- a/assets/skills/complete.md +++ b/assets/skills/complete.md @@ -23,7 +23,6 @@ Review comments are input, not approval, even a merge verdict on the maintainer' Consider ordering, queuing any merges if they would result in conflicts. Run each `/quest-ready`, `/quest-merge`, or `/quest-iterate` in its own sub-agent with its own isolated worktree. -Each brief carries the quest or PR, the user's picks, and the scope; leave repository rules to that repository's own instructions instead of restating them. 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. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index 1e3fd393..b7346ee8 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -26,7 +26,6 @@ Present those one at a time: a short paragraph explaining the problem, the quest - `/quest-delete`: If the quest should be deleted. Start each quest in a background sub-agent with its own isolated worktree, since agents cannot write to a worktree their parent created. -Each brief carries the quest or PR, the user's picks, and the scope; leave repository rules to that repository's own instructions instead of restating them. Each agent reports back only when done or blocked. Limit the number of active agents to the physical CPU core count.