switchman-dev 0.1.4 → 0.1.6

package/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}

package/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}

package/README.md

@@ -38,13 +38,14 @@ In short:
 ## Quickstart
 
 Recommended first run:
-- editor: Cursor
+- editor: Claude Code
 - 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 5
+switchman verify-setup
 
 switchman task add "Implement auth helper" --priority 9
 switchman task add "Add auth tests" --priority 8
@@ -61,14 +62,15 @@ What `switchman setup` gives you:
 - local MCP config for Claude Code and Cursor
 
 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.
+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.
 
 If you want the recommended editor setup guide, start here:
-- [Cursor setup](docs/setup-cursor.md)
+- [Claude Code setup](docs/setup-claude-code.md)
 
 If you want a guided demo, see [examples/README.md](examples/README.md).
 
@@ -129,6 +131,7 @@ More help:
 - [Status and recovery](docs/status-and-recovery.md)
 - [Merge queue](docs/merge-queue.md)
 - [Stale lease policy](docs/stale-lease-policy.md)
+- [Telemetry](docs/telemetry.md)
 
 ## More docs
 
@@ -136,6 +139,7 @@ More help:
 - [Pipelines and PRs](docs/pipelines.md)
 - [Stale lease policy](docs/stale-lease-policy.md)
 - [MCP tools](docs/mcp-tools.md)
+- [Telemetry](docs/telemetry.md)
 - [Command reference](docs/command-reference.md)
 
 ## Feedback

package/examples/README.md

@@ -35,13 +35,31 @@ npm install -g .   # from the switchman repo root
 Then from the switchman repo root:
 ```bash
 bash examples/setup.sh
+bash examples/demo.sh
 bash examples/walkthrough.sh
 ```
 
 If you want the shortest path:
 - `setup.sh` creates the repo, worktrees, and seed tasks
+- `demo.sh` is the 45-90 second recordable version
 - `walkthrough.sh` shows one complete 3-agent happy path, including a real claim conflict
 
+## Recordable demo
+
+If you want the short “wow” version for recording or showing the product quickly:
+
+```bash
+bash examples/setup.sh
+bash examples/demo.sh
+```
+
+What it shows:
+- a clean repo dashboard
+- one agent locking files safely
+- another agent getting blocked from overlapping work
+- both branches landing through the queue
+- a clean `switchman gate ci` at the end
+
 ## What the walkthrough shows
 
 1. **3 worktrees created** — simulating 3 parallel Claude Code instances each on their own branch

