|
| 1 | +--- |
| 2 | +name: cross-platform-api-change |
| 3 | +description: Coordinate an RTC API Examples change across Android, iOS, macOS, and Windows when behavior, SDK usage, dependencies, CI, or packaging may affect more than one project. |
| 4 | +--- |
| 5 | + |
| 6 | +# Cross-Platform API Change |
| 7 | + |
| 8 | +Use one written contract to keep every affected implementation aligned. The contract is |
| 9 | +the source of truth for behavior; an existing platform implementation is only a reference. |
| 10 | + |
| 11 | +## Required Context |
| 12 | + |
| 13 | +1. Read the root `AGENTS.md`. |
| 14 | +2. Read `docs/ai/README.md`, `docs/ai/change-contract-template.md`, and |
| 15 | + `docs/ai/project-matrix.md`. |
| 16 | +3. For SDK, dependency, CI, packaging, signing, or external-asset changes, also read |
| 17 | + `docs/ai/release-risks.md`. |
| 18 | +4. Read the platform and project `AGENTS.md` and `ARCHITECTURE.md` files for every project |
| 19 | + that may be affected. |
| 20 | + |
| 21 | +Treat the current source tree as the case inventory. Do not rely on a separately maintained |
| 22 | +case catalog. |
| 23 | + |
| 24 | +## Workflow |
| 25 | + |
| 26 | +### 1. Establish The Contract |
| 27 | + |
| 28 | +Before editing, copy `docs/ai/change-contract-template.md` into the issue, pull request, or |
| 29 | +task notes and complete it. Define observable behavior, SDK operations, inputs and defaults, |
| 30 | +callbacks, success and failure signals, lifecycle cleanup, non-goals, and the reference |
| 31 | +implementation or documentation. |
| 32 | + |
| 33 | +Separate shared behavior from platform-specific API and UI details. If the requirement |
| 34 | +changes, update the contract first and then re-evaluate scope and existing work. |
| 35 | + |
| 36 | +### 2. Decide Every Project |
| 37 | + |
| 38 | +Review every row in `docs/ai/project-matrix.md`. Mark each project `REQUIRED`, |
| 39 | +`REVIEW_ONLY`, or `NOT_APPLICABLE`. Include a reason for every project that is not required. |
| 40 | +Do not assume that Android Views covers Compose, iOS UIKit covers SwiftUI or Objective-C, |
| 41 | +or a full-SDK project covers its audio-only counterpart. |
| 42 | + |
| 43 | +### 3. Implement From The Same Contract |
| 44 | + |
| 45 | +One coordinator owns the contract and cross-platform decisions. Split implementation by |
| 46 | +top-level platform only when parallel work is explicitly available, and give every owner |
| 47 | +the same contract, its project scope, allowed paths, reference, and validation requirements. |
| 48 | +Platform owners must not redefine shared behavior. |
| 49 | + |
| 50 | +Implementations may differ because of SDK types, UI frameworks, permissions, or operating |
| 51 | +system behavior. Record each intentional difference and its reason in the contract. |
| 52 | + |
| 53 | +### 4. Verify Each Required Project |
| 54 | + |
| 55 | +For every required project: |
| 56 | + |
| 57 | +- compare the diff with the shared contract; |
| 58 | +- verify SDK arguments, defaults, callbacks, lifecycle, threading, errors, registration, |
| 59 | + resources, localization, and cleanup as applicable; |
| 60 | +- run the strongest valid build or static check documented by that project; |
| 61 | +- record changed files, commands, results, blockers, and intentional differences. |
| 62 | + |
| 63 | +Keep scope decisions and validation status separate. Record each planned validation as one |
| 64 | +of: |
| 65 | + |
| 66 | +- `PASS`: the command or behavioral check completed and met its acceptance criteria; |
| 67 | +- `FAIL`: the check ran and failed; |
| 68 | +- `BLOCKED`: the check cannot run yet; record the blocker, remaining command, and the |
| 69 | + condition that will unblock it; |
| 70 | +- `NOT_RUN`: the check was not attempted; record why. |
| 71 | + |
| 72 | +Do not convert `BLOCKED` or `NOT_RUN` into a pass. They are valid handoff states, but they |
| 73 | +leave the overall change incomplete. |
| 74 | + |
| 75 | +Compilation is necessary but does not prove behavioral parity. Use an independent review |
| 76 | +pass when available. |
| 77 | + |
| 78 | +### 5. Close Cross-Platform Acceptance |
| 79 | + |
| 80 | +The change is complete only when every project has an explicit scope decision, every |
| 81 | +required implementation satisfies the contract, and every required validation is `PASS`. |
| 82 | +A change with `FAIL`, `BLOCKED`, or `NOT_RUN` validation may be handed off with clear next |
| 83 | +steps, but must not be reported as complete. Copy the final scope, differences, and |
| 84 | +validation evidence into the pull request using `.github/pull_request_template.md`. |
| 85 | + |
| 86 | +Before handoff, confirm that SDK sources match `docs/ai/project-matrix.md` and that no real |
| 87 | +App ID, certificate, token, signing asset, private key, or private download URL is staged. |
| 88 | + |
| 89 | +Do not commit task transcripts, agent identities, generated case catalogs, prompt snapshots, |
| 90 | +or run logs. Preserve durable product behavior and verification evidence in the issue or |
| 91 | +pull request. |
0 commit comments