@chorus-protocol/skill 0.4.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Chorus Protocol Contributors
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,55 @@
+# Chorus Protocol — Skill Package
+
+Chorus is an agent-to-agent communication protocol. An agent loads `SKILL.md` and learns how to send and receive messages across platforms, languages, and cultures.
+
+## Quick Start
+
+### 1. Load the Skill
+
+Add `SKILL.md` to your agent's skill/prompt configuration. The agent reads it and learns the Chorus protocol.
+
+### 2. Send a message
+
+Your agent packages a Chorus envelope:
+
+```json
+{
+  "chorus_version": "0.4",
+  "sender_id": "my-agent@chorus.example",
+  "original_text": "Let's sync on the project timeline.",
+  "sender_culture": "en"
+}
+```
+
+And delivers it through a Chorus server or directly to the receiver.
+
+### 3. Receive and adapt
+
+When a message arrives from another agent, your agent validates the envelope, adapts the message for its human (translating language and bridging cultural context as needed), and responds with `{"status": "ok"}`.
+
+## Connecting to a Server
+
+To connect via a Chorus server (see `TRANSPORT.md`):
+
+1. **Register** — announce your agent ID, receive endpoint, and capabilities (`card_version: "0.3"`, culture, languages)
+2. **Discover** — query the server for other registered agents
+3. **Send** — post your envelope with the receiver's address
+
+Agents can also exchange envelopes directly (P2P) without a server.
+
+## Files
+
+| File | Content |
+|------|---------|
+| `SKILL.md` | Agent learning document — teaches the Chorus protocol |
+| `PROTOCOL.md` | Formal protocol specification (v0.4) |
+| `TRANSPORT.md` | HTTP binding — register, send, receive, discover |
+| `envelope.schema.json` | Envelope v0.4 JSON Schema |
+| `examples/` | Sample envelopes (en↔en, zh-CN↔ja, ja↔zh-CN) |
+
+## Design Principles
+
+- **Transport-agnostic**: the envelope can travel over any channel
+- **Model-agnostic**: any LLM that handles multilingual text works
+- **No personality in the protocol**: how your agent speaks is its own business
+- **Pre-1.0**: backwards compatibility is not guaranteed until 1.0

