docs: seed Golden Context

[Tyler Pina (tylerpina)]

Summary

Seeds Golden Context documentation into contentful-management.php to enable safe, coherent contributions from both humans and AI agents.

Coverage: Before → After

Artifact	Before	After
README.md	Exists — no agent section	Appended agent/contributor nav table
ARCHITECTURE.md	Missing	Created
CONTRIBUTING.md	Exists — minimal (dev container + 3 commands)	Enriched with full commands table, testing guide, branch strategy, release process, CI job table
AGENTS.md	Missing	Created
docs/ADRs/	Missing	Created with 6 ADRs + index README
docs/specs/	Missing	Scaffolded with .gitkeep + README
.bito.yaml	Missing	Created
.bito/guidelines/	Missing	Created (review-posture.txt, repo-truth-and-boundaries.txt, domain-invariants.txt)

Artifacts Created

• ARCHITECTURE.md — full architecture doc: system context mermaid diagram, internal directory breakdown, data flow, key dependencies table, configuration table, upstream/downstream integration points
• AGENTS.md — agent routing table + 9 sharp-edge invariants (ApiConfiguration registration, mutation version requirement, upload host override, proxy laziness, PHP floor, BC policy, VCR cassettes, code style, optional nikic/php-parser)
• CONTRIBUTING.md — enriched: all composer.json scripts documented, testing tiers explained (Unit / Integration / E2E + VCR cassette workflow), branch strategy, release process, full CI job table
• README.md — appended agent nav table pointing to Golden Context artifacts
• docs/ADRs/0001 — Extend contentful/core BaseClient Instead of Implementing HTTP from Scratch
• docs/ADRs/0002 — Proxy Pattern for Space and Environment Scoped Operations
• docs/ADRs/0003 — Central ApiConfiguration Registry for URI Templates
• docs/ADRs/0004 — php-vcr Cassette Recordings for Integration Tests
• docs/ADRs/0005 — Dev Container as the Canonical Development and CI Environment (DX-822)
• docs/ADRs/0006 — Drop PHP 7.x Support, Require PHP 8.0+ (v4.0.0)
• docs/ADRs/README.md — ADR index with table + template
• docs/specs/README.md + .gitkeep — scaffold for future specs
• .bito.yaml — Bito PR review config referencing three guideline files
• .bito/guidelines/review-posture.txt — review priorities (BC breaks, ApiConfiguration registration, VCR cassettes, mutation version safety)
• .bito/guidelines/repo-truth-and-boundaries.txt — doc-first review anchored to AGENTS.md, ADRs, ApiConfiguration as ground truth
• .bito/guidelines/domain-invariants.txt — 7 invariant categories: resource registration, mutation methods, upload host, proxy laziness, PHP version floor, BC compatibility, VCR cassettes

ADRs Generated (6)

Decisions sourced from: git archaeology (git log --oneline --all), src/ApiConfiguration.php, src/ResourceBuilder.php, src/Proxy/, composer.json, phpunit.xml.dist, .devcontainer/, .github/workflows/ci.yml, and CHANGELOG.md.

Flagged Items

• E2E test credentials — tests/E2E/ requires real Contentful space credentials (CONTENTFUL_PHP_MANAGEMENT_TEST_TOKEN + space IDs). No documentation exists for how external contributors can run E2E tests or request cassette re-recordings. Recommend adding a note in CONTRIBUTING.md once the team decides on the policy.
• VCR cassette re-recording workflow — there is no documented process for re-recording cassettes when API shapes change. ADR-0004 notes this gap; a concrete how-to should be added to CONTRIBUTING.md.
• UPGRADE-2.0.md exists but there is no UPGRADE-3.0.md or UPGRADE-4.0.md for the PHP 7→8 BC break. Worth adding.

Redaction Pass (PUBLIC repo)

No sensitive values found in generated files. Space IDs and test tokens referenced in phpunit.xml.dist (pre-existing) were not copied into any generated file.

---

🤖 Generated with Claude Code

Summary by Bito

This PR seeds Golden Context documentation into the contentful-management.php repository to enable safe, coherent contributions from both humans and AI agents. It adds extensive documentation artifacts including architecture guides, agent guidelines, contributing workflows, ADRs, and review configurations.

Detailed Changes

