Skip to content

docs(skills): state the guide and skill rules agents kept needing - #187

Merged
kixelated merged 3 commits into
mainfrom
quest/m0/helpers/guide-rules
Oct 22, 2026
Merged

kixelated merged 3 commits into
mainfrom
quest/m0/helpers/guide-rules

Conversation

@kixelated

@kixelated kixelated commented Oct 22, 2026 •

Copy link
Copy Markdown
Collaborator

Finishes quest/m0/helpers/guide-rules.md: the guide and skills now state the rules the moq maintainer kept typing as corrections, so agents stop needing them. Prose only; no CLI changes.

Changes

  • Pushing (guide, Execution): never rebase or force-push a branch another session may hold; before each push to a branch with a PR, confirm the PR is still open, since a push after the merge brings the deleted branch back. The quest start claim push is exempt.
  • Briefs (guide, Questions): a sub-agent's brief carries the quest or PR, the user's picks, and the scope, and leaves repository rules to the repository's own instructions. The plan named spawn and complete; it lives once in the guide instead, per review, since both skills would carry it verbatim.
  • Hand-back (guide, start): a complete quest is marked ready even if the agent made choices without asking, listing them in the PR body. Only a decision left for the maintainer, or unfinished work, keeps it a draft with ## Decisions needed. Drops the start gate ("the user has settled every decision, including choices you made without asking") that disagreed with the guide.
  • Planning (plan): before anything else, search the quest tree, git history for deleted quests, and open PRs touching quest/, and show any overlap in the first round.
  • Audit (audit): moving a quest between milestones or changing its rank is always the user's decision, never a factual correction.
  • Follow-ups (guide, Creation): a follow-up becomes a quest only through /quest-plan, never as an agent-session task or a GitHub issue.
  • Reviews (guide): 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 from the maintainer's account, does not count. Helper commands still never decide this.
  • Decisions (iterate): a sub-agent that cannot prompt picks the recommendation only for decisions the repository's instructions don't reserve for the maintainer; reserved or truly consequential ones stay open in the PR.
  • Deletes the quest and its mention in quest/m0/helpers/README.md.

Choices made without asking

  • Generic wording kept the core independent of any one agent or repository: "agent-session task" instead of "session task card", and no moq example ("API shape, naming, and scope") in iterate.
  • iterate keeps its old "truly consequential" stop alongside the new reserved-decision rule, rather than dropping it.
  • The planning search names what to search, not the commands, following PROMPTING.md.
  • The follow-up rule sits in the guide's Creation section, next to the existing "search the tree and git history" rule.

Validation

just check and just test pass locally (Nix shell). quest check --base origin/main passes.

Follow-ups

None. Expect merge conflicts with the parallel PR state commands and Unattended work quests, which also edit these skills and the guide.

🤖 Generated with Claude Code

(written by Claude Opus 5.5)

kixelated and others added 2 commits October 21, 2026 22:39
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 <noreply@anthropic.com>
@kixelated kixelated changed the title Guide and skill rules agents kept needing docs(skills): state the guide and skill rules agents kept needing Oct 22, 2026
@kixelated
kixelated marked this pull request as ready for review October 22, 2026 05:45
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 22, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review 🔄 Running since 2026-10-22T06:28:48.441768Z a477407 New commits
🔒 Security Review ✅ Completed 2026-10-22T06:33:44.210653Z a477407 New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 51a0acf19d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread assets/skills/complete.md Resolved
Spawn and complete shared it verbatim; shared workflow instructions
belong in the guide.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@kixelated
kixelated merged commit 64e17aa into main Oct 22, 2026
5 checks passed
@kixelated
kixelated deleted the quest/m0/helpers/guide-rules branch October 22, 2026 06:45
@kixelated

Copy link
Copy Markdown
Collaborator Author

Merge summary for a477407:

  • The one Codex finding (the sub-agent brief rule was duplicated in spawn and complete) is fixed in a477407: the rule now lives once in the guide Questions section, and both skills are back to their main text, which also shrinks the overlap with feat(skills): keep quest work moving unattended with /quest-afk #184.
  • CI passes on the head. quest check --base origin/main --branch quest/m0/helpers/guide-rules, run with a quest built from main, reports 47 documents ok; just check and just test pass locally.
  • The Codex review of 51a0acf counts as this PR review; the only change since moves that one line to address it, so the Codex re-review is not awaited.
  • No decisions are open and no follow-ups are suggested.

Auto-merge (squash) is enabled for a477407.

(written by Claude Opus 5.5)

kixelated added a commit that referenced this pull request Oct 22, 2026
Resolve the conflict with #187 by dropping both finished quests (Unattended
work and Guide rules) from the helpers epic's Required list.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
kixelated added a commit that referenced this pull request Oct 22, 2026
Resolve conflicts with the guide rules (#187) and /quest-afk (#184):
drop the helpers epic's links to the now-finished pr-states, afk, and
guide-rules quests, and rename the PR state commands' token printer so
it no longer shadows claims' `held`.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant