Change a Large Platform Monorepo and Keep Every Affected Client in Sync

## Read the Root Rules, Then Each Folder's Own Instructions Use the repository root as the coordination point and the nearest local instruction file as the task-specific authority. Apply root rules first, then add the rules owned by each affected directory rather than assuming one module's conventions govern the whole change. For areas without a local instruction file, use the nearest maintained development guide, module README, and continuous-integration workflow as the next sources of truth. Read every applicable guide before editing a cross-cutting change. ## Find Which Module Owns Each Part Before Editing Identify which modules own the control plane, runtime components, public specifications, client libraries, deployment resources, command-line interface, end-to-end tests, documentation, examples, and architectural proposals. Route lifecycle and configuration behavior to the control-plane owner, runtime process behavior to the nearest component guide, public schema changes to the specification owner, client generation to the library owner, deployment behavior to its operator or packaging owner, and command behavior to the CLI owner. For a change spanning a contract, implementation, and clients, start with the public specification and then load every affected consumer guide. Keep component APIs, test assumptions, and deployment integration aligned with the same contract. ## Confirm the Goal and Change Only the Needed Lines State assumptions, expose ambiguity, and ask for direction when the request has conflicting interpretations. Convert nontrivial work into observable success criteria before implementation and stop when a decision is required. Choose the smallest solution that satisfies the request. Avoid speculative features, one-off abstractions, unnecessary configurability, unrelated refactoring, and deletion of pre-existing work. Touch only the files and lines required by the task, match local style, add or update focused tests when behavior changes, and iterate until checks pass or the remaining blocker is explicit. ## Update Clients and Docs When the Public Spec Changes Treat public specifications as authoritative contract sources. When user-visible behavior changes, keep the specification, implementation, client libraries, documentation, examples, configuration, command behavior, and release outputs synchronized. When deployment APIs or orchestrator resources change, also update or verify generated manifests, deployment packages, controller behavior, server integration, and operational documentation. Do not allow a contract to drift intentionally from an implementation without explicit approval. Update user-facing and operations-facing documentation before or with the implementation so the documented behavior remains the governing public promise. ## Fix the Source, Then Regenerate Generated Files Never edit generated output as the only fix. Locate and change the authoritative schema, template, configuration, or generator input, then regenerate all affected clients, manifests, references, examples, and packaged artifacts through the supported workflow. Review the generated diff for unexpected changes and verify downstream consumers against the regenerated contract. Keep handwritten adapters separate from generated code and preserve the repository's ownership boundary between them. If regeneration is blocked, report the missing tool or environment and leave the source and derived outputs in a clearly identified incomplete state rather than presenting them as synchronized. ## Ask Before Making Breaking Public Changes Prefer additive, backward-compatible changes for public APIs, client interfaces, configuration, protocols, command behavior, deployment resources, annotations, labels, and package values. Ask before making a breaking public change, introducing intentional contract drift, or changing visible behavior without a clear migration path. Describe affected consumers, compatibility impact, migration requirements, and release consequences before seeking approval. Never hide a breaking change behind a generated diff or mix unrelated component work into the same change. Keep the approved compatibility decision explicit in implementation, documentation, tests, and release notes. ## Run Checks on the Smallest Scope First, Then Widen Run file-scoped or package-scoped formatters, linters, unit tests, contract checks, and command-output assertions before broader validation. Expand to integration, cross-language, deployment, or documentation builds when the change crosses those boundaries. Verify command help and output alongside CLI tests, contract examples alongside schema checks, client behavior across supported languages, and deployment output on the affected platform. Update focused tests whenever behavior changes or a bug is fixed. Mention every unrun or blocked check in the final handoff. Do not claim completion while a required check is failing or while an affected consumer remains unverified without an explicit limitation. ## Keep Each Doc in One Place and Link Instead of Copying Keep long-form user and operations guidance in the designated documentation tree. Reserve the root README for the repository entry point and publishable package READMEs for installation, quick starts, and package entry points. Keep internal component READMEs minimal when a maintained documentation page exists. Store runnable examples in the example tree and their explanatory pages in the documentation tree; use proposal documents as the authority and community pages only as indexes when that is the repository convention. Link community and development policies instead of duplicating them. Prefer version-relative links from repository files so documentation follows the checked-out branch or tag, and do not use a public website as the only source from versioned code. ## Follow the Docs Site's Page Rules and Build with Zero Errors Use the configured documentation engine and static site configuration without introducing undocumented build-time generation. Put images in the designated public asset directory and reference them using the site's approved path convention. Give every published page the required metadata, use the configured internal-link style, and use full source links when linking outside the documentation tree. Apply approved callouts, code groups, and navigation conventions consistently. Keep contributor-only instructions excluded from the published site. Add localized copies only where the localization policy permits them, and run the documentation build to zero errors before considering publication-ready changes complete. ## Review Breaking Changes and Report Remaining Risks Prioritize review of breaking changes in public specifications, client interfaces, configuration, command behavior, deployment resources, and protocols. Flag changes that are unnecessary, internally inconsistent, difficult for consumers to implement, or missing a credible migration path. Check for broken source-of-truth boundaries, violated layering, stale generated output, missing tests, undocumented behavior, and compatibility regressions. Separate confirmed defects from unverified risk and cite the affected contract or consumer. End with an evidence-based report covering changed areas, synchronized consumers, checks run, blocked verification, compatibility decisions, and remaining risks.