Skip to content

docs(agents): hold ADR requests to the bar, and record criteria for plugin-author and developer docs - #534

Merged
bomly-guy merged 3 commits into
mainfrom
claude/adr-bar-precedence
Oct 25, 2026
Merged

bomly-guy merged 3 commits into
mainfrom
claude/adr-bar-precedence

Conversation

@bomly-guy

@bomly-guy bomly-guy commented Oct 25, 2026 •

Copy link
Copy Markdown
Collaborator

Two changes to bomly-cli's documentation guidance, combined from #534 and #535.

An ADR request is still held to the bar

  • The rule: an issue, plan or acceptance checklist that asks for an ADR is asking for the decision to be recorded, not for a new file. The three-part bar still decides.
    • If the decision fails the bar, the reasoning goes in a code comment or dev-docs/ARCHITECTURE.md, and the pull request says so.
    • If it passes, revise the live record that owns the topic, and start a new one only when none does.
  • Where it goes: the shared ADR section of AGENTS.md, and dev-docs/adr/README.md, which that section names as the full rule.
  • Why: the planning#51 issues were written before the ADR cleanup and asked for ADRs. Following them produced ADR-0050 and ADR-0051, which failed the bar and were folded back into ADR-0020 and ARCHITECTURE.md in feat: preflight declared component requirements and disclose plugin access #531.
  • The AGENTS.md section is shared, so it changes together with the companion PR docs(agents): an ADR request in an issue or plan is still held to the bar bomly-sdk#122.

Criteria for plugin-author and developer docs

A docs review of #531 found no written criteria for three kinds of document. These are taken from what the existing documents already do:

  • Plugin-author pages: they may name SDK API, which is the one exception to style rule 5.
  • dev-docs/ARCHITECTURE.md paragraphs: present tense, with the reason given beside the rule, and no chronology.
  • AGENTS.md summaries: a summarized rule lands in its full document in the same pull request.

It also states that links in dev-docs/ and AGENTS.md are checked by review only.

🤖 Generated with Claude Code

… bar

Issues written before the ADR cleanup ask for "an ADR under dev-docs/adr"
in their acceptance lists, and an agent following them wrote two records
(bomly-cli ADR-0050 and ADR-0051) that failed the bar and were folded
back into ADR-0020 and ARCHITECTURE.md in bomly-cli#531. The rule now
says such a request asks for the decision to be recorded, not for a new
file: the bar still decides, and a passing decision revises the live
record that owns the topic first. The same section appears in both
repositories and changes in both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 25, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-25T20:19:02.027448Z b46624a New commits
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@coderabbitai

coderabbitai Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 20 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration
Commits

Reviewing files that changed from the base of the PR and between 67be1d0 and b46624a.

Files selected for processing: 2
  • AGENTS.md
  • dev-docs/adr/README.md
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

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

@github-actions

github-actions Bot commented Oct 25, 2026 •

Copy link
Copy Markdown
Contributor

Bomly Diff Summary

Compared 67be1d087f514d750c6da373e85576b8356ba798 to b46624ada3ef7a636a495b81f4bea54ec7f997f3.

Overview

Status Manifests Dependencies Findings Duration
✅ Pass +0 / ~0 / -0 0 added / 0 version changed / 0 detail changes / 0 removed 0 introduced / 0 persisted / 0 resolved 1m 45s

Dependency Changes

✅ No dependency changes.

Vulnerabilities

✅ No vulnerability changes.

License Changes

✅ No license changes.

Project Posture

✅ No project posture changes (--matchers +scorecard was not selected).

Policy Findings

✅ No policy differences were identified.

bomly-guy and others added 2 commits October 25, 2026 13:11
…ummary points at

Both AGENTS.md summaries end by naming dev-docs/adr/README.md as the full
rule, so the full rule now carries the same sentence. The CLI summary uses
"code comment", the term the sentence after it already uses.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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 <noreply@anthropic.com>
@bomly-guy bomly-guy changed the title docs(agents): an ADR request in an issue or plan is still held to the bar docs(agents): hold ADR requests to the bar, and record criteria for plugin-author and developer docs Oct 25, 2026
@bomly-guy
bomly-guy merged commit 78f2f6e into main Oct 25, 2026
16 checks passed
@bomly-guy
bomly-guy deleted the claude/adr-bar-precedence branch October 25, 2026 20: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.

1 participant