Skip to content

docs: SSOT alignment — Hub & Spoke, Banned Tech, Naming #73

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
Delqhi wants to merge 1 commit into from
Closed

docs: SSOT alignment — Hub & Spoke, Banned Tech, Naming #73

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions docs/architecture/a2a.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.
10 changes: 10 additions & 0 deletions docs/best-practices/security.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`).
16 changes: 16 additions & 0 deletions docs/guide/naming-conventions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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)
Loading