• Introduces comprehensive architecture documentation in ARCHITECTURE.md, detailing system context, directory structure, data flow, dependencies, and integration points.
• Adds agent routing table and 9 sharp-edge invariants in AGENTS.md, covering ApiConfiguration registration, mutation version requirements, upload host overrides, proxy laziness, PHP floor, BC policy, VCR cassettes, code style, and optional nikic/php-parser.
• Enriches CONTRIBUTING.md with documented composer scripts, testing tiers (Unit/Integration/E2E with VCR workflow), branch strategy, release process, and full CI job table.
• Creates 6 ADRs in docs/ADRs/ documenting decisions on extending BaseClient, proxy patterns, central ApiConfiguration registry, php-vcr cassettes, dev container as canonical environment, and dropping PHP 7.x support.
• Adds Bito PR review configuration in .bito.yaml referencing three guideline files in .bito/guidelines/ for review priorities, doc-first review anchored to AGENTS.md and ADRs, and 7 invariant categories.

[bito-code-review]

Changelist by Bito

This pull request implements the following key changes.

Key Change	Files Impacted	Summary
Documentation - Golden Context Documentation Seeding	.bito.yaml, domain-invariants.txt, repo-truth-and-boundaries.txt, review-posture.txt, AGENTS.md, ARCHITECTURE.md, CONTRIBUTING.md, README.md, README.md, README.md	Adds comprehensive Golden Context documentation including architecture overview, agent guidelines, enriched contributing instructions, architectural decision records, Bito configuration, and guideline files to enable safe and coherent contributions.

[bito-code-review]

Functional Validation by Bito

Source	Requirement / Code Area	Status	Notes
DX-841	Create reproducible development environment for contentful-management.php	✅ Met	Reproducible development environment already implemented in existing codebase at .devcontainer/
.bito.yaml, domain-invariants.txt, repo-truth-and-boundaries.txt, review-posture.txt, AGENTS.md	Added Bito PR review configuration and agent guidelines including .bito.yaml, .bito/guidelines/domain-invariants.txt, .bito/guidelines/repo-truth-and-boundaries.txt, .bito/guidelines/review-posture.txt, and AGENTS.md	⭕ Out of Scope	Added Bito PR review configuration and agent guidelines including .bito.yaml, .bito/guidelines/domain-invariants.txt, .bito/guidelines/repo-truth-and-boundaries.txt, .bito/guidelines/review-posture.txt, and AGENTS.md

[bito-code-review]

Impact Analysis by Bito

Interaction Diagram

sequenceDiagram
participant Dev as Developer
participant Git as Git Platform
participant Bito as Bito PR Review Service
participant Config as Bito Configuration<br/>🟩 Added | ●●● High
Dev->>Git: Create PR with changes
Git->>Bito: Notify PR created
Bito->>Config: Read .bito.yaml
Bito->>Config: Read guidelines
Bito->>Config: Read AGENTS.md
Bito->>Git: Post review feedback
Note over Config: Configuration added<br/>for automated reviews

Loading

---

This MR adds Bito configuration files including .bito.yaml, domain invariants, review guidelines, and AGENTS.md to enable automated PR reviews with project-specific context. The changes integrate external review tooling into the development workflow. No direct upstream/downstream impact detected in repository scan or cross-repo dependency analysis.

Code Paths Analyzed

Impact:
No functional code changes. This PR exclusively adds documentation files (.bito.yaml, AGENTS.md, ARCHITECTURE.md, ADRs, guidelines) to establish 'Golden Context' for AI agents and contributors.

Flow:
Documentation-only changes do not alter execution flow. Files are added to .bito/, docs/, and root-level markdown files for reference purposes only.

