docs: seed Golden Context#210
Conversation
Adds ARCHITECTURE.md, AGENTS.md, 7 ADRs, .bito config, docs/specs/ scaffold, and enriches CONTRIBUTING.md and README.md with agent-visible context. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Changelist by BitoThis pull request implements the following key changes.
|
|
| Source | Requirement / Code Area | Status | Notes |
|---|---|---|---|
| DX-822 | Create reproducible development environment for contentful-management.java | ✅ Met | Requirement already implemented in existing code with .devcontainer/ providing reproducible development environment as documented in ARCHITECTURE.md and AGENTS.md. |
| .bito.yaml, domain-invariants.txt, repo-truth-and-boundaries.txt, review-posture.txt | Added Bito AI reviewer configuration and custom guidelines for code review posture, domain invariants, and repository boundaries. | ⭕ Out of Scope | Added Bito AI reviewer configuration and custom guidelines for code review posture, domain invariants, and repository boundaries. |
| AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md | Added comprehensive repository documentation including agent guide, architecture overview, and updated contributing guidelines. | ⭕ Out of Scope | Added comprehensive repository documentation including agent guide, architecture overview, and updated contributing guidelines. |
| 0001-module-per-resource-architecture.md, 0002-retrofit2-as-http-client.md, 0003-rxjava2-async-pattern.md, 0004-java8-android-compatibility.md, 0005-kotlin-for-tests-java-for-production.md, 0006-devcontainer-for-ci-parity.md, 0007-maven-central-publishing.md, README.md | Added architecture decision records documenting key technical decisions for the SDK. | ⭕ Out of Scope | Added architecture decision records documenting key technical decisions for the SDK. |
| README.md | Added specs directory structure for documenting active and planned work. | ⭕ Out of Scope | Added specs directory structure for documenting active and planned work. |
Impact Analysis by BitoInteraction DiagramsequenceDiagram
participant Dev as Developer
participant PR as GitHub PR
participant BitoAI as Bito AI
participant Config as .bito.yaml<br/>🟩 Added | ●●● High
participant Guidelines as Review Guidelines<br/>🟩 Added | ●●○ Medium
participant SeqGen as Sequence Diagram Generator
Dev->>PR: Create PR with changes
PR->>BitoAI: Trigger automated review
BitoAI->>Config: Load Bito configuration
Config->>BitoAI: Enable sequence diagrams
BitoAI->>Guidelines: Load custom guidelines
Guidelines->>BitoAI: Provide domain invariants and review rules
BitoAI->>SeqGen: Request sequence diagram generation
SeqGen->>BitoAI: Return generated diagram
BitoAI->>PR: Post review with diagram
PR->>Dev: Display enhanced review feedback
Note over Config: Configuration enables AI-assisted reviews<br/>with sequence diagrams for code diffs
This MR adds Bito AI configuration files to enable sequence diagram generation and custom review guidelines for the contentful-management.java repository. The configuration activates comprehensive suggestions, sequence diagrams, and custom guidelines for PR reviews. The domain invariants guideline documents critical architectural rules for the SDK, including data transformation layers (Gson type adapters), external integrations (Retrofit services), and communication layers (HTTP contracts). This enhances the review process by providing visual sequence diagrams for code changes, improving developer understanding of system flows. Code Paths AnalyzedImpact: Flow: Direct Changes (Diff Files): Repository Impact: Cross-Repository Dependencies: Database/Caching Impact: API Contract Violations: Infrastructure Dependencies: Additional Insights: Testing RecommendationsFrontend Impact: Service Integration: Data Serialization: Privacy Compliance: Backward Compatibility: OAuth Functionality: Cross-Service Communication: Reliability Testing: Additional Insights: Analysis based on known dependency patterns and edges. Actual impact may vary. |
![bito-code-review[bot]](https://avatars.githubusercontent.com/in/1061978?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review Agent Run #97a6fb
Actionable Suggestions - 4
-
CONTRIBUTING.md - 1
- Inaccurate CI checkstyle claim · Line 53-53
-
docs/ADRs/0005-kotlin-for-tests-java-for-production.md - 1
- Incorrect Build Behavior Claim · Line 29-29
-
.bito/guidelines/domain-invariants.txt - 1
- Inaccurate module scoping list · Line 3-3
-
AGENTS.md - 1
- Incomplete Invariants Documentation · Line 18-28
Review Details
-
Files reviewed - 17 · Commit Range:
e8d2a1d..e8d2a1d- .bito.yaml
- .bito/guidelines/domain-invariants.txt
- .bito/guidelines/repo-truth-and-boundaries.txt
- .bito/guidelines/review-posture.txt
- AGENTS.md
- ARCHITECTURE.md
- CONTRIBUTING.md
- README.md
- docs/ADRs/0001-module-per-resource-architecture.md
- docs/ADRs/0002-retrofit2-as-http-client.md
- docs/ADRs/0003-rxjava2-async-pattern.md
- docs/ADRs/0004-java8-android-compatibility.md
- docs/ADRs/0005-kotlin-for-tests-java-for-production.md
- docs/ADRs/0006-devcontainer-for-ci-parity.md
- docs/ADRs/0007-maven-central-publishing.md
- docs/ADRs/README.md
- docs/specs/README.md
-
Files skipped - 0
-
Tools
- Whispers (Secret Scanner) - ✔︎ Successful
- Detect-secrets (Secret Scanner) - ✔︎ Successful
Bito Usage Guide
Commands
Type the following command in the pull request comment and save the comment.
-
/review- Manually triggers a full AI review. -
/pause- Pauses automatic reviews on this pull request. -
/resume- Resumes automatic reviews. -
/resolve- Marks all Bito-posted review comments as resolved. -
/abort- Cancels all in-progress reviews.
Refer to the documentation for additional commands.
Configuration
This repository uses Default Agent You can customize the agent settings here or contact your Bito workspace admin at jared.jolton@contentful.com.
Documentation & Help
AI Code Review powered by
|
|
||
| - **Enables:** Concise, readable tests with Kotlin assertions; no Kotlin dependency burden on pure-Java SDK consumers. | ||
| - **Requires:** `kotlin-stdlib` in compile scope (minimal); `kotlin-maven-plugin` configured for test-compile phase. | ||
| - **Sharp edge:** Do not add Kotlin files under `src/main/java/`. The Maven build does not compile Kotlin there, and it would silently be excluded. |
There was a problem hiding this comment.
The ADR incorrectly states that the Maven build 'does not compile Kotlin' in src/main/java/, but pom.xml shows kotlin-maven-plugin's compile phase includes src/main/java in sourceDirs, meaning Kotlin files would be compiled if present. This could mislead developers about build behavior. Update the sharp edge to reflect the actual configuration while maintaining the no-Kotlin-in-main decision.
Code Review Run #97a6fb
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
| @@ -0,0 +1,21 @@ | |||
| Critical domain invariants for contentful-management.java. Violations of these rules will cause runtime failures, silent data loss, or consumer-facing breakage. | |||
|
|
|||
| 1. ENVIRONMENT SCOPING: The modules apiKeys, environments, roles, spaceMemberships, uiExtensions, uploads, and webhooks do NOT support non-master environments. If a module that extends AbsModule operates in a space-only context, it must call throwIfEnvironmentIdIsSet() in its constructor or before any operation. Failing to do this causes CMANotWithEnvironmentsException at runtime. | |||
There was a problem hiding this comment.
The listed modules 'environments' and 'uiExtensions' actually support environment-scoped operations (e.g., ModuleUiExtensions.fetchAll(spaceId, environmentId)) and do not throw CMANotWithEnvironmentsException when environmentId is configured, unlike apiKeys, roles, spaceMemberships, uploads, and webhooks. This discrepancy could mislead developers into avoiding valid API usage.
Code Review Run #97a6fb
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
| ## Sharp Edges & Invariants | ||
|
|
||
| - **Never call environment-scoped operations on the wrong modules.** The modules `apiKeys`, `environments`, `roles`, `spaceMemberships`, `uiExtensions`, `uploads`, and `webhooks` throw `CMANotWithEnvironmentsException` if the client is configured with a non-`master` `environmentId`. Always use a separate client (no `environmentId`) for those modules. | ||
| - **Java 8 is the minimum target — do not use Java 9+ APIs in production code.** The Android dependency (`com.google.android:android`) is marked `optional` but must remain compilable on API 21+. Tests may use newer JVM features. | ||
| - **Do not add new runtime dependencies without an ADR.** The dependency footprint is deliberately small to keep Android app size predictable. | ||
| - **Every Module must extend `AbsModule<T>`.** The base class handles argument validation, executor injection, and space/environment ID pre-configuration. Never bypass it. | ||
| - **Custom Gson adapters must be registered in `CMAClient`.** The Gson instance is built once in `CMAClient` and shared across all modules. New model types with non-trivial wire formats need a type adapter registered there. | ||
| - **RichText hierarchy rules are enforced by the API** — the SDK models them but does not validate at write time. Violating the hierarchy (Document in Document, Link outside Paragraph, etc.) will produce a 422 from the CMA. See `ARCHITECTURE.md` for the full rule set. | ||
| - **The `CMACallback.onFailure()` default implementation is empty.** Code that needs to handle failures must override it explicitly. This is a common source of silently dropped errors. | ||
| - **Test files are Kotlin; production code is Java.** Keep this split. Do not introduce Kotlin into `src/main/java/`. | ||
| - **Checkstyle is enforced on every build (`./mvnw verify`).** Violations fail CI. The config is in `checkstyle.xml` at the repo root. |
There was a problem hiding this comment.
AGENTS.md omits critical invariants documented in .bito/guidelines/domain-invariants.txt, such as public API stability rules and sensitive logging constraints. Since AGENTS.md is the authoritative guide for sharp edges, it should include all invariants to prevent violations.
Code Review Run #97a6fb
Should Bito avoid suggestions like this for future reviews? (Manage Rules)
- Yes, avoid them
✅ Review Settings OverriddenStatus: Guidelines:
Note: Extra guidelines beyond 3 general purpose guidelines and 1 language specific guideline per language are not processed. Guidelines are fetched from the source branch. |
- CONTRIBUTING.md: CI uses `./mvnw -B verify` for checkstyle, not `./mvnw -B test` - AGENTS.md: relabel build commands so `./mvnw -B test` is NOT described as "full verification"; `./mvnw -B verify` is the full check - ADR-0005: correct kotlin-stdlib framing from "internal use" to "transitive runtime dependency for consumers", with Android jar-size callout
- Fix module list in domain-invariants.txt: remove environments/uiExtensions (they support environment scope), add previewApiKeys (verified by grep) - Fix ADR 0005 sharp edge: Kotlin plugin does scan src/main/java in sourceDirs; clarify that .kt files must not be added there - Fix CONTRIBUTING.md: CI runs ./mvnw -B test, not verify — checkstyle is not enforced in CI - Fix README.md: convert Agent & Contributor Context heading from === underline style to ## to match rest of file - Add missing AGENTS.md invariants: public API stability rules and sensitive logging constraint - Correct AGENTS.md checkstyle note: violations do not fail CI (CI skips verify) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Tyler Pina (tylerpina)
dismissed
bito-code-review[bot]’s stale review
via
b613e6b
|
Bito Automatic Review Skipped – PR Already Merged |
1 participant
Summary
Adds the full Golden Context artifact set to
contentful-management.javaso that agents and new contributors can orient quickly without a human tour guide.Coverage: Before → After
README.mdARCHITECTURE.mdAGENTS.mdCONTRIBUTING.mddocs/ADRs/docs/specs/.bito.yaml.bito/guidelines/Artifacts Created
ADRs Generated
Redaction Pass (Public Repo)
One mention of "CMA credentials" in ARCHITECTURE.md — this is documentation-appropriate context for E2E test setup, not an actual credential. No redactions applied.
Flagged Items
kotlin-stdlibin compile scope: ADR-0005 notes this means Kotlin stdlib ships with the jar. This is a known trade-off but worth revisiting if jar size becomes a concern.nodeTypedeserialization between the API and SDK is not addressed by this PR. Flagged for follow-up.src/test/kotlin/.../e2e/tests requireCONTENTFUL_ACCESS_TOKENandCONTENTFUL_SPACE_IDenv vars. There is no documented CI secret setup for these — they may only be runnable locally or with specific credentials. Worth documenting or gating explicitly.checkstyle.xmlis present but theverifyphase is not part of the standard./mvnw -B testCI command —testphase runs beforeverify. Checkstyle only runs duringverify. CI currently usestest. This means checkstyle is not enforced in CI as documented. Consider updating ci.yml to use./mvnw -B verifyor adding a separate checkstyle step.Generated by
seed-golden-contextpipeline — 2026-05-11Summary by Bito
This pull request adds the full Golden Context artifact set to contentful-management.java, enabling agents and new contributors to orient quickly. It creates comprehensive documentation including architectural overviews, agent guidelines, ADRs, review guidelines, and enhances existing guides with additional context.
Detailed Changes