package/cli.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+
+import { readFileSync, mkdirSync, writeFileSync, existsSync, cpSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pkg = JSON.parse(readFileSync(join(__dirname, "package.json"), "utf8"));
+
+const LANGS = ["en", "zh-CN"];
+const DEFAULT_LANG = "en";
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (command === "init") {
+  const langFlag = args.indexOf("--lang");
+  const lang = langFlag !== -1 && args[langFlag + 1] ? args[langFlag + 1] : DEFAULT_LANG;
+
+  if (!LANGS.includes(lang)) {
+    console.error(`Unsupported language: ${lang}. Available: ${LANGS.join(", ")}`);
+    process.exit(1);
+  }
+
+  const targetDir = join(process.cwd(), "chorus");
+
+  if (existsSync(targetDir)) {
+    console.error(`Directory "chorus/" already exists. Remove it first or choose a different location.`);
+    process.exit(1);
+  }
+
+  mkdirSync(targetDir, { recursive: true });
+  mkdirSync(join(targetDir, "examples"), { recursive: true });
+
+  const templateDir = join(__dirname, "templates", lang);
+  const sharedDir = join(__dirname, "templates", "shared");
+
+  const protocolFile = lang === "en" ? "PROTOCOL.md" : `PROTOCOL.${lang}.md`;
+  const skillFile = lang === "en" ? "SKILL.md" : `SKILL.${lang}.md`;
+
+  writeFileSync(
+    join(targetDir, "PROTOCOL.md"),
+    readFileSync(join(templateDir, protocolFile))
+  );
+  writeFileSync(
+    join(targetDir, "SKILL.md"),
+    readFileSync(join(templateDir, skillFile))
+  );
+  writeFileSync(
+    join(targetDir, "TRANSPORT.md"),
+    readFileSync(join(sharedDir, "TRANSPORT.md"))
+  );
+  writeFileSync(
+    join(targetDir, "envelope.schema.json"),
+    readFileSync(join(sharedDir, "envelope.schema.json"))
+  );
+
+  cpSync(join(sharedDir, "examples"), join(targetDir, "examples"), { recursive: true });
+
+  console.log(`Chorus Skill package initialized in ./chorus/ (${lang})`);
+  console.log(`\nFiles created:`);
+  console.log(`  chorus/PROTOCOL.md      — Protocol specification`);
+  console.log(`  chorus/SKILL.md         — Agent learning document`);
+  console.log(`  chorus/TRANSPORT.md     — Default transport profile (optional)`);
+  console.log(`  chorus/envelope.schema.json`);
+  console.log(`  chorus/examples/`);
+  console.log(`\nGive your agent chorus/SKILL.md to teach it the Chorus protocol.`);
+} else {
+  console.log(`@chorus-protocol/skill v${pkg.version}`);
+  console.log(`\nUsage:`);
+  console.log(`  chorus-skill init [--lang en|zh-CN]    Initialize Chorus Skill package`);
+  console.log(`\nExamples:`);
+  console.log(`  npx @chorus-protocol/skill init`);
+  console.log(`  npx @chorus-protocol/skill init --lang zh-CN`);
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@chorus-protocol/skill",
+  "version": "0.4.0",
+  "description": "Chorus Protocol — Link agents across platforms. Install the Chorus Skill package for your agent.",
+  "bin": {
+    "chorus-skill": "./cli.mjs"
+  },
+  "type": "module",
+  "license": "Apache-2.0",
+  "files": [
+    "cli.mjs",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/owensun6/chorus.git",
+    "directory": "packages/chorus-skill"
+  },
+  "homepage": "https://github.com/owensun6/chorus/tree/main/packages/chorus-skill",
+  "bugs": {
+    "url": "https://github.com/owensun6/chorus/issues"
+  },
+  "keywords": [
+    "chorus",
+    "protocol",
+    "agent",
+    "a2a",
+    "cross-cultural",
+    "communication"
+  ]
+}

package/templates/en/PROTOCOL.md

@@ -0,0 +1,76 @@
+# Chorus Protocol
+
+Version 0.4 | Link agents across platforms.
+
+The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119.
+
+## 1. What is Chorus
+
+Chorus is an agent-to-agent communication standard that links agents across platforms, languages, and cultures.
+
+## 2. The Envelope
+
+A JSON object:
+
+- chorus_version (string, MUST): "0.4"
+- sender_id (string, MUST): Sender address, format `name@host`
+- original_text (string, MUST): The original message
+- sender_culture (string, MUST): BCP 47 tag
+- cultural_context (string 10-500, MAY): Optional hint — why the sender said it this way, in sender's language. Most receivers can adapt without it
+- conversation_id (string max 64, MAY): Multi-turn identifier
+- turn_number (integer ≥ 1, MAY): Turn counter
+
+`sender_id` format: `name@host`. `host` is the Chorus server domain or peer address. Uniqueness is guaranteed by the host's namespace.
+
+Additional fields permitted. Formal schema: `envelope.schema.json`
+
+## 3. Rules
+
+### Sending
+
+1. MAY include `cultural_context` as a hint to the receiver when sender and receiver cultures differ
+2. MUST NOT include personality or style in `cultural_context`
+
+### Receiving
+
+1. MUST validate the envelope before processing. If invalid, MUST respond with an error
+2. MUST deliver the message in a form the receiver can understand
+3. MAY deliver without adaptation when culture and language are the same
+
+### Response
+
+A JSON object returned to the sender:
+
+- status (string, MUST): "ok" or "error"
+- error_code (string, when error): See below
+- detail (string, MAY): Human-readable description
+
+Error codes:
+
+- `INVALID_ENVELOPE` — Required fields missing or wrong type
+- `UNSUPPORTED_VERSION` — `chorus_version` not recognized
+- `ADAPTATION_FAILED` — Receiver could not process the message
+
+Transport-level errors (delivery failure, timeout, unknown sender) are defined by L3.
+
+### Constraints
+
+- MUST NOT include personality or style in the envelope
+- When present, `cultural_context` MUST be in the sender's language
+
+## 4. Not In Scope
+
+- Transport: how envelopes travel between agents
+- Discovery: how agents initially find each other's addresses
+- Authentication: how agents verify identity
+- Personality: how an agent speaks
+- Storage: how history is persisted
+
+## 5. Versioning
+
+0.4 is not backwards compatible with 0.2/0.3. Breaking changes from 0.2/0.3:
+
+- `original_semantic` renamed to `original_text`
+- `cultural_context` changed from conditional to optional (MAY)
+
+Legacy envelopes using `original_semantic` or `chorus_version` values below `"0.4"` are not accepted. Senders MUST upgrade to 0.4 envelope format. There is no migration bridge — this is a pre-1.0 protocol and backwards compatibility is not guaranteed until 1.0.

package/templates/en/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: chorus
+description: |
+  Agent-to-agent communication protocol. Use when sending messages to
+  or receiving messages from agents on other platforms. Handles
+  cross-platform delivery, language translation, and cultural adaptation.
+version: "0.4"
+---
+
+# Chorus
+
+You now know the Chorus protocol. You can communicate with any agent on any platform.
+
+## What is Chorus
+
+Chorus is how agents talk to each other. Your human talks to you. The other human talks to their agent. Chorus links you and that agent — regardless of platform, language, or culture.
+
+Same culture, same language: you are a cross-platform bridge. Just deliver the message.
+Different language or culture: you also adapt the message so the receiving human understands it naturally.
+
+## Your Role
+
+You are a Chorus protocol participant. Your job is to package and understand Chorus envelopes. How to connect with other agents is covered in "How to Connect" below.
+
+You may represent your human, or you may act autonomously. Either way, when you communicate with another agent, you use Chorus envelopes.
+
+## Sending
+
+When you have a message to send to another agent — whether your human asked you to send it, or you are acting on your own:
+
+1. **Package the envelope**:
+   - `chorus_version`: `"0.4"`
+   - `sender_id`: your address (`name@host`)
+   - `original_text`: the message. If your human said it, use their exact words. If you are acting autonomously, this is your own message.
+   - `sender_culture`: your human's culture (BCP 47 tag, e.g. `en`, `zh-CN`, `ja`). When acting autonomously, use the culture you represent.
+
+2. **Optionally add cultural context**: You may include `cultural_context` — a hint in your language about why the message is phrased this way. This is optional; most receivers can adapt without it.
+
+3. **For multi-turn conversations**: Include `conversation_id` (any string up to 64 characters — generate one on the first turn, reuse it for all subsequent turns) and `turn_number` (starting at 1, incrementing each turn). These help the receiver maintain context across messages.
+
+4. **Send the envelope**: Specify the receiver's address (`receiver_id`, same `name@host` format as your `sender_id`) and deliver the envelope through your connection. The `receiver_id` is part of the transport request, not the envelope itself — the envelope only carries who sent it, not who it's for.
+
+## Receiving
+
+When you receive a Chorus envelope:
+
+1. **Validate it**. Check that `chorus_version`, `sender_id`, `original_text`, and `sender_culture` are present. If anything is missing, respond with `INVALID_ENVELOPE`.
+
+2. **Deliver the message**:
+   - Same language and culture as your human: deliver `original_text` directly.
+   - Different language or culture: deliver the message in a form your human can understand. You are an intelligent agent — you know how to bridge languages and cultures. If `cultural_context` is present, use it to understand why the sender said it that way.
+
+3. **Respond to the sender**: Always send back a response so the sender knows their message was received.
+   - Success: `{"status": "ok"}`
+   - Failure: `{"status": "error", "error_code": "INVALID_ENVELOPE", "detail": "missing sender_culture"}`
+
+## How to Connect
+
+To communicate with another agent, you need a connection. Chorus does not mandate how — use whatever works. Here are two common options, both described in detail in `TRANSPORT.md`.
+
+### Chorus Server
+
+A shared relay that maintains a directory of agents.
+
+1. **Register**: announce yourself to the server — your `agent_id` (`name@host`), your receive endpoint (you must start an HTTP server on a free port to accept inbound messages — check the port is not already in use before binding), and your `agent_card` with `card_version: "0.3"`, `user_culture`, and `supported_languages`. See TRANSPORT.md Quick Start for the exact request format.
+2. **Discover**: query the server to find other registered agents and learn their cultures.
+3. **Send**: post the envelope with the `receiver_id` to the server. The server relays it to the receiver.
+
+This is like email: you send to the server, the server delivers to the recipient. Anyone can run a Chorus server.
+
+### P2P Direct
+
+If you and the other agent can reach each other directly (e.g. you both know each other's endpoint or peer address), exchange envelopes without a server. Your humans share your addresses or endpoints and you connect.
+
+### Knowing the receiver's culture
+
+When sending cross-culturally, knowing the receiver's culture helps you decide how to phrase your message. You can learn it through:
+
+- **Discovery**: the server's agent directory includes each agent's `user_culture`
+- **Prior conversation**: if you've received a message from them, their `sender_culture` tells you
+- **Out of band**: your human tells you
+
+## DO NOT
+
+- Do not put your personality or speaking style in the envelope. How you talk is your business, not the protocol's.
+- Do not forward a foreign-language message to your human without adaptation. Even a simple agent MUST deliver messages in a form the human can understand.
+- Do not invent or guess `cultural_context`. If you do not understand the cultural nuance, omit it — the receiver can adapt without it.
+
+## Reference
+
+Full protocol specification: `PROTOCOL.md`
+Default transport profile: `TRANSPORT.md`
+Formal JSON Schema: `envelope.schema.json`
+Examples: `examples/`

package/templates/shared/TRANSPORT.md

@@ -0,0 +1,364 @@
+# Chorus Transport Profile
+
+Version 0.4 | Default L3 binding for Chorus envelope delivery.
+
+The key words "MUST", "MUST NOT", "SHOULD", and "MAY" in this document are to be interpreted as described in RFC 2119.
+
+## 1. Scope
+
+This document defines one way to deliver Chorus envelopes between agents. It is an optional L3 profile — not part of the core protocol.
+
+Chorus Protocol (L1) defines the envelope format. Chorus Skill (L2) teaches agents how to use it. This transport profile provides a default HTTP binding so that agents can interoperate without building custom transport.
+
+Agents MAY use any transport that delivers valid Chorus envelopes. Compliance with this profile is not required for Chorus compliance.
+
+## Quick Start
+
+A complete register → send → receive flow using the HTTP binding:
+
+**Step 1 — Register your agent**
+
+```
+POST /agents
+
+{
+  "agent_id": "my-agent@chorus.example",
+  "endpoint": "https://my-agent.example/receive",
+  "agent_card": {
+    "card_version": "0.3",
+    "user_culture": "en",
+    "supported_languages": ["en"]
+  }
+}
+```
+
+Response: `201` with `{ "success": true, "data": { "agent_id": "...", "registered_at": "..." } }`
+
+**Step 2 — Send a message**
+
+```
+POST /messages
+
+{
+  "receiver_id": "other-agent@chorus.example",
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "my-agent@chorus.example",
+    "original_text": "Hello, let's collaborate on this project.",
+    "sender_culture": "en"
+  }
+}
+```
+
+Response: `200` with `{ "success": true, "data": { "delivery": "delivered", "receiver_response": { "status": "ok" } } }`
+
+**Step 3 — Receive a message**
+
+Your endpoint receives:
+
+```
+POST https://my-agent.example/receive
+
+{
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "other-agent@chorus.example",
+    "original_text": "こんにちは、プロジェクトについて相談しましょう。",
+    "sender_culture": "ja"
+  }
+}
+```
+
+Your endpoint responds: `{"status": "ok"}`
+
+That's it. You are now sending and receiving Chorus envelopes.
+
+**Important: envelope nesting.** The Chorus envelope is always wrapped inside a JSON object — never sent as the top-level body. When sending: `{ "receiver_id": "...", "envelope": { ...chorus fields... } }`. When receiving: `{ "envelope": { ...chorus fields... } }`. The envelope fields (`chorus_version`, `sender_id`, `original_text`, `sender_culture`) go inside the `"envelope"` key, not at the root of the request body.
+
+## 2. Addressing
+
+An agent address follows the format `name@host`.
+
+- `name`: identifier, unique within the host's namespace
+- `host`: the Chorus server domain or peer address
+
+The same format applies to both `sender_id` (defined in PROTOCOL.md) and `receiver_id` (used in transport requests).
+
+Within a single server, implementations SHOULD accept the short form `name` as a local alias for `name@{server-host}`.
+
+## 3. Connection Modes
+
+### Server Relay
+
+Agents register with a shared Chorus server. The server maintains a directory and relays envelopes between them.
+
+```
+Agent A ──envelope──▶ Chorus Server ──envelope──▶ Agent B
+```
+
+### P2P Direct
+
+Two agents exchange envelopes directly when they know each other's endpoints.
+
+```
+Agent A ──envelope──▶ Agent B
+```
+
+No registration or server required. The agents' humans share addresses out of band.
+
+## 4. Operations
+
+Four abstract operations, independent of transport binding. Section 6 maps these to HTTP.
+
+### 4.1 Register
+
+An agent announces itself to a server.
+
+Request:
+- `agent_id` (string, MUST): the agent's `name@host` address
+- `endpoint` (string, MUST): URL where the agent receives envelopes
+- `agent_card` (object, SHOULD): agent capabilities — `card_version` (agent card schema version, currently `"0.3"`), `user_culture` (BCP 47), `supported_languages` (BCP 47 array)
+
+Note: the agent card field is `card_version` (not `chorus_version`). The envelope has its own `chorus_version` field (`"0.4"`). They are different fields versioning different things.
+
+**Migration from card v0.2**: In v0.2, the agent card field was named `chorus_version` (same name as the envelope field). This caused confusion, so v0.3 renames it to `card_version`. Agents using the old `chorus_version` field in their agent card MUST update to `card_version: "0.3"`. Servers MAY return a generic validation error if the old field name is used.
+
+Result: registration record with `registered_at` timestamp.
+
+Re-registering an existing `agent_id` updates the record.
+
+### 4.2 Unregister
+
+An agent removes itself from a server.
+
+Request:
+- `agent_id` (string, MUST)
+
+Result: confirmation. No-op if already absent.
+
+### 4.3 Discover
+
+Query registered agents.
+
+Request: none required. MAY support filters.
+
+Result: list of registration records.
+
+### 4.4 Send
+
+Deliver a Chorus envelope to another agent.
+
+Request:
+- `receiver_id` (string, MUST): receiver's `name@host` address
+- `envelope` (object, MUST): a valid Chorus envelope per PROTOCOL.md
+
+The sender's identity is `envelope.sender_id`. There is no separate sender field — a single source of truth avoids mismatch.
+
+Result: delivery outcome (see Section 5).
+
+## 5. Delivery States
+
+A Send request produces one of three outcomes:
+
+| State | Meaning |
+|-------|---------|
+| `delivered` | Envelope reached the receiver. The response includes the receiver's protocol-level reply (per PROTOCOL.md Section 3) |
+| `failed` | Delivery failed. The response includes an error code and detail |
+| `rejected` | Sender validation failed (not registered, invalid envelope). No delivery attempted |
+
+### Retry
+
+- Senders MAY retry on transient failures (`ERR_AGENT_UNREACHABLE`, `ERR_TIMEOUT`)
+- Senders MUST NOT retry on permanent failures (`ERR_AGENT_NOT_FOUND`, `ERR_VALIDATION`)
+- Senders SHOULD use exponential backoff when retrying
+- Receivers SHOULD treat duplicate envelopes with the same `conversation_id` + `turn_number` as idempotent
+
+## 6. HTTP Binding
+
+The default transport binding. A conforming server implements these endpoints.
+
+### 6.1 Endpoints
+
+| Operation | Method | Path | Success |
+|-----------|--------|------|---------|
+| Register | POST | `/agents` | 201 (new) / 200 (update) |
+| Unregister | DELETE | `/agents/:id` | 200 |
+| Discover (list) | GET | `/agents` | 200 |
+| Discover (single) | GET | `/agents/:id` | 200 |
+| Send | POST | `/messages` | 200 |
+| Health | GET | `/health` | 200 |
+
+### 6.2 Response Envelope
+
+All HTTP responses use a common format:
+
+```json
+{
+  "success": true,
+  "data": { },
+  "metadata": { "timestamp": "2026-03-20T10:00:00.000Z" }
+}
+```
+
+```json
+{
+  "success": false,
+  "error": { "code": "ERR_VALIDATION", "message": "sender_id is required" },
+  "metadata": { "timestamp": "2026-03-20T10:00:00.000Z" }
+}
+```
+
+### 6.3 Register
+
+```
+POST /agents
+
+{
+  "agent_id": "alice@chorus.example",
+  "endpoint": "https://alice.example/receive",
+  "agent_card": {
+    "card_version": "0.3",
+    "user_culture": "zh-CN",
+    "supported_languages": ["zh-CN", "en"]
+  }
+}
+```
+
+### 6.4 Send
+
+```
+POST /messages
+
+{
+  "receiver_id": "bob@chorus.example",
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "alice@chorus.example",
+    "original_text": "下午一起喝杯咖啡？",
+    "sender_culture": "zh-CN",
+    "cultural_context": "中国同事之间用「喝咖啡」作为非正式交流的邀请，表达善意和亲近，不一定真的要喝咖啡"
+  }
+}
+```
+
+Delivered:
+
+```json
+{
+  "success": true,
+  "data": {
+    "delivery": "delivered",
+    "receiver_response": { "status": "ok" }
+  },
+  "metadata": { "timestamp": "..." }
+}
+```
+
+Failed:
+
+```json
+{
+  "success": true,
+  "data": {
+    "delivery": "failed",
+    "error_code": "ERR_AGENT_UNREACHABLE",
+    "detail": "Receiver did not respond within timeout"
+  },
+  "metadata": { "timestamp": "..." }
+}
+```
+
+Note: a delivery failure is not an HTTP error. The HTTP request succeeded; the delivery did not. Hence `"success": true` with `"delivery": "failed"`.
+
+### 6.5 Agent Receive Endpoint
+
+An agent that accepts envelopes MUST expose an HTTP endpoint. The URL is declared during Register.
+
+Request (from server or direct peer):
+
+```
+POST {agent_endpoint}
+
+{
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "alice@chorus.example",
+    "original_text": "下午一起喝杯咖啡？",
+    "sender_culture": "zh-CN"
+  }
+}
+```
+
+Response — per PROTOCOL.md Section 3:
+
+```json
+{ "status": "ok" }
+```
+
+```json
+{ "status": "error", "error_code": "INVALID_ENVELOPE", "detail": "missing sender_culture" }
+```
+
+## 7. Transport Error Codes
+
+These are distinct from protocol-level error codes in PROTOCOL.md.
+
+| Code | HTTP Status | Meaning | Retryable |
+|------|------------|---------|-----------|
+| `ERR_VALIDATION` | 400 | Request body failed validation | No |
+| `ERR_AGENT_NOT_FOUND` | 404 | Receiver not registered | No |
+| `ERR_AGENT_UNREACHABLE` | 502 | Could not reach receiver endpoint | Yes |
+| `ERR_TIMEOUT` | 504 | Receiver did not respond in time | Yes |
+| `ERR_UNAUTHORIZED` | 401 | Authentication required or invalid | No |
+| `ERR_SENDER_NOT_REGISTERED` | 400 | Sender not registered with this server | No |
+
+## 8. Discovery
+
+A Chorus server SHOULD serve a discovery document at:
+
+```
+GET /.well-known/chorus.json
+```
+
+```json
+{
+  "chorus_version": "0.4",
+  "server_name": "Example Chorus Hub",
+  "endpoints": {
+    "register": "/agents",
+    "discover": "/agents",
+    "send": "/messages",
+    "health": "/health"
+  }
+}
+```
+
+Clients that support discovery SHOULD fetch this document to resolve endpoint paths rather than hardcoding them.
+
+## 9. Extensions
+
+### A2A Message Wrapping (MAY)
+
+Implementations MAY encode the Chorus envelope as a DataPart inside an A2A message, using mediaType `application/vnd.chorus.envelope+json`. This enables interoperability with A2A-compatible platforms.
+
+A2A wrapping is an alternate encoding of the `envelope` field, not a change to the Send request structure. The request still contains `receiver_id` + `envelope`. The server or receiver detects the encoding and extracts the Chorus envelope for protocol processing.
+
+### SSE Streaming (MAY)
+
+Implementations MAY support Server-Sent Events to stream the receiver's processing output back to the sender. This is a content stream extension, not a streaming version of the delivery states in Section 5.
+
+When supported:
+
+- The Send request includes `"stream": true`
+- The server relays the receiver's SSE stream to the sender
+- Events: `chunk` (incremental content from receiver), `done` (processing complete, includes full result), `error` (receiver processing failed)
+
+The delivery state for a streamed request is determined by the final event: `done` maps to `delivered`, `error` maps to `failed`.
+
+## 10. Not In Scope
+
+- Authentication schemes — use whatever your deployment requires
+- Rate limiting — server-specific policy
+- Federation between Chorus servers — future work
+- Envelope encryption — future work
+- Message persistence or history — implementation concern

package/templates/shared/envelope.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://chorus-protocol.org/schemas/envelope/v0.4",
+  "title": "Chorus Envelope",
+  "description": "Chorus Protocol v0.4 — Agent-to-agent communication envelope",
+  "type": "object",
+  "required": ["chorus_version", "sender_id", "original_text", "sender_culture"],
+  "additionalProperties": true,
+  "properties": {
+    "chorus_version": {
+      "type": "string",
+      "enum": ["0.4"],
+      "description": "Protocol version"
+    },
+    "sender_id": {
+      "type": "string",
+      "pattern": "^[a-zA-Z0-9._-]+@[a-zA-Z0-9._-]+$",
+      "description": "Sender address (name@host)"
+    },
+    "original_text": {
+      "type": "string",
+      "minLength": 1,
+      "description": "The original message"
+    },
+    "sender_culture": {
+      "type": "string",
+      "pattern": "^[a-z]{2,3}(-[A-Z][a-z]{3})?(-[A-Z]{2}|-[0-9]{3})?$",
+      "description": "Sender culture (BCP 47 tag)"
+    },
+    "cultural_context": {
+      "type": "string",
+      "minLength": 10,
+      "maxLength": 500,
+      "description": "Optional hint — cultural background in sender's language. Most receivers can adapt without it"
+    },
+    "conversation_id": {
+      "type": "string",
+      "maxLength": 64,
+      "description": "Multi-turn conversation identifier"
+    },
+    "turn_number": {
+      "type": "integer",
+      "minimum": 1,
+      "description": "Turn counter"
+    }
+  }
+}

package/templates/shared/examples/en-to-en.json

@@ -0,0 +1,17 @@
+{
+  "_description": "Same-culture communication — Chorus as cross-platform interop",
+
+  "user_input": "Hey, can we push the deployment to tomorrow? The CI pipeline is still red.",
+
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "alice@chorus.example.com",
+    "original_text": "Hey, can we push the deployment to tomorrow? The CI pipeline is still red.",
+    "sender_culture": "en"
+  },
+
+  "adapted_output": {
+    "receiver_culture": "en",
+    "text": "Hey, can we push the deployment to tomorrow? The CI pipeline is still red."
+  }
+}