package/examples/demo.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# examples/demo.sh
+#
+# Short, recordable Switchman demo for terminal capture.
+# Run AFTER setup.sh:
+#   bash examples/demo.sh
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+TASKAPI_DIR="$SCRIPT_DIR/taskapi"
+WT_RATE="$SCRIPT_DIR/worktrees/agent-rate-limiting"
+WT_VALID="$SCRIPT_DIR/worktrees/agent-validation"
+
+if [ -f "$REPO_ROOT/src/cli/index.js" ]; then
+  SWITCHMAN=(node "$REPO_ROOT/src/cli/index.js")
+else
+  SWITCHMAN=(switchman)
+fi
+
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BOLD='\033[1m'
+RESET='\033[0m'
+
+step() { echo ""; echo -e "${BOLD}── $1 ──────────────────────────────────────${RESET}"; }
+info() { echo -e "${YELLOW}→${RESET} $1"; }
+ok() { echo -e "${GREEN}✓${RESET} $1"; }
+
+json_field() {
+  local payload="$1"
+  local expression="$2"
+  node -e "const data = JSON.parse(process.argv[1]); console.log(${expression});" "$payload"
+}
+
+ensure_setup() {
+  if [ ! -d "$TASKAPI_DIR/.switchman" ]; then
+    echo "Switchman example is not set up yet."
+    echo "Run: bash examples/setup.sh"
+    exit 1
+  fi
+}
+
+append_demo_change() {
+  local file_path="$1"
+  local message="$2"
+  printf "\n// %s\n" "$message" >> "$file_path"
+}
+
+git_commit_files() {
+  local repo_dir="$1"
+  local message="$2"
+  shift 2
+  if [ "$#" -gt 0 ]; then
+    git -C "$repo_dir" add "$@"
+    git -C "$repo_dir" commit -m "$message" -q
+  fi
+}
+
+ensure_setup
+cd "$TASKAPI_DIR"
+
+MAIN_BRANCH="$(git branch --show-current)"
+
+echo ""
+echo -e "${BOLD}━━━ Switchman Demo ━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"
+echo ""
+echo "This is the short version: two agents, one blocked overlap, safe landing, clean gate."
+
+step "1. Repo dashboard"
+"${SWITCHMAN[@]}" status
+
+step "2. Agent 1 starts work and locks files"
+TASK1="$("${SWITCHMAN[@]}" lease next --json --worktree agent-rate-limiting --agent cursor)"
+TASK1_ID="$(json_field "$TASK1" "data.task.id")"
+"${SWITCHMAN[@]}" claim "$TASK1_ID" agent-rate-limiting src/middleware/auth.js src/server.js
+append_demo_change "$WT_RATE/src/middleware/auth.js" "demo: rate-limiting agent touched auth middleware"
+append_demo_change "$WT_RATE/src/server.js" "demo: rate-limiting agent touched server"
+git_commit_files "$WT_RATE" "Demo: rate-limiting change" src/middleware/auth.js src/server.js
+ok "Agent 1 has its own files and a committed branch"
+
+step "3. Agent 2 tries to overlap and gets blocked"
+TASK2="$("${SWITCHMAN[@]}" lease next --json --worktree agent-validation --agent cursor)"
+TASK2_ID="$(json_field "$TASK2" "data.task.id")"
+"${SWITCHMAN[@]}" claim "$TASK2_ID" agent-validation src/middleware/auth.js src/middleware/validate.js src/routes/tasks.js || true
+info "Switchman blocks the overlapping claim before merge-time pain."
+
+step "4. Agent 2 switches to safe files"
+"${SWITCHMAN[@]}" claim "$TASK2_ID" agent-validation src/middleware/validate.js src/routes/tasks.js
+append_demo_change "$WT_VALID/src/middleware/validate.js" "demo: validation agent touched validation middleware"
+append_demo_change "$WT_VALID/src/routes/tasks.js" "demo: validation agent touched tasks route"
+git_commit_files "$WT_VALID" "Demo: validation change" src/middleware/validate.js src/routes/tasks.js
+ok "Agent 2 adapts instead of colliding"
+
+step "5. Finish work and watch the repo stay readable"
+"${SWITCHMAN[@]}" task done "$TASK1_ID"
+"${SWITCHMAN[@]}" task done "$TASK2_ID"
+"${SWITCHMAN[@]}" status --watch --max-cycles 1
+
+step "6. Queue both finished branches for safe landing"
+"${SWITCHMAN[@]}" queue add --worktree agent-rate-limiting --target "$MAIN_BRANCH"
+"${SWITCHMAN[@]}" queue add --worktree agent-validation --target "$MAIN_BRANCH"
+"${SWITCHMAN[@]}" queue status
+
+step "7. Land the work safely"
+"${SWITCHMAN[@]}" queue run --max-items 2 --target "$MAIN_BRANCH"
+
+step "8. Final safety check"
+"${SWITCHMAN[@]}" gate ci
+
+echo ""
+echo -e "${GREEN}✓ Demo complete.${RESET}"
+echo ""
+echo "What just happened:"
+echo "  • agents took different tasks"
+echo "  • Switchman blocked an overlapping file claim early"
+echo "  • finished branches landed through the queue"
+echo "  • the repo safety gate passed"
+echo ""
+echo "Reset and run again:"
+echo "  bash examples/teardown.sh && bash examples/setup.sh"
+echo ""

package/examples/setup.sh

@@ -15,9 +15,16 @@
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 TASKAPI_DIR="$SCRIPT_DIR/taskapi"
 WORKTREES_DIR="$SCRIPT_DIR/worktrees"
 
+if [ -f "$REPO_ROOT/src/cli/index.js" ]; then
+  SWITCHMAN=(node "$REPO_ROOT/src/cli/index.js")
+else
+  SWITCHMAN=(switchman)
+fi
+
 echo ""
 echo "━━━ Switchman Example Setup ━━━━━━━━━━━━━━━━━━"
 echo ""
@@ -68,26 +75,26 @@ git worktree list
 
 echo ""
 echo "→ Initialising Switchman in taskapi..."
-switchman init
+"${SWITCHMAN[@]}" init
 
 # ── Step 4: Seed tasks ────────────────────────────────────────────────────────
 
 echo ""
 echo "→ Seeding 4 parallel tasks..."
 
-switchman task add "Add rate limiting to all API routes" \
+"${SWITCHMAN[@]}" task add "Add rate limiting to all API routes" \
   --priority 8 \
   --description "Token bucket: 100 req/min per API key. Return 429 with Retry-After header."
 
-switchman task add "Add input validation to POST /tasks and PATCH /tasks/:id" \
+"${SWITCHMAN[@]}" task add "Add input validation to POST /tasks and PATCH /tasks/:id" \
   --priority 7 \
   --description "Validate title length, status enum, priority enum. Return 400 with descriptive errors."
 
-switchman task add "Write tests for the auth middleware" \
+"${SWITCHMAN[@]}" task add "Write tests for the auth middleware" \
   --priority 6 \
   --description "Test requireAuth and requireAdmin: valid key, missing key, bad key, wrong role."
 
-switchman task add "Add pagination to GET /tasks" \
+"${SWITCHMAN[@]}" task add "Add pagination to GET /tasks" \
   --priority 5 \
   --description "Add ?page=1&limit=20. Return { tasks, count, page, totalPages }."
 
@@ -96,7 +103,7 @@ echo "━━━━━━━━━━━━━━━━━━━━━━━━
 echo "✓ Setup complete."
 echo ""
 echo "Tasks ready:"
-switchman task list
+"${SWITCHMAN[@]}" task list
 echo ""
 echo "→ Next: bash examples/walkthrough.sh"
 echo ""

