From b309226fc4b8743199e244e65c8905dd2d264b93 Mon Sep 17 00:00:00 2001
From: saladday <1203511142@qq.com>
Date: Mon, 28 Sep 2026 21:11:43 +0800
Subject: [PATCH] docs: establish component decoupling principle

---
 AGENTS.md       | 10 ++++++++++
 CONTRIBUTING.md | 28 ++++++++++++++++++++++++++++
 2 files changed, 38 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index 9a4fbdeb1..303be1247 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -4,6 +4,16 @@ OpenAgentCore is the independent execution service behind Parsar. Product busine
 code, its database and migrations stay in the Parsar repository. Read
 [CONTRIBUTING.md](CONTRIBUTING.md) before changing code.
 
+## Decoupling principle
+
+Sandbox providers (including user-owned machines), models and harnesses must be
+replaceable through shared protocols and interfaces. Keep implementation-specific
+behavior inside registered providers and adapters; do not add harness-, runtime-
+or vendor-name branches to Core orchestration. Fix shared lifecycle or performance
+problems in the common protocol and flow. Validate combinations through declared
+capabilities, with explicit errors rather than silent fallback. See
+[the canonical rules](CONTRIBUTING.md#decoupling-principle).
+
 ## Interfaces and credentials
 
 Core serves three namespaces. Each has one kind of caller and its own credential;
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index b32f49e9c..80420dc72 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -16,6 +16,34 @@ documented below. The source snapshot and per-file
 hashes provide an audit trail; future Core development need not preserve those
 hashes. Do not automatically sync or delete the original repository's Core.
 
+## Decoupling principle
+
+Core orchestrates protocol-defined operations. Sandbox providers, Runtime
+implementations, harnesses and model providers are replaceable components.
+User-owned machines, E2B, Docker and other environments must expose the same
+execution protocol; placement and connection details belong to their providers.
+
+- Keep component boundaries explicit through shared interfaces and versioned
+  protocols. Register implementations behind those interfaces. Adding an
+  implementation must not require a new orchestration path selected by its name.
+- Core owns durable Session/Turn state and scheduling. Runtime owns local
+  execution resources. Harness adapters translate the common execution contract
+  into native operations; model and sandbox provider details remain behind their
+  respective interfaces.
+- Fix shared lifecycle, admission, cancellation, reuse and performance problems
+  in the common protocol or flow. Do not patch them with harness-, runtime- or
+  vendor-specific branches in Core. Adapters may implement native differences,
+  but must preserve the shared operation and event semantics.
+- Express compatibility through declared capabilities and validate selected
+  combinations explicitly. Replaceability does not guarantee that every model,
+  harness and environment combination is supported. Do not silently substitute
+  another implementation or give a capability different meanings per vendor.
+- Evolve shared contracts and their implementations together, documenting
+  ownership and validating the same contract across implementations. This rule
+  does not claim existing implementations already satisfy every target, change
+  the pinned public API, or authorize unrelated refactors or live Session
+  configuration switching.
+
 ## Workflow and quality
 
 Develop in an isolated worktree on a feature branch and submit a PR. Do not edit