From 44a9bfb1a5a6488e7ec808ceb86c396c00d2a91e Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 23:47:24 -0700 Subject: [PATCH 1/2] docs(skills): plan follow-ups only through /quest-merge /quest-start offered follow-ups before /quest-ready, so a quest with no open decisions still stopped on a question. It now runs /quest-ready right away when no decision is left, and /quest-merge alone decides which suggested follow-ups to plan. ready and iterate stop offering them; spawn and complete offer them only for PRs a merge sub-agent landed. Co-Authored-By: Claude Opus 5.5 --- assets/AGENTS.md | 2 +- assets/skills/complete.md | 2 +- assets/skills/iterate.md | 2 +- assets/skills/ready.md | 1 - assets/skills/spawn.md | 4 ++-- assets/skills/start.md | 11 +++++------ 6 files changed, 10 insertions(+), 12 deletions(-) diff --git a/assets/AGENTS.md b/assets/AGENTS.md index 53fdf31b..c1251ffd 100644 --- a/assets/AGENTS.md +++ b/assets/AGENTS.md @@ -141,7 +141,7 @@ When a quest is complete, mark its PR ready for review, even if you made choices 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. +Include a summary of the changes made and suggest follow-up quests based on issues encountered; `/quest-merge` decides which to plan. 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 44944eae..6f014ad7 100644 --- a/assets/skills/complete.md +++ b/assets/skills/complete.md @@ -38,7 +38,7 @@ the user's choice, since a new head needs fresh approval. Keep going until all PRs have been decided, then wait for all spawned sub-agents and enqueued PRs to finish. Before finishing, refresh the open PR list and process any new PRs in scope. -As each sub-agent reports, include a summary and interactively prompt the user for any outstanding decisions, offering `/quest-plan` for its suggested follow-ups. +As each sub-agent reports, include a summary and interactively prompt the user for any outstanding decisions, offering `/quest-plan` for the suggested follow-ups of each PR it merged. 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/iterate.md b/assets/skills/iterate.md index 9afe7f85..1c2fa626 100644 --- a/assets/skills/iterate.md +++ b/assets/skills/iterate.md @@ -22,7 +22,7 @@ Address the automated review findings already posted, without waiting on optiona One round only; never request a review, including by toggling a ready PR to draft and back. Push your changes to the PR and update its summary. -Summarize the changes made, and offer `/quest-plan` for follow-ups that belong outside this PR. +Summarize the changes made. Mark the PR ready once nothing is unfinished and no decisions need the user. Never merge; that is `/quest-merge`, once the user picks it. diff --git a/assets/skills/ready.md b/assets/skills/ready.md index faca72ec..a0ef2d78 100644 --- a/assets/skills/ready.md +++ b/assets/skills/ready.md @@ -16,5 +16,4 @@ Summarize the reviews and CI from `quest status `, then interactively prompt - skip: If the PR should not be merged yet. - `/quest-delete`: If the quest should be deleted. -Also offer `/quest-plan` for suggested follow-ups. A background agent that cannot prompt lists these in its report instead. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index b7346ee8..1e1a9af6 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -31,7 +31,7 @@ Each agent reports back only when done or blocked. Limit the number of active agents to the physical CPU core count. When done, each agent's claim PR holds its work, still a draft if decisions or unfinished work remain. -Its report lists every open decision and suggested follow-up with a recommendation. +Its report lists every open decision with a recommendation. Report each sub-agent's final status, staying silent on interim notifications, but do not monitor their PRs. As each agent reports, explain its result in a few lines, then ask about its PR in the same way, offering: @@ -42,7 +42,7 @@ As each agent reports, explain its result in a few lines, then ask about its PR - skip: If the PR should not be merged yet. - `/quest-delete`: If the quest should be deleted. -Also offer `/quest-plan` for its suggested follow-ups. +Once a `/quest-merge` sub-agent reports its PR merged, offer `/quest-plan` for that PR's suggested follow-ups. Include quest context, as many quests are concurrently in flight. Run each selected `/quest-ready`, `/quest-merge`, or `/quest-iterate` in a background sub-agent with its own isolated worktree, as for `/quest-start`. diff --git a/assets/skills/start.md b/assets/skills/start.md index 0fd078d9..ee6b6d27 100644 --- a/assets/skills/start.md +++ b/assets/skills/start.md @@ -18,11 +18,10 @@ Implement the quest until it is complete, or some blocker is hit, then push to i Never write to or clean up a directory other agents share, such as a session scratchpad. When done, explain the result in a few lines and summarize any issues encountered. -Prompt the user interactively for any open decisions, including your recommendation. -Record the outcome as a PR comment as a paper-trail. +List choices you made without asking in the PR body rather than waiting on them. -Also offer to `/quest-plan` any suggested follow-ups as a multi-select. +If the quest is complete and you see no decision left for the maintainer, run `/quest-ready` on it right away. +Otherwise, prompt the user interactively for each open decision, including your recommendation, and record the outcome as a PR comment as a paper-trail. +Once the quest is complete and the PR reflects the user's answers, 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 no decision is left for the maintainer. +A background agent that cannot prompt lists its open decisions in its report instead, running `/quest-ready` only when the quest is complete and no decision is left for the maintainer. From bb3dde3694c4e0b84a21b0f79eeb80cd3c540938 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Wed, 21 Oct 2026 23:57:33 -0700 Subject: [PATCH 2/2] docs(skills): let suggested follow-ups wait for the merge Co-Authored-By: Claude Opus 5.5 --- assets/skills/complete.md | 2 +- assets/skills/merge.md | 2 +- assets/skills/spawn.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/assets/skills/complete.md b/assets/skills/complete.md index 6f014ad7..5f355de4 100644 --- a/assets/skills/complete.md +++ b/assets/skills/complete.md @@ -38,7 +38,7 @@ the user's choice, since a new head needs fresh approval. Keep going until all PRs have been decided, then wait for all spawned sub-agents and enqueued PRs to finish. Before finishing, refresh the open PR list and process any new PRs in scope. -As each sub-agent reports, include a summary and interactively prompt the user for any outstanding decisions, offering `/quest-plan` for the suggested follow-ups of each PR it merged. +As each sub-agent reports, include a summary and interactively prompt the user for any outstanding decisions, offering `/quest-plan` for a PR's suggested follow-ups once it merges. 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 b3439d47..c962a893 100644 --- a/assets/skills/merge.md +++ b/assets/skills/merge.md @@ -17,7 +17,7 @@ Never request a review, including by toggling a ready PR to draft and back. Abort the merge if there is a significant decision to be made. Interactively prompt the user with your recommendation and any alternatives. -This includes deciding if we should `/quest-plan` for suggested follow-ups. +Suggested follow-ups do not hold the merge; once the PR merges, offer `/quest-plan` for them. A background agent that cannot prompt lists its decisions and suggested follow-ups in its report instead. diff --git a/assets/skills/spawn.md b/assets/skills/spawn.md index 1e1a9af6..587232d6 100644 --- a/assets/skills/spawn.md +++ b/assets/skills/spawn.md @@ -42,7 +42,7 @@ As each agent reports, explain its result in a few lines, then ask about its PR - skip: If the PR should not be merged yet. - `/quest-delete`: If the quest should be deleted. -Once a `/quest-merge` sub-agent reports its PR merged, offer `/quest-plan` for that PR's suggested follow-ups. +Once a PR merges, offer `/quest-plan` for the suggested follow-ups its `/quest-merge` sub-agent reported. Include quest context, as many quests are concurrently in flight. Run each selected `/quest-ready`, `/quest-merge`, or `/quest-iterate` in a background sub-agent with its own isolated worktree, as for `/quest-start`.