Skip to content

docs(AGENTS.md): make just the only build/test surface for agents - #1115

Merged
norrietaylor merged 3 commits into
mainfrom
docs/agents-just-only
Jul 31, 2026
Merged

docs(AGENTS.md): make just the only build/test surface for agents#1115
norrietaylor merged 3 commits into
mainfrom
docs/agents-just-only

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Jul 30, 2026

Copy link
Copy Markdown
Member

Why

The Platform matrix said minimald "does not build" on macOS. Read literally that is
true only of a native build — and agents took it as licence to declare daemon-side work
unverifiable on a Mac, or to hand-roll cargo invocations around the scoping. just test-cross already cross-compiles --workspace --exclude minvmd to musl in Docker and
runs its tests, so minimald and the min CLI's test targets (whose dev-dependencies
pull minimald) are reachable from macOS.

What changed

  • Platform matrix: the native-only limit stated as such, with just test-cross named
    as the macOS answer for everything the darwin scope skips. Pre-PR verification now says
    outright that a minimald / CLI-test change is unverified until it has run.
  • just-only rule, stated once at the top of the matrix: the recipes carry the per-OS
    scoping, the pinned flags, and the ordering constraints (the macOS codesign most
    sharply); a hand-rolled cargo line drops them silently. No recipe for a task → add one.
  • The two raw-cargo instructions are gone: the cargo test -p <crate> inner loop and
    the cargo clippy --allow-dirty --fix … variant are now just test and just fix
    which are exactly those commands, already scoped for the host.
  • Recipe descriptions no longer quote runnable cargo lines; an agent copies what it sees.

Inventory refresh (drive-by)

The recipe count and list had both fallen nine behind the justfile. Now 42 on Linux / 37 on
macOS (verified against just --summary plus the [linux]/[macos] attributes: six
Linux-only recipes, one macOS-only), with fix, lint-shell, msrv, miri, fuzz,
fuzz-check, test-promote-gate, stress, bulk-upload, and kernel-review documented.

Not touched

CONTRIBUTING.md:63 still pairs cargo test --workspace --doc with just doctest in its
CI-mapping table. That is a human-facing cross-reference, not an agent instruction — say
the word if you want it collapsed to the recipe too.

Docs only; no code paths affected.

🤖 Generated with Claude Code

Note

Update AGENTS.md to make just recipes the sole build and test surface

Updates AGENTS.md to establish just recipes as the canonical workflow for building and testing, replacing direct cargo commands throughout.

  • Clarifies per-OS scoping: Linux runs the full workspace natively; macOS runs the session stack via just ci and Linux-only crates via just test-cross
  • Adds documentation for new recipes: fix, test-promote-gate, lint-shell, msrv, miri, fuzz-check, fuzz, stress, bulk-upload, and kernel-review
  • Updates recipe counts to 42 on Linux and 37 on macOS, and notes OS-specific recipe visibility
  • Expands the footguns section to note that changes touching minimald or min CLI tests are unverified on macOS until just test-cross runs

Changes since #1115 opened

  • Replaced manual enumeration of justfile recipes with directive to run just --list or bare just for auto-generated, OS-scoped recipe list [b10f422]
  • Removed detailed subsections documenting CI-parity gates, e2e/test harnesses, stack bring-up, and build artifacts along with their per-recipe descriptions [b10f422]
  • Retained note about justfile mirroring CI workflows and clarified OS-scoped attribute filtering for recipe visibility [b10f422]
  • Added warning that just soak reaps between iterations and terminates the checkout's live dev stack, noting this may not surface in just --list output [b10f422]
  • Reworked comments throughout justfile to follow the convention that just --list displays only the last comment line above each recipe as a standalone summary, moving detailed rationale and warnings into preceding comment blocks [f71f5e2]
  • Removed warning paragraph from documentation stating that just soak reaps between iterations and terminates the checkout's live dev stack each pass [f71f5e2]

Macroscope summarized 0b398f4.

Summary by CodeRabbit

  • Documentation
    • Updated contributor guidance for platform-specific builds and tests.
    • Added instructions for stress testing, bulk-upload testing, and kernel review workflows.
    • Clarified macOS testing guidance and recommended pre-PR validation commands.

The platform matrix read as "macOS cannot build or test minimald", which
is only true of a *native* build: `just test-cross` cross-compiles the
whole workspace (minus minvmd) to musl in Docker and runs its tests, so
the daemon and the CLI's test targets are reachable from a Mac. Agents
took the old wording as licence to skip that coverage, or to hand-roll
cargo invocations around it.

- State the native-only limit, then name `just test-cross` as the macOS
  answer for everything the darwin scope skips, and say plainly that a
  minimald / CLI-test change is unverified until it has run.