package/examples/taskapi/.cursor/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}

package/examples/taskapi/.mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "switchman": {
+      "command": "switchman-mcp",
+      "args": []
+    }
+  }
+}

package/examples/taskapi/src/middleware/auth.js

@@ -94,3 +94,7 @@ function optionalAuth(req, res, next) {
 }
 
 module.exports = { requireAuth, requireRole, optionalAuth };
+
+// demo: rate-limiting agent touched auth middleware
+
+// demo: rate-limiting agent touched auth middleware

package/examples/taskapi/src/middleware/validate.js

@@ -131,3 +131,7 @@ module.exports = {
   // Export primitives so routes can build ad-hoc schemas
   validators: { required, isString, isNumber, isEmail, oneOf, maxLength, minLength, compose },
 };
+
+// demo: validation agent touched validation middleware
+
+// demo: validation agent touched validation middleware

package/examples/taskapi/src/routes/tasks.js

@@ -63,3 +63,7 @@ router.delete('/:id', (req, res) => {
 });
 
 module.exports = router;
+
+// demo: validation agent touched tasks route
+
+// demo: validation agent touched tasks route

package/examples/taskapi/src/server.js

@@ -5,3 +5,7 @@ const PORT = process.env.PORT || 3000;
 app.listen(PORT, () => {
   console.log(`TaskAPI running on port ${PORT}`);
 });
+
+// demo: rate-limiting agent touched server
+
+// demo: rate-limiting agent touched server

package/examples/walkthrough.sh

@@ -10,11 +10,18 @@
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 TASKAPI_DIR="$SCRIPT_DIR/taskapi"
 WT_RATE="$SCRIPT_DIR/worktrees/agent-rate-limiting"
 WT_VALID="$SCRIPT_DIR/worktrees/agent-validation"
 WT_TESTS="$SCRIPT_DIR/worktrees/agent-tests"
 
+if [ -f "$REPO_ROOT/src/cli/index.js" ]; then
+  SWITCHMAN=(node "$REPO_ROOT/src/cli/index.js")
+else
+  SWITCHMAN=(switchman)
+fi
+
 # Colours
 CYAN='\033[0;36m'
 GREEN='\033[0;32m'
@@ -44,7 +51,7 @@ read -r
 step "1. Starting state"
 info "4 tasks waiting in the queue, 3 worktrees ready"
 echo ""
-switchman status
+"${SWITCHMAN[@]}" status
 
 read -r
 
@@ -54,7 +61,7 @@ step "2. Agent 1 picks up the highest-priority task"
 agent "agent-rate-limiting" "calling: switchman lease next --json"
 echo ""
 
-TASK1=$(switchman lease next --json --worktree agent-rate-limiting --agent claude-code 2>/dev/null || echo "null")
+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
@@ -73,7 +80,7 @@ step "3. Agent 1 claims the files it needs"
 agent "agent-rate-limiting" "I'll be editing the middleware and server files"
 echo ""
 
-switchman claim "$TASK1_ID" agent-rate-limiting \
+"${SWITCHMAN[@]}" claim "$TASK1_ID" agent-rate-limiting \
   src/middleware/auth.js \
   src/server.js
 
@@ -87,7 +94,7 @@ step "4. Agent 2 picks up the next task"
 agent "agent-validation" "calling: switchman lease next --json"
 echo ""
 
-TASK2=$(switchman lease next --json --worktree agent-validation --agent claude-code 2>/dev/null || echo "null")
+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"
 
@@ -100,7 +107,7 @@ agent "agent-validation" "Input validation also touches auth.js..."
 echo ""
 
 # This should warn about the conflict
-switchman claim "$TASK2_ID" agent-validation \
+"${SWITCHMAN[@]}" claim "$TASK2_ID" agent-validation \
   src/middleware/auth.js \
   src/middleware/validate.js \
   src/routes/tasks.js || true
@@ -117,7 +124,7 @@ step "6. Agent 2 claims only the files that aren't taken"
 agent "agent-validation" "Claiming only validate.js and routes/tasks.js instead"
 echo ""
 
-switchman claim "$TASK2_ID" agent-validation \
+"${SWITCHMAN[@]}" claim "$TASK2_ID" agent-validation \
   src/middleware/validate.js \
   src/routes/tasks.js
 
@@ -131,7 +138,7 @@ step "7. Full conflict scan across all worktrees"
 info "This is what you'd run before any merge"
 echo ""
 
-switchman scan
+"${SWITCHMAN[@]}" scan
 
 read -r
 
@@ -141,7 +148,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"
+"${SWITCHMAN[@]}" task done "$TASK1_ID"
 ok "Task done. src/middleware/auth.js and src/server.js are now free."
 
 read -r
@@ -149,7 +156,7 @@ read -r
 # ── Step 9: Final status ──────────────────────────────────────────────────────
 
 step "9. Final status"
-switchman status
+"${SWITCHMAN[@]}" status
 
 echo ""
 echo -e "${BOLD}━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━${RESET}"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "switchman-dev",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Project manager for AI coding assistants running safely on one codebase",
   "type": "module",
   "main": "src/index.js",