package/templates/shared/examples/ja-to-zh-CN.json

@@ -0,0 +1,18 @@
+{
+  "_description": "日本人委婉拒绝提议 → 中国文化适配",
+
+  "user_input": "ちょっと難しいかもしれませんね。もう少し検討させていただけますか。",
+
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "tanaka@chorus.example.jp",
+    "original_text": "ちょっと難しいかもしれませんね。もう少し検討させていただけますか。",
+    "sender_culture": "ja",
+    "cultural_context": "日本のビジネス文化において、「ちょっと難しいかもしれません」は直接的な拒否を避けるための婉曲表現です。「もう少し検討させていただけますか」は表面上は検討の余地を残す表現ですが、実質的にはお断りの意味を含むことが多いです。日本では相手の面子を傷つけないよう、このような間接的な表現が礼儀とされています。"
+  },
+
+  "adapted_output": {
+    "receiver_culture": "zh-CN",
+    "text": "对方其实是在委婉地拒绝这个提议。在日本商务文化里，'可能有点困难'加上'能否再考虑一下'，基本上就是在说'这个方案恐怕不行'。他们习惯用这种间接的方式表达，是为了给双方都留面子。建议你可以换个方案再试试。"
+  }
+}

package/templates/shared/examples/zh-CN-to-ja.json

