docs: seed Golden Context

[Tyler Pina (tylerpina)]

Summary

Seeds the full Golden Context artifact set into contentful.php so that any engineer (or AI agent) can get productive quickly and work safely without a human tour guide.

Coverage: Before → After

Artifact	Before	After
README.md	Present (no agent nav section)	Enriched — agent navigation table appended
ARCHITECTURE.md	Absent	Created — full system context, internal structure, data flow, key deps, config table
AGENTS.md	Absent	Created — routing table, sharp edges & invariants, key conventions, build commands
CONTRIBUTING.md	Minimal (devcontainer setup only)	Enriched — testing, linting, BC check, branch strategy, release workflow, CI/CD table
docs/ADRs/	Absent	Created — 6 ADRs + index
docs/specs/	Absent	Scaffolded with .gitkeep + README
.bito.yaml	Absent	Created
.bito/guidelines/	Absent	Created — review-posture.txt, repo-truth-and-boundaries.txt, domain-invariants.txt

ADRs Generated

ADR	Decision
0001	Use contentful/core as the shared SDK foundation
0002	Accept PSR-6/PSR-3 interfaces, not concrete implementations
0003	Devcontainer for reproducible local and CI environments (DX-822)
0004	PHPStan at level 5 with one accepted known violation
0005	php-vcr for integration tests + known migration debt
0006	Semver with major bumps for PHP version drops

Flagged Items

1. php-vcr migration needed — The space used to record existing integration test cassettes no longer exists. php-vcr is also unmaintained. Existing cassettes are preserved but new integration tests should use Guzzle mock handlers. Documented in ADR-0005 and AGENTS.md.
2. LocalizedResource::$sys PHPStan violation — Intentionally unfixed (fix requires PHP 8.2+ attribute that would break PHP 8.1 consumers). Documented in ADR-0004 and AGENTS.md.
3. No Conventional Commits hook — The team uses feat:/fix:/chore: prefixes by convention but nothing enforces it. Could be added via commitlint in a follow-up.

Redactions Applied (PUBLIC repo)

• Removed internal Confluence runbook URL (contentful.atlassian.net/wiki/...) from AGENTS.md and CONTRIBUTING.md. Replaced with a reference to the release workflow section within CONTRIBUTING.md itself.

Checklist

• All generated sections marked <!-- Generated by seed-golden-context | Last updated: 2026-05-11 -->
• CONTRIBUTING.md commands sourced from composer.json scripts and .github/workflows/ci.yml — no invented commands
• No internal URLs in public-facing files (redaction pass completed)
• EXISTING FILE RULE respected — README.md and CONTRIBUTING.md appended/enriched, not rewritten

🤖 Generated with Claude Code

Summary by Bito

Seeds the full Golden Context artifact set into contentful.php so that any engineer (or AI agent) can get productive quickly and work safely without a human tour guide, establishing comprehensive documentation including architecture overviews, development guidelines, and decision records.

Detailed Changes

• Added comprehensive documentation artifacts including enriched README.md with agent navigation, new ARCHITECTURE.md with system context and data flows, AGENTS.md guide for repository navigation, and CONTRIBUTING.md with development workflows
• Created 6 Architecture Decision Records documenting key technical decisions around SDK foundation, PSR interfaces, devcontainer usage, PHPStan configuration, testing approach, and versioning policy
• Established Bito configuration and review guidelines to enable automated code review tooling with domain invariants, repository standards, and review posture guidance
• Scaffolded specifications framework for tracking active development work with standardized naming and status conventions
• Applied redactions for public repository visibility by removing internal URLs while maintaining comprehensive documentation coverage

[bito-code-review]

Code Review Agent Run #0e4556

Actionable Suggestions - 0

Review Details

• Files reviewed - 16 · Commit Range: 94ba2eb..94ba2eb

  • .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-contentful-core-foundation.md
  • docs/ADRs/0002-psr-interfaces-for-cache-and-logging.md
  • docs/ADRs/0003-devcontainer-for-reproducible-ci.md
  • docs/ADRs/0004-phpstan-level-and-known-violations.md
  • docs/ADRs/0005-php-vcr-integration-testing.md
  • docs/ADRs/0006-semver-and-php-version-policy.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]

Changelist by Bito

This pull request implements the following key changes.

Key Change	Files Impacted	Summary
Documentation - Documentation Infrastructure Setup	.bito.yaml, domain-invariants.txt, repo-truth-and-boundaries.txt, review-posture.txt	Added Bito configuration and review guidelines to enable automated code review tooling and establish review standards for the repository.
Documentation - Core Documentation Enhancement	README.md, ARCHITECTURE.md, AGENTS.md, CONTRIBUTING.md	Created comprehensive documentation including architecture overview, agent navigation guide, and enriched contributing guidelines with development workflows and CI/CD processes.
Documentation - Architecture Decision Records	0001-contentful-core-foundation.md, 0002-psr-interfaces-for-cache-and-logging.md, 0003-devcontainer-for-reproducible-ci.md, 0004-phpstan-level-and-known-violations.md, 0005-php-vcr-integration-testing.md, 0006-semver-and-php-version-policy.md, README.md	Documented 6 key architectural decisions covering SDK foundation, PSR interfaces, devcontainer usage, PHPStan configuration, testing approach, and versioning policy.
Documentation - Specifications Framework	README.md	Scaffolded framework for implementation specifications with naming conventions and status tracking for active development work.

