From 18d92631adbd05ed8a470c0f18ebe3f801ac77bd Mon Sep 17 00:00:00 2001 From: Ahmed ElMallah Date: Sun, 25 Oct 2026 13:07:10 -0700 Subject: [PATCH] docs(agents): record criteria for plugin-author pages and developer docs The documentation style rules cover pages under docs/. Plugin-author pages, dev-docs/ARCHITECTURE.md paragraphs and AGENTS.md summaries had no written criteria, though the existing documents already follow consistent conventions. This records those conventions: - Plugin-author pages name the SDK's public API, which rule 5 would otherwise forbid, but never a CLI-internal identifier. - An ARCHITECTURE.md paragraph that carries reasoning below the ADR bar states the rule in the present tense with its reason, with no PR chronology, and links an ADR instead of restating it. - A rule AGENTS.md summarizes changes in its full-rule document in the same pull request. - The docs link check does not cover dev-docs/ or AGENTS.md, so links there are checked by review only. Co-Authored-By: Claude Opus 5.5 --- AGENTS.md | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index bba02f97..33586281 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -384,6 +384,31 @@ Mechanics that go with the rules: `commands/`, `detectors/`, `matchers/`, `auditors/`, `plugins/`, `schemas/`. +### Plugin-author and developer documentation + +The rules above apply to every page under `docs/`. Three other kinds of +document follow these conventions: + +- **Plugin-author pages** (`docs/plugins/`) differ from rule 5 in one way. + They name the SDK's public API (packages, types, methods, descriptor + fields, manifest keys, requirement tokens), because that is what an + author writes. They never name a CLI-internal identifier. +- **`dev-docs/ARCHITECTURE.md`** describes how Bomly works today. A + paragraph there carries the reasoning for a choice that does not meet the + ADR bar in [`dev-docs/adr/README.md`](dev-docs/adr/README.md). It states + the rule in the present tense, gives the reason in the same paragraph, and + names identifiers only where the reader must go. It carries no + pull-request or release chronology, and it links an ADR instead of + restating it. +- **`AGENTS.md`** summarizes some rules and names the document that holds + the full rule, as the ADR bar names `dev-docs/adr/README.md`. A change to + such a rule lands in that document in the same pull request, so the + summary never states a rule the full text lacks. + +The `Docs link check` CI job covers `docs/`, `README.md` and +`CONTRIBUTING.md`. Links in `dev-docs/` and `AGENTS.md` are checked by +review only. + ### Fuzz tests - Every new or materially changed pure in-process parser for untrusted repository, configuration, baseline, SBOM, plugin, or analyzer data must have a native Go fuzz target. (The SDK's own parsers carry their fuzz targets in the SDK repo.)