Initialize the repository with tests

Author: phuryn

.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: agentsync
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd pg_isready
+          --health-interval 10s
+          --health-timeout 5s
+          --health-retries 5
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - run: npm ci
+      - run: npm run build
+      - run: npm test
+        env:
+          DATABASE_URL: postgresql://postgres:postgres@localhost:5432/agentsync

.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+dist/
+.env
+*.tsbuildinfo

CLAUDE.md

@@ -0,0 +1,76 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+AgentSync 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.
+
+## 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. AgentSync solves multi-human multi-agent coordination across teams. See 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).
+- **MCP-native is the differentiator.** The "UI" is Claude Code itself. No REST API or web dashboard in v1.
+- **Ship fast, iterate in public.** This is a first-mover play on the "agent coordination protocol" category. Simplicity and speed of adoption matter more than feature completeness.
+- **The CLAUDE.md integration pattern is as important as the server itself.** The drop-in snippet in `claude-md/COORDINATION.md` is what makes adoption zero-friction — agents coordinate automatically without humans configuring anything.
+
+## Tech Stack
+
+- Node.js + TypeScript
+- PostgreSQL (raw SQL via `pg` driver, no ORM)
+- `@modelcontextprotocol/sdk` for the MCP server
+- No auth layer or UI in v1
+
+## Build & Development Commands
+
+```bash
+docker compose up -d   # start PostgreSQL
+npm install            # install dependencies
+npm run build          # compile TypeScript
+npm start              # start the MCP server (stdio transport)
+npm test               # run integration tests (needs PostgreSQL)
+npm run dev            # watch mode for TypeScript compilation
+```
+
+Database: PostgreSQL on `localhost:5432`, database `agentsync`. Schema auto-applies on startup via `initDb()`. Connection string via `DATABASE_URL` env var (default: `postgresql://postgres:postgres@localhost:5432/agentsync`).
+
+Tests: Vitest, integration tests against real PostgreSQL. No mocks. Run `npm test` — requires a running PostgreSQL instance.
+
+## Architecture
+
+### Four Core Primitives
+
+1. **Intent** — A unit of desired work outcome (not a ticket). Lifecycle: `draft → open → claimed → blocked/done/cancelled`. Intents can have parent-child relationships (decomposition) and depend on other intents.
+
+2. **Claim** — Declaration that an agent/human is actively working on an intent. Tracks files being touched, branch name, and has a heartbeat mechanism (30-min stale threshold). Key for conflict detection.
+
+3. **Signal** — Event notifications (completion, blocked, conflict, info, request) that flow between agents. Completion signals can unblock dependent intents.
+
+4. **Context Package** — Assembled on-demand when an agent picks up work. Bundles the intent, dependencies, overlapping claims, recent signals, and team conventions into a single response.
+
+### MCP Tools (the entire interface)
+
+All interaction happens through 19 MCP tools — no REST API. Tools are grouped into:
+- **Intent Management:** create, publish, list, get, update, decompose
+- **Claim Management:** claim_work, heartbeat, release, complete
+- **Conflict Detection:** check_conflicts (the key safety check before starting work)
+- **Signals:** send_signal, get_signals
+- **Context:** get_context (first call when an agent starts work)
+- **Team/Overview:** list_teams, get_team_status, get_overview
+
+### Key Design Decisions
+
+- Conflicts are **advisory, not enforced** — no file-level locking
+- `claimed_by` is a trust-based string identifier (auth deferred to v2)
+- Single PostgreSQL instance (designed for <1000 users)
+- Polling via MCP tools, no WebSocket subscriptions in v1
+
+## Source Layout
+
+All source goes under `src/`. Key entry point is `src/index.ts` (MCP server). Database layer in `src/db/` (schema, connection pool, query functions). Each tool group gets its own file in `src/tools/`. Shared types in `src/types.ts`.

CONTRIBUTING.md

