switchman-dev 0.1.6 → 0.1.7

package/README.md

@@ -2,9 +2,9 @@
 
 **Run 10+ agents on one codebase. Safely.**
 
-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 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, merge gates, and landing workflows so they can move in parallel without stepping on each other.
+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.
 
 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.
 
@@ -20,20 +20,60 @@ Requirements:
 npm install -g @switchman-dev
 ```
 
+## 2 minute proof
+
+If you want the fastest possible “does this actually work?” run:
+
+```bash
+switchman demo
+```
+
+That creates a throwaway repo and shows:
+- one agent claiming `src/auth.js`
+- another agent getting blocked from claiming the same file
+- that second agent rerouting to a safe docs file instead
+- both branches landing back through the queue cleanly
+
+Typical proof output looks like:
+
+```text
+$ switchman demo
+✓ Created Switchman demo repo
+  /tmp/switchman-demo-1234567890
+  proof: agent2 was blocked from src/auth.js
+  safe reroute: agent2 claimed docs/auth-flow.md instead
+  landing: 2 queue item(s) merged safely
+
+Try these next:
+  cd /tmp/switchman-demo-1234567890
+  switchman status
+  switchman queue status
+```
+
+Then inspect it:
+
+```bash
+cd /tmp/switchman-demo-...
+switchman status
+switchman queue status
+```
+
 ## Why Switchman?
 
 Git worktrees, branches, and raw coding agents are useful, but they do not coordinate themselves.
 
 What it adds that plain Git does not:
+- task planning, so incoming goals can be broken into governed parallel work
 - 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
+- queue intelligence, so the clearest work lands first across competing goals
+- governed landing, so finished work reaches `main` one item at a time with retries, checks, and policy enforcement
 
 In short:
 - Git gives you branches
-- Switchman gives you coordination
+- Switchman gives you coordination, governance, and a safe path to land
 
 ## Quickstart
 
@@ -56,11 +96,19 @@ switchman status --watch
 switchman gate ci
 ```
 
