docs: golden context [DX-1029]#3270
Conversation
Changelist by BitoThis pull request implements the following key changes.
|
|
| Source | Requirement / Code Area | Status | Notes |
|---|---|---|---|
| DX-1029 | Seed a baseline golden context file in every DX-owned repository, covering purpose, stack, conventions, and key entry points | ✅ Met | The PR adds baseline golden context files including AGENTS.md, ARCHITECTURE.md, and guideline files in .bito/guidelines/ covering the repository's purpose, stack, conventions, and key entry points for the contentful-cli. |
| DX-689 | Replace deprecated pkg package in contentful-cli to support cma-v12 | ✅ Met | No change in diff, but requirement already implemented in existing code: the deprecated pkg package has been replaced with @yao-pkg/pkg in package.json, and the build:standalone script uses pkg which resolves to the installed community-maintained fork. |
| DX-689 | Update the cli to use cma-v12 | ✅ Met | No change in diff, but requirement already implemented in existing code: the CLI already uses contentful-management ^12.2.0 as specified in package.json. |
Impact Analysis by BitoInteraction DiagramsequenceDiagram
participant User as User
participant Bin as bin/contentful.js
participant CLI as dist/lib/cli.js
participant Config as Configuration Handler
participant Cmd as Command Handler
participant CMA as contentful-management.js
participant API as Contentful Management API
User->>Bin: Run command (e.g. contentful space list)
Bin->>CLI: Execute compiled CLI entrypoint
CLI->>Config: Load user configuration
Config-->>CLI: Return config object
CLI->>Cmd: Parse command and delegate execution
Cmd->>CMA: Initialize API client
CMA->>API: Send HTTP request
API-->>CMA: Return API response
CMA-->>Cmd: Process and return data
Cmd-->>CLI: Format command output
CLI-->>User: Display results to terminal
This MR adds Bito AI configuration and review guidelines that document the CLI's build process (TypeScript compilation to CommonJS), runtime invariants (yargs version pinning, module system), and command interface stability. Changes to command names, flags, or output formats are treated as breaking changes affecting downstream CI pipelines and scripts. The guidelines also cover integration with satellite packages like contentful-migration and the Contentful Management API. 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 #767ef7
Actionable Suggestions - 1
-
docs/ADRs/2023-09-01-talkback-integration-tests.md - 1
- CWE-540: Inclusion of Sensitive Information in Source Code · Line 21-27
Review Details
-
Files reviewed - 17 · Commit Range:
ba05674..35414f9- .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/2017-08-31-yargs-cli-framework.md
- docs/ADRs/2021-09-01-semantic-release.md
- docs/ADRs/2022-07-29-typescript-adoption.md
- docs/ADRs/2023-09-01-talkback-integration-tests.md
- docs/ADRs/2025-11-14-gha-publishing.md
- docs/ADRs/2025-12-02-lavamoat-allow-scripts.md
- docs/ADRs/2026-04-10-yao-pkg-standalone-binaries.md
- docs/ADRs/2026-04-22-cma-v12-migration.md
- docs/ADRs/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
✅ 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. |
… downstream - Semantic-release ADR: 2021-09-01 → 2019-02-21 (actual adoption date, PR #122) - Talkback ADR: 2023-09-01 → 2018-08-30 (actual introduction date) - ADR index: reordered chronologically with corrected dates - ARCHITECTURE.md: fix lib/config.js description (command auth lists, not config management) - ARCHITECTURE.md: improve lib/context.js description (reads .contentfulrc.json) - ARCHITECTURE.md: add sync command to top-level commands list and overview - ARCHITECTURE.md: label @yao-pkg/pkg as dev dependency - ARCHITECTURE.md: remove speculative EDS SDK downstream integration - CONTRIBUTING.md: clarify Node >=22 supported alongside .nvmrc 24
Code Review Agent Run #ef1299Actionable Suggestions - 0Review Details
Bito Usage GuideCommands Type the following command in the pull request comment and save the comment.
Refer to the documentation for additional commands. Configuration This repository uses Documentation & Help AI Code Review powered by |
Michael Pham (michaelphamcf)
changed the title
There was a problem hiding this comment.
Code Review Agent Run #c3f511
Actionable Suggestions - 2
-
ARCHITECTURE.md - 2
- Documentation inconsistency · Line 5-5
- Documentation inconsistency · Line 30-30
Review Details
-
Files reviewed - 3 · Commit Range:
7f31afa..15b54a7- ARCHITECTURE.md
- AGENTS.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
Address gaps identified by newcomer simulation (15/23 → target ≥80%): - CONTRIBUTING: add type-check command, linting status note, direct-run examples, new command template - AGENTS.md: add sensitive areas table, operational model section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
- CONTRIBUTING: clarify CLI is not a service (no npm start) - AGENTS.md: add release diagnosis guidance (GitHub Issues, Slack, npm stats) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Code Review Agent Run #67a29fActionable Suggestions - 0Review Details
Bito Usage GuideCommands Type the following command in the pull request comment and save the comment.
Refer to the documentation for additional commands. Configuration This repository uses Documentation & Help AI Code Review powered by |
- Add provenance markers to all agent-generated files - ARCHITECTURE.md: add Domain Concepts section, add Operational Knowledge section (Deployment, Failure Modes, Monitoring, Incident Playbook) - CONTRIBUTING.md: add source citations on all commands, add Code Style section, add File-Level Guidance table (moved from AGENTS.md) - AGENTS.md: refactor to pure routing table — move sensitive files to CONTRIBUTING.md, move operational model to ARCHITECTURE.md, add new Quick Reference pointers for moved sections - README.md: add provenance marker to agent section Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Code Review Agent Run #7d849a
Actionable Suggestions - 2
-
CONTRIBUTING.md - 2
- Inaccurate config references · Line 160-166
- Wrong file extension · Line 171-171
Review Details
-
Files reviewed - 4 · Commit Range:
3c9887c..83981eb- AGENTS.md
- ARCHITECTURE.md
- CONTRIBUTING.md
- 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
| - Standalone binaries can target Node 22, matching the runtime requirement | ||
| - Binary artifacts are attached to GitHub releases as `.zip` files (macOS, Linux, Windows) | ||
| - E2E tests validate the binaries work correctly on ubuntu and macOS runners | ||
| - ARM/Apple Silicon macOS binaries are not built — macOS x64 runs via Rosetta 2 |
There was a problem hiding this comment.
today I learned.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Michael Pham (michaelphamcf)
force-pushed
the
docs/seed-golden-context
branch
from
673abe6 to
6cffec1
Compare
…vely Preserves the original file structure and tone, appends Golden Context enrichments below a clear separator with provenance marker. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Michael Pham (michaelphamcf)
changed the title
- Setup: npm ci + allow-scripts instead of npm install/yarn - Code style: ESLint + Prettier instead of standard - Integration tests: talkback starts automatically via concurrently, not after build:standalone - Tests run in Node.js only (not browser), Babel used for Jest transpilation Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Already covered in the Setup section above. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
The sync command (space sync between regions) is registered and working. It was incorrectly removed in an earlier commit based on a wrong assumption that it wasn't in config.js — but config.js only tracks auth/space-id exemptions, not command registration. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
…editorconfig - .eslintrc.json → .eslintrc.js (actual filename) - ES2022 → es2016 (actual tsconfig target) - Remove .editorconfig reference (file doesn't exist) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Code Review Agent Run #b46188Actionable Suggestions - 0Review Details
Bito Usage GuideCommands Type the following command in the pull request comment and save the comment.
Refer to the documentation for additional commands. Configuration This repository uses Documentation & Help AI Code Review powered by |
3 participants
DX-1029
Summary
Artifacts Created
README.md— appended agent section, replaced stale CircleCI badge with GHA badgeARCHITECTURE.md— internal structure, diagrams, domain concepts, operational knowledge, integration pointsCONTRIBUTING.md— dev setup, workflow, source-cited commands, file-level guidance, code styledocs/ADRs/— 8 architecture decision recordsdocs/specs/— scaffolded directory for active implementation specsAGENTS.md— agent-facing routing table (pure routing, no duplicate content).bito.yaml+.bito/guidelines/— Bito review configurationNewcomer Simulation Score
Score: 19/23 (83%) — above 80% threshold ✅
Remaining failures are structural mismatches (CLI tool vs. service-oriented questions):
Flagged Items (require human action)
packageManagerfield is missing frompackage.json— recommend adding (e.g.,"packageManager": "npm@10.x.x") for corepack support.npmrc— present (ignore-scripts=true) ✅.nvmrc— present (24) ✅ADRs Generated
Coverage Before / After
Generated with Claude Code
Summary by Bito
This PR seeds golden context documentation for the contentful-cli repository, providing comprehensive guidance on architecture, development workflow, and technical decisions. It adds core documentation files, configures AI review settings, and documents 8 architecture decision records covering the CLI's evolution. The changes enhance repository maintainability and newcomer onboarding without introducing any code modifications.
Detailed Changes