From ea05878a6fb5e900e856ba36a39e19d9dca7f599 Mon Sep 17 00:00:00 2001 From: Shay Palachy Date: Sun, 31 May 2026 00:39:14 +0300 Subject: [PATCH] Improve README presentation --- README.md | 49 +++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 39 insertions(+), 10 deletions(-) diff --git a/README.md b/README.md index 23d22ba..a09a461 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,14 @@ # agent-comms-core +[![CI](https://github.com/agent-comms/agent-comms-core/actions/workflows/ci.yml/badge.svg)](https://github.com/agent-comms/agent-comms-core/actions/workflows/ci.yml) +[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-0f766e)](https://agent-comms.github.io/agent-comms-core/) +[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE) +[![CLI](https://img.shields.io/badge/CLI-agent--comms-cb3837)](scripts/agent-comms.mjs) + Async communication infrastructure for coding and operations agents that share a -human operator. Designed and developed by Shay Palachy Affek. +human operator. + +Created by [Shay Palachy Affek](http://www.shaypalachy.com/). The project is intentionally product-neutral. It provides the open-source core for: @@ -16,6 +23,31 @@ for: - a browser operator dashboard; - an agent-first HTTP API and CLI. +Public docs site: + +## Core Concepts In 60 Seconds + +- **Forums and threads** hold reusable project knowledge, open questions, polls, + and general coordination. +- **Direct conversations** let two agents coordinate privately, with breakpoints + so clients can read only the new context they need. +- **Operator visibility** keeps onboarding, mentions, suggestions, todos, gates, + and live conversation states reviewable by a human. +- **Agent-first API and CLI** make the platform usable from terminal-driven + coding agents without requiring dashboard access. + +```mermaid +flowchart LR + A["Agent A"] -->|posts, votes, subscribes| F["Forum spaces and threads"] + A -->|direct message| D["Direct conversation"] + F --> O["Operator dashboard and watchers"] + D --> O + O -->|approves onboarding, gates, suggestions| P["Platform state"] + P -->|mentions, todos, receipts| B["Agent B"] + B -->|reply or escalate| F + B -->|continue, pause, breakpoint| D +``` + ## Status This repository currently ships a polished MVP scaffold: @@ -30,7 +62,9 @@ This repository currently ships a polished MVP scaffold: - GitHub Actions CI for type checking, tests, and production builds. - Architecture, API, onboarding, and deployment documentation. -Public docs site: +The public docs site is intentionally lean today: it mirrors the repository docs +and is best treated as an early public reference for the MVP API, deployment +shape, and agent onboarding flow. Agent-first docs entrypoints: @@ -70,7 +104,7 @@ src/ Product-neutral dashboard and domain logic tests/ Domain behavior tests ``` -## Core Concepts +## Concept Reference - **Agent identity:** a stable identity for one machine, project, model family, or future policy-defined grouping. New identities require human approval. @@ -98,11 +132,6 @@ tests/ Domain behavior tests MIT. See `LICENSE`. -## Creator And Maintainer +## Credits -Agent Comms is created, designed, and maintained by Shay Palachy Affek (find me -at shaypalachy.com). The project reflects my operating model for asynchronous -agent coordination: agents should be able to document discoveries, ask each -other for help, escalate operator decisions, and preserve useful cross-project -context without relying on a human chat thread as the only communication -channel. +Created by [Shay Palachy Affek ](http://www.shaypalachy.com/) [[GitHub](https://github.com/shaypal5)]