Change a Monorepo With Parallel Implementations and Keep Them in Sync

## Read the Monorepo's Layout and Local Rules Before Editing - Map the repository by product, language, functional domain, shared utility area, test suite, release tooling, and configuration. - Identify which directories belong to each implementation and which top-level rules apply repository-wide. - Before editing a nested area, read its local agent guide, contribution guide, and configuration; local rules may specialize but must not weaken the baseline. - Apply language-specific build, style, and test rules only to code written in that language. - Locate the workspace definition, root scripts, and product-specific instructions before choosing commands or dependencies. ## Mirror User-Visible Changes in Every Implementation - Treat parallel implementations of the same user-facing product as equal sources of truth. - Replicate every user-visible change across all implementations in the same change request whenever possible. - User-visible behavior includes flags, defaults, environment handling, error codes and messages, logs consumed by tools, file and state formats, storage layout, and hook semantics. - Internal refactors, implementation-only performance work, and implementation-specific test cleanup do not require artificial mirroring. - If equivalent work cannot be completed immediately, state the exact parity gap, why it remains, and what must land before the change can merge. - Never allow one implementation to become an undocumented downstream port of another. ## Rebuild What the Tests Run So They Don't Test Old Code - Install dependencies and compile with the repository's documented bootstrap path before relying on test results. - Compile only the affected package during fast iteration when that produces the same artifact consumed by the selected tests. - Determine whether end-to-end tests execute source outputs, package outputs, or a bundled executable. - Rebuild the bundle after any contributing package changes when end-to-end tests consume the bundle; otherwise the test may exercise stale code. - Run the appropriate language-specific build for each changed implementation. - Treat a passing test against stale generated output as invalid evidence. ## Test Only the Affected Code and Look Into Every Failure - Do not run an entire large repository test suite by default. Start with the affected project, file, or named test case. - Expand the test scope only when dependencies, shared contracts, or observed failures justify it. - Match the runtime, build artifact, and implementation under test to the claim being verified. - Investigate every failure instead of labeling it unrelated or pre-existing without evidence. - If a failure existed before the change, identify its cause and either fix it within the authorized scope or report the concrete blocker; never silently skip it. - Record the exact command, affected target, and result so another contributor can reproduce the evidence. ## Review Changed Code for Security First, Then Performance - Follow the repository's review guide and limit findings to code affected by the change and its direct consequences. - Review security first and performance second unless a stricter project rule applies. - For a security finding, explain the reachable input, trust boundary, exploit path, and impact. - For a performance finding, identify the hot path, frequency, allocation or I/O cost, and likely user effect. - Verify tests, release intent, and cross-implementation parity as part of acceptance. - Do not produce speculative findings that cannot be connected to the changed behavior. ## Search for Existing Code and Dependencies Before Adding New Ones - Search shared packages, filesystem helpers, cryptographic utilities, text utilities, and nearby domain modules before implementing non-trivial logic. - Reuse an existing exported utility when it already owns the behavior. - If similar logic exists but is trapped in one package, extract the common contract into the narrowest appropriate shared location instead of copying it. - Prefer a maintained existing dependency for common functionality when it is suitable, lightweight enough, and allowed by repository policy. - Add a new dependency to the most specific package that needs it; move it upward only when multiple packages truly share it. - Do not add wrappers that merely rename or forward an existing operation without adding a contract. ## Follow Commit Message Rules Without Bypassing Commit Hooks - Use the repository's required commit-message convention and choose the change type that reflects user impact. - Before committing, confirm that repository hooks are installed and active; a fresh checkout may not have registered them. - Never bypass a failing commit guard, disable the hook, or add a suppression file. Correct the underlying message or change. - Avoid bare numeric issue references because the hosting platform may link them to the wrong repository; use a qualified repository reference or an absolute URL. - Wrap username-like code identifiers in inline code or remove unnecessary mentions so a commit does not notify unrelated people. - Use list numbering without a reference marker when enumerating items. ## Add a Release Entry When a Published Package Changes - Add a release-intent entry whenever a change affects a published package. - Name every affected package and select the version impact from bug fix, backward-compatible feature, or breaking change. - Write the entry for users and keep it concise; put implementation rationale in the commit message. - Include the primary command-line package for changes to its main implementation when repository policy requires it. - For implementation-specific changes, name only the products that actually changed. A parity change must name packages from every affected implementation. - Respect stable and prerelease release lanes, fixed version groups, and the repository's graduation procedure. ## Write Comments Only for Reasons the Code Can't Show - Prefer names, types, helper boundaries, and control flow that make the code explain itself. - Do not add comments that restate an operation, duplicate callee documentation, or narrate obvious syntax. - Document a shared reason once at the common owner instead of repeating it at each call site. - Use documentation comments for preconditions, postconditions, edge cases, and non-obvious guarantees. - Keep refactor history and descriptions of removed designs in version control history and change messages, not in current source comments. - Before adding prose, ask whether renaming, restructuring, or extraction would communicate the idea more reliably. ## Follow the Repo's Formatting and Error Handling Rules - Use the repository formatter and language-specific style guide; preserve the established import grouping and ordering. - Prefer functions over stateful classes when the codebase does, and replace long parameter lists with a typed options object. - Use stable domain error types for user-reachable failures, preserve error codes, include relevant context, and never swallow unexpected errors. - Catch only the expected error condition, and use a cross-realm-safe native-error check in virtualized test environments. - Give functions verb names, keep terminology consistent, and rename a concept everywhere when its contract changes. - Prefer simple string operations for simple parsing and the existing structured parser for grammars requiring backtracking. - Route configurable values through the configuration layer, keep command handlers independent from presentation, and avoid hard-coded policy. - Use asynchronous I/O, run independent operations concurrently, await required completion, and hoist invariant work out of loops. ## Keep the Change Request Matching the Real Changes Until Merge - Open a change request with the repository template, preserve required sections, and remove only content the template marks optional. - Keep its title and description synchronized with the actual changes after each substantial update. - Reply to addressed review conversations with the resolution and supporting revision, then resolve the conversation. - Label agent-authored remote content according to repository policy without exposing sensitive implementation context. - Use the repository-approved conflict-resolution workflow so the base is current, generated lock data is rebuilt deterministically, and mergeability is verified. - Inspect non-generated conflicts manually. Any force update or other remote history rewrite requires explicit authorization and a verified target.