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/.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/AGENTS.md b/AGENTS.md index a30ffe18e..50aa4e8a8 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 a compile error with a source span, never a warning, a silent fallback, or a runtime failure. Generated code panics only where the Rust source does. +- An unsupported construct or malformed input is a compile error with a source span, never a warning, a silent fallback, or a runtime failure. Generated code panics only where the Rust source does. - 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. - Everything is configless, with opinionated names and defaults. 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. - A vanity rename, if ever supported, is opt-in and lives inline in source next to the item, never in a config file. -- 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. -- 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. +- moq is the first consumer of every project here. +- Prefer upstream and maintained crates over hand-rolling. Measure before claiming an improvement over them. # 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 any work, run `quest context` and follow it. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d09a31cb6..c6df1b948 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/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..358cbd7fa 100644 --- a/flake.lock +++ b/flake.lock @@ -62,20 +62,37 @@ ], "nixpkgs": [ "nixpkgs" - ] + ], + "quest-pinned": "quest-pinned" + }, + "locked": { + "lastModified": 1793993537, + "narHash": "sha256-P6TNDveeSpho3IWopGjTyIb3l5MlgyWq6WPsZXewUVI=", + "owner": "moq-dev", + "repo": "quest", + "rev": "a3789c7bd7197089d40bb540517b1323f4d40fab", + "type": "github" }, + "original": { + "owner": "moq-dev", + "repo": "quest", + "rev": "a3789c7bd7197089d40bb540517b1323f4d40fab", + "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..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/dc8008bc9e846a206403b1b738ede19fdd797f5e"; + url = "github:moq-dev/quest/a3789c7bd7197089d40bb540517b1323f4d40fab"; inputs.nixpkgs.follows = "nixpkgs"; inputs.flake-utils.follows = "flake-utils"; };