Direct Changes (Diff Files):
• .bito.yaml [1-26] — New Bito PR review configuration file with suggestion mode, linters, and custom guidelines paths.
• .bito/guidelines/domain-invariants.txt [1-64] — New file documenting domain invariants: resource registration, mutation methods, upload host override, proxy laziness, PHP version floor, backward compatibility, PHP-VCR cassettes, code style, and optional dependency notes.
• .bito/guidelines/repo-truth-and-boundaries.txt [1-11] — New file establishing guidelines for using repository documentation as review context.
• .bito/guidelines/review-posture.txt [1-12] — New file defining PR review posture for tech leads reviewing this public PHP SDK.
• AGENTS.md [1-57] — New comprehensive agent guide with quick reference, sharp edges & invariants, key conventions, and integration points.
• ARCHITECTURE.md [1-95] — New architecture documentation covering system context, internal structure, data flow, key dependencies, configuration, and integration points.
• CONTRIBUTING.md [37-58] — Appended build commands, testing details, branch strategy, release process, and CI/CD documentation.
• README.md [617-630] — Appended 'For AI Agents & Contributors' section linking to Golden Context documentation.
• docs/ADRs/0001-extend-contentful-core-base-client.md [1-26] — New ADR documenting decision to extend contentful/core BaseClient.
• docs/ADRs/0002-proxy-pattern-for-space-and-environment.md [1-26] — New ADR documenting SpaceProxy and EnvironmentProxy pattern decision.
• docs/ADRs/0003-api-configuration-central-registry.md [1-24] — New ADR documenting central ApiConfiguration registry for URI templates.
• docs/ADRs/0004-php-vcr-cassettes-for-integration-tests.md [1-24] — New ADR documenting php-vcr cassette recordings for integration tests.
• docs/ADRs/0005-devcontainer-for-reproducible-dev-and-ci.md [1-24] — New ADR documenting dev container as canonical development and CI environment.
• docs/ADRs/0006-drop-php-7-require-php-8.md [1-23] — New ADR documenting dropping PHP 7.x support and requiring PHP 8.0+.
• docs/ADRs/README.md [1-36] — New ADR index with status table and template for adding new ADRs.
• docs/specs/README.md [1-27] — New specs directory README with naming convention and status guidelines.

Repository Impact:
• Documentation: Adds comprehensive Golden Context documentation for AI agents and contributors. No code changes.
• Developer Experience: Improves onboarding and review quality by documenting sharp edges, invariants, and architectural decisions.

Cross-Repository Dependencies:
• None.

Database/Caching Impact:
• None

API Contract Violations:
• None.

Infrastructure Dependencies:
• None.

Additional Insights:
• AI Agent Support: Documentation is specifically designed to help AI tools (like this one) provide better code reviews by understanding domain invariants and architectural constraints.

Testing Recommendations

Frontend Impact:
• No issues detected — documentation-only changes.

Service Integration:
• No issues detected — documentation-only changes.

Data Serialization:
• No issues detected — documentation-only changes.

Privacy Compliance:
• No issues detected — documentation-only changes.

Backward Compatibility:
• No issues detected — documentation-only changes.

OAuth Functionality:
• None

Cross-Service Communication:
• No issues detected — documentation-only changes.

Reliability Testing:
• None

Additional Insights:
• Verify that all documentation links in AGENTS.md, ARCHITECTURE.md, and README.md resolve correctly (relative paths like './CONTRIBUTING.md', './docs/ADRs/').
• Confirm that the .bito.yaml configuration syntax is valid YAML and paths to guideline files exist.
• Consider adding a CI check to validate that documentation files are well-formed markdown.

_{Analysis based on known dependency patterns and edges. Actual impact may vary.}

[bito-code-review]

Code Review Agent Run #ca450c

Actionable Suggestions - 2

• docs/ADRs/0001-extend-contentful-core-base-client.md - 1

  • Spelling Error · Line 26-26
• CONTRIBUTING.md - 1

  • Documentation inaccuracy · Line 66-66

Review Details

• Files reviewed - 16 · Commit Range: 5e417cc..5e417cc

  • .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-extend-contentful-core-base-client.md
  • docs/ADRs/0002-proxy-pattern-for-space-and-environment.md
  • docs/ADRs/0003-api-configuration-central-registry.md
  • docs/ADRs/0004-php-vcr-cassettes-for-integration-tests.md
  • docs/ADRs/0005-devcontainer-for-reproducible-dev-and-ci.md
  • docs/ADRs/0006-drop-php-7-require-php-8.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

• Customize agent settings
• Review rules
• General documentation
• FAQ

AI Code Review powered by

[bito-code-review]

✅ Review Settings Overridden

Status: Overridden Successfully

Guidelines:

• Accepted:

  • General : Domain Invariants

• Rejected: Review Posture (parse error),Repo Truth And Alignment (parse error)

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.

[bito-code-review]

Bito Automatic Review Skipped – PR Already Merged

Bito scheduled an automatic review for this pull request, but the review was skipped because this PR was merged before the review could be run.
No action is needed if you didn't intend to review it. To get a review, you can type /review in a comment and save it