- Add the just-only rule: the recipes carry the per-OS scoping, the
  pinned flags, and the ordering constraints (the macOS codesign, most
  sharply); a hand-rolled cargo line drops them silently. If a task has
  no recipe, add one.
- Replace the two remaining raw-cargo instructions — the `cargo test -p
  <crate>` inner loop and the `cargo clippy --allow-dirty --fix` variant
  — with `just test` and `just fix`, which are those commands, scoped.
- Stop quoting runnable cargo lines in the recipe descriptions; they read
  as commands to copy.

Refresh the recipe inventory while here: the count (33) and the list had
both fallen nine recipes behind the justfile. Now 42 on Linux / 37 on
macOS, with fix, lint-shell, msrv, miri, fuzz, fuzz-check,
test-promote-gate, stress, bulk-upload, and kernel-review documented.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@norrietaylor
norrietaylor requested a review from a team as a code owner July 30, 2026 23:56
@coderabbitai

coderabbitai Bot commented Jul 30, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Updated AGENTS.md with expanded platform-specific workflows, revised justfile recipe documentation, additional validation harnesses, kernel review guidance, and scoped pre-PR commands.

Changes

Workflow guidance

Layer / File(s) Summary
Platform-scoped build and test workflows
AGENTS.md
Build and test instructions now use scoped just recipes and document test-cross coverage for Linux-only crates and CLI tests.
Recipe catalog and validation commands
AGENTS.md
Recipe counts and descriptions now include fixing, CI checks, fuzzing, stress, bulk upload, and kernel review commands.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

Suggested reviewers: twitchyliquid64

Poem

A rabbit hops through recipes bright,
With just commands lined up right.
Cross-platform tests thump and run,
Stress and uploads join the fun.
Kernel notes now guide the way—
Fresh instructions for review day!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The description explains the changes well but omits the required Summary, Testing, and Checklist sections, including test commands and evidence. Add the required Summary, Testing, and Checklist sections, and include the commands run with relevant output or state why testing was not applicable.
✅ Passed checks (4 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title clearly and concisely describes the main documentation change and follows the required Conventional Commit format.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch docs/agents-just-only

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai 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.

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@AGENTS.md`:
- Around line 118-119: Update the recipe-count explanation in the documentation
so it is arithmetically consistent: either change “six” to “five” to describe
the net difference, or explicitly explain that six Linux-only recipes are
replaced by one macOS-only test-cross recipe.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: d8b77371-5244-4f99-b0c8-5304935f5b56

📥 Commits

Reviewing files that changed from the base of the PR and between 957c076 and 0b398f4.

📒 Files selected for processing (1)
  • AGENTS.md

Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
Comment thread AGENTS.md Outdated
norrietaylor and others added 2 commits July 30, 2026 21:07
…ventory

Per review: the recipe count and the four enumerated recipe lists were both
going to go stale, and the lists gobble context for no gain — `just --list`
already prints every recipe available on the host, each with its own
description, generated from the justfile.

- Drop the "42 on Linux / 37 on macOS" count. It moots the arithmetic
  CodeRabbit flagged (five vs six) by removing the claim rather than
  correcting a number that changes every time a recipe lands.
- Drop the four enumerated lists (CI-parity gates, e2e & harnesses, stack
  bring-up, build artifacts): 53 lines that restate `just --list`.
- Keep what the generated list cannot carry: the justfile/CI-twin
  relationship, the `.scratch/` scoping rule, and the `just soak` warning.

That last one is kept deliberately. `just --list` renders only the *last*
comment line above a recipe, so soak's leading
"# Reaps between iterations — this WILL kill this checkout's live dev stack"
never reaches the listing; only the trailing description does.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
`just --list` renders only the LAST comment line above a recipe, so any
multi-line block loses everything before its final line. Eleven captions
were unusable as a result:

- Mid-sentence fragments: `fix` ("usual case here is running mid-edit
  with staged/unstaged work."), `lint-shell`, `test-promote-gate`,
  `test-root-integration`.
- CI pointers standing in for a description: `clippy`, `deny`,
  `fmt-check`, `miri`, `msrv`, `e2e-native`.
- Dropped warning: `soak` led with "reaps between iterations — this WILL
  kill this checkout's live dev stack" and ended on the neutral line, so
  the listing showed only the harmless half.

Reorder each block to the convention the rest of the file already uses —
rationale and CI pointers first, a bare `#`, then a one-line summary —
and fold soak's warning into its summary. No recipe body changes.

State the convention in the justfile header so it stops regressing, and
drop the AGENTS.md paragraph that existed only to carry soak's warning
past the listing: the caption carries it now.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@norrietaylor
norrietaylor merged commit 4fb9b1e into main Jul 31, 2026
30 checks passed
@norrietaylor
norrietaylor deleted the docs/agents-just-only branch July 31, 2026 04:26
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.

3 participants