diff --git a/assets/AGENTS.md b/assets/AGENTS.md index d606cc2d..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. @@ -87,6 +88,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 +127,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 +137,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 +153,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/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/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