[bito-code-review]

Impact Analysis by Bito

Interaction Diagram

sequenceDiagram
participant Dev as Developer
participant BitoYaml as .bito.yaml<br/>🟩 Added | ●●● High
participant DomainInv as domain-invariants.txt<br/>🟩 Added | ●●● High
participant RepoTruth as repo-truth-and-boundaries.txt<br/>🟩 Added | ●●● High
participant ReviewPost as review-posture.txt<br/>🟩 Added | ●●● High
Dev->>BitoYaml: Create file with Bito config
Dev->>DomainInv: Add backward compatibility rules
Dev->>RepoTruth: Add documentation alignment rules
Dev->>ReviewPost: Add review posture guidelines
BitoYaml->>BitoYaml: Enable sequence_diagram_enabled
DomainInv->>DomainInv: Define resource pool invariants
RepoTruth->>RepoTruth: Set repo boundaries
ReviewPost->>ReviewPost: Establish review guidelines
DomainInv->>DomainInv: Include link resolution depth rules
DomainInv->>DomainInv: Add PHP version minimum

Loading

---

This MR adds a .bito.yaml configuration file and three guideline files to the contentful.php repository. The .bito.yaml enables Bito AI features like sequence diagrams, while the guidelines define domain invariants (including resource pool for persistence, link resolution for integration, and PHP version for communication), repository boundaries, and review posture. No code changes were made, so the library's runtime behavior and user journeys remain unaffected. Future PR reviews will follow these guidelines to maintain backward compatibility and architectural integrity.

Code Paths Analyzed

Impact:
No functional impact. This PR adds comprehensive project documentation including architecture docs, ADRs, contributing guidelines, and Bito review configuration. No code changes.

Flow:
N/A - Documentation-only PR with no code paths affected.

Direct Changes (Diff Files):
• .bito.yaml [1-24] — Added Bito configuration for comprehensive review mode with custom guidelines.
• .bito/guidelines/domain-invariants.txt [27-65] — Added critical invariants: backward compatibility rules, ResourcePool identity map, link resolution depth limit (MAX_DEPTH=20), PHP 8.0 minimum, namespace discipline.
• .bito/guidelines/repo-truth-and-boundaries.txt [68-82] — Added guidelines for checking implementation against documented architecture.
• .bito/guidelines/review-posture.txt [85-99] — Added review priorities: BC breaks, cache correctness, link resolution, PSR contracts.
• AGENTS.md [102-172] — Added agent guide with quick reference, sharp edges, key conventions, and integration points.
• ARCHITECTURE.md [175-295] — Added comprehensive architecture documentation with system context, internal structure, data flow diagrams, and key dependencies.
• CONTRIBUTING.md [298-377] — Extended with testing commands, linting, BC checks, branch strategy, release process, and CI overview.
• README.md [380-400] — Added agent/contributor documentation index table.
• docs/ADRs/0001-contentful-core-foundation.md [403-434] — ADR documenting use of contentful/core as shared SDK foundation.
• docs/ADRs/0002-psr-interfaces-for-cache-and-logging.md [437-469] — ADR documenting PSR-6/PSR-3 interface acceptance for cache/logging.
• docs/ADRs/0003-devcontainer-for-reproducible-ci.md [472-501] — ADR documenting devcontainer usage for environment parity.
• docs/ADRs/0004-phpstan-level-and-known-violations.md [504-533] — ADR documenting PHPStan level 5 and accepted LocalizedResource::$sys violation.
• docs/ADRs/0005-php-vcr-integration-testing.md [536-571] — ADR documenting php-vcr usage and migration debt (cassettes cannot be re-recorded).
• docs/ADRs/0006-semver-and-php-version-policy.md [574-609] — ADR documenting Semver policy: PHP version drops require major bump.
• docs/ADRs/README.md [612-633] — Added ADR index with 6 accepted decisions.
• docs/specs/README.md [636-660] — Added specs directory README with naming conventions and status values.

Repository Impact:
• Developer onboarding: New AGENTS.md, ARCHITECTURE.md, and ADRs significantly improve context for new contributors and automated agents.
• Review process: .bito.yaml and guidelines establish automated review rules for BC breaks, cache correctness, and link resolution.

Cross-Repository Dependencies:
• None.

Database/Caching Impact:
• None

API Contract Violations:
• None.

Infrastructure Dependencies:
• None.

Additional Insights:
• Documentation completeness: PR establishes comprehensive documentation structure matching industry best practices for open-source SDKs.

Testing Recommendations

Frontend Impact:
• No issues detected - no frontend changes.

Service Integration:
• No issues detected - no service changes.

Data Serialization:
• No issues detected - no serialization changes.

Privacy Compliance:
• No issues detected - no PII handling changes.

Backward Compatibility:
• No issues detected - documentation additions do not affect BC.

OAuth Functionality:
• None

Cross-Service Communication:
• No issues detected - no service communication changes.

Reliability Testing:
• None

Additional Insights:
• Verify all markdown files render correctly (links, tables, mermaid diagrams).
• Confirm ADR numbering is sequential and index is complete.
• Validate that .bito.yaml paths reference existing guideline files.

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

[bito-code-review]

✅ Review Settings Overridden

Status: Overridden Successfully

Guidelines:

• Accepted:

  • General : Domain Invariants

• Rejected: Repo Truth And Alignment (parse error),Review Posture (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.