Open History to see the last commit
1{
2 "$schema": "./coupling.schema.json",
3 "couplings": [
4 {
5 "id": "ai-source-touches-agent-skills",
6 "trigger": "packages/ai*/src/**/*.ts",
7 "impacts": [
8 {
9 "target": [
10 "packages/ai/skills/ai-core/structured-outputs/SKILL.md",
11 "packages/ai/skills/ai-core/chat-experience/SKILL.md",
12 "packages/ai/skills/ai-core/tool-calling/SKILL.md",
13 "packages/ai/skills/ai-core/adapter-configuration/SKILL.md",
14 "packages/ai/skills/ai-core/middleware/SKILL.md",
15 "packages/ai/skills/ai-core/media-generation/SKILL.md",
16 "packages/ai/skills/ai-core/ag-ui-protocol/SKILL.md",
17 "packages/ai/skills/ai-core/debug-logging/SKILL.md",
18 "packages/ai/skills/ai-core/custom-backend-integration/SKILL.md",
19 "packages/ai-code-mode/skills/ai-code-mode/SKILL.md"
20 ],
21 "kind": "change-required",
22 "why": "Agent skills are a contract with downstream coding agents. When the source surface they cover changes (new public API, changed type, new pattern, removed pattern, deprecation), the skill must be updated in the same PR — otherwise agents reading the skill keep generating obsolete or wrong code targeting a surface that no longer exists. Use this list to decide which skill(s) cover the file you're touching: `activities/chat/**` → chat-experience / structured-outputs / tool-calling; `activities/generateImage|generateAudio|generateVideo|generateSpeech|generateTranscription|summarize/**` → media-generation; `middleware/**` → middleware; `protocol/**` → ag-ui-protocol; `adapters/**` or anything that affects the adapter contract → adapter-configuration. Skip only for pure refactors / perf / internal-only changes that don't surface a new pattern or change observable behavior."
23 }
24 ]
25 },
26 {
27 "id": "ai-source-touches-public-docs",
28 "trigger": "packages/ai*/src/**/*.ts",
29 "impacts": [
30 {
31 "target": [
32 "docs/structured-outputs/**/*.md",
33 "docs/chat/**/*.md",
34 "docs/tools/**/*.md",
35 "docs/adapters/**/*.md",
36 "docs/advanced/**/*.md",
37 "docs/api/**/*.md",
38 "docs/getting-started/**/*.md",
39 "docs/protocol/**/*.md",
40 "docs/media/**/*.md",
41 "docs/code-mode/**/*.md",
42 "docs/migration/**/*.md"
43 ],
44 "kind": "change-required",
45 "why": "Public docs are the canonical source for users. When the source surface they describe changes — new capability, behavior change, deprecation — the docs must be updated in the same PR. Cases to watch for: (1) the new behavior contradicts existing doc advice (e.g. removing a hack the doc still recommends); (2) the new capability opens a use case no existing page covers (consider whether a new page is needed, plus nav config and cross-links); (3) a public type / function gains or loses generic parameters, optional fields, etc. Run `pnpm test:docs` after editing to catch cross-link rot. Skip only for pure refactors / perf / internal-only changes."
46 }
47 ]
48 },
49 {
50 "id": "ai-source-touches-e2e-coverage",
51 "trigger": "packages/ai*/src/**/*.ts",
52 "impacts": [
53 {
54 "target": [
55 "testing/e2e/tests/**/*.spec.ts",
56 "testing/e2e/fixtures/**",
57 "testing/e2e/src/lib/feature-support.ts",
58 "testing/e2e/src/lib/types.ts"
59 ],
60 "kind": "new-code-required",
61 "why": "Per CLAUDE.md, every feature / bug fix / behavior change MUST include E2E test coverage. When a new public capability is added, a corresponding spec under testing/e2e/tests/ plus a fixture under testing/e2e/fixtures/ are required — often plus a new entry in feature-support.ts and types.ts. The full pattern is: add the Feature flag, decide provider support, optionally add a per-feature config (system prompt, schema, tools), wire it through src/routes/api.chat.ts (or the relevant route), write the fixture(s), write the spec iterating `providersFor(feature)`. Spec must run against every supported provider so non-native-streaming providers exercise the fallback path. Skip only for refactors that don't change observable behavior."
62 }
63 ]
64 },
65 {
66 "id": "sandbox-core-contract-touches-providers",
67 "trigger": "packages/ai-sandbox/src/**/*.ts",
68 "impacts": [
69 {
70 "target": [
71 "packages/ai-sandbox-local-process/src/**/*.ts",
72 "packages/ai-sandbox-docker/src/**/*.ts",
73 "packages/ai-sandbox-cloudflare/src/**/*.ts"
74 ],
75 "kind": "change-required",
76 "why": "The SandboxProvider / SandboxHandle / SandboxCapabilities contracts in @tanstack/ai-sandbox are the seam every provider package implements. When a method, capability flag, lifecycle field, or the ensure/resume algorithm changes in core, every provider package must be updated in the same PR or it falls out of contract (silent type breaks, missing capability handling, broken resume). Also re-check capability degradation: a provider that returns capabilities().snapshots===false must keep working when core adds a snapshot-dependent path."
77 }
78 ]
79 },
80 {
81 "id": "harness-adapter-sandbox-execution",
82 "trigger": "packages/ai-claude-code/src/**/*.ts",
83 "impacts": [
84 {
85 "target": [
86 "packages/ai-acp/src/**/*.ts",
87 "packages/ai-codex/src/**/*.ts",
88 "packages/ai-gemini-cli/src/**/*.ts",
89 "packages/ai-grok-build/src/**/*.ts",
90 "packages/ai-opencode/src/**/*.ts",
91 "packages/ai-sandbox/src/**/*.ts"
92 ],
93 "kind": "change-required",
94 "why": "Harness adapters share one execution contract: declare requires:[SandboxCapability], run the agent via sandbox.process or an in-sandbox ACP WebSocket server (stdio when writableStdin, else ports.connect), translate ACP/session-json output through @tanstack/ai-acp or a per-adapter translator, and proxy host tools via the MCP-over-channel bridge. When the sandbox-execution pattern, ACP transport/session layer, host MCP tool-bridge shape, or policy->permission mapping changes in one adapter (or in @tanstack/ai-sandbox / @tanstack/ai-acp), mirror it across the other harness adapters so they don't diverge."
95 }
96 ]
97 },
98 {
99 "id": "acp-shared-layer-coupling",
100 "trigger": "packages/ai-acp/src/**/*.ts",
101 "impacts": [
102 {
103 "target": [
104 "packages/ai-gemini-cli/src/**/*.ts",
105 "packages/ai-grok-build/src/**/*.ts"
106 ],
107 "kind": "change-required",
108 "why": "@tanstack/ai-acp is the shared ACP client, stdio/WebSocket transport, sandbox-server bootstrap, and AG-UI translator. Changes to session lifecycle, transport framing, translate labels, or permission helpers must be reflected in every harness adapter that imports it (gemini-cli, grok-build; claude/codex when wired)."
109 }
110 ]
111 },
112 {
113 "id": "sandbox-source-persistence-ready",
114 "trigger": "packages/ai-sandbox*/src/**/*.ts",
115 "impacts": [
116 {
117 "target": ["packages/ai-sandbox/src/**/*.ts"],
118 "kind": "change-required",
119 "why": "The sandbox layer ships with zero persistence package but MUST stay persistence-ready so the persistence proposal drops in without re-architecture. Invariant to preserve on any sandbox change: SandboxStore and LockStore stay PLUGGABLE optional capabilities (in-memory defaults only - never hardcode storage), emitted chunks stay conceptually offset-addressable ({runId, seq, ts, chunk}) so a future EventLog/DurableRunStream can capture+replay by cursor, and approvals keep using the existing resume-based approval-requested flow. Do not introduce a sandbox-owned durable store, a bespoke replay buffer, or a non-AG-UI event type that the persistence layer would later have to rip out."
120 }
121 ]
122 }
123 ]
124}