From dd954ffee37b41fee7d768a831435911d6e28f26 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Thu, 5 Feb 2026 12:33:43 -0600
Subject: [PATCH] docs(#235): Update README with orchestration layer
 information

- Add orchestrator and coordinator to deployment list
- Update project structure with agent orchestration apps
- Add Agent Orchestration Layer section with architecture overview
- Update implementation status to reflect M6 milestone completion
- Document test coverage (2168+ tests passing)

Fixes #235

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
---
 README.md | 57 ++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 44 insertions(+), 13 deletions(-)

diff --git a/README.md b/README.md
index 5fc044a..0890556 100644
--- a/README.md
+++ b/README.md
@@ -110,6 +110,8 @@ docker compose down
 - Valkey (Redis-compatible cache)
 - Mosaic API (NestJS)
 - Mosaic Web (Next.js)
+- Mosaic Orchestrator (Agent lifecycle management)
+- Mosaic Coordinator (Task assignment & monitoring)
 - Authentik OIDC (optional, use `--profile authentik`)
 - Ollama AI (optional, use `--profile ollama`)
 
@@ -124,13 +126,29 @@ mosaic-stack/
 │   │   ├── src/
 │   │   │   ├── auth/             # BetterAuth + Authentik OIDC
 │   │   │   ├── prisma/           # Database service
+│   │   │   ├── coordinator-integration/ # Coordinator API client
 │   │   │   └── app.module.ts     # Main application module
 │   │   ├── prisma/
 │   │   │   └── schema.prisma     # Database schema
 │   │   └── Dockerfile
-│   └── web/                      # Next.js 16 frontend (planned)
-│       ├── app/
-│       ├── components/
+│   ├── web/                      # Next.js 16 frontend
+│   │   ├── app/
+│   │   ├── components/
+│   │   │   └── widgets/          # HUD widgets (agent status, etc.)
+│   │   └── Dockerfile
+│   ├── orchestrator/             # Agent lifecycle & spawning (NestJS)
+│   │   ├── src/
+│   │   │   ├── spawner/          # Agent spawning service
+│   │   │   ├── queue/            # Valkey-backed task queue
+│   │   │   ├── monitor/          # Health monitoring
+│   │   │   ├── git/              # Git worktree management
+│   │   │   └── killswitch/       # Emergency agent termination
+│   │   └── Dockerfile
+│   └── coordinator/              # Task assignment & monitoring (FastAPI)
+│       ├── src/
+│       │   ├── webhook.py        # Gitea webhook receiver
+│       │   ├── parser.py         # Issue metadata parser
+│       │   └── security.py       # HMAC signature verification
 │       └── Dockerfile
 ├── packages/
 │   ├── shared/                   # Shared types & utilities
@@ -159,23 +177,36 @@ mosaic-stack/
 └── pnpm-workspace.yaml           # Workspace configuration
 ```
 
+## Agent Orchestration Layer (v0.0.6)
+
+Mosaic Stack includes a sophisticated agent orchestration system for autonomous task execution:
+
+- **Orchestrator Service** (NestJS) - Manages agent lifecycle, spawning, and health monitoring
+- **Coordinator Service** (FastAPI) - Receives Gitea webhooks, assigns tasks to agents
+- **Task Queue** - Valkey-backed queue for distributed task management
+- **Git Worktrees** - Isolated workspaces for parallel agent execution
+- **Killswitch** - Emergency stop mechanism for runaway agents
+- **Agent Dashboard** - Real-time monitoring UI with status widgets
+
+See [Agent Orchestration Design](docs/design/agent-orchestration.md) for architecture details.
+
 ## Current Implementation Status
 
-### ✅ Completed (v0.0.1)
+### ✅ Completed (v0.0.1-0.0.6)
 
-- **Issue #1:** Project scaffold and monorepo setup
-- **Issue #2:** PostgreSQL 17 + pgvector database schema
-- **Issue #3:** Prisma ORM integration with tests and seed data
-- **Issue #4:** Authentik OIDC authentication with BetterAuth
+- **M1-Foundation:** Project scaffold, PostgreSQL 17 + pgvector, Prisma ORM
+- **M2-MultiTenant:** Workspace isolation with RLS, team management
+- **M3-Features:** Knowledge management, tasks, calendar, authentication
+- **M4-MoltBot:** Bot integration architecture (in progress)
+- **M6-AgentOrchestration:** Orchestrator service, coordinator, agent dashboard ✅
 
-**Test Coverage:** 26/26 tests passing (100%)
+**Test Coverage:** 2168+ tests passing
 
 ### 🚧 In Progress (v0.0.x)
 
-- **Issue #5:** Multi-tenant workspace isolation (planned)
-- **Issue #6:** Frontend authentication UI ✅ **COMPLETED**
-- **Issue #7:** Activity logging system (planned)
-- **Issue #8:** Docker compose setup ✅ **COMPLETED**
+- Agent orchestration E2E testing
+- Usage budget management
+- Performance optimization
 
 ### 📋 Planned Features (v0.1.0 MVP)