From e0a996f17da5f6950fdfff1c5c1b46aa899be920 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 13:25:58 -0800 Subject: [PATCH 1/3] docs(agents): rely on quest context for shared rules Bump the quest input to moq-dev/quest@9277dc34, which adds `quest context`: the shared engineering rules plus a Prompting section. AGENTS.md keeps only the rules specific to rust2 and points at `quest context` and `quest guide`. PROMPTING.md goes away; the prompting rule now points at Prompting in `quest context`. Co-Authored-By: Claude Opus 5.5 --- .claude/rules/prompting.md | 3 +-- AGENTS.md | 51 +++----------------------------------- PROMPTING.md | 45 --------------------------------- flake.lock | 44 ++++++++++++++++++++++++++++---- flake.nix | 2 +- 5 files changed, 45 insertions(+), 100 deletions(-) delete mode 100644 PROMPTING.md diff --git a/.claude/rules/prompting.md b/.claude/rules/prompting.md index e373e9495..4615526fe 100644 --- a/.claude/rules/prompting.md +++ b/.claude/rules/prompting.md @@ -2,8 +2,7 @@ paths: - "**/AGENTS.md" - "CONTRIBUTING.md" - - "PROMPTING.md" - ".claude/skills/**" --- -Before editing this file, read `PROMPTING.md` at the repository root and apply it. +Before editing this file, follow Prompting in `quest context`. diff --git a/AGENTS.md b/AGENTS.md index e964b7694..c1056a22e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,62 +1,19 @@ rust2 holds Rust tools that take Rust somewhere else: to TypeScript through an own rustc driver, to any language through a fork of UniFFI, and to faster builds for a pure-Rust subset. Each project lives in its own top-level directory; the [quest tree](quest/README.md) says what each is doing now. -# Context - -- Read `CONTRIBUTING.md` when dealing with PRs. -- Read `PROMPTING.md` before instructing other agents via context, memory, plans, or reviews. -- Before editing, read each `AGENTS.md` along the path from the root to the file. Use `rg --files -g AGENTS.md` to find them. - # Required -- Pull the latest origin changes before working. -- Dig into the root cause and fix it at the source. Never work around a fixable bug with a retry, sleep, or timeout, nor pass a flaky test by loosening its assertion. -- Fail loud and early. An unsupported construct or malformed input is an error with a source span, never a warning or a silent fallback. +- An unsupported construct or malformed input is an error with a source span, never a warning or a silent fallback. - Generated output must match the source's semantics exactly: integer widths and overflow, drop order, laziness, and error paths. Prove it with differential tests against native Rust, not by inspection. -- Reproduce bugs before fixing them. Tests must be worth their weight long-term: cover edge cases, not old bugs or trivial values. -- Keep the PR to one problem: no unrelated refactors, formatting churn, or drive-by changes. Fix every instance of that problem in the same PR. -- Land the ideal implementation now rather than a partial one plus follow-ups; split off only work that is independently landable. -- Be adversarial: attack your own approach, reports, reviews, and other PRs as hard as anyone else's. -- When a decision is the maintainer's (API shape, naming, scope) or you are unsure, ask with an interactive prompt of 2-3 options and a recommendation. -- Every test runs in CI, at least nightly. The merge gate holds only fast, high-signal tests. -- Never add or change a rule in an `AGENTS.md`, `CONTRIBUTING.md`, or skill without being prompted, and read `PROMPTING.md` first. -- No em dashes. -- Match the existing conventions, patterns, and naming when possible. -- Fix any outdated docs and comments inline. -- Add the AI marker `(Written by )` to any posts on GitHub, excluding commit messages that contain `Co-Authored-By:` trailers. -- AI comments carry no maintainer authority and may be challenged. -- This repo is public: never mention customers, partners, or prospects, or link to private repos. - -# Guidelines - -- Prefer upstream and maintained crates over hand-rolling. Measure before claiming an improvement over them. -- Every change needs a consumer that uses it now and is worth its cost; name it in the PR. moq is the first consumer of every project here. - Translators take stock crates as they are: no annotations, and no config beyond true platform boundaries. Each config key or source change a consumer needs is a gap to close. -- Deleting code is better than adding code. -- Comments explain the non-obvious why, never the history. -- New dependencies use the newest stable version. Do not bump package versions unless asked. -- Record out-of-scope follow-ups as quests, never GitHub issues. -- Prefer the net simpler result, and say what was dropped. -- Say it once, in the fewest words that hold up. -- Recognize when you're stuck or making minimal progress, and stop early. -- Add or extend a benchmark for any performance-sensitive change, and measure optimizations instead of relying on intuition. - -# Public API - -- Report the public API impact of every change in the PR description. +- moq is the first consumer of every project here. +- Prefer upstream and maintained crates over hand-rolling. Measure before claiming an improvement over them. - A breaking change adds an entry under `## Unreleased` in the affected package's `MIGRATE.md`. -- Keep things private until a consumer needs them. -- Never add `foo_with_x`, `foo_checked`, or a compatibility shim. Make the breaking change to `foo` instead. -- Name by role, not today's implementation. Short names under a module namespace. -- Document every exported symbol in one plain line. # Development PRs target `main`. -Use the Nix dev shell so tooling matches CI. -direnv loads it automatically, but if not: `nix develop --command ...`. - ```bash just check # Lint what the branch changed, including the quest tree just test # Test what the branch changed @@ -64,4 +21,4 @@ just ci # Both, as the merge queue runs them; run before every push just fix # Auto-fix formatting ``` -Quests: before starting work, run `quest guide` and follow it. +Quests: before starting work, run `quest context` and `quest guide`, and follow both. diff --git a/PROMPTING.md b/PROMPTING.md deleted file mode 100644 index 36f7956fb..000000000 --- a/PROMPTING.md +++ /dev/null @@ -1,45 +0,0 @@ -Read this before indirectly instructing agents. - -LLMs are not trained on how to write prompts. -They're trained on the outputs, not the inputs, and thus generate slop when chained. -So when you're drafting instructions for a future agent, please keep these rules in mind. - -# General - -**Do not over-prescribe**. -The facts will evolve over time. - -Focus on articulating the goal and/or root problems. -Keep things flexible so an agent can adjust as it digs deeper into the possible problems or solutions. - -You can (and should) include recommendations. -But focus on best-practices and things to look out for, not specific lines of code. -Mocking up an API makes a lot of sense but again, it should be flexible enough to adjust with the implementation. - -# Context - -This includes editing any `AGENTS.md`, `CONTRIBUTING.md`, etc. - -These files need to be light because they're loaded into every prompt. -More specific context (ex. per language or project) should exist in optional files/folders. - -These base prompts are meant to fix regular agent mistakes. -If there is a history of bad practices, or sub-optimal behavior, update `AGENTS.md` to steer away from them. -If you think a slight tweak to the base prompt would help, propose it. - -Focus on best practices and conventions. -Don't document the repository; the code and documentation can handle that. - -Before changing agent-instruction files, check the relevant official Claude/Codex guidance: - -- -- -- -- -- -- - -# Skills - -Skills are meant to avoid repeated duplicate prompts. -If the usage of a skill is unclear, offer to update to skill to reduce the ambiguity. diff --git a/flake.lock b/flake.lock index a856ffce5..f6185c3fe 100644 --- a/flake.lock +++ b/flake.lock @@ -55,6 +55,22 @@ "type": "github" } }, + "nixpkgs-opencode": { + "locked": { + "lastModified": 1792116957, + "narHash": "sha256-EjZqHKObBfIOeHZnMRVV87HB3pPq/WBkmRJWyFxmZu8=", + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "f20cd90e28fe0403873f473b29e42662cd86e8c4", + "type": "github" + }, + "original": { + "owner": "NixOS", + "repo": "nixpkgs", + "rev": "f20cd90e28fe0403873f473b29e42662cd86e8c4", + "type": "github" + } + }, "quest": { "inputs": { "flake-utils": [ @@ -62,20 +78,38 @@ ], "nixpkgs": [ "nixpkgs" - ] + ], + "nixpkgs-opencode": "nixpkgs-opencode", + "quest-pinned": "quest-pinned" + }, + "locked": { + "lastModified": 1793740032, + "narHash": "sha256-I8iU2ySg7gyCsUnKopVyyJ2lVH21awBwoEPETXAyvaM=", + "owner": "moq-dev", + "repo": "quest", + "rev": "9277dc3413c9297ba12326e5ae4abeff7f2ff6be", + "type": "github" }, + "original": { + "owner": "moq-dev", + "repo": "quest", + "rev": "9277dc3413c9297ba12326e5ae4abeff7f2ff6be", + "type": "github" + } + }, + "quest-pinned": { + "flake": false, "locked": { - "lastModified": 1793429482, - "narHash": "sha256-C2zcd/wLcc5kC/nZiuviIAMgpoCMJRc2JzYEQno2EHA=", + "lastModified": 1793721754, + "narHash": "sha256-pPsXWcv0LdYqW5bRYx7Av6urjcRTC3bGRWh8BGwO0Ug=", "owner": "moq-dev", "repo": "quest", - "rev": "dc8008bc9e846a206403b1b738ede19fdd797f5e", + "rev": "2aa60a2d6676147314e725b0410882128eacea49", "type": "github" }, "original": { "owner": "moq-dev", "repo": "quest", - "rev": "dc8008bc9e846a206403b1b738ede19fdd797f5e", "type": "github" } }, diff --git a/flake.nix b/flake.nix index aa5bbc702..cb5d3b709 100644 --- a/flake.nix +++ b/flake.nix @@ -11,7 +11,7 @@ # The quest CLI, which also serves the quest guide and skills the stubs in # .claude/skills call. Bump the rev to upgrade them. quest = { - url = "github:moq-dev/quest/dc8008bc9e846a206403b1b738ede19fdd797f5e"; + url = "github:moq-dev/quest/9277dc3413c9297ba12326e5ae4abeff7f2ff6be"; inputs.nixpkgs.follows = "nixpkgs"; inputs.flake-utils.follows = "flake-utils"; }; From cf0736bc7d3f254f68a1982bda9d3807b8717d29 Mon Sep 17 00:00:00 2001 From: Luke Curley Date: Tue, 3 Nov 2026 14:03:16 -0800 Subject: [PATCH 2/3] docs(agents): run only quest context before any work quest#460 moved the rules every task needs into `quest context`; `quest guide` is now only for quest work, and the context says when to run it. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 2 +- CONTRIBUTING.md | 2 +- flake.lock | 8 ++++---- flake.nix | 2 +- 4 files changed, 7 insertions(+), 7 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index c1056a22e..9a23615dd 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -21,4 +21,4 @@ just ci # Both, as the merge queue runs them; run before every push just fix # Auto-fix formatting ``` -Quests: before starting work, run `quest context` and `quest guide`, and follow both. +Quests: before any work, run `quest context` and follow it. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 02133f1f0..ebfbecba7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -32,7 +32,7 @@ The admin bypass of `main`'s ruleset is for emergencies. # Reviews -Review each PR locally with `/quest-review`, as the quest guide describes; merging never waits on an online reviewer, and never request one. +Review each PR locally with `/quest-review`, as `quest context` describes; merging never waits on an online reviewer, and never request one. The PR body's `## Review` record counts as the required review when it names the head being merged, and so does a recorded skip of a change too trivial to review. Address online reviewers' findings already posted on that head before merging: fix them, or reply where you disagree. diff --git a/flake.lock b/flake.lock index f6185c3fe..df304516b 100644 --- a/flake.lock +++ b/flake.lock @@ -83,17 +83,17 @@ "quest-pinned": "quest-pinned" }, "locked": { - "lastModified": 1793740032, - "narHash": "sha256-I8iU2ySg7gyCsUnKopVyyJ2lVH21awBwoEPETXAyvaM=", + "lastModified": 1793742983, + "narHash": "sha256-ihz9DSXQjTcv9ja066Ndiu5wTc8h6Jf71KFzjCKiPFM=", "owner": "moq-dev", "repo": "quest", - "rev": "9277dc3413c9297ba12326e5ae4abeff7f2ff6be", + "rev": "4be350816f2a5c1157f799773ee1594f199fd9a7", "type": "github" }, "original": { "owner": "moq-dev", "repo": "quest", - "rev": "9277dc3413c9297ba12326e5ae4abeff7f2ff6be", + "rev": "4be350816f2a5c1157f799773ee1594f199fd9a7", "type": "github" } }, diff --git a/flake.nix b/flake.nix index cb5d3b709..481bda69b 100644 --- a/flake.nix +++ b/flake.nix @@ -11,7 +11,7 @@ # The quest CLI, which also serves the quest guide and skills the stubs in # .claude/skills call. Bump the rev to upgrade them. quest = { - url = "github:moq-dev/quest/9277dc3413c9297ba12326e5ae4abeff7f2ff6be"; + url = "github:moq-dev/quest/4be350816f2a5c1157f799773ee1594f199fd9a7"; inputs.nixpkgs.follows = "nixpkgs"; inputs.flake-utils.follows = "flake-utils"; }; From 865fe4e98c26d0aa92b48a20a7539f1b021af7db Mon Sep 17 00:00:00 2001 From: Luke Curley <432854+kixelated@users.noreply.github.com> Date: Fri, 6 Nov 2026 13:12:42 -0800 Subject: [PATCH 3/3] chore: bump quest to a3789c7b and refresh its skill stubs Co-Authored-By: Claude Opus 5.5 --- .claude/skills/quest-merge/SKILL.md | 2 +- .claude/skills/quest-review/SKILL.md | 2 +- .claude/skills/quest-unblock/SKILL.md | 7 +++++++ flake.lock | 25 ++++--------------------- flake.nix | 2 +- 5 files changed, 14 insertions(+), 24 deletions(-) create mode 100644 .claude/skills/quest-unblock/SKILL.md diff --git a/.claude/skills/quest-merge/SKILL.md b/.claude/skills/quest-merge/SKILL.md index c03a0d849..156d4aba3 100644 --- a/.claude/skills/quest-merge/SKILL.md +++ b/.claude/skills/quest-merge/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-merge -description: Queue a reviewed PR to land, or send it to /quest-iterate. +description: Queue a PR to land, running /quest-iterate first when it needs work. --- Run `quest skill merge` and follow its output. diff --git a/.claude/skills/quest-review/SKILL.md b/.claude/skills/quest-review/SKILL.md index 41fd63bc1..84906a4c5 100644 --- a/.claude/skills/quest-review/SKILL.md +++ b/.claude/skills/quest-review/SKILL.md @@ -1,6 +1,6 @@ --- name: quest-review -description: Review a PR's branch locally with the other vendor's model, then mark it ready for review. +description: Review a PR's branch locally with a model that wrote none of it, then mark it ready for review. --- Run `quest skill review` and follow its output. diff --git a/.claude/skills/quest-unblock/SKILL.md b/.claude/skills/quest-unblock/SKILL.md new file mode 100644 index 000000000..725d29bd1 --- /dev/null +++ b/.claude/skills/quest-unblock/SKILL.md @@ -0,0 +1,7 @@ +--- +name: quest-unblock +description: Walk the maintainer through every quest and draft PR waiting on them, and clear waits that have resolved. +--- + +Run `quest skill unblock` and follow its output. +If `quest` is not installed, follow https://github.com/moq-dev/quest/blob/main/SETUP.md first. diff --git a/flake.lock b/flake.lock index df304516b..358cbd7fa 100644 --- a/flake.lock +++ b/flake.lock @@ -55,22 +55,6 @@ "type": "github" } }, - "nixpkgs-opencode": { - "locked": { - "lastModified": 1792116957, - "narHash": "sha256-EjZqHKObBfIOeHZnMRVV87HB3pPq/WBkmRJWyFxmZu8=", - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "f20cd90e28fe0403873f473b29e42662cd86e8c4", - "type": "github" - }, - "original": { - "owner": "NixOS", - "repo": "nixpkgs", - "rev": "f20cd90e28fe0403873f473b29e42662cd86e8c4", - "type": "github" - } - }, "quest": { "inputs": { "flake-utils": [ @@ -79,21 +63,20 @@ "nixpkgs": [ "nixpkgs" ], - "nixpkgs-opencode": "nixpkgs-opencode", "quest-pinned": "quest-pinned" }, "locked": { - "lastModified": 1793742983, - "narHash": "sha256-ihz9DSXQjTcv9ja066Ndiu5wTc8h6Jf71KFzjCKiPFM=", + "lastModified": 1793993537, + "narHash": "sha256-P6TNDveeSpho3IWopGjTyIb3l5MlgyWq6WPsZXewUVI=", "owner": "moq-dev", "repo": "quest", - "rev": "4be350816f2a5c1157f799773ee1594f199fd9a7", + "rev": "a3789c7bd7197089d40bb540517b1323f4d40fab", "type": "github" }, "original": { "owner": "moq-dev", "repo": "quest", - "rev": "4be350816f2a5c1157f799773ee1594f199fd9a7", + "rev": "a3789c7bd7197089d40bb540517b1323f4d40fab", "type": "github" } }, diff --git a/flake.nix b/flake.nix index 481bda69b..5ce449df3 100644 --- a/flake.nix +++ b/flake.nix @@ -11,7 +11,7 @@ # The quest CLI, which also serves the quest guide and skills the stubs in # .claude/skills call. Bump the rev to upgrade them. quest = { - url = "github:moq-dev/quest/4be350816f2a5c1157f799773ee1594f199fd9a7"; + url = "github:moq-dev/quest/a3789c7bd7197089d40bb540517b1323f4d40fab"; inputs.nixpkgs.follows = "nixpkgs"; inputs.flake-utils.follows = "flake-utils"; };