unbound-force · jflowers · Apr 6, 2026 · Apr 6, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -235,6 +235,7 @@ make install  # Install to GOPATH/bin
 | `replicator doctor` | Check environment health |
 | `replicator stats` | Display activity summary |
 | `replicator query` | Run preset SQL analytics queries |
+| `replicator docs` | Generate MCP tool reference (markdown) |
 | `replicator version` | Print version, commit, build date |
 
 ## Project Structure

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format follows [Keep a Changelog](https://keepachangelog.com/) and
+this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [0.2.0] - 2026-04-06
+
+### Added
+- 53 MCP tools across 4 categories: Hive (11), Swarm Mail (10),
+  Swarm (24), Memory (8)
+- Swarm orchestration with git worktree isolation
+- Agent messaging with file reservations
+- Dewey memory proxy with graceful degradation
+- CLI commands: init, doctor, stats, query, setup
+- Parity testing engine (100% shape match vs TypeScript)
+- macOS code signing and notarization
+- Homebrew distribution via `brew install unbound-force/tap/replicator`
+- GoReleaser v2 release pipeline (darwin-arm64, linux-amd64, linux-arm64)
+- Dewey MCP tool name update (dewey#28 prefix drop)
+- `replicator init` command for per-repo setup
+- Constitution and expanded AGENTS.md
+
+### Changed
+- Version command now displays commit hash and build date
+- Makefile: added release, install targets
+
+## [0.1.0] - 2026-04-04
+
+### Added
+- Initial release: Phase 0 scaffold
+- MCP JSON-RPC server (stdio transport)
+- SQLite database via `modernc.org/sqlite` (pure Go, no CGo)
+- Tool registry framework
+- 4 hive tools: `hive_cells`, `hive_create`, `hive_close`, `hive_update`
+- CLI: `replicator serve`, `replicator cells`, `replicator version`
+- 16 tests across 3 packages
+- CI workflow (go vet + go test + go build)
+- MIT LICENSE with Joel Hooks attribution
+
+[0.2.0]: https://github.com/unbound-force/replicator/releases/tag/v0.2.0
+[0.1.0]: https://github.com/unbound-force/replicator/releases/tag/v0.1.0
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,69 @@
+# Contributing to Replicator
+
+## Prerequisites
+
+- Go 1.25+
+- Git
+- Make
+
+## Development Setup
+
+```bash
+git clone git@github.com:unbound-force/replicator.git
+cd replicator
+make check   # builds, vets, and runs all tests
+```
+
+## Building and Testing
+
+```bash
+make build    # Build binary to bin/replicator
+make test     # Run all tests
+make vet      # Run go vet
+make check    # Vet + test (use this before submitting PRs)
+```
+
+## Testing Conventions
+
+- **Standard library only**: Use `testing` package. No testify, gomega, or
+  external assertion libraries.
+- **Assertions**: Use `t.Errorf` / `t.Fatalf` directly.
+- **Naming**: `TestXxx_Description` (e.g., `TestCreateCell_Defaults`).
+- **Database tests**: Use `db.OpenMemory()` for in-memory SQLite.
+- **Filesystem tests**: Use `t.TempDir()` for temporary directories.
+- **HTTP tests**: Use `httptest.NewServer` for mock servers.
+- **No shared state**: Each test creates its own fixtures.
+- **Git tests**: Guard with `if testing.Short() { t.Skip("requires git") }`.
+
+Always run tests with `-count=1` to disable caching.
+
+## Pull Request Workflow
+
+1. **Create a branch**: Speckit features use `NNN-feature-name`, OpenSpec
+   changes use `opsx/change-name`.
+2. **Spec first**: Non-trivial changes require a spec (either Speckit under
+   `specs/` or OpenSpec under `openspec/changes/`). When in doubt, use a spec.
+3. **Conventional commits**: Use `type: description` format
+   (feat, fix, docs, chore, refactor, test).
+4. **CI must pass**: Run `make check` locally before pushing.
+5. **One concern per PR**: Keep changes focused and minimal.
+
+## Coding Conventions
+
+- `gofmt` and `goimports` for formatting
+- GoDoc comments on all exported functions and types
+- Error wrapping: `fmt.Errorf("context: %w", err)`
+- Use `errors.Is` for sentinel errors (not string comparison)
+- Import grouping: stdlib, then third-party, then internal
+- JSON tags required on serialized struct fields
+- No global mutable state
+
+## Project Structure
+
+See [AGENTS.md](AGENTS.md) for the full project structure, constitution,
+behavioral constraints, and specification framework.
+
+## License
+
+By contributing, you agree that your contributions will be licensed under
+the [MIT License](LICENSE).
diff --git a/README.md b/README.md
@@ -1,74 +1,185 @@
 # Replicator
 
+[![CI](https://github.com/unbound-force/replicator/actions/workflows/ci.yml/badge.svg)](https://github.com/unbound-force/replicator/actions/workflows/ci.yml)
+![Go 1.25+](https://img.shields.io/badge/Go-1.25+-00ADD8?logo=go&logoColor=white)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 Multi-agent coordination for AI coding agents. Single Go binary, zero runtime dependencies.
 
 > Go rewrite of [cyborg-swarm](https://github.com/unbound-force/cyborg-swarm) (TypeScript). Same tools, same protocol, faster startup, simpler distribution.
 
-## Status: Phase 0 (Scaffold)
+## Status
+
+**53 MCP tools** | **190+ tests** | **15MB binary** | **<50ms startup**
 
-Working:
-- [x] SQLite database with hive schema (cells, events, agents)
-- [x] MCP JSON-RPC server (stdio transport)
-- [x] 4 tools: `hive_cells`, `hive_create`, `hive_close`, `hive_update`
-- [x] CLI: `replicator serve`, `replicator cells`, `replicator version`
+All 5 implementation phases are complete:
 
-Planned:
-- [ ] Phase 1: Remaining hive tools + swarm mail messaging
-- [ ] Phase 2: Swarm orchestration (decompose, spawn, worktrees)
-- [ ] Phase 3: Memory (Dewey proxy, Zen LLM client)
-- [ ] Phase 4: Full CLI (setup, doctor, stats, query, dashboard)
-- [ ] Phase 5: Parity testing against cyborg-swarm
+- [x] Phase 0: MCP server, SQLite, tool registry
+- [x] Phase 1: Hive (11 tools) + Swarm Mail (10 tools)
+- [x] Phase 2: Swarm Orchestration (24 tools)
+- [x] Phase 3: Memory / Dewey proxy (8 tools)
+- [x] Phase 4: CLI (9 commands)
+- [x] Phase 5: Parity testing (100% shape match)
 
 ## Install
 
+### Homebrew (macOS)
+
 ```bash
-# From source
-go install github.com/unbound-force/replicator/cmd/replicator@latest
+brew install unbound-force/tap/replicator
+```
+
+### Go Install
 
-# Or download binary from releases
-# https://github.com/unbound-force/replicator/releases
+```bash
+go install github.com/unbound-force/replicator/cmd/replicator@latest
 ```
 
+### Binary Download
+
+Download from [GitHub Releases](https://github.com/unbound-force/replicator/releases). Available for macOS (arm64), Linux (amd64, arm64).
+
 ## Usage
 
 ```bash
-# Initialize a project for swarm operations
+# Per-repo setup (creates .hive/ directory)
 replicator init
 
-# Start MCP server (for AI agent connections)
+# Per-machine setup (creates ~/.config/swarm-tools/ + SQLite DB)
+replicator setup
+
+# Start MCP server (AI agents connect via stdio)
 replicator serve
 
-# List hive cells
+# List work items
 replicator cells
 
-# Version
+# Check environment health
+replicator doctor
+
+# Activity summary
+replicator stats
+
+# Run preset analytics queries
+replicator query cells_by_status
+
+# Generate tool reference docs
+replicator docs
+
+# Version info
 replicator version
 ```
 
-## Development
+## MCP Tools (53)
 
-```bash
-make build    # Build binary to bin/replicator
-make test     # Run all tests
-make vet      # Go vet
-make check    # vet + test
-make serve    # Build and run MCP server
+Replicator exposes 53 tools via the [MCP protocol](https://modelcontextprotocol.io/) over stdio JSON-RPC:
+
+| Category | Tools | Purpose |
+|----------|-------|---------|
+| **Hive** | 11 | Work item tracking: create, query, update, close, epics, sessions, sync |
+| **Swarm Mail** | 10 | Agent messaging: send, inbox, ack, file reservations |
+| **Swarm** | 24 | Orchestration: decompose, spawn, worktrees, progress, review, insights |
+| **Memory** | 8 | Dewey proxy: store/find learnings, deprecated tool stubs |
+
+See the full [Tool Reference](docs/tools.md) for schemas and examples.
+
+## Connecting an AI Agent
+
+Add replicator to your `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "replicator": {
+      "type": "stdio",
+      "command": "replicator",
+      "args": ["serve"]
+    }
+  }
+}
+```
+
+For Claude Code, add to `mcp_servers` in your config:
+
+```json
+{
+  "mcp_servers": {
+    "replicator": {
+      "command": "replicator",
+      "args": ["serve"]
+    }
+  }
+}
 ```
 
+## Environment Variables
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `REPLICATOR_DB` | `~/.config/swarm-tools/swarm.db` | SQLite database path |
+| `DEWEY_MCP_URL` | `http://localhost:3333/mcp/` | Dewey semantic memory endpoint |
+| `ZEN_API_KEY` | *(none)* | OpenCode Zen gateway for LLM calls |
+
 ## Architecture
 
+```mermaid
+flowchart LR
+    Agent["AI Agent\n(OpenCode, Claude)"]
+    MCP["MCP Server\n(stdio JSON-RPC)"]
+    Reg["Tool Registry\n(53 tools)"]
+    Domain["Domain Logic\n(hive, swarm, mail)"]
+    DB["SQLite\n(WAL mode)"]
+    Dewey["Dewey\n(semantic memory)"]
+    Git["Git\n(worktrees)"]
+
+    Agent -->|stdin/stdout| MCP
+    MCP --> Reg
+    Reg --> Domain
+    Domain --> DB
+    Domain -->|HTTP proxy| Dewey
+    Domain -->|os/exec| Git
+```
+
+### Package Layout
+
 ```
-cmd/replicator/     CLI entrypoint (cobra)
+cmd/replicator/       CLI entrypoint (cobra)
 internal/
-  config/           Configuration (env vars, defaults)
-  db/               SQLite connection + migrations
-  hive/             Cell (work item) domain logic
-  mcp/              MCP JSON-RPC server
+  config/             Configuration (env vars, defaults)
+  db/                 SQLite + migrations (7 tables)
+  hive/               Cell CRUD, epics, sessions, sync
+  swarmmail/          Agent messaging, file reservations
+  swarm/              Decomposition, spawning, worktrees, review, insights
+  memory/             Dewey proxy, deprecated tool stubs
+  gitutil/            Git worktree operations (os/exec)
+  doctor/             Health check engine
+  stats/              Database activity summary
+  query/              Preset SQL analytics
+  mcp/                MCP JSON-RPC server
   tools/
-    registry/       Tool registration framework
-    hive/           Hive MCP tool handlers
+    registry/         Tool registration framework
+    hive/             Hive tool handlers (11)
+    swarmmail/        Swarm mail tool handlers (10)
+    swarm/            Swarm tool handlers (24)
+    memory/           Memory tool handlers (8)
+test/parity/          Shape comparison engine + fixtures
+docs/                 Generated tool reference
 ```
 
+## Development
+
+```bash
+make build    # Build binary to bin/replicator
+make test     # Run all tests
+make vet      # Go vet
+make check    # Vet + test
+make serve    # Build and run MCP server
+make release  # GoReleaser dry-run (local)
+make install  # Install to GOPATH/bin
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR workflow.
+
 ## Credits
 
 Go rewrite of [cyborg-swarm](https://github.com/unbound-force/cyborg-swarm), originally forked from [swarm-tools](https://github.com/joelhooks/swarm-tools) by [Joel Hooks](https://github.com/joelhooks). See [LICENSE](LICENSE).