Skip to content

πŸ™Œ OpenHands: AI-Driven Development

docs: document OpenHands repository boundaries (#16834)

Graham Neubig1e995e89ab03
diff --git a/.agents/skills/custom-codereview-guide.md b/.agents/skills/custom-codereview-guide.md
index 9bda2209fb..e542d573d0 100644
--- a/.agents/skills/custom-codereview-guide.md
+++ b/.agents/skills/custom-codereview-guide.md
@@ -15,6 +15,19 @@ You have permission to **APPROVE** or **COMMENT** on PRs. Do not use REQUEST_CHA
**Mandatory:** Always submit exactly one PR review object before finishing. If you found no actionable issues, post a short **APPROVE** review rather than ending silently without posting a review. If you found actionable issues or concerns, post a **COMMENT** review.
+
+## Repository Boundaries
+
+Review each change in the context of the repository that owns the behavior:
+
+- [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) owns Agent Canvas UI, frontend state, backend selection, and local-stack orchestration.
+- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and canonical server API.
+- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns the browser-compatible typed client and generated/maintained types for that API.
+- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations.
+- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations; [`OpenHands/automation`](https://github.com/OpenHands/automation) owns automation definitions, scheduling, webhooks, run history, and dispatching; the Agent Server/SDK executes dispatched conversations.
+
+The usual flow is `software-agent-sdk` / Agent Server β†’ OpenAPI contract β†’ `typescript-client` β†’ Agent Canvas. When reviewing a cross-repository change, verify that backend behavior and endpoints are implemented in the SDK, client access is implemented in `typescript-client`, frontend integration is implemented in Canvas, and automation lifecycle behavior is implemented in `automation`. Flag duplicated or misplaced logic, and check that linked PRs update the appropriate contract layer in order. If a PR is opened in the wrong repository, say so explicitly in the review and recommend that it may need to be closed and moved to the repository that owns the change rather than merged here.
+
### Review decision policy (eval / benchmark risk)
Do **NOT** submit an **APPROVE** review when the PR changes agent behavior or anything
diff --git a/AGENTS.md b/AGENTS.md
index 5ada25794f..936157a940 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -40,6 +40,22 @@ Common mis-placements to avoid:
- **New server endpoints / agent or tool logic** β†’ belongs in `software-agent-sdk`.
- **Skills / automations / integrations** β†’ belong in `extensions`.
+## Cross-Repository Boundaries
+
+The four repositories have distinct ownership boundaries:
+
+| Repository | Owns |
+|---|---|
+| [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) | Agent Canvas frontend, user-facing control center, backend selection, and local-stack orchestration. |
+| [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) | Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and the canonical server API. |
+| [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) | Browser-compatible TypeScript client and generated/maintained types for the Agent Server API. |
+| [`OpenHands/automation`](https://github.com/OpenHands/automation) | Automation definitions, scheduling, webhooks, run history, and dispatching. It manages when automations run; the Agent Server/SDK executes them. |
+
+The usual dependency direction is `software-agent-sdk` / Agent Server β†’ OpenAPI contract β†’ `typescript-client` β†’ Agent Canvas. Automation scheduling and dispatching flow from Agent Canvas to `automation`, which starts work on the Agent Server/SDK. Put new server behavior and endpoints in `software-agent-sdk`, client access in `typescript-client`, UI and frontend integration in this repository, and scheduling/webhook lifecycle behavior in `automation`.
+
+All pull requests for this repository must comply with [`.agents/skills/custom-codereview-guide.md`](.agents/skills/custom-codereview-guide.md), in addition to the general contribution requirements and CI checks.
+
+
## PR Description Human Check
The `HUMAN:` section in PR descriptions is reserved for human contributors only.
diff --git a/README.md b/README.md
index 913095dc94..538682ff33 100644
--- a/README.md
+++ b/README.md
@@ -136,6 +136,20 @@ The Agent Server is often paired with an [Automation Server](https://github.com/
<img width="1456" height="1258" alt="image" src="https://github.com/user-attachments/assets/cb6de6f5-ac30-4d04-a76a-b5c259f0c163" />
+### Repository boundaries
+
+Agent Canvas is part of a multi-repository OpenHands system. Changes should go to the repository that owns the behavior:
+
+| Repository | Responsibility |
+|---|---|
+| [`OpenHands/OpenHands`](https://github.com/OpenHands/OpenHands) | Agent Canvas frontend, user-facing control center, backend selection, and local-stack orchestration. |
+| [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) | Python SDK, Agent Server, agents, tools, conversations, workspaces, events, and the canonical server API. |
+| [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) | Browser-compatible TypeScript client for the Agent Server API. |
+| [`OpenHands/automation`](https://github.com/OpenHands/automation) | Automation definitions, scheduling, webhooks, run history, and dispatching. |
+
+The Agent Server API is implemented by the SDK and consumed through the TypeScript client by Agent Canvas. The automation service decides when work runs and dispatches conversations to the Agent Server/SDK, which decides what runs. See [`AGENTS.md`](./AGENTS.md) for contributor-specific boundaries and the required custom code-review guide.
+
+
## More documentation
- [Documentation index](./docs/README.md)
diff --git a/docs/DEVELOPMENT.md b/docs/DEVELOPMENT.md
index 48c3b725ad..bc557a4d6a 100644
--- a/docs/DEVELOPMENT.md
+++ b/docs/DEVELOPMENT.md
@@ -8,6 +8,18 @@ This document is for contributors working on `agent-canvas` itself.
`uvx`, Vite dev server with live reload, and an ingress proxy) β€” all without
Docker.
+## Repository boundaries
+
+This repository contains the Agent Canvas frontend and local-stack orchestration. Use the sibling repositories for their owned layers:
+
+- [`OpenHands/software-agent-sdk`](https://github.com/OpenHands/software-agent-sdk) owns the Python SDK, Agent Server, agent/tool behavior, conversations, workspaces, events, and server API.
+- [`OpenHands/typescript-client`](https://github.com/OpenHands/typescript-client) owns browser-compatible typed access to that Agent Server API. Add client methods there rather than reimplementing API calls in Canvas.
+- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations.
+- [`OpenHands/extensions`](https://github.com/OpenHands/extensions) owns reusable skills, plugins, automations, and integrations; [`OpenHands/automation`](https://github.com/OpenHands/automation) owns automation definitions, scheduling, webhooks, run history, and dispatching; Agent Server/SDK code executes the dispatched conversations.
+
+When a feature crosses repositories, implement the backend contract in the SDK first, expose it through `typescript-client`, and consume it in Canvas. Coordinate automation lifecycle changes in `automation`. See the repository [contributor notes](../AGENTS.md) and follow the [custom code-review guide](../.agents/skills/custom-codereview-guide.md) for every pull request.
+
+
For a static frontend build (better for slow networks, remote access, tunnels):
```sh