Updated docs

Author: phuryn

.github/workflows/test.yml

@@ -9,6 +9,8 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
+    env:
+      FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true
 
     services:
       postgres:

CLAUDE.md

@@ -6,13 +6,13 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 Swarm Protocol is a headless MCP server for AI agent team coordination. It solves state synchronization when multiple people work through AI agents (Claude Code, etc.) on the same codebase simultaneously — preventing file conflicts, tracking work in flight, and managing task dependencies.
 
-**Status:** Alpha — all 19 MCP tools implemented, integration tests written. See SPEC.md for the full design.
+**Status:** Alpha — all 19 MCP tools implemented, integration tests written. See docs/SPEC.md for the full design.
 
 ## Philosophy & Positioning
 
 This is a **coordination protocol, not a project management tool**. The origin insight: "Jira was built for humans clicking buttons. This is coordination infrastructure for agent-first teams." The problem isn't Kanban or sprints — it's state synchronization when agents are the primary interface.
 
-**Key differentiator:** Every existing tool (Claude Code Agent Teams, CCPM, tick-md, Agent-MCP, 1Code, etc.) solves single-developer multi-agent coordination. Swarm Protocol solves multi-human multi-agent coordination across teams. See LANDSCAPE.md for the full competitive analysis.
+**Key differentiator:** Every existing tool (Claude Code Agent Teams, CCPM, tick-md, Agent-MCP, 1Code, etc.) solves single-developer multi-agent coordination. Swarm Protocol solves multi-human multi-agent coordination across teams. See docs/LANDSCAPE.md for the full competitive analysis.
 
 When making implementation decisions:
 - **Protocol over product.** Keep it minimal and composable. Resist feature creep toward traditional PM concepts (sprints, boards, velocity, story points).

CONTRIBUTING.md

@@ -25,7 +25,7 @@ npm test
 
 1. Fork the repo and create a branch from `main`
 2. Make your changes
-3. Add or update tests — we use integration tests against real PostgreSQL (see [TESTING.md](TESTING.md))
+3. Add or update tests — we use integration tests against real PostgreSQL (see [TESTING.md](docs/TESTING.md))
 4. Run `npm test` and make sure all 67+ tests pass
 5. Open a PR with a clear description of what and why
 
@@ -68,7 +68,7 @@ Open an issue with:
 
 ## Design Philosophy
 
-Before proposing large changes, read [SPEC.md](SPEC.md) and the Philosophy section in [CLAUDE.md](CLAUDE.md). The key principles:
+Before proposing large changes, read [SPEC.md](docs/SPEC.md) and the Philosophy section in [CLAUDE.md](CLAUDE.md). The key principles:
 
 - **Protocol over product** — resist feature creep toward traditional PM tools
 - **MCP-native** — the interface is MCP tools, not REST or UI

README.md

@@ -1,45 +1,154 @@
 # Swarm Protocol
 
-> MCP server for AI agent team coordination. No UI. No sprints. Just state sync.
+[![Tests](https://github.com/phuryn/swarm-protocol/actions/workflows/test.yml/badge.svg)](https://github.com/phuryn/swarm-protocol/actions/workflows/test.yml)
+![GitHub stars](https://img.shields.io/github/stars/phuryn/swarm-protocol?style=flat-square&color=0d9488)
+[![License: MIT](https://img.shields.io/badge/License-MIT-0d9488?style=flat-square)](https://github.com/phuryn/swarm-protocol/blob/main/LICENSE)
+[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-0d9488?style=flat-square)](https://github.com/phuryn/swarm-protocol/blob/main/CONTRIBUTING.md)
 
-**Status: Alpha — building in public**
+**Coordination protocol for agent-first teams. No UI. No sprints. Just state sync.**
+
+![Swarm Protocol](docs/welcome.png)
+
+**Status: Alpha — building in public. [19 MCP tools](#all-19-tools) implemented, integration tests passing.**
+
+## The Coordination Loop
+
+Drop [`COORDINATION.md`](claude-md/COORDINATION.md) into your repo's `CLAUDE.md` and agents coordinate automatically:
+
+```
+Agent starts session
+  → get_team_status        "What's in flight?"
+  → claim_work             "I'm taking this — here are my files"
+  → check_conflicts        "Anyone else touching src/api/router.ts?"
+  → heartbeat              "Still working" (every 10-15 min)
+  → complete_claim          "Done — this unblocks intent_xyz"
+                              ↳ intent_xyz status: blocked → open
+                              ↳ Next agent picks it up automatically
+```
+
+Zero Slack messages. Zero status meetings. Agents coordinate through shared state.
+
+## What This Is
+
+A headless coordination layer exposed as an MCP server — the same protocol Claude Code already speaks. No REST API. No dashboard. Agents query it to see what's in flight, claim work, detect file conflicts, and hand off unblocked tasks.
+
+This is a **coordination protocol, not a project management tool.** Jira was built for humans clicking buttons. This is state synchronization infrastructure for teams where agents are the primary development interface.
+
+The CLAUDE.md integration pattern is as important as the server itself. Agents coordinate automatically without humans configuring anything.
+
+## Who Is This For
+
+Teams of 2+ developers where AI agents (Claude Code, etc.) are the primary development interface. If your workflow is "open terminal → tell Claude Code what to build → review the PR" and teammates are doing the same thing at the same time — this is the missing layer.
+
+**Not for:** solo devs running multiple agents in parallel (tools like [CCPM](https://github.com/automazeio/ccpm) and [1Code](https://www.1code.io/) solve that). Not a Jira replacement. Not a project management tool.
 
 ## The Problem
 
-When multiple people work through AI agents simultaneously:
-- No one knows what's in flight right now
-- Two agents edit the same files and create conflicts
-- Completed work sits idle because no one picks up the next dependent task
+Every existing tool in this space solves **single-player** multi-agent coordination: one developer dispatching 3-5 agents. Useful, but insufficient.
+
+Nobody is solving **multiplayer**: multiple humans, each working through agents, across teams. That's not a project management problem — it's a state synchronization problem.
+
+What happens without coordination:
+- Two agents edit the same files → ugly merge conflicts
+- Completed work sits idle — no one picks up the next dependent task
 - Context is lost between agent sessions
-- There's no shared state of "done / in progress / blocked"
+- No shared state of what's done, in progress, or blocked
 
-Every existing tool solves **single-developer** multi-agent coordination. Nobody is solving: **"We're a team of 8 humans, each working through agents, across multiple repos and teams. How do we stay in sync?"**
+See [LANDSCAPE.md](docs/LANDSCAPE.md) for the full competitive breakdown.
 
-This isn't a project management problem. It's a state synchronization problem.
+## Four Primitives
 
-## What This Is
+| Primitive | What It Does |
+|-----------|-------------|
+| **Intent** | A unit of desired outcome — not a ticket. Lifecycle: `draft → open → claimed → done`. Has constraints, acceptance criteria, and dependency chains. |
+| **Claim** | "I'm working on this." Tracks which files are being touched. Includes heartbeat — claims with no heartbeat for 30 min get flagged as stale. |
+| **Signal** | Event notification: completion, blocked, conflict, info. When a completion signal fires, dependent intents auto-unblock. |
+| **Context Package** | Everything an agent needs to start work — intent, dependencies, active claims on overlapping files, recent signals, team conventions — assembled in one call via `get_context`. |
+
+## Architecture
+
+![Architecture](docs/architecture.png)
+
+**Stack:** Node.js + TypeScript · PostgreSQL (raw SQL, no ORM) · `@modelcontextprotocol/sdk`
+
+**Design decisions:**
+- Conflicts are advisory, not enforced — no file-level locking
+- Auth is trust-based in v1 (`claimed_by` is a string the agent passes)
+- Single PostgreSQL instance (designed for <1000 users)
+- Polling via MCP tools, no WebSocket subscriptions
+- Protocol over product — minimal and composable by design
+
+## Key Tools
 
-A headless coordination layer exposed as an MCP server. Agents query it to see what's in flight, claim work, detect file conflicts, and hand off unblocked tasks — all without human overhead.
+### `check_conflicts` — Prevent file collisions before they happen
 
-The "UI" is Claude Code itself. Drop a snippet in your repo's CLAUDE.md and agents coordinate automatically.
+```
+→ check_conflicts({ files: ["src/api/router.ts", "src/middleware/auth.ts"] })
+
+← { conflicts: [{
+     file: "src/api/router.ts",
+     claimed_by: "anna",
+     intent: "Refactor API error handling",
+     claim_id: "claim_abc123"
+   }]}
+```
+
+### `get_context` — One call, full onboarding
+
+```
+→ get_context({ intent_id: "intent_abc123" })
+
+← { intent: { title, description, constraints, acceptance_criteria },
+    parent: null,
+    dependencies: [{ id: "intent_xyz", status: "done" }],
+    active_claims: [{ file: "src/middleware/rateLimit.ts", claimed_by: "pawel" }],
+    recent_signals: [...],
+    team_conventions: "Use Prettier. Tests required. No console.log in production." }
+```
+
+### `complete_claim` — Done. Dependents auto-unblock.
+
+```
+→ complete_claim({ claim_id: "claim_def456", unblocks: ["intent_xyz"] })
+
+← intent_abc123: claimed → done
+   intent_xyz: blocked → open  (all dependencies met)
+   signal: completion created
+```
+
+### All 19 Tools
+
+<details>
+<summary>Full tool reference</summary>
+
+| Group | Tools |
+|-------|-------|
+| **Teams** | `create_team`, `list_teams`, `get_team_status`, `get_overview` |
+| **Intents** | `create_intent`, `publish_intent`, `list_intents`, `get_intent`, `update_intent`, `decompose_intent` |
+| **Claims** | `claim_work`, `heartbeat`, `release_claim`, `complete_claim` |
+| **Conflicts** | `check_conflicts` |
+| **Signals** | `send_signal`, `get_signals` |
+| **Context** | `get_context` |
+
+See [SPEC.md](docs/SPEC.md) for full parameter specs and data model.
+
+</details>
 
 ## Quick Start
 
 **Prerequisites:** Docker, Node.js 22+
 
 ```bash
-# 1. Clone and set up
+# Clone and set up
 git clone https://github.com/phuryn/swarm-protocol.git
 cd swarm-protocol
 
-# 2. Start PostgreSQL
+# Start PostgreSQL
 docker compose up -d
 
-# 3. Build
+# Build and test
 npm install
 npm run build
-
-# 4. Test
 npm test
 ```
 
@@ -59,66 +168,45 @@ npm test
 }
 ```
 
-**Enable automatic coordination** — copy [`claude-md/COORDINATION.md`](claude-md/COORDINATION.md) into your repo's CLAUDE.md. Agents will automatically check for conflicts, claim work, and signal completions.
-
-## How It Works
-
-### Four Primitives
-
-| Primitive | What It Does |
-|-----------|-------------|
-| **Intent** | Unit of desired outcome. Lifecycle: `draft → open → claimed → done`. Not a ticket — an outcome. |
-| **Claim** | "I'm working on this." Tracks files being touched, includes heartbeat for stale detection. |
-| **Signal** | Event notification — completion, blocked, conflict, info. Flows to whoever needs to know. |
-| **Context Package** | Everything an agent needs to start work, assembled in one call. |
-
-### The Coordination Loop
-
-```
-Agent starts session
-  → get_team_status (what's in flight?)
-  → claim_work (I'm taking this, here are my files)
-  → check_conflicts (am I stepping on anyone?)
-  → heartbeat (still working, every 10-15 min)
-  → complete_claim (done — this unblocks X, Y, Z)
-```
-
-### 19 MCP Tools
+**Enable automatic coordination** — copy [`claude-md/COORDINATION.md`](claude-md/COORDINATION.md) into your repo's `CLAUDE.md`. That's it.
 
-| Group | Tools |
-|-------|-------|
-| **Teams** | `create_team`, `list_teams`, `get_team_status`, `get_overview` |
-| **Intents** | `create_intent`, `publish_intent`, `list_intents`, `get_intent`, `update_intent`, `decompose_intent` |
-| **Claims** | `claim_work`, `heartbeat`, `release_claim`, `complete_claim` |
-| **Conflicts** | `check_conflicts` |
-| **Signals** | `send_signal`, `get_signals` |
-| **Context** | `get_context` |
+## What's Not in v1
 
-## Architecture
+Intentional omissions, not missing features:
 
-- **Runtime:** Node.js + TypeScript
-- **Database:** PostgreSQL (raw SQL, no ORM)
-- **Interface:** MCP-native via `@modelcontextprotocol/sdk`
-- **Auth:** Trust-based v1 (agent passes user identifier)
+- **No web UI** — agents and terminal are the interface
+- **No auth** — trust-based identity. Auth layer comes when it needs to.
+- **No real-time subscriptions** — MCP polling is sufficient
+- **No notifications** — Slack/Discord integration is a natural v2 extension
+- **No file locking** — conflicts are advisory by design
+- **No multi-repo** — single repo per team assumed
 
-See [SPEC.md](SPEC.md) for the full design. See [LANDSCAPE.md](LANDSCAPE.md) for competitive analysis. See [TESTING.md](TESTING.md) for test architecture, coverage, and assumptions.
+## Looking for Co-Builders
 
-## What Makes This Different
+The market for agent-team coordination is tiny today and enormous in 12-18 months. Every team adopting Claude Code, Codex, or similar tools will hit this exact problem the moment they scale past one developer.
 
-Every tool in this space — Claude Code Agent Teams, CCPM, tick-md, Agent-MCP, 1Code — solves the **single-player** version: one dev running multiple agents in parallel. That's useful but insufficient.
+This isn't a side project looking for drive-by PRs. It's a category that needs to be built. I'm looking for people who want to **own parts of this protocol** — lead feature areas, review PRs, shape the design.
 
-Swarm Protocol solves the **multiplayer** version: multiple humans, each working through agents, across teams. Cross-human conflict detection, dependency chains that auto-unblock, context packages that onboard agents instantly.
+**Where to plug in:**
 
-See [LANDSCAPE.md](LANDSCAPE.md) for the full competitive breakdown.
+- **Tool groups** (`src/tools/`) are natural ownership boundaries — each one is a self-contained module with its own tests
+- **The protocol design itself** — the four primitives are v1. What's missing? What's wrong? Open an issue and make the case.
+- **Adapters** — SQLite backend, auth layer, Slack signal forwarding, dashboard read-model. Each is a standalone contribution.
+- **The CLAUDE.md pattern** — better coordination instructions, support for other agents beyond Claude Code
 
-## Contributing
+The raw SQL + no-framework design is intentional — fork it, swap PostgreSQL for SQLite, add auth, build custom tools.
 
-This is early-stage, building in public. We're looking for **contributors and maintainers** — people who want to own parts of this project, not just submit patches.
+See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. Or just open an issue with your idea.
 
-Interested in leading a feature area, reviewing PRs, or managing releases? See [CONTRIBUTING.md](CONTRIBUTING.md).
+## Docs
 
-The tool groups (`src/tools/`) are natural contribution boundaries. The raw SQL + no-framework design is intentional — fork it, swap PostgreSQL for SQLite, add auth, build custom tools.
+| Doc | What's In It |
+|-----|-------------|
+| [SPEC.md](docs/SPEC.md) | Full protocol design, data model, SQL schema, tool specifications |
+| [LANDSCAPE.md](docs/LANDSCAPE.md) | Competitive analysis — every tool in the space and why this is different |
+| [TESTING.md](docs/TESTING.md) | Test architecture, coverage, assumptions |
+| [COORDINATION.md](claude-md/COORDINATION.md) | Drop-in CLAUDE.md snippet for your repo |
 
 ## License
 
-MIT
+MIT

docs/EXAMPLE_TEST_RESULTS.md

@@ -0,0 +1,37 @@
+# Example Test Results
+
+**Run date:** 2026-03-13 16:40 UTC+1
+**Environment:** Windows 11, Node.js 22, PostgreSQL 16 (Docker), Vitest 3.2.4
+
+```
+ ✓ tests/edge-cases.test.ts (22 tests) 1328ms
+ ✓ tests/intents.test.ts (10 tests) 619ms
+ ✓ tests/claims.test.ts (8 tests) 552ms
+ ✓ tests/teams.test.ts (7 tests) 388ms
+ ✓ tests/scenarios.test.ts (4 tests) 387ms
+ ✓ tests/overview.test.ts (5 tests) 386ms
+ ✓ tests/conflicts.test.ts (5 tests) 348ms
+ ✓ tests/signals.test.ts (4 tests) 290ms
+ ✓ tests/context.test.ts (2 tests) 158ms
+
+ Test Files  9 passed (9)
+      Tests  67 passed (67)
+   Start at  16:40:36
+   Duration  6.80s (transform 104ms, setup 0ms, collect 905ms, tests 4.46s, environment 1ms, prepare 527ms)
+```
+
+## Test Breakdown
+
+| File | Tests | What It Covers |
+|------|-------|----------------|
+| `edge-cases.test.ts` | 22 | Error paths, boundary conditions, invalid state transitions |
+| `intents.test.ts` | 10 | Create/publish lifecycle, filtering, draft visibility, decomposition |
+| `claims.test.ts` | 8 | Claim lifecycle, heartbeat, release/reopen, completion, dependency unblocking |
+| `teams.test.ts` | 7 | Team CRUD, duplicate rejection, empty list, null handling |
+| `scenarios.test.ts` | 4 | End-to-end coordination stories |
+| `overview.test.ts` | 5 | Team status, stale claims, blocked intents, conflicts, completed |
+| `conflicts.test.ts` | 5 | File overlap detection, ignoring completed/abandoned claims |
+| `signals.test.ts` | 4 | Send/retrieve, filtering by type/team, limit |
+| `context.test.ts` | 2 | Full context package assembly, non-existent intent |
+
+For live CI results, see the [Actions tab](https://github.com/phuryn/swarm-protocol/actions).