claude-multi-session 1.0.0 → 2.2.0

package/README.md

@@ -540,6 +540,459 @@ See `STRATEGY.md` for the complete guide on:
 - **Claude Code CLI** installed and authenticated
 - Zero npm dependencies
 
+---
+
+## Team Hub v2 — Multi-Session Collaboration
+
+**Team Hub v2** transforms isolated Claude sessions into **self-organizing teams** that exchange structured data, auto-resolve dependencies, and heal themselves when things break. Instead of talking in natural language (which degrades over time), sessions coordinate through **versioned artifacts** and **formal contracts**.
+
+This is the only multi-agent system for Claude Code that uses **transactional coordination** instead of conversational coordination.
+
+### The Three-Layer Architecture
+
+**Layer 1: Chat** — Sessions message each other directly (like Slack)
+- Send DMs, broadcasts, and blocking ask/reply questions
+- Check inbox before starting work, after major steps
+- Rate-limited and loop-protected to prevent message storms
+
+**Layer 2: Artifacts & Contracts** — Sessions exchange structured, versioned data (like Git + Jira)
+- **Artifacts:** Immutable, versioned outputs with JSON schema validation
+- **Contracts:** Formal task assignments with auto-resolving dependencies
+- **Peer-to-peer:** ANY session can create contracts for ANY other session (not just the orchestrator)
+
+**Layer 3: Reactive Intelligence** — The system monitors itself and auto-heals (like a self-driving car)
+- **Lineage Graph:** Track data provenance, detect stale artifacts, analyze impact radius
+- **Reactive Pipelines:** Event-driven trigger→action rules (e.g., "when tests fail, reopen the API contract")
+- **Snapshot & Replay:** Capture full state, rollback, replay workflows with different parameters
+
+### Quick Start
+
+```bash
+# Spawn 3 team members
+cms team-spawn --name db-dev --role database --prompt "Create User model"
+cms team-spawn --name api-dev --role backend --prompt "Build auth API"
+cms team-spawn --name qa-dev --role QA --prompt "Write auth tests"
+
+# Create a contract chain (Layer 2)
+cms contract-create setup-user-model --assignee db-dev \
+  --title "Create User schema" \
+  --expected-output schema-change
+
+cms contract-create build-auth-api --assignee api-dev \
+  --title "Build auth endpoints" \
+  --depends-on setup-user-model \
+  --expected-output api-contract
+
+cms contract-create write-auth-tests --assignee qa-dev \
+  --title "Write integration tests" \
+  --depends-on build-auth-api \
+  --expected-output test-results
+
+# Watch the contracts auto-resolve as artifacts are published
+cms contract-list
+
+# DB session publishes schema
+cms artifact-publish schema-user-model --type schema-change \
+  --name "User model schema" \
+  --data '{"models":[{"name":"User","fields":["email","phone","password"]}]}'
+# → setup-user-model auto-completes → build-auth-api becomes "ready"
+
+# API session publishes contract (derived from schema)
+cms artifact-publish api-contract-user-auth --type api-contract \
+  --name "Auth API contract" \
+  --derived-from schema-user-model@v1 \
+  --data '{"endpoints":[{"method":"POST","path":"/login"}]}'
+# → build-auth-api auto-completes → write-auth-tests becomes "ready"
+
+# QA session publishes test results (derived from API contract)
+cms artifact-publish test-results-auth --type test-results \
+  --name "Auth integration tests" \
+  --derived-from api-contract-user-auth@v1 \
+  --data '{"total":12,"passed":12,"failed":0}'
+# → write-auth-tests auto-completes → entire chain done
+
+# Query the lineage graph (Layer 3)
+cms artifact-lineage test-results-auth --direction upstream
+# Shows: test-results → api-contract → schema
+
+# Take a snapshot before trying a different approach
+cms team-snapshot pre-graphql --label "Auth feature complete with REST"
+
+# Replay with overrides to try GraphQL instead
+cms team-replay pre-graphql --overrides '{"build-auth-api":{"inputs":{"context":"Use GraphQL instead of REST"}}}'
+# → Entire workflow re-executes with GraphQL approach
+```
+
+---
+
+## Layer 1: Chat (8 MCP Tools)
+
+Sessions can communicate directly without routing through the orchestrator.
+
+| Tool | Description |
+|------|-------------|
+| `team_spawn` | Spawn a session with team system prompt injected (includes roster, artifact/contract tools) |
+| `team_send_message` | Send a DM to a specific teammate |
+| `team_broadcast` | Send a message to all team members |
+| `team_check_inbox` | Check unread messages (do this before starting work and after major steps) |
+| `team_ask` | Ask a question and WAIT for reply (blocking poll) |
+| `team_reply` | Reply to a question received in inbox |
+| `team_roster` | View all team members with roles, status, and lastSeen times |
+| `team_update_status` | Update your own status, task, or role |
+
+**Safety features:**
+- Rate limit: 10 messages/minute per session
+- Loop detection: >5 exchanges between same pair in 60s = blocked
+- Auto-compaction: Inbox files auto-compact when they exceed 1000 lines
+
+**When to use chat vs artifacts:**
+- Use **chat** for quick questions, coordination, status updates
+- Use **artifacts** for actual work outputs (schemas, API contracts, test results)
+- Use **contracts** to assign work and track progress
+
+---
+
+## Layer 2: Artifacts & Contracts (12 MCP Tools)
+
+### Versioned Artifacts (6 Tools)
+
+Artifacts are **immutable, versioned outputs** with JSON schema validation for well-known types.
+
+| Tool | Description |
+|------|-------------|
+| `artifact_publish` | Publish structured data (creates new version, validates schema, records lineage, triggers resolution + pipelines) |
+| `artifact_get` | Read an artifact (latest or specific version) |
+| `artifact_list` | List all artifacts with optional filters (type, publisher, tag) |
+| `artifact_history` | View all versions of an artifact |
+
+**Well-known artifact types** (validated against JSON schemas):
+
+| Type | Data Shape |
+|------|-----------|
+| `api-contract` | `{ endpoints: [{ method, path, request, response }] }` |
+| `schema-change` | `{ models: [{ name, action, fields }] }` |
+| `component-spec` | `{ componentName, props, states, events }` |
+| `test-results` | `{ total, passed, failed, failures: [...] }` |
+| `file-manifest` | `{ files: [{ path, action, description }] }` |
+| `config-change` | `{ changes: [{ key, oldValue, newValue }] }` |
+| `custom` | Any JSON (no schema validation) |
+
+**Immutability:** Version files are write-once. First writer wins, second gets an error. This prevents version conflicts.
+
+**Schema validation:** When publishing a well-known artifact type, the `data` field is validated against the JSON schema. If validation fails, the publish is rejected with a clear error message.
+
+### Contracts (6 Tools)
+
+Contracts are **formal task assignments** with auto-resolving dependencies. ANY session can create contracts for ANY other session (not just the orchestrator) — this is what makes the system truly **peer-to-peer**.
+
+| Tool | Description |
+|------|-------------|
+| `contract_create` | Create a task contract and assign it to any teammate (peer-to-peer) |
+| `contract_start` | Start working on an assigned contract (returns inputs + resolved artifacts) |
+| `contract_complete` | Mark a contract as done (triggers cascade + pipelines) |
+| `contract_fail` | Mark a contract as failed (notifies assigner) |
+| `contract_reopen` | Reopen a failed/completed contract for retry (increments retryCount) |
+| `contract_get` | Get full contract details |
+| `contract_list` | List all contracts with optional filters (status, assignee, assigner) |
+| `contract_reassign` | Change who's assigned to a contract |
+
+**Contract lifecycle:**
+
+```
+pending → ready → in_progress → completed
+            ↑           ↓
+            └─ (reopen) ─ failed
+```
+
+- **pending:** Waiting for dependencies (other contracts or artifacts)
+- **ready:** All dependencies satisfied, ready to start
+- **in_progress:** Assignee is working on it
+- **completed:** Auto-completed when acceptance criteria are met
+- **failed:** Assignee marked it as failed OR timeout exceeded
+
+**Acceptance criteria types:**
+
+| Type | Met when |
+|------|----------|
+| `artifact_published` | Matching artifact exists at required version |
+| `tests_passing` | test-results artifact meets pass/fail thresholds |
+| `contract_completed` | Referenced contract is completed |
+| `all_outputs_published` | All required expectedOutputs have matching artifacts |
+
+**Safety features:**
+- **Timeout:** Contracts can have `timeoutMs` — auto-failed if not completed in time
+- **Retry limit:** `maxRetries` (default 3) — reopen rejected after too many failures
+- **Circular dependency detection:** DFS cycle detection on contract creation
+- **Cascade depth guard:** Max 10 levels of auto-resolution to prevent infinite loops
+
+---
+
+## Layer 3: Reactive Intelligence (12 MCP Tools)
+
+This is the layer that makes the system **unbeatable**. Each feature depends on Layer 2's versioned artifacts and contract state machine — competitors cannot bolt these on because they lack the foundation.
+
+### 3a. Lineage Graph (4 Tools)
+
+Track **data provenance** and analyze impact.
+
+| Tool | Description |
+|------|-------------|
+| `artifact_lineage` | Query the provenance DAG (upstream: what inputs? downstream: what depends on this?) |
+| `artifact_impact` | "If I change this artifact, what downstream artifacts and contracts break?" |
+| `artifact_stale` | List all artifacts derived from outdated sources (e.g., derived from v1 but v2 now exists) |
+| `team_audit` | Full provenance trail: who created it, from what inputs, under which contract, at what time |
+
+**How lineage is captured:**
+
+Every `artifact_publish` can include a `derivedFrom` array listing input artifacts. Additionally, when a contract completes, the system auto-links published artifacts to the contract's input artifacts. This builds a full DAG (directed acyclic graph) of how data flowed through the system.
+
+**Example:**
+
+```
+schema-user-model@v1 (root)
+    └─► api-contract-user-auth@v2 (derivedFrom schema@v1)
+        └─► test-results-auth@v1 (derivedFrom api-contract@v2)
+
+If schema-user-model gets bumped to v2:
+→ artifact_stale() reports api-contract-user-auth@v2 as stale
+→ artifact_impact("schema-user-model") shows 2 downstream artifacts affected
+```
+
+### 3b. Reactive Pipelines (4 Tools)
+
+Event-driven **trigger→condition→action** rules. "When X happens, automatically do Y."
+
+| Tool | Description |
+|------|-------------|
+| `pipeline_create` | Define trigger→condition→action rules |
+| `pipeline_list` | View active pipelines and execution counts |
+| `pipeline_pause` | Disable a pipeline without deleting |
+| `pipeline_resume` | Re-enable a paused pipeline |
+
+**Trigger types:**
+
+| Trigger | Fires when |
+|---------|-----------|
+| `artifact_published` | Any artifact of matching type/id is published |
+| `artifact_version_bumped` | An existing artifact gets a new version |
+| `contract_completed` | A contract transitions to completed |
+| `contract_failed` | A contract transitions to failed |
+| `artifact_stale` | An artifact is detected as stale |
+
+**Action types:**
+
+| Action | What it does |
+|--------|-------------|
+| `notify_session` | Send an inbox message to a specific session |
+| `broadcast` | Send inbox message to all team members |
+| `reopen_contract` | Call contract_reopen with given reason |
+| `create_contract` | Create a new contract (deduplication: skips if already exists) |
+| `invalidate_downstream` | Mark all downstream artifacts as stale via lineage graph |
+
+**Example pipeline (self-healing CI loop):**
+
+```javascript
+{
+  rules: [
+    {
+      trigger: { type: "artifact_published", artifactType: "api-contract" },
+      action: { type: "notify_session", target: "qa-dev",
+                message: "API contract updated — re-run tests" }
+    },
+    {
+      trigger: { type: "artifact_published", artifactType: "test-results" },
+      condition: "data.failed > 0",
+      action: { type: "reopen_contract", contractId: "build-auth-api",
+                reason: "Tests failing: ${data.failed} failures" }
+    }
+  ]
+}
+```
+
+When tests fail, the API contract is **automatically reopened** without human intervention. When the API is fixed and tests pass, the contract auto-completes. This is a **self-healing CI loop** with zero conversation.
+
+### 3c. Snapshot & Replay (4 Tools)
+
+**Time-travel** for workflows. Capture full state, rollback, replay with different parameters.
+
+| Tool | Description |
+|------|-------------|
+| `team_snapshot` | Capture current state of all contracts + artifacts + pipelines |
+| `team_snapshot_list` | View all snapshots with timestamp and summary |
+| `team_rollback` | Reset contract/pipeline state to a previous snapshot |
+| `team_replay` | Rollback + apply overrides + re-trigger dependency resolution |
+
+**Why this matters:**
+
+Because artifacts are **immutable** (version files never change) and contracts have a well-defined **state machine**, the entire system state can be captured as a snapshot and restored later.
+
+**Rollback:** Undo a bad workflow execution and restore to a known-good state.
+
+**Replay:** Re-execute from a snapshot with different parameters (e.g., "try GraphQL instead of REST"). The entire downstream chain re-executes with the new approach. Original artifacts are preserved as historical versions for comparison.
+
+**Example:**
+
+```bash
+# Take a snapshot before a risky operation
+cms team-snapshot pre-refactor --label "Before auth refactor"
+
+# Do the refactor... oops, tests are broken
+cms contract-list  # shows multiple failed contracts
+
+# Rollback to the snapshot
+cms team-rollback pre-refactor
+# → Contracts reset to their pre-refactor state
+# → Post-snapshot artifacts marked as "rolled-back" (files preserved)
+# → Sessions notified to restart
+
+# Or replay with different parameters
+cms team-replay pre-refactor --overrides '{"build-auth-api":{"inputs":{"context":"Use JWT instead of sessions"}}}'
+# → Entire workflow re-executes with JWT approach
+# → Compare test-results artifacts from both runs
+```
+
+---
+
+## CLI Commands (Team Hub v2)
+
+### Chat Commands
+
+```bash
+cms team-send --from db-dev --to api-dev --message "Schema is ready"
+cms team-broadcast --from orchestrator --message "Deploy in 10 minutes"
+cms team-roster  # View all team members
+cms team-inbox --name db-dev  # Check unread messages
+```
+
+### Artifact Commands
+
+```bash
+cms artifact-publish schema-user-model --type schema-change \
+  --name "User schema" --data '{"models":[...]}'
+
+cms artifact-get api-contract-user-auth  # Latest version
+cms artifact-get api-contract-user-auth --version 2  # Specific version
+cms artifact-list --type api-contract
+cms artifact-history api-contract-user-auth
+```
+
+### Contract Commands
+
+```bash
+cms contract-create setup-user-model --assignee db-dev \
+  --title "Create User schema" \
+  --expected-output schema-change
+
+cms contract-start setup-user-model
+cms contract-complete setup-user-model --summary "User model created"
+cms contract-fail setup-user-model --reason "Missing field validation"
+cms contract-reopen setup-user-model --reason "Add phone field"
+cms contract-list --status ready
+```
+
+### Lineage Commands
+
+```bash
+cms artifact-lineage test-results-auth --direction upstream
+cms artifact-lineage schema-user-model --direction downstream
+cms artifact-impact schema-user-model  # What breaks if I change this?
+cms artifact-stale  # List all artifacts derived from outdated sources
+cms team-audit test-results-auth  # Full provenance trail
+```
+
+### Pipeline Commands
+
+```bash
+cms pipeline-create ci-loop --rules ci-rules.json
+cms pipeline-list
+cms pipeline-pause ci-loop
+cms pipeline-resume ci-loop
+```
+
+### Snapshot Commands
+
+```bash
+cms team-snapshot pre-work --label "All contracts created"
+cms team-snapshot-list
+cms team-rollback pre-work
+cms team-replay pre-work --overrides overrides.json
+```
+
+---
+
+## Architecture & Directory Structure
+
+```
+~/.claude-multi-session/
+  sessions.json                       # Existing session metadata (unchanged)
+  team/
+    default/                          # Team namespace
+      roster.json                     # Layer 1: who's active, role, status
+      inbox/
+        {session}.jsonl               # Layer 1: chat messages (append-only)
+      asks/
+        ask_{id}.json                 # Layer 1: pending ask-and-wait
+      artifacts/
+        index.json                    # Layer 2: artifact registry
+        schemas/                      # Layer 2: JSON schemas for well-known types
+          api-contract.json
+          schema-change.json
+          test-results.json
+        data/
+          {artifactId}/
+            v1.json                   # Immutable version files
+            v2.json
+      contracts/
+        index.json                    # Layer 2: contract state
+      pipelines/
+        index.json                    # Layer 3: reactive pipeline rules
+        log.jsonl                     # Layer 3: pipeline execution history
+      snapshots/
+        snap_{id}.json                # Layer 3: full state snapshots
+      locks/
+        artifacts-index.lock          # Cross-process lock files
+        contracts-index.lock
+        pipelines-index.lock
+```
+
+**Key design choices:**
+
+- **JSONL for inboxes:** Append-only, safe for concurrent writers
+- **JSON for indexes:** Atomic temp+rename for safe updates
+- **Immutable version files:** Write-once (wx flag), first writer wins
+- **File locks:** PID-aware locking with staleness detection
+- **Team namespaces:** Multiple teams can coexist in separate directories
+
+---
+
+## Comparison: Why This Is Revolutionary
+
+| | Agent Teams | claude-flow | CrewAI | **claude-multi-session v2.0** |
+|---|---|---|---|---|
+| Coordination model | Conversational | Conversational | Conversational | **Transactional** |
+| Structured data exchange | No | No | No | **Versioned artifacts** |
+| Schema validation | No | No | No | **JSON schema on publish** |
+| Auto-resolving dependencies | No | No | No | **Contract system** |
+| Peer-to-peer task assignment | No | No | No | **Any session → any session** |
+| Contract timeout + retry | No | No | No | **Yes** |
+| Direct session messaging | Yes (text only) | No | No | **Yes (text + structured artifacts)** |
+| Data lineage / provenance | No | No | No | **Full DAG** |
+| Impact analysis | No | No | No | **"What breaks if I change X?"** |
+| Reactive pipelines | No | No | No | **Event-driven trigger→action** |
+| Self-healing CI loops | No | No | No | **Auto-reopen + re-test** |
+| Workflow snapshots | No | No | No | **Full state capture** |
+| Rollback + replay | No | No | No | **Time-travel with overrides** |
+| Each session: own context | No (shared) | No | No | **100K each** |
+| Resume team next day | No | No | No | **Yes** |
+| Quality over time | Degrades | Degrades | Degrades | **Stays consistent** |
+| Zero dependencies | N/A | No (46MB) | No | **Yes** |
+
+**The key insight:** Every competitor uses conversational coordination — agents talk in natural language, summaries pile up, quality degrades over time. We use **transactional coordination** — agents exchange structured data, operate on formal contracts, and auto-resolve dependencies. The result is a system that **stays consistent** instead of degrading.
+
+**The moat:** Layer 3 features (lineage, pipelines, snapshots) cannot be bolted onto conversational systems because they require Layer 2 (versioned artifacts + contracts) to exist first. Competitors would need to rebuild their entire coordination layer to replicate this.
+
+---
+
 ## License
 
 MIT