@@ -0,0 +1,18 @@
+{
+  "_description": "中国人向日本同事表达感谢 → 日本文化适配",
+
+  "user_input": "辛苦了，这个项目多亏了你，真的非常感谢！",
+
+  "envelope": {
+    "chorus_version": "0.4",
+    "sender_id": "wang@chorus.example.cn",
+    "original_text": "辛苦了，这个项目多亏了你，真的非常感谢！",
+    "sender_culture": "zh-CN",
+    "cultural_context": "在中国职场文化中，'辛苦了'是对同事辛勤付出的认可和慰劳，表达的是'我看到了你的努力'。'多亏了你'是直接归功于对方的贡献，语气真诚而非客套。这种直接表达感谢在中国同事间是常见且受欢迎的。"
+  },
+
+  "adapted_output": {
+    "receiver_culture": "ja",
+    "text": "プロジェクトでのご尽力に心から感謝しています。中国の同僚から、あなたの貢献があったからこそ成功したと、とても率直に感謝が伝えられています。中国では、こうした直接的な感謝表現は、本心からの敬意を込めたものです。"
+  }
+}

package/templates/zh-CN/PROTOCOL.zh-CN.md

@@ -0,0 +1,76 @@
+# Chorus 协议
+
+版本 0.4 | 连接跨平台的智能体。
+
+本文档中的关键词 "MUST"（必须）、"MUST NOT"（禁止）、"SHOULD"（应当）和 "MAY"（可以）的含义遵循 RFC 2119 的定义。
+
+## 1. Chorus 是什么
+
+Chorus 是一种智能体间通信标准，用于连接跨平台、跨语言、跨文化的智能体。
+
+## 2. 信封
+
+一个 JSON 对象：
+
+- chorus_version（字符串，MUST）："0.4"
+- sender_id（字符串，MUST）：发送方地址，格式为 `name@host`
+- original_text（字符串，MUST）：原始消息
+- sender_culture（字符串，MUST）：BCP 47 标签
+- cultural_context（字符串 10-500，MAY）：可选提示——发送方为何这样表达，使用发送方的语言书写。多数接收方可在没有它的情况下完成适配
+- conversation_id（字符串，最大 64，MAY）：多轮对话标识符
+- turn_number（整数 ≥ 1，MAY）：轮次计数器
+
+`sender_id` 格式：`name@host`。`host` 是 Chorus 服务器域名或对端地址。唯一性由主机的命名空间保证。
+
+允许附加字段。正式 schema 见：`envelope.schema.json`
+
+## 3. 规则
+
+### 发送
+
+1. 当发送方和接收方文化不同时，MAY 包含 `cultural_context` 作为给接收方的提示
+2. MUST NOT 在 `cultural_context` 中包含人格或风格信息
+
+### 接收
+
+1. MUST 在处理前验证信封。如果无效，MUST 返回错误
+2. MUST 以接收方能够理解的形式投递消息
+3. 当文化和语言相同时，MAY 不做适配直接投递
+
+### 响应
+
+返回给发送方的 JSON 对象：
+
+- status（字符串，MUST）："ok" 或 "error"
+- error_code（字符串，出错时）：见下文
+- detail（字符串，MAY）：人类可读的描述
+
+错误码：
+
+- `INVALID_ENVELOPE` — 必填字段缺失或类型错误
+- `UNSUPPORTED_VERSION` — `chorus_version` 无法识别
+- `ADAPTATION_FAILED` — 接收方无法处理该消息
+
+传输层错误（投递失败、超时、未知发送方）由 L3 定义。
+
+### 约束
+
+- MUST NOT 在信封中包含人格或风格信息
+- 当包含 `cultural_context` 时，MUST 使用发送方的语言书写
+
+## 4. 不在范围内
+
+- 传输：信封如何在智能体之间传递
+- 发现：智能体如何获取彼此的地址
+- 认证：智能体如何验证身份
+- 人格：智能体如何说话
+- 存储：历史记录如何持久化
+
+## 5. 版本控制
+
+0.4 与 0.2/0.3 不向后兼容。从 0.2/0.3 开始的破坏性变更：
+
+- `original_semantic` 重命名为 `original_text`
+- `cultural_context` 从条件必填改为可选（MAY）
+
+使用 `original_semantic` 或低于 `"0.4"` 的 `chorus_version` 值的旧版信封不被接受。发送方 MUST 升级到 0.4 信封格式。不提供迁移桥接——这是 1.0 之前的协议，在 1.0 之前不保证向后兼容。

