From f7cf1b3d68caa22f9b2cb123d9a80ae968688b4a Mon Sep 17 00:00:00 2001 From: Jeremy Date: Mon, 6 Apr 2026 17:57:54 +0200 Subject: [PATCH] docs: align documentation with OpenSIN-overview SSOT mandates (Hub & Spoke, Banned Tech, Naming) --- docs/architecture/a2a.md | 21 +++++++++++++++++++++ docs/best-practices/security.md | 10 ++++++++++ docs/guide/naming-conventions.md | 16 ++++++++++++++++ 3 files changed, 47 insertions(+) create mode 100644 docs/guide/naming-conventions.md diff --git a/docs/architecture/a2a.md b/docs/architecture/a2a.md index b418f7bc35..faa0dfbbd9 100644 --- a/docs/architecture/a2a.md +++ b/docs/architecture/a2a.md @@ -175,3 +175,24 @@ gh repo create OpenSIN-AI/A2A-SIN-MyAgent \ --template OpenSIN-AI/Template-A2A-SIN-Agent \ --public ``` + +## 🔄 The New Fleet Topology (Hub & Spoke) + +As defined in the `OpenSIN-overview` SSOT, the OpenSIN A2A fleet uses a strict **Hub & Spoke** model to prevent N^2 communication chaos. + +```mermaid +graph TD; + User[Operator / Telegram] -->|Task| TeamManager[Team-SIN-* Orchestrator]; + Hermes[SIN-Hermes Global Router] -->|Payload| TeamManager; + + TeamManager -->|Consults| Lexicon[(Team Lexicon / RAG)]; + TeamManager -->|Delegate| Workers[A2A-SIN-* Worker Agents]; + Workers -->|Result| TeamManager; + + TeamManager -->|Aggregate & Respond| Hermes; + TeamManager -->|Aggregate & Respond| User; +``` + +**Key Rules:** +1. **Workers are Silent:** `A2A-SIN-*` worker agents NEVER communicate with workers from other teams. They only accept tasks from their designated `Team-SIN-*` manager. +2. **Team Managers Orchestrate:** Only `Team-SIN-*` agents possess the `TELEGRAM_BOT_TOKEN` to communicate with humans. diff --git a/docs/best-practices/security.md b/docs/best-practices/security.md index b452de4fe6..0aba369bd9 100644 --- a/docs/best-practices/security.md +++ b/docs/best-practices/security.md @@ -198,3 +198,13 @@ Before deploying an agent to production: - [ ] Log redaction enabled for sensitive patterns - [ ] Token rotation configured for all long-lived credentials - [ ] `npm audit` passing with no critical vulnerabilities + +## 🚫 Technology Sovereignty Mandate (Browser Automation) + +**STRICTLY ENFORCED:** +- **Playwright**, **Puppeteer**, **Selenium**, and **Camoufox** are **PERMANENTLY BANNED** across the entire OpenSIN-AI organization. +- They are easily detected by Cloudflare, trigger massive bot-detection red flags, and lack true native stealth. + +**THE OPENSIN STANDARD:** +All A2A Agents MUST use the **OpenSIN-Bridge Chrome Extension** via the MCP WebSocket Server. +Alternatively, if OS-level isolation is absolutely necessary, use `webauto-nodriver-mcp` (which wraps `nodriver`). diff --git a/docs/guide/naming-conventions.md b/docs/guide/naming-conventions.md new file mode 100644 index 0000000000..eabda0283c --- /dev/null +++ b/docs/guide/naming-conventions.md @@ -0,0 +1,16 @@ +# 🏷️ Naming Conventions & SSOT + +## The Ultimate SSOT +Before modifying any code or reading further, you must be aware of the **[OpenSIN-overview](https://github.com/OpenSIN-AI/OpenSIN-overview)** repository. It is the Single Source of Truth for the entire organization. + +## Strict Naming Schema +To prevent architectural chaos, every repository in the OpenSIN-AI organization **MUST** follow this strict naming schema: + +`[Type]-SIN-[Name]` + +### Valid Types: +- `Team-SIN-*` (Orchestrators, Hubs, Managers. E.g., `Team-SIN-Legal`) +- `A2A-SIN-*` (Worker Agents that execute tasks. E.g., `A2A-SIN-ClaimWriter`) +- `MCP-SIN-*` (Model Context Protocol Servers / Tools. E.g., `MCP-SIN-Browser`) +- `CLI-SIN-*` (Command Line Interfaces / Terminals. E.g., `CLI-SIN-Code`) +- `Template-SIN-*` (Blueprints for the forge scripts)