switchman-dev 0.1.7 → 0.1.8

package/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repo
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: '22'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm install
+
+      - name: Run test suite
+        run: npm test

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+All notable changes to Switchman will be documented in this file.
+
+The format is based on Keep a Changelog, adapted for the project’s current stage.
+
+## [Unreleased]
+
+## [0.1.7] - 2026-03-13
+
+### Added
+- plan-aware merge queue execution with merge budgets
+- clearer first-run guidance in `switchman setup`, `switchman demo`, and `switchman status`
+- richer queue planning, stale-wave handling, policy evidence, and governed landing documentation
+- CI workflow for running the test suite on pushes and pull requests
+
+### Changed
+- `switchman status` now leads with a simpler summary, top attention item, and one exact next command
+- `switchman queue status` no longer crashes on an empty queue summary shape
+- `switchman setup` now re-registers existing worktrees cleanly without leaking raw git branch-exists noise
+- CLI output now suppresses the noisy Node SQLite experimental warning on normal happy-path runs
+
+### Fixed
+- broken install docs that pointed at the org name instead of the package name
+- queue status regression found in manual smoke testing before publish
+
+## [0.1.6] - 2026-03-12
+
+### Added
+- stronger governed landing flows, recovery loops, and PR/CI handoff
+- policy-aware planning, policy evidence, and landing enforcement
+- stale cluster grouping, stale-wave reasoning, and richer operator explainability
+- synthetic landing branches, refresh, recover, resume, and cleanup
+
+### Changed
+- the core product moved from basic coordination toward governed parallel delivery

package/CLAUDE.md

