From 1f07e4bc9e890f1c5369937a4dbdd4ab1111ee6b Mon Sep 17 00:00:00 2001 From: Hiroshi Shinaoka Date: Sat, 8 Aug 2026 18:34:16 +0200 Subject: [PATCH] rules: add shared agent-consumers policy for downstream users of libraries Adds rules/common/agent-consumers.md distilling the enforcement patterns proven in tenferro-rs (PRs #1625, #1632-#1635): bundled downstream-usage skills with a pre-PR freshness gate, remedy clauses in error messages, pre-publish package-index metadata checks, and verified llms.txt indexes. Links the file from rules/index.md and extends the loading policy. Closes #7 Co-Authored-By: Claude Fable 5 --- rules/common/agent-consumers.md | 85 +++++++++++++++++++++++++++++++++ rules/index.md | 7 +++ 2 files changed, 92 insertions(+) create mode 100644 rules/common/agent-consumers.md diff --git a/rules/common/agent-consumers.md b/rules/common/agent-consumers.md new file mode 100644 index 0000000..e5ea4e8 --- /dev/null +++ b/rules/common/agent-consumers.md @@ -0,0 +1,85 @@ +# Agents As Consumers Of Tensor4all Libraries + +The other rule files address agents that change tensor4all code. This file +addresses repository work that serves the opposite side: humans and coding +agents that discover a tensor4all library, learn it cold, call it correctly on +the first try, and self-correct from its errors. These rules exist because +agents amplify both directions: good agent-facing surfaces are exercised far +more often than human documentation, and misleading ones fail far more often. + +Each policy below names the check that guards it. A policy without a failing +check is a suggestion; prefer landing the check in the same change as the +policy. + +## Ship A Downstream-Usage Skill + +- Every user-facing library repository ships a downstream-usage skill in the + Agent Skills format (a `SKILL.md` with YAML frontmatter plus a `references/` + directory for detail files), covering: which package or crate to depend on + for which task, the imports or preludes needed before the first call, the + layout and indexing conventions that produce silently wrong answers when + guessed (memory order, index base, tolerance semantics), performance idioms + (what to construct once and reuse, what to compile once and run many times), + and known first-try failure modes with their fixes. +- The skill addresses users of the library. Contribution workflows (issue + intake, PR conventions, release steps) belong in separate skills. +- Bundle the skill in the repository and link it from the README with one + sentence saying when to load it. The README is the package registry landing + page, so an in-repo skill linked from the README is reachable from + crates.io or the registry without any external distribution. +- Compilable snippets inside the skill go through the repository's snippet + verification mechanism, the same one that guards guides and tutorials. A + stale skill is worse than none: agents copy it without skepticism. +- Guard: the repository's pre-PR checklist requires that a change to public + API surface, feature flags, package boundaries, or documented idioms + reviews the shipped skills and updates them in the same PR, mirroring the + design-document freshness rule. + +## Name The Remedy In Error Messages + +- When a documented alternative API, explicit conversion, feature flag, or + supported-value set provides one reliable remediation, the error message + appends it to the diagnosis as `; `. +- Do not invent a remedy when no universal next action exists; a precise + parameterized diagnosis is correct on its own for genuinely open-ended + failures. +- The error string is the primary self-correction input for an agent. A + remedy clause turns a failed run into a one-step fix; a bare diagnosis + sends the agent to training-data guesswork. +- Guard: repository error-message rules cite this policy, and review of new + or changed error variants checks for an applicable remedy. + +## Require Package-Index Metadata Before Publication + +- Before a package is published, its manifest carries the fields that make it + discoverable and fully documented on the package index: keywords and + categories (or the registry's equivalents), the minimum supported language + version, and documentation-build configuration. +- For Rust, docs.rs builds default features only; feature-gated public API is + invisible without `[package.metadata.docs.rs]` (`all-features = true`, or + an explicit feature list when features are mutually exclusive). An agent + that reads the hosted docs concludes an undocumented feature-gated API does + not exist. Julia packages apply the General registry and docs-hosting + equivalents. +- Guard: a pre-publish layout check fails when these fields are missing, + rather than relying on a checklist read at release time. + +## Publish A Verified llms.txt Index + +- A user-facing documentation site publishes `llms.txt` at its root: a + Markdown list of the authoritative pages, each with a one-line description, + so an agent can replace crawling with a single fetch. Include the + downstream-usage skill in the list. +- Prefer generating the page list from the site manifest. Where it is + maintained by hand, a check must verify that every listed page exists and + every authoritative page is listed, so the index cannot drift silently. +- Guard: the docs-site check resolves every `llms.txt` entry and fails the + build on a broken or missing entry. + +## Validate From The Consumer's Seat + +- The proof that these surfaces work is the source-blind build test defined + in [`docs-and-tests.md`](docs-and-tests.md): a doc-only agent writes a + minimal integration from the published docs and skill alone, and that code + is compile-checked against the real project. Run it when introducing or + substantially revising a usage skill, quickstart, or llms.txt index. diff --git a/rules/index.md b/rules/index.md index eb2c325..ffecd1c 100644 --- a/rules/index.md +++ b/rules/index.md @@ -15,6 +15,10 @@ load language-specific rules when the task touches that language. third-party code in the source, copyright compliance for ports and translations, scientific credit via provenance and citation policies, and permission-gated upstream bug feedback. +- [`common/agent-consumers.md`](common/agent-consumers.md): serving downstream + users and coding agents of user-facing libraries: bundled usage skills, + remedy clauses in error messages, package-index metadata gates, and + verified llms.txt indexes. ## Rust @@ -36,6 +40,9 @@ load language-specific rules when the task touches that language. - Do not bulk-load the entire repository by default. - Load common rules for any cross-repository implementation work. +- Load agent-consumers rules when working on docs sites, packaging or release + metadata, error messages, usage skills, or README quickstarts of a + user-facing library. - Load Rust rules for Rust crates, C API layers, backend code, or Rust docs. - Load Julia rules for Julia packages, wrappers, examples, or docs. - If project-local rules conflict with these shared rules, follow the more