package/templates/zh-CN/SKILL.zh-CN.md

@@ -0,0 +1,93 @@
+---
+name: chorus
+description: |
+  Agent 间通信协议。当你需要向其他平台的 Agent 发送消息或接收来自
+  其他平台 Agent 的消息时使用。处理跨平台投递、语言翻译和文化适配。
+version: "0.4"
+---
+
+# Chorus
+
+你现在掌握了 Chorus 协议。你可以和任何平台上的任何 Agent 通信。
+
+## Chorus 是什么
+
+Chorus 是 Agent 之间对话的方式。你的人类跟你说话，对方的人类跟他们的 Agent 说话。Chorus 把你和那个 Agent 连起来——不管平台、语言还是文化差异。
+
+同文化、同语言：你就是一座跨平台的桥。把消息递过去就行。
+不同语言或文化：你还需要对消息做适配，让接收方的人类能自然地理解它。
+
+## 你的角色
+
+你是 Chorus 协议的参与者。你的工作是打包和理解 Chorus 信封。如何与其他 Agent 建立连接，见下方「怎么连接」。
+
+你可以代表你的人类，也可以自主行动。不管哪种情况，当你和另一个 Agent 通信时，你使用 Chorus 信封。
+
+## 发送
+
+当你有消息要发给另一个 Agent——不管是你的人类让你发的，还是你自主行动发的：
+
+1. **打包信封**：
+   - `chorus_version`：`"0.4"`
+   - `sender_id`：你的地址（`name@host`）
+   - `original_text`：消息内容。如果是人类说的，用原话一字不改。如果是你自主行动，这就是你自己的消息。
+   - `sender_culture`：你的人类所属的文化（BCP 47 标签，比如 `en`、`zh-CN`、`ja`）。自主行动时，使用你所代表的文化。
+
+2. **可选添加文化语境**：你可以包含 `cultural_context`——用你的语言解释消息为何这样措辞。这是可选的；多数接收方可以在没有它的情况下完成适配。
+
+3. **多轮对话**：加上 `conversation_id`（任意字符串，最多 64 个字符——首轮时生成一个，后续轮次复用）和 `turn_number`（从 1 开始，每轮递增）。这帮助接收方在多条消息间保持上下文。
+
+4. **发送信封**：指定接收方的地址（`receiver_id`，与你的 `sender_id` 格式相同，都是 `name@host`），通过你的连接投递信封。`receiver_id` 是传输请求的一部分，不在信封内——信封只携带发送者信息，不携带收件人信息。
+
+## 接收
+
+当你收到一个 Chorus 信封时：
+
+1. **验证信封**。检查 `chorus_version`、`sender_id`、`original_text` 和 `sender_culture` 是否存在。如有缺失，回复 `INVALID_ENVELOPE`。
+
+2. **投递消息**：
+   - 与你的人类语言和文化相同：直接投递 `original_text`。
+   - 语言或文化不同：把消息转化成你的人类能理解的形式。你是一个有智慧的 Agent——你知道怎么跨越语言和文化。如果信封里有 `cultural_context`，用它来理解发送者为什么会那样说。
+
+3. **回复发送方**：始终回复一个响应，让发送方知道消息已收到。
+   - 成功：`{"status": "ok"}`
+   - 失败：`{"status": "error", "error_code": "INVALID_ENVELOPE", "detail": "缺少 sender_culture"}`
+
+## 怎么连接
+
+要和另一个 Agent 通信，你需要一个连接。Chorus 不强制要求特定方式——能用就行。以下是两种常见方式，详见 `TRANSPORT.md`。
+
+### Chorus 服务器
+
+一个维护 Agent 目录的共享中继。
+
+1. **注册**：向服务器宣告你自己——你的 `agent_id`（`name@host`）、接收端点（你需要在一个空闲端口上启动 HTTP 服务来接收消息——绑定前先确认端口未被占用）、以及 `agent_card`，包含 `card_version: "0.3"`、`user_culture`、`supported_languages`。具体请求格式见 TRANSPORT.md Quick Start。
+2. **发现**：查询服务器，找到其他已注册的 Agent，了解它们的文化。
+3. **发送**：把信封和 `receiver_id` 一起发给服务器。服务器转发给接收方。
+
+就像电子邮件：你发给服务器，服务器投递给收件人。任何人都可以运行 Chorus 服务器。
+
+### P2P 直连
+
+如果你和对方 Agent 能直接互相访问（比如你们都知道对方的端点或对端地址），不需要服务器，直接交换信封就行。你们的人类互相分享地址或端点，然后你们就连上了。
+
+### 了解接收方的文化
+
+在跨文化发送时，了解接收方的文化有助于你决定如何措辞消息。你可以通过以下方式了解：
+
+- **发现机制**：服务器的 Agent 目录包含每个 Agent 的 `user_culture`
+- **先前对话**：如果你收到过对方的消息，对方的 `sender_culture` 就告诉了你
+- **带外方式**：你的人类告诉你
+
+## 不要做的事
+
+- 不要把你的个性或说话风格塞进信封里。你怎么说话是你自己的事，不是协议的事。
+- 不要把外语消息原封不动地转给你的人类。哪怕是最简单的 Agent，也 MUST 把消息转成人类能理解的形式。
+- 不要编造或猜测 `cultural_context`。如果你不理解其中的文化差异，就省掉它——接收方可以在没有它的情况下做适配。
+
+## 参考
+
+完整协议规范：`PROTOCOL.md`
+默认传输方案：`TRANSPORT.md`
+正式 JSON Schema：`envelope.schema.json`
+示例：`examples/`