+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`
+
 What `switchman setup` gives you:
 - one shared Switchman database in `.switchman/`
 - linked workspaces for each agent
 - local MCP config for Claude Code and Cursor
 
+Current limit:
+- `switchman setup --agents` currently supports up to `10` agent workspaces in one command
+
 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.
@@ -84,6 +132,79 @@ You know the first run is working when:
 
 That is the moment Switchman should feel different from “just using a few branches.”
 
+## Start Here
+
+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 understand blocked or stale work: run `switchman status`
+- want a longer hands-on walkthrough: open [examples/README.md](examples/README.md)
+
+## 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.
+
+In practice, that means it helps teams:
+- break work into parallel tasks
+- assign work across agents and humans
+- stop overlapping edits early
+- detect stale or drifted work before merge chaos
+- route validation and governance follow-ups
+- decide what should land next
+- leave an audit trail of what happened and why
+
+## Real-World Walkthrough
+
+Here is what a real first team workflow can look like across several goals in one shared repo:
+
+1. Product work arrives:
+   - harden auth flows
+   - ship a schema update
+   - refresh related docs
+2. You create parallel work:
+
+```bash
+switchman setup --agents 5
+switchman task add "Harden auth middleware" --priority 9
+switchman task add "Ship schema migration" --priority 8
+switchman task add "Update auth and schema docs" --priority 6
+switchman status --watch
+```
+
+3. Agents pick up work in separate workspaces:
+   - agent1 takes auth
+   - agent2 takes the migration
+   - agent3 takes docs
+4. If two agents reach for the same file, Switchman blocks the second claim early instead of letting the overlap turn into merge cleanup later.
+5. While work is running, `switchman status` shows:
+   - what is active
+   - what is blocked
+   - what has gone stale
+   - what should land next
+6. When branches finish, queue them:
+
+```bash
+switchman queue add agent1
+switchman queue add agent2
+switchman queue add agent3
+switchman queue status
+switchman queue run --follow-plan --merge-budget 2
+```
+
+7. If a shared change invalidates another task, Switchman marks it stale and points at the exact recovery command instead of leaving the team to guess.
+8. Before merge, run the repo gate:
+
+```bash
+switchman gate ci
+```
+
+What good looks like:
+- each agent stayed in its own lane
+- overlap was blocked before wasted work spread
+- stale work was visible instead of silently wrong
+- the queue made it obvious what should land now and what should wait
+- the repo reached `main` through a governed path instead of manual merge babysitting
+
 ## Why not just use branches or worktrees?
 
 Because branches and worktrees solve isolation, not coordination.
@@ -133,6 +254,52 @@ More help:
 - [Stale lease policy](docs/stale-lease-policy.md)
 - [Telemetry](docs/telemetry.md)
 
+The most useful explain commands when something is unclear:
+
+```bash
+switchman explain claim src/auth/login.js
+switchman explain queue <item-id>
+switchman explain stale --pipeline <pipeline-id>
+switchman explain landing <pipeline-id>
+```
+
+## Turn On PR Checks
+
+If you want GitHub to block risky changes the same way your local terminal does:
+
+```bash
+switchman gate install-ci
+```
+
+That installs `.github/workflows/switchman-gate.yml`, which:
+- runs `switchman gate ci --github` on pushes and pull requests
+- auto-runs `switchman pipeline sync-pr --pipeline-from-env --skip-missing-pipeline --pr-from-env --github` on pull request updates
+- publishes a readable Switchman summary into the GitHub job output
+- fails the PR check when Switchman detects unmanaged changes, stale work, or risky overlap
+
+For pipeline-specific landing state in GitHub job summaries or PR checks, use:
+
+```bash
+switchman pipeline bundle pipe-123 --github
+```
+
+If you want one command that bundles artifacts, updates the PR comment, and emits GitHub outputs together:
+
+```bash
+switchman pipeline sync-pr pipe-123 --pr-from-env --github
+```
+
+## Add Change Policy
+
+If you want Switchman to enforce extra review or validation for high-risk areas like auth, schema, or payments:
+
+```bash
+switchman policy init-change
+switchman policy show-change
+```
+
+That writes `.switchman/change-policy.json`, which planning and follow-up generation use to require the right tests, docs, and governance work before landing.
+
 ## More docs
 
 - [Merge queue](docs/merge-queue.md)

package/examples/README.md

@@ -2,6 +2,12 @@
 
 A real Express REST API used to test Switchman locally.
 
+This folder is the best place to go after `switchman demo` if you want to feel the fuller workflow:
+- multiple agents
+- one real repo
+- an intentional claim conflict
+- clean landing back through the queue
+
 ## What's in here
 
 ```
@@ -27,6 +33,18 @@ examples/
 
 This is the fastest way to understand Switchman as a new user.
 
+If you just want the shortest proof run, start with:
+
+```bash
+switchman demo
+```
+
+Use the `examples/` scripts when you want a longer walkthrough you can customize or record.
+
+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:
 ```bash
 npm install -g .   # from the switchman repo root
@@ -44,6 +62,14 @@ If you want the shortest path:
 - `demo.sh` is the 45-90 second recordable version
 - `walkthrough.sh` shows one complete 3-agent happy path, including a real claim conflict
 
+If you only want one script after setup, use:
+
+```bash
+bash examples/walkthrough.sh
+```
+
+That is the clearest “real workflow” version of Switchman in this repo.
+
 ## Recordable demo
 
 If you want the short “wow” version for recording or showing the product quickly:
@@ -81,6 +107,8 @@ At the end of the walkthrough, you want to see:
 - `switchman scan` showing no unclaimed changes
 - `switchman status` giving a clean overview of what happened
 
+If that all happens without confusion, the onboarding is doing its job.
+
 ## The taskapi project
 
 A minimal but real Express API with:

package/package.json

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