@@ -0,0 +1,113 @@
+# Switchman Agent Instructions
+
+This repository uses **Switchman** to coordinate parallel AI coding agents.
+You MUST follow these instructions every session to avoid conflicting with other agents.
+
+You must use the Switchman MCP tools for coordination. Do not read from or write to `.switchman/switchman.db` directly, and do not bypass Switchman by issuing raw SQLite queries.
+
+---
+
+## Your worktree
+
+Find your worktree name by running:
+```bash
+git worktree list
+```
+The path that matches your current directory is your worktree. Use the last path segment as your worktree name (e.g. `/projects/myapp-feature-auth` → `feature-auth`). The main repo root is always named `main`.
+
+---
+
+## Required workflow — follow this every session
+
+### 1. Start of session — get your task
+
+Call the `switchman_task_next` MCP tool with your worktree name:
+```
+switchman_task_next({ worktree: "<your-worktree-name>", agent: "claude-code" })
+```
+
+- If `task` is `null` — the queue is empty. Ask the user what to work on, or stop.
+- If you receive a task — note the `task.id`. You'll need it in the next steps.
+- If the `switchman_*` tools are unavailable, stop and tell the user the MCP server is not connected. Do not fall back to direct SQLite access.
+
+### 2. Before editing any files — claim them
+
+Call `switchman_task_claim` with every file you plan to edit **before you edit them**:
+```
+switchman_task_claim({
+  task_id: "<task-id>",
+  worktree: "<your-worktree-name>",
+  files: ["src/auth/login.js", "tests/auth.test.js"]
+})
+```
+
+- If `safe_to_proceed` is `false` — there are conflicts. Do NOT edit those files.
+  Read the `conflicts` array to see which worktrees own them, then either:
+  - Choose different files that accomplish the same goal
+  - Ask the user how to proceed
+
+- If `safe_to_proceed` is `true` — you are clear to edit.
+
+### 3. Do the work
+
+Implement the task. Make commits as normal. Other agents will avoid your claimed files.
+
+If you discover mid-task that you need to edit additional files, call `switchman_task_claim` again for those files before editing them.
+
+When MCP write tools are available, prefer the Switchman enforcement gateway over native file writes:
+```text
+switchman_write_file(...)
+switchman_append_file(...)
+switchman_make_directory(...)
+switchman_move_path(...)
+switchman_remove_path(...)
+```
+
+These tools validate your active lease and claimed paths before changing the filesystem. Use native file writes only when the Switchman write tools are unavailable and you have already claimed the path.
+
+### 4. End of session — mark complete or failed
+
+**On success:**
+```
+switchman_task_done({ task_id: "<task-id>" })
+```
+
+**On failure (can't complete the task):**
+```
+switchman_task_fail({ task_id: "<task-id>", reason: "Brief explanation of what blocked you" })
+```
+
+Always call one of these before ending your session. Released file claims allow other agents to proceed.
+
+---
+
+## Checking for conflicts
+
+At any time you can scan for conflicts across all worktrees:
+```
+switchman_scan()
+```
+
+Run this before merging your branch. If `safe_to_proceed` is `false`, do not merge until conflicts are resolved.
+
+---
+
+## Checking system state
+
+To see what other agents are doing:
+```
+switchman_status()
+```
+
+This shows all pending and in-progress tasks, file claims per worktree, and worktree list.
+
+---
+
+## Rules
+
+1. **Always claim files before editing them** — not after.
+2. **Always call `switchman_task_done` or `switchman_task_fail` at end of session** — never leave tasks as `in_progress` when you stop.
+3. **If `safe_to_proceed` is false, do not edit the conflicting files** — coordinate first.
+4. **Do not claim files you don't need** — over-claiming blocks other agents unnecessarily.
+5. **One task per session** — complete or fail your current task before taking another.
+6. **Never query or mutate the Switchman SQLite database directly** — use MCP tools only.

package/README.md

@@ -2,6 +2,9 @@
 
 **Run 10+ agents on one codebase. Safely.**
 
+[![CI](https://github.com/switchman-dev/switchman/actions/workflows/ci.yml/badge.svg)](https://github.com/switchman-dev/switchman/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/switchman-dev.svg)](https://www.npmjs.com/package/switchman-dev)
+
 Switchman is the coordination and governance layer for AI-native software teams. It helps you plan work, route tasks across agents, prevent overlap, and land changes safely instead of stitching parallel output back together by hand.
 
 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, policy gates, queue planning, and governed landing workflows so they can move in parallel without stepping on each other.
@@ -16,8 +19,16 @@ Requirements:
 - Node.js 22.5+
 - Git 2.5+
 
+Why Node 22.5+?
+- Switchman uses the built-in `node:sqlite` runtime support for its repo-local coordination database.
+- Keeping that dependency in the Node runtime makes install and recovery simpler, but it currently means targeting newer Node releases on purpose.
+
+TypeScript and API surface
+- Switchman is CLI-first today. The supported interface is the `switchman` command and the MCP integration, not a stable embeddable library API yet.
+- That means there are no published TypeScript types right now by design. We plan to add typed surfaces once the programmatic API is stable enough to support cleanly.
+
 ```bash
-npm install -g @switchman-dev
+npm install -g switchman-dev
 ```
 
 ## 2 minute proof
@@ -84,22 +95,20 @@ Recommended first run:
 
 ```bash
 cd my-project
-switchman setup --agents 5
-switchman verify-setup
-
+switchman demo
+switchman setup --agents 3
 switchman task add "Implement auth helper" --priority 9
-switchman task add "Add auth tests" --priority 8
-switchman task add "Update auth docs" --priority 7
-
-switchman status
 switchman status --watch
 switchman gate ci
+switchman queue run
 ```
 
-If you only do three things on the first run, do these:
-1. `switchman setup --agents 5`
-2. `switchman task add "Implement auth helper" --priority 9`
-3. `switchman status --watch`
+If you only do five things on the first run, do these:
+1. `switchman demo`
+2. `switchman setup --agents 3`
+3. `switchman task add "Implement auth helper" --priority 9`
+4. `switchman status --watch`
+5. `switchman gate ci && switchman queue run`
 
 What `switchman setup` gives you:
 - one shared Switchman database in `.switchman/`
@@ -113,14 +122,18 @@ Fastest path to success:
 1. Use Claude Code for the first run.
 2. Run `switchman verify-setup` once so editor wiring is confirmed before you start.
 3. Open one Claude Code window per generated workspace.
-4. Let each agent pick up one clearly separate task.
-5. Keep `switchman status --watch` open in another terminal.
-6. Run `switchman gate ci` when the tasks finish.
+4. Add clear tasks before the agents start.
+5. Let each agent pick up one clearly separate task.
+6. Keep `switchman status --watch` open in another terminal.
+7. Run `switchman gate ci`, then `switchman queue run`, when the tasks finish.
 
 If you want the recommended editor setup guide, start here:
 - [Claude Code setup](docs/setup-claude-code.md)
 
 If you want a guided demo, see [examples/README.md](examples/README.md).
+If you want the deeper multi-task planning and PR workflow, see [docs/pipelines.md](docs/pipelines.md).
+
+> Free tier supports up to 3 agents. Run `switchman upgrade` for unlimited.
 
 ## What good looks like
 
@@ -136,10 +149,21 @@ That is the moment Switchman should feel different from “just using a few bran
 
 If you are trying to decide where to start:
 - want the fastest proof: run `switchman demo`
-- want to wire up a real repo: run `switchman setup --agents 5`
+- want to wire up a real repo: run `switchman setup --agents 3`
+- want to add real work: run `switchman task add "Your task" --priority 8`
 - want to understand blocked or stale work: run `switchman status`
 - want a longer hands-on walkthrough: open [examples/README.md](examples/README.md)
 
+## Enforcement Gateway
+
+Switchman is strongest when agents write through the governed gateway instead of editing files directly.
+
+- MCP agents should prefer `switchman_write_file`, `switchman_append_file`, `switchman_make_directory`, `switchman_move_path`, and `switchman_remove_path`
+- CLI operators can use `switchman write` and `switchman wrap` for governed writes and wrapped commands
+- `switchman monitor` is started automatically by `switchman setup` unless you opt out, so rogue edits are detected in the background
+
+That closes the gap between "please follow the claiming protocol" and "Switchman can actually catch ungoverned writes when something goes wrong."
+
 ## The Workflow
 
 Switchman is built for the workflow of turning multiple competing engineering goals into coordinated parallel execution and a trusted, dependency-aware path to merge.
@@ -217,6 +241,96 @@ They do not tell you:
 
 Switchman is for the point where “we can manage this by hand” stops being true.
 
+## Safety note on `--force`
+
+`switchman claim --force` exists for manual recovery, not normal operation.
+
+Legitimate use:
+- you have already confirmed the conflicting claim is stale, abandoned, or otherwise incorrect
+- you are performing operator-led cleanup and need to unblock the repo deliberately
+
+Not a legitimate use:
+- "the other agent is probably done"
+- "I just want to keep moving"
+- "we'll clean it up in the PR later"
+
+Normal path:
+1. run `switchman status`
+2. run `switchman explain claim <path>`
+3. reap or retry the stale work if needed
+4. only then use `--force` if you intentionally want to override a known-bad claim
+
+If that feels too risky, that is the point. It is meant to be an escape hatch, not a convenience flag.
+
+## Releases and changelog
+
+If you want to track what changed between versions:
+- [CHANGELOG.md](CHANGELOG.md)
+- [GitHub releases](https://github.com/switchman-dev/switchman/releases)
+
+## What's included today
+
+Today Switchman already includes:
+- agent worktree setup and repo verification
+- lease, claim, heartbeat, and stale-reap coordination
+- governed write gateways and a rogue-edit monitor
+- repo status, repair, queue planning, and safe landing
+- pipeline planning, execution, PR bundles, and GitHub sync
+- audit trail, change policy enforcement, and CI integration
+- MCP support for Claude Code, Cursor, and Windsurf
+
+## Switchman Pro
+
+Pro gives you unlimited agents, cloud-synced team coordination, and 90-day history.
+
+```bash
+switchman upgrade       # open switchman.dev/pro in your browser
+switchman login         # activate Pro after subscribing
+switchman login --status  # check your current plan
+```
+
+**What's included in Pro:**
+- Unlimited concurrent agents (free tier: up to 3)
+- Cloud-synced task queues and lease state across your team
+- Team invites — `switchman team invite alice@example.com`
+- AI task planning — `switchman plan "Add authentication"` proposes parallel tasks from an explicit goal
+- 90-day audit trail (free tier: 7 days)
+- Email support within 48 hours
+
+**Pricing:** $25/month or $250/year per seat · [switchman.dev/pro](https://switchman.dev/pro)
+
+After subscribing, activate in your terminal:
+```bash
+switchman login
+# Opens GitHub sign-in, saves credentials locally
+# Credentials cached 24h · works offline for 7 days
+
+switchman setup --agents 10
+# Pro removes the 3-agent limit
+```
+
+### Pro planning launch order
+
+Switchman Pro planning ships in this order:
+- `switchman plan "goal"` first
+- `switchman plan --issue 47` next
+- zero-argument `switchman plan` later, once real usage data makes that inference trustworthy
+
+Today, the supported Pro planning flow is:
+
+```bash
+switchman plan "Add authentication"
+switchman plan "Add authentication" --apply
+```
+
+## What's next
+
+The next product steps are:
+- `switchman plan --issue 47`
+- a more magical zero-argument planning flow that can read richer repo and issue context
+- a web dashboard for repo and landing visibility
+- a Homebrew install path for faster first-run setup
+
 ## Choose your setup
 
 Pick the guide that matches how you work:

package/examples/README.md

@@ -45,12 +45,19 @@ Good rule of thumb:
 - want the 2-minute proof: `switchman demo`
 - want the 5-10 minute “how would a team actually use this?” version: use `examples/`
 
-Make sure Switchman is installed globally first:
+Make sure Switchman is installed globally first.
+
+If you cloned the Switchman repo:
 ```bash
 npm install -g .   # from the switchman repo root
 ```
 
-Then from the switchman repo root:
+If you installed from npm instead:
+```bash
+cd "$(npm root -g)/switchman-dev"
+```
+
+Then from the Switchman package root:
 ```bash
 bash examples/setup.sh
 bash examples/demo.sh

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchman-dev",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Project manager for AI coding assistants running safely on one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -17,11 +17,16 @@
     "mcp": "node src/mcp/server.js",
     "test": "NODE_NO_WARNINGS=1 node tests/test.js"
   },
+  "engines": {
+    "node": ">=22.5.0"
+  },
   "dependencies": {
+    "@anthropic-ai/sdk": "^0.78.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "chalk": "^5.3.0",
     "commander": "^12.0.0",
     "node-sqlite3-wasm": "^0.8.35",
+    "open": "^11.0.0",
     "ora": "^8.0.1",
     "zod": "^4.3.6"
   },