switchman-dev 0.1.2 → 0.1.4

package/README.md

@@ -1,260 +1,150 @@
 # Switchman
 
-**Stop your AI agents from overwriting each other.**
+**Run 10+ agents on one codebase. Safely.**
 
-When you run multiple Claude Code instances on the same repo, they have no idea what each other is doing. One agent edits a file while another rewrites it. Hours of work disappear at merge time.
+Switchman acts like a project manager for your AI coding assistants. It hands out tasks, stops agents from editing the same file at the same time, and double-checks their work before saving.
 
-Switchman gives them a shared task queue and file locking so they stay on separate tracks — and you stay in control.
+When you run multiple agents on the same repo, they need shared coordination or they collide, duplicate work, and create risky merges. Switchman gives them leases, scoped ownership, merge gates, and landing workflows so they can move in parallel without stepping on each other.
 
----
+In the docs, `workspace` means the folder each agent works in. Some commands still use the Git term `worktree`, because that is the underlying Git feature.
 
-## Requirements
+Questions, feedback, or testing Switchman with your team? Join the [Discord](https://discord.gg/pnT8BEC4D)
 
+## Install
+
+Requirements:
 - Node.js 22.5+
 - Git 2.5+
 
----
-
-## Install
-
 ```bash
 npm install -g @switchman-dev
 ```
 
----
+## Why Switchman?
+
+Git worktrees, branches, and raw coding agents are useful, but they do not coordinate themselves.
 
-## Pick your setup
+What it adds that plain Git does not:
+- task assignment, so agents do not duplicate work
+- file locking, so parallel edits do not quietly collide
+- live status, so you can see what is running, blocked, or stale
+- stale-work recovery, so abandoned work does not clog the repo
+- governed landing, so finished work reaches `main` one item at a time with retries and checks
 
-### Option A — Claude Code (recommended)
+In short:
+- Git gives you branches
+- Switchman gives you coordination
 
-Claude Code has a native Switchman integration via MCP. Your agents coordinate automatically — no manual CLI calls, no extra prompting.
+## Quickstart
 
-**Step 1 — Create your agent workspaces**
+Recommended first run:
+- editor: Cursor
+- goal: feel safe parallel agent work in under 10 minutes
+- proof: status stays clear, agents stay separated, and the repo gate passes
 
 ```bash
 cd my-project
-switchman setup --agents 3
-```
-
-That's it. Switchman creates three isolated workspaces, one per agent, and initialises the database. You'll see the folder paths printed — you'll need them in step 4.
+switchman setup --agents 5
 
-**Step 2 — Add Switchman to Claude Code**
+switchman task add "Implement auth helper" --priority 9
+switchman task add "Add auth tests" --priority 8
+switchman task add "Update auth docs" --priority 7
 
-Add this to `~/.claude/claude_desktop_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "switchman": {
-      "command": "switchman-mcp",
-      "args": []
-    }
-  }
-}
-```
-
-Then restart Claude Code.
-
-**Step 3 — Copy CLAUDE.md into your repo root**
-
-```bash
-curl -O https://raw.githubusercontent.com/switchman-dev/switchman/main/CLAUDE.md
+switchman status
+switchman status --watch
+switchman gate ci
 ```
 
-This tells your agents how to use Switchman. Without it they won't know to coordinate.
+What `switchman setup` gives you:
+- one shared Switchman database in `.switchman/`
+- linked workspaces for each agent
+- local MCP config for Claude Code and Cursor
 
-**Step 4 — Add your tasks**
+Fastest path to success:
+1. Use Cursor for the first run.
+2. Open one Cursor window per generated workspace.
+3. Let each agent pick up one clearly separate task.
+4. Keep `switchman status --watch` open in another terminal.
+5. Run `switchman gate ci` when the tasks finish.
 
-```bash
-switchman task add "Fix the login bug" --priority 8
-switchman task add "Add rate limiting" --priority 6
-switchman task add "Update README" --priority 2
-```
+If you want the recommended editor setup guide, start here:
+- [Cursor setup](docs/setup-cursor.md)
 
-**Step 5 — Open Claude Code in each workspace**
+If you want a guided demo, see [examples/README.md](examples/README.md).
 
-Open a separate Claude Code window in each folder that `switchman setup` created. Each agent will automatically pick up a task, lock the files it needs, and release them when it's done.
+## What good looks like
 
-**Step 6 — Check before merging**
+You know the first run is working when:
+- agents claim different files instead of stepping on each other
+- `switchman status` stays calm and readable instead of filling with blocked work
+- the landing queue moves finished work safely back toward `main`
+- `switchman gate ci` passes cleanly
 
-```bash
-switchman scan
-```
+That is the moment Switchman should feel different from “just using a few branches.”
 
----
+## Why not just use branches or worktrees?
 
-### Option B — Any other agent (Cursor, Windsurf, Aider, etc.)
+Because branches and worktrees solve isolation, not coordination.
 
-Switchman works as a CLI tool with any agent that can run terminal commands. The coordination isn't automatic — you'll need to prompt your agents to use Switchman commands.
+They do not tell you:
+- which task each agent should take next
+- who already owns a file
+- whether a session is stale
+- whether finished work is still safe to land
 
-**Step 1 — Create your agent workspaces**
+Switchman is for the point where “we can manage this by hand” stops being true.
 
-```bash
-cd my-project
-switchman setup --agents 3
-```
+## Choose your setup
 
-**Step 2 — Add your tasks**
+Pick the guide that matches how you work:
 
-```bash
-switchman task add "Fix the login bug" --priority 8
-switchman task add "Add rate limiting" --priority 6
-```
+| Setup | Guide |
+|------|------|
+| Claude Code | [Claude Code setup](docs/setup-claude-code.md) |
+| Cursor | [Cursor setup](docs/setup-cursor.md) |
+| Windsurf | [Windsurf setup](docs/setup-windsurf.md) |
+| Any CLI-driven agent | [CLI agent setup](docs/setup-cli-agents.md) |
 
-**Step 3 — Give each agent this prompt**
+## If something feels stuck
 
-Paste this into your agent at the start of each session:
+Use `switchman status` first.
 
-```
-Before starting any work:
-1. Run `switchman lease next --json` to get your assigned task and lease
-2. Run `switchman claim <taskId> <worktreeName> <files...>` to lock the files you'll edit
-   - If a file is already claimed, pick a different approach or different files
-3. If the task runs for a while, refresh the lease with `switchman lease heartbeat <leaseId>`
-4. When finished, run `switchman task done <taskId>`
-
-Never edit a file you haven't claimed. If a claim fails, do not use --force.
-```
+It is the main terminal dashboard for the repo:
+- top health banner and compact counts
+- boxed sections for `Running`, `Blocked`, `Warnings`, `Queue`, and `Next action`
+- exact follow-up commands when something needs attention
+- `--watch` mode for a live terminal view
 
-**Step 4 — Check before merging**
+Useful commands:
 
 ```bash
-switchman scan
-```
-
----
-
-## What your agents will see
-
-Here's what a normal session looks like with Switchman running:
-
-```
-# Agent 1 picks up a task
-switchman lease next
-✓  Lease acquired: "Add rate limiting to all routes"  [task-abc-123 / lease-xyz-123]
-
-# Agent 1 locks its files
-switchman claim task-abc-123 agent1 src/middleware/auth.js src/server.js
-✓  2 files locked — no conflicts
-
-# Agent 2 picks up a different task
-switchman lease next
-✓  Lease acquired: "Add validation to POST /tasks"  [task-def-456 / lease-xyz-456]
-
-# Agent 2 tries to claim a file already locked by Agent 1
-switchman claim task-def-456 agent2 src/middleware/auth.js
-⚠  Conflict: auth.js is locked by agent1
-
-# Agent 2 claims different files instead
-switchman claim task-def-456 agent2 src/middleware/validate.js src/routes/tasks.js
-✓  2 files locked — no conflicts
-
-# Both agents working, zero collisions
 switchman status
-  agent1  →  "Add rate limiting"      editing auth.js, server.js
-  agent2  →  "Add validation"         editing validate.js, tasks.js
+switchman status --watch
+switchman status --json
+switchman scan
+switchman gate ci
 ```
 
----
-
-## Commands
-
-### `switchman setup`
-One-command setup — creates agent workspaces and initialises the database.
-- `--agents 3` — number of workspaces to create (default: 3, max: 10)
-- `--prefix switchman` — branch name prefix (default: switchman)
-
-### `switchman init`
-Initialise in the current git repo without creating worktrees. Creates `.switchman/switchman.db` and auto-detects existing worktrees.
-
-### `switchman task add <title>`
-Add a task to the queue.
-- `--priority 1-10` (default: 5)
-- `--description "..."`
-
-### `switchman task list`
-List all tasks. Filter with `--status pending|in_progress|done|failed`.
-
-### `switchman task next`
-Get and assign the next pending task. This is a compatibility shim over the lease workflow. Use `--json` for agent automation.
-- `--worktree <name>` — worktree to assign to (defaults to current folder name)
-- `--agent <name>` — agent identifier for logging
-
-### `switchman lease next`
-Acquire the next pending task as a first-class lease. Use `--json` for agent automation.
-- `--worktree <name>` — worktree to assign to (defaults to current folder name)
-- `--agent <name>` — agent identifier for logging
-
-### `switchman lease list`
-List active and historical leases. Filter with `--status active|completed|failed|expired`.
-
-### `switchman lease heartbeat <leaseId>`
-Refresh the heartbeat timestamp for a long-running lease so it does not get treated as stale.
-
-### `switchman lease reap`
-Expire stale leases, release their claims, and return their tasks to `pending`.
-- `--stale-after-minutes <n>` — staleness threshold (default: 15)
-
-### `switchman task done <taskId>`
-Mark a task complete and release all file claims.
-
-### `switchman task fail <taskId>`
-Mark a task failed and release all file claims.
-
-### `switchman claim <taskId> <worktree> [files...]`
-Lock files before editing. Warns immediately if any file is already claimed by another agent.
-
-### `switchman release <taskId>`
-Release all file claims for a task.
-
-### `switchman scan`
-Check all worktrees for conflicts — both uncommitted file overlaps and branch-level merge conflicts. Run this before merging.
-
-### `switchman status`
-Full overview: task counts, active leases, stale leases, locked files, and a quick conflict scan.
-
-### `switchman worktree list`
-List all git worktrees with their registered agents and status.
-
-### `switchman worktree sync`
-Re-sync git worktrees into the Switchman database (useful if you add worktrees after init).
-
----
-
-## MCP tools (Claude Code)
-
-| Tool | What it does |
-|------|-------------|
-| `switchman_task_next` | Get + assign the next pending task |
-| `switchman_task_add` | Add a new task to the queue |
-| `switchman_task_claim` | Claim files before editing (conflict check) |
-| `switchman_task_done` | Mark task complete, release file claims |
-| `switchman_task_fail` | Mark task failed, release file claims |
-| `switchman_lease_heartbeat` | Refresh a long-running lease heartbeat |
-| `switchman_scan` | Scan all worktrees for conflicts |
-| `switchman_status` | Full system overview |
-
----
-
-## Roadmap
-
-- [ ] Merge queue — serialize worktree→main merges with auto-retry
-- [ ] Automatic stale-lease policies — configurable heartbeat/reap behaviour
-- [ ] Cursor and Windsurf native MCP integration
-- [ ] Web dashboard
-- [ ] `brew install switchman`
+More help:
+- [Status and recovery](docs/status-and-recovery.md)
+- [Merge queue](docs/merge-queue.md)
+- [Stale lease policy](docs/stale-lease-policy.md)
 
----
+## More docs
 
-## Feedback & contact
+- [Merge queue](docs/merge-queue.md)
+- [Pipelines and PRs](docs/pipelines.md)
+- [Stale lease policy](docs/stale-lease-policy.md)
+- [MCP tools](docs/mcp-tools.md)
+- [Command reference](docs/command-reference.md)
 
-Building this in public — if you're running parallel agents and hit something broken or missing, I'd love to hear about it.
+## Feedback
 
-- **GitHub Issues** — [github.com/switchman-dev/switchman/issues](https://github.com/switchman-dev/switchman/issues)
-- **Email** — [hello@switchman.dev](mailto:hello@switchman.dev)
+Building this in public. If you're running parallel agents and hit something broken or missing, I’d love to hear about it.
 
----
+- GitHub Issues: [github.com/switchman-dev/switchman/issues](https://github.com/switchman-dev/switchman/issues)
+- Email: [hello@switchman.dev](mailto:hello@switchman.dev)
 
 ## License
 
-MIT — free to use, modify, and distribute.
+MIT

package/examples/README.md

@@ -25,6 +25,8 @@ examples/
 
 ## Quick start
 
+This is the fastest way to understand Switchman as a new user.
+
 Make sure Switchman is installed globally first:
 ```bash
 npm install -g .   # from the switchman repo root
@@ -36,16 +38,30 @@ bash examples/setup.sh
 bash examples/walkthrough.sh
 ```
 
+If you want the shortest path:
+- `setup.sh` creates the repo, worktrees, and seed tasks
+- `walkthrough.sh` shows one complete 3-agent happy path, including a real claim conflict
+
 ## What the walkthrough shows
 
 1. **3 worktrees created** — simulating 3 parallel Claude Code instances each on their own branch
-2. **Agent 1 picks up a task** — `switchman task next` returns the highest-priority item
+2. **Agent 1 picks up a task** — `switchman lease next` returns the highest-priority item and lease
 3. **Agent 1 claims files** — declares which files it will edit before touching them
 4. **Agent 2 picks up a task** — takes the next item from the queue
 5. **Agent 2 tries to claim a conflicting file** — Switchman blocks it
 6. **Agent 2 adapts** — claims only the safe files instead
 7. **Agent 1 finishes** — marks task done, releases file claims
-8. **Final status** — queue updated, no lingering conflicts
+
+Under the hood, Switchman now treats the lease as the execution record. That means reviewer artifacts and audit history can point back to the exact lease that performed the work, not just the task title.
+8. **Final status** — queue updated, readable status output, no lingering conflicts
+
+## What a good demo run looks like
+
+At the end of the walkthrough, you want to see:
+- tasks moving from `pending` -> `in_progress` -> `done`
+- one agent blocked from claiming a file already owned by another
+- `switchman scan` showing no unclaimed changes
+- `switchman status` giving a clean overview of what happened
 
 ## The taskapi project
 

package/examples/walkthrough.sh

@@ -2,7 +2,7 @@
 # examples/walkthrough.sh
 #
 # Walks through the Switchman workflow step by step.
-# Simulates 3 agents working in parallel — including a real conflict.
+# Simulates 3 agents working in parallel, including a real file-claim conflict.
 #
 # Run AFTER setup.sh:
 #   bash examples/walkthrough.sh
@@ -51,11 +51,11 @@ read -r
 # ── Step 2: Agent 1 picks up a task ──────────────────────────────────────────
 
 step "2. Agent 1 picks up the highest-priority task"
-agent "agent-rate-limiting" "calling: switchman task next --json"
+agent "agent-rate-limiting" "calling: switchman lease next --json"
 echo ""
 
-TASK1=$(switchman task next --json 2>/dev/null || echo "null")
-TASK1_ID=$(echo "$TASK1" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])" 2>/dev/null || echo "")
+TASK1=$(switchman lease next --json --worktree agent-rate-limiting --agent claude-code 2>/dev/null || echo "null")
+TASK1_ID=$(echo "$TASK1" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['task']['id'])" 2>/dev/null || echo "")
 
 if [ -z "$TASK1_ID" ]; then
   echo "  No pending tasks found. Run setup.sh first."
@@ -63,9 +63,7 @@ if [ -z "$TASK1_ID" ]; then
 fi
 
 echo "$TASK1" | python3 -m json.tool 2>/dev/null || echo "$TASK1"
-echo ""
-switchman task assign "$TASK1_ID" agent-rate-limiting --agent claude-code
-ok "Task assigned to agent-rate-limiting"
+ok "Task + lease assigned to agent-rate-limiting"
 
 read -r
 
@@ -86,14 +84,12 @@ read -r
 # ── Step 4: Agent 2 picks up a task ──────────────────────────────────────────
 
 step "4. Agent 2 picks up the next task"
-agent "agent-validation" "calling: switchman task next --json"
+agent "agent-validation" "calling: switchman lease next --json"
 echo ""
 
-TASK2=$(switchman task next --json 2>/dev/null || echo "null")
-TASK2_ID=$(echo "$TASK2" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['id'])" 2>/dev/null || echo "")
-
-switchman task assign "$TASK2_ID" agent-validation --agent cursor
-ok "Task assigned to agent-validation"
+TASK2=$(switchman lease next --json --worktree agent-validation --agent claude-code 2>/dev/null || echo "null")
+TASK2_ID=$(echo "$TASK2" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['task']['id'])" 2>/dev/null || echo "")
+ok "Task + lease assigned to agent-validation"
 
 read -r
 
@@ -145,7 +141,7 @@ step "8. Agent 1 finishes — marks task done and releases files"
 agent "agent-rate-limiting" "Rate limiting implemented and committed."
 echo ""
 
-switchman task done "$TASK1_ID" --release-files
+switchman task done "$TASK1_ID"
 ok "Task done. src/middleware/auth.js and src/server.js are now free."
 
 read -r
@@ -161,11 +157,11 @@ echo ""
 echo -e "${GREEN}✓ Walkthrough complete.${RESET}"
 echo ""
 echo "What you saw:"
-echo "  • 2 agents picked up tasks from the shared queue"
+echo "  • 2 agents picked up tasks from the shared queue with real leases"
 echo "  • Agent 2 was blocked from claiming a file already owned by Agent 1"
 echo "  • Agent 2 adapted by claiming different files"
 echo "  • Agent 1 completed and released its claims"
-echo "  • The queue updated in real time throughout"
+echo "  • switchman status and switchman scan stayed readable throughout"
 echo ""
 echo "To reset and run again:"
 echo "  bash examples/teardown.sh && bash examples/setup.sh"

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchman-dev",
-  "version": "0.1.2",
-  "description": "Route your AI agents so they don't collide",
+  "version": "0.1.4",
+  "description": "Project manager for AI coding assistants running safely on one codebase",
   "type": "module",
   "main": "src/index.js",
   "bin": {
@@ -15,7 +15,7 @@
   "scripts": {
     "start": "node src/cli/index.js",
     "mcp": "node src/mcp/server.js",
-    "test": "node tests/test.js"
+    "test": "NODE_NO_WARNINGS=1 node tests/test.js"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",