docs: audit and update CLAUDE.md + BOOKMARKS.md#1292
Merged
jeremyeder merged 5 commits intoambient-code:mainfrom Apr 11, 2026
Merged
docs: audit and update CLAUDE.md + BOOKMARKS.md#1292jeremyeder merged 5 commits intoambient-code:mainfrom
jeremyeder merged 5 commits intoambient-code:mainfrom
Conversation
CLAUDE.md: add 3 missing components (ambient-api-server, ambient-sdk, open-webui-llm), 3 Makefile targets (kind-rebuild, kind-login, dev-bootstrap), strip stale test counts, establish convention authority hierarchy (CLAUDE.md > constitution for shared conventions). BOOKMARKS.md: add Governance section (ACP Constitution, Runner Constitution, SDD Preflight), ADR-0007, 3 component guides, OpenShift dev guide, 3 design docs. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (3)
🚧 Files skipped from review as they are similar to previous changes (2)
📝 WalkthroughWalkthroughDocumentation-only updates across project guides and governance: added Governance links and new ADR/component/design guides in Changes
🚥 Pre-merge checks | ✅ 6✅ Passed checks (6 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
✨ Simplify code
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@CLAUDE.md`:
- Line 157: The two documents conflict on governance precedence; update them to
a single authoritative source by choosing one rule (prefer making
.specify/memory/constitution.md the superseding authority) and align both files:
change the sentence in CLAUDE.md (the line that currently says "If they
conflict, this file wins.") to state that the ACP Constitution
(.specify/memory/constitution.md) takes precedence in conflicts, and also edit
.specify/memory/constitution.md to explicitly assert the same precedence
language so both files match exactly; ensure any references to BOOKMARKS.md
remain consistent with the chosen precedence.
🪄 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: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 7f7e0798-7f04-408d-ae56-b7bbbafb67b7
📒 Files selected for processing (2)
BOOKMARKS.mdCLAUDE.md
Updated API Server Guide link to point to GitHub repository.
Drop duplicated Development Standards (Go, Frontend, Python, Naming) and Pre-Deployment Validation from the constitution — these are now maintained in CLAUDE.md and BOOKMARKS.md as the single source of truth. Add Authority section to Governance establishing that CLAUDE.md wins on conflicts with shared conventions. Remove "supersedes all" language. Resolves CodeRabbit review comment on precedence contradiction. Constitution version bumped: 1.0.0 → 1.1.0 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (2)
.specify/memory/constitution.md (2)
298-302: Consider defining "spec-kit-governed concerns" explicitly.The term "spec-kit-governed concerns" is inferable from the Authority section (lines 294-296: principles, commit discipline, amendment process), but could be more explicit for new contributors.
Optional: Explicit scope definition
### Compliance -- All pull requests MUST verify constitution compliance for spec-kit-governed concerns +- All pull requests MUST verify constitution compliance for spec-kit-governed concerns (core principles I-X, commit discipline thresholds, amendment process) - Complexity violations MUST be justified in implementation plansThis makes the compliance scope self-evident without requiring cross-reference to Authority section.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/memory/constitution.md around lines 298 - 302, Add an explicit definition for the phrase "spec-kit-governed concerns" in the Constitution near the Compliance section: insert a short sentence or a new "Scope" sub-bullet that lists what falls under spec-kit governance (e.g., repository structure, contribution rules, release process, security and licensing policies, CI/CD configuration, and amendment procedures) so readers can understand the compliance boundary without cross-referencing the Authority section; update the "Compliance" heading text to reference this new scoped definition and ensure the exact phrase "spec-kit-governed concerns" is defined verbatim.
294-296: LGTM: Authority hierarchy clearly established.The new section successfully limits constitution scope to spec-kit governance while deferring conventions to CLAUDE.md/BOOKMARKS.md. The precedence rule "CLAUDE.md wins" is consistent with CLAUDE.md's own Convention Authority section.
Optional: Clarify the three-tier precedence chain
For maximum clarity, could explicitly state the full precedence hierarchy:
-[`/CLAUDE.md`](/CLAUDE.md) and [`/BOOKMARKS.md`](/BOOKMARKS.md) are the authoritative source of project conventions. This constitution covers spec-kit-specific governance (principles, commit discipline, amendment process) and defers to those files for shared conventions. If they conflict, CLAUDE.md wins. +[`/CLAUDE.md`](/CLAUDE.md) and [`/BOOKMARKS.md`](/BOOKMARKS.md) are the authoritative source of project conventions. This constitution covers spec-kit-specific governance (principles, commit discipline, amendment process) and defers to those files for shared conventions. Precedence for conflicts: CLAUDE.md > BOOKMARKS.md > Constitution.However, the current wording is sufficiently precise.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.specify/memory/constitution.md around lines 294 - 296, Update the "Authority" section to explicitly state the precedence chain so it's unambiguous: add a single sentence listing the three-tier order (e.g., "Precedence: CLAUDE.md > BOOKMARKS.md > this constitution") and keep the existing text that defers to /CLAUDE.md and /BOOKMARKS.md and the phrase "CLAUDE.md wins"; edit the Authority heading and lines referencing `/CLAUDE.md` and `/BOOKMARKS.md` to include that one-line precedence statement.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In @.specify/memory/constitution.md:
- Around line 298-302: Add an explicit definition for the phrase
"spec-kit-governed concerns" in the Constitution near the Compliance section:
insert a short sentence or a new "Scope" sub-bullet that lists what falls under
spec-kit governance (e.g., repository structure, contribution rules, release
process, security and licensing policies, CI/CD configuration, and amendment
procedures) so readers can understand the compliance boundary without
cross-referencing the Authority section; update the "Compliance" heading text to
reference this new scoped definition and ensure the exact phrase
"spec-kit-governed concerns" is defined verbatim.
- Around line 294-296: Update the "Authority" section to explicitly state the
precedence chain so it's unambiguous: add a single sentence listing the
three-tier order (e.g., "Precedence: CLAUDE.md > BOOKMARKS.md > this
constitution") and keep the existing text that defers to /CLAUDE.md and
/BOOKMARKS.md and the phrase "CLAUDE.md wins"; edit the Authority heading and
lines referencing `/CLAUDE.md` and `/BOOKMARKS.md` to include that one-line
precedence statement.
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 8d0052b9-f672-45bd-828d-40149d146ced
📒 Files selected for processing (1)
.specify/memory/constitution.md
CLAUDE.md: compress pre-commit hooks section from 48 to 5 lines (config file is source of truth), merge Convention Authority + More Info. BOOKMARKS.md: convert H3+description format to tables (-136 lines), merge duplicate CRC/OpenShift entries into one. Constitution: replace duplicated implementation details in Principles II, III, VII with cross-references to CLAUDE.md Critical Context and pattern files. Keeps principle statements and rationale intact. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Test plan
🤖 Generated with Claude Code
Summary by CodeRabbit