@@ -0,0 +1,78 @@
+# Contributing to AgentSync
+
+AgentSync is early-stage and building in public. We're looking for contributors at every level — from bug fixes to leading entire feature areas.
+
+## We're Looking for Co-Maintainers
+
+This isn't just "submit a PR and we'll review it." We're looking for people who want to **co-own this project** — review PRs, shape the roadmap, make design calls, help the community. Everyone pitches in on everything.
+
+If you're interested, open an issue titled "Maintainer interest" and tell us what drew you to the project. No prior contributions required.
+
+## Contributing Code
+
+### Setup
+
+```bash
+git clone https://github.com/phuryn/SwarmProtocol.git
+cd agentsync
+docker compose up -d
+npm install
+npm run build
+npm test
+```
+
+### Making Changes
+
+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))
+4. Run `npm test` and make sure all 67+ tests pass
+5. Open a PR with a clear description of what and why
+
+### Where to Contribute
+
+The codebase is organized into natural contribution boundaries:
+
+| Area | Files | Complexity |
+|------|-------|------------|
+| Tool groups | `src/tools/*.ts` | Low — each file is independent |
+| Database queries | `src/db/queries.ts` | Medium — SQL + state transitions |
+| Tests | `tests/*.test.ts` | Low — add new scenarios |
+| CLAUDE.md integration | `claude-md/` | Low — improve the drop-in snippet |
+| Documentation | `*.md` | Low |
+
+### Good First Contributions
+
+- Add a new signal type
+- Improve error messages in query functions
+- Add a `since` filter test for `get_signals`
+- Write a SQLite adapter for `src/db/connection.ts`
+- Add a `--port` flag for HTTP/SSE transport alongside stdio
+- Improve `get_overview` with additional aggregations
+
+### Code Style
+
+- TypeScript strict mode
+- Raw SQL with parameterized queries (`$1`, `$2`) — no ORM, no query builder
+- Each tool group in its own file under `src/tools/`
+- Tests are integration tests against real PostgreSQL — no mocks
+- Keep it simple. If you're adding a dependency, explain why in the PR.
+
+## Reporting Issues
+
+Open an issue with:
+- What you expected
+- What happened
+- Steps to reproduce (if applicable)
+- Your environment (Node version, PostgreSQL version, OS)
+
+## Design Philosophy
+
+Before proposing large changes, read [SPEC.md](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
+- **Advisory, not enforced** — conflicts are warnings, not locks
+- **Simple by default** — raw SQL, no frameworks, no magic
+
+If your proposal adds significant complexity, open an issue to discuss the design before writing code.

LANDSCAPE.md

@@ -0,0 +1,139 @@
+# AgentSync — Competitive Landscape & Market Signals
+
+## The Gap
+
+Every existing tool solves: **"I'm one developer running 3-5 agents in parallel, how do I prevent them from colliding?"**
+
+Nobody is solving: **"We're a team of 8 humans, each working through agents, across multiple repos and teams. How do we know what's in flight, avoid stepping on each other, and automatically hand off unblocked work?"**
+
+This is single-player multiplayer vs. true multiplayer. Different product category.
+
+---
+
+## Existing Tools (All Single-Developer Focus)
+
+### 1. Claude Code Agent Teams (Anthropic, experimental)
+- One lead agent coordinates teammates within a single session
+- Shared task list, file locking, inter-agent messaging
+- Intra-session only — not cross-team, not cross-human
+- Still experimental, known limitations around session resumption
+- https://code.claude.com/docs/en/agent-teams
+
+### 2. Claude Code Tasks (Anthropic, native)
+- Task management persisting to `~/.claude/tasks/`
+- Can share state across sessions via `CLAUDE_CODE_TASK_LIST_ID` env var
+- Session-scoped by design — no cross-human coordination
+- Dependencies and blockers supported
+- https://venturebeat.com/orchestration/claude-codes-tasks-update-lets-agents-work-longer-and-coordinate-across
+
+### 3. CCPM — Claude Code Project Manager (automazeio)
+- GitHub Issues as database, git worktrees for parallel execution
+- PRD → Epic → Task → Issue → Code → Commit pipeline
+- Closer to our idea but assumes single developer dispatching agents
+- No cross-team coordination or conflict detection
+- https://github.com/automazeio/ccpm
+
+### 4. tick-md (Purple Horizons)
+- Markdown file as database, git-backed, MCP server included
+- 7 GitHub stars — tiny traction
+- File locking, dependency tracking, real-time monitoring
+- Elegant but single-file approach doesn't scale to multiple teams
+- No intent/outcome abstraction — still task/ticket-oriented
+- https://www.tick.md/
+- https://github.com/Purple-Horizons (org page)
+
+### 5. Agent-MCP (rinadelph)
+- Shared memory graph ("Obsidian for AI agents"), file locking, task management
+- Real-time dashboard visualization
+- Single-repo, single-developer scope
+- https://github.com/rinadelph/Agent-MCP
+
+### 6. 1Code (21st.dev, YC W26)
+- GUI wrapper for Claude Code / OpenAI Codex
+- Cloud-based background execution, kanban board
+- Git worktree isolation per agent
+- GitHub/Linear/Slack automation triggers
+- Orchestration client, not a coordination protocol
+- https://dev.to/_46ea277e677b888e0cd13/1code-managing-multiple-ai-coding-agents-without-terminal-hell-14o4
+
+### 7. multi-agent-coordination-mcp (AndrewDavidRivers)
+- MCP server for Cursor IDE specifically
+- File locking, dependency management, Projects → Tasks → Todo Items
+- Single-developer scope
+- https://github.com/AndrewDavidRivers/multi-agent-coordination-mcp
+
+### 8. GitButler
+- Auto-sorts parallel Claude Code sessions into separate git branches via hooks
+- Each session gets its own branch automatically
+- Smart but solves git conflict isolation, not team coordination
+- https://blog.gitbutler.com/parallel-claude-code
+
+### 9. multi-agent-coordination-framework (timothyjrainwater-lab)
+- Methodology/protocol repo, not a tool
+- Built by a non-technical operator coordinating Claude + GPT agents
+- Handoff checklists, consistency gates, structured memo formats
+- "If it's not in a file, it doesn't exist" — core principle
+- Proves the pain is real but solution is manual protocols
+- https://github.com/timothyjrainwater-lab/multi-agent-coordination-framework
+
+---
+
+## What Jira Is Doing
+
+- Atlassian launched **"agents in Jira"** (open beta, Feb 2026) — assign tasks to AI agents from the same dashboard as human employees
+- Rovo Dev — AI agent for developers working with Jira + Bitbucket
+- Agentic CI/CD in Bitbucket Pipelines — natural language workflow automation
+- All of this is bolting agents onto the existing ticket model — opposite of agent-native
+- https://techcrunch.com/2026/02/25/jiras-latest-update-allows-ai-agents-and-humans-to-work-side-by-side/
+- https://www.atlassian.com/blog/announcements/ai-agents-in-jira
+
+---
+
+## Pain Signals From the Community
+
+### "Recipe for disaster"
+> One developer called multi-agent coding "a recipe for disaster" with "too much code to review" and "ugly conflicts due to agents all modifying the same files in different ways."
+- Source: https://www.eqengineered.com/insights/multiple-coding-agents
+
+### "You're the synchronization layer"
+> "With two agents it's manageable. With three it gets stressful. With five — it's impossible. The difference is whether the agents can operate autonomously... In a shared directory, the answer is no."
+- Source: https://vibehackers.io/blog/git-worktrees-multi-agent-development
+
+### "Agents forget everything between sessions"
+> A non-technical builder coordinating Claude + GPT over 100+ sessions found: "Agents forget everything between sessions. Parallel agents conflict. Nobody holds the full picture. Documents drift from reality. The human coordinator becomes the bottleneck."
+- Source: https://github.com/timothyjrainwater-lab/multi-agent-coordination-framework
+
+### "Terminal hell"
+> 1Code's creator after 4 months with Claude Code: "Running 3-4 agents in parallel, the CLI became painful." No visibility, git diffs scattered, merge conflicts waiting to happen.
+- Source: https://dev.to/_46ea277e677b888e0cd13/1code-managing-multiple-ai-coding-agents-without-terminal-hell-14o4
+
+### "Productivity decreased by 23%"
+> A Medium article reported one e-commerce team's productivity actually decreased by 23% after introducing their third AI tool, because tools were fighting each other with conflicting suggestions.
+- Source: https://medium.com/@techdigesthq/when-ai-tools-fight-each-other-the-hidden-chaos-of-multi-agent-workflows-83169e8dcc6f
+
+### Reddit/community signals
+> From r/programming: "Spent 4 hours debugging why my tests kept failing only to discover that my AI code formatter and my AI test generator were in a literal fight over syntax preferences."
+> From r/ExperiencedDevs: "Junior devs think AI tools are magic, but they don't understand that each tool has its own 'opinion' about best practices."
+
+---
+
+## AgentSync Differentiation
+
+| Dimension | Existing Tools | AgentSync |
+|-----------|---------------|-----------|
+| Scope | One dev, multiple agents | Multiple humans + agents across teams |
+| Primitive | Tasks / Tickets | Intents (outcome-oriented) |
+| Coordination | File locking, git worktrees | Claims + conflict detection + signals |
+| Context | Per-session, lost between sessions | Context packages assembled on demand |
+| Interface | GUI / CLI / Markdown files | MCP-native, embedded in CLAUDE.md |
+| Team support | None | Multi-team with conventions |
+| State sharing | Env vars, shared files | PostgreSQL, real-time via MCP |
+| Draft workflow | No | Draft → publish → claim |
+
+## Key Positioning
+
+- Not "Jira but with AI" — that's what Atlassian is doing and they'll always do it better
+- Not "one dev managing agent fleet" — that's what 1Code, CCPM, tick-md do
+- **"Coordination infrastructure for agent-first teams"** — a new category
+- The market for this is tiny today and enormous in 12-18 months
+- First mover who names the category owns the narrative

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentSync Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.