claude-multi-session 1.0.1 → 2.3.0

package/STRATEGY.md

@@ -177,3 +177,309 @@ If a conversation ends and you start a new one:
 5. **Don't send vague corrections** — be specific about what's wrong and how to fix it
 6. **Don't forget to finish_task** — stopped sessions consume stored data
 7. **Don't coordinate file edits across parallel sessions on the same file** — they'll conflict
+
+---
+
+# Team Hub v2 Strategy — From Conversations to Transactions
+
+## The Positioning Statement
+
+**claude-multi-session is the only multi-agent coordination system for Claude Code that replaces conversation with transactions.**
+
+Agents exchange **versioned artifacts**, not messages. Any agent can assign work to any other agent — the team **self-organizes** without a central bottleneck. Workflows **auto-heal** through reactive pipelines. Data lineage tracks exactly how every output was derived. And the entire coordination state can be **rolled back and replayed** — something no conversational system can ever do.
+
+Every competitor is racing to make agents talk better. We're building a system where agents don't need to talk at all — and don't need a boss to tell them what to do next.
+
+---
+
+## The Flywheel: How All Three Layers Reinforce Each Other
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│  Layer 2: Artifacts (versioned, immutable)                  │
+│      │                                                       │
+│      ├──► Layer 3a: Lineage Graph tracks how artifacts      │
+│      │        relate to each other                          │
+│      │        │                                              │
+│      │        └──► Knows which artifacts are STALE when     │
+│      │             sources change                           │
+│      │             │                                         │
+│      │             └──► Layer 3b: Reactive Pipelines        │
+│      │                  auto-trigger regeneration           │
+│      │                  │                                    │
+│      │                  └──► Self-healing CI loops          │
+│      │                       without chat                   │
+│      │                                                       │
+│      └──► Layer 3c: Snapshots capture the full state at     │
+│           any point in time                                 │
+│           │                                                  │
+│           └──► Replay re-executes from snapshots with       │
+│                overrides                                    │
+│                │                                             │
+│                └──► Lineage shows what changed between runs │
+│                     │                                        │
+│                     └──► Artifacts store both runs' outputs │
+│                          for comparison                     │
+│                                                              │
+│  The cycle:                                                 │
+│    Build → Track lineage → React to changes → Snapshot     │
+│    → Replay if needed → Lineage shows delta                │
+│                                                              │
+│  Competitors can't replicate this because step 1 (versioned │
+│  artifacts) doesn't exist in their systems. Every Layer 3   │
+│  feature depends on Layer 2 existing first.                 │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Why Competitors Can't Replicate This
+
+### Conversational Systems (Agent Teams, claude-flow, CrewAI, AutoGen)
+
+**What they do:**
+- Agents talk in natural language
+- Messages pile up in shared context
+- Orchestrator summarizes and routes
+- Quality degrades over time
+
+**Their limitations:**
+
+1. **No data provenance:** Can't answer "how was this output derived?" without reading conversation history
+2. **No impact analysis:** Can't answer "what breaks if I change X?" without asking every agent
+3. **No snapshot/replay:** Can't rollback to a previous state — conversation is linear, irreversible
+4. **No self-healing:** When tests fail, someone has to notice and manually retry
+5. **No peer-to-peer:** Only the orchestrator can assign work (hub-and-spoke bottleneck)
+
+**Why they can't bolt this on:**
+
+To add lineage tracking, they'd need versioned artifacts. To add impact analysis, they'd need a dependency graph. To add snapshot/replay, they'd need a state machine. But all of these require **structured, transactional coordination** — which means rebuilding their entire coordination layer.
+
+---
+
+### The Moat: Each Layer 3 Feature Requires Layer 2
+
+| Layer 3 Feature | Why it depends on Layer 2 |
+|----------------|---------------------------|
+| **Lineage Graph** | Needs immutable artifact versions and explicit `derivedFrom` relationships |
+| **Impact Analysis** | Needs dependency graph built from artifact relationships |
+| **Staleness Detection** | Needs version numbers to compare (derived from v1 but v2 exists) |
+| **Reactive Pipelines** | Needs structured events (artifact_published, contract_completed) with typed data |
+| **Self-Healing CI** | Needs contract state machine (reopen → retry) and artifact validation (test-results schema) |
+| **Snapshots** | Needs serializable state (contracts + artifacts + pipelines) |
+| **Rollback** | Needs immutable version files (can restore without losing data) |
+| **Replay with Overrides** | Needs contract inputs to be structured and modifiable |
+
+Competitors would need to:
+1. Add versioned artifacts (breaking change to their data model)
+2. Add contract state machines (breaking change to their coordination model)
+3. Add structured schema validation (breaking change to their output format)
+4. Add lineage tracking (requires rewriting artifact publish logic)
+5. Add reactive pipelines (requires event system + rule engine)
+6. Add snapshot/replay (requires full state serialization)
+
+This is not "add a feature" — this is "rebuild the entire system."
+
+---
+
+## When to Use Team Hub v2
+
+### Use Team Hub when:
+
+1. **You have a multi-step workflow with dependencies**
+   - Example: Schema → API → Tests
+   - Why: Contracts auto-resolve as artifacts are published
+
+2. **You want self-healing behavior**
+   - Example: When tests fail, auto-reopen the API contract
+   - Why: Reactive pipelines handle this without chat
+
+3. **You need data provenance**
+   - Example: "How was this test result derived?"
+   - Why: Lineage graph tracks the full chain
+
+4. **You want to try multiple approaches**
+   - Example: Build with REST, then replay with GraphQL
+   - Why: Snapshots + replay let you compare both runs
+
+5. **You have peer-to-peer coordination needs**
+   - Example: QA finds a bug and assigns it directly to the backend dev
+   - Why: Any session can create contracts for any other session
+
+### Don't use Team Hub when:
+
+1. **You have a single, linear task** — just use delegate_task
+2. **You're just exploring/reading code** — use Grep/Glob directly
+3. **The task is too small** — overhead of contracts isn't worth it
+
+---
+
+## Team Strategy Patterns
+
+### Pattern 1: Linear Chain (Schema → API → Tests)
+
+**Setup:**
+```javascript
+contract_create("setup-schema", assignee: "db-dev",
+  expectedOutputs: [{ artifactType: "schema-change" }])
+
+contract_create("build-api", assignee: "api-dev",
+  dependencies: [{ type: "contract", contractId: "setup-schema" }],
+  expectedOutputs: [{ artifactType: "api-contract" }])
+
+contract_create("write-tests", assignee: "qa-dev",
+  dependencies: [{ type: "contract", contractId: "build-api" }],
+  expectedOutputs: [{ artifactType: "test-results" }])
+```
+
+**What happens:**
+- setup-schema is `ready` immediately
+- build-api is `pending` until setup-schema completes
+- write-tests is `pending` until build-api completes
+- Each session auto-starts when its contract becomes `ready`
+- No orchestrator involvement after initial setup
+
+### Pattern 2: Self-Healing CI Loop
+
+**Setup:**
+```javascript
+pipeline_create("ci-loop", 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-api",
+              reason: "Tests failing: ${data.failed} failures" }
+  }
+])
+```
+
+**What happens:**
+- API dev publishes api-contract → QA gets notified → re-runs tests
+- If tests fail → contract auto-reopens → API dev gets notification → fixes → publishes new version
+- If tests pass → contract auto-completes → done
+- Zero human intervention, zero orchestrator messages
+
+### Pattern 3: Peer-to-Peer Bug Assignment
+
+**Scenario:** QA discovers a bug during testing
+
+**Traditional approach (hub-and-spoke):**
+```
+QA → tells orchestrator → orchestrator assigns to api-dev → api-dev works on it
+```
+
+**Team Hub v2 approach (peer-to-peer):**
+```javascript
+// QA creates contract directly for api-dev
+contract_create("fix-sql-injection", assigner: "qa-dev", assignee: "api-dev",
+  title: "Fix SQL injection in login endpoint",
+  inputs: { context: "Parameterized queries missing in /login handler" },
+  expectedOutputs: [{ artifactType: "api-contract", required: true }])
+// → api-dev gets inbox: "contract_ready" from qa-dev (not orchestrator)
+// → Orchestrator also notified (broadcast on contract creation) but not involved
+```
+
+**What happens:**
+- QA assigns work directly to api-dev without going through orchestrator
+- api-dev starts work immediately
+- When api-dev publishes the fix, CI pipeline auto-triggers QA's tests
+- Team self-organizes without a bottleneck
+
+### Pattern 4: Snapshot → Try Different Approach → Compare
+
+**Scenario:** Auth feature is done with REST, want to try GraphQL
+
+```bash
+# Take snapshot of completed work
+team_snapshot "auth-rest-complete" --label "Auth feature done with REST"
+
+# Replay from the beginning with GraphQL override
+team_replay "pre-work" --overrides '{
+  "build-api": {
+    "inputs": { "context": "Use GraphQL instead of REST" }
+  }
+}'
+
+# Both runs' artifacts are preserved:
+# - api-contract-user-auth@v2 (REST approach)
+# - api-contract-user-auth@v3 (GraphQL approach)
+# - test-results-auth@v1 (REST tests)
+# - test-results-auth@v2 (GraphQL tests)
+
+# Compare test results
+artifact_get api-contract-user-auth --version 2  # REST
+artifact_get api-contract-user-auth --version 3  # GraphQL
+artifact_get test-results-auth --version 1       # REST tests
+artifact_get test-results-auth --version 2       # GraphQL tests
+```
+
+**What happens:**
+- Original work is preserved
+- Entire workflow re-executes with different parameters
+- Both approaches' outputs are stored for comparison
+- Lineage shows how each output was derived
+
+---
+
+## Budget Strategy for Teams
+
+When using Team Hub, your budget is split across:
+1. **Contract execution** (sessions doing the work)
+2. **Orchestrator monitoring** (checking contract status, handling failures)
+3. **Reserve** (corrections, retries)
+
+**Example:** $10 total budget for a 3-agent team building an auth feature
+
+| Allocation | Amount | Purpose |
+|------------|--------|---------|
+| db-dev contract | $2.00 | Schema design + migrations |
+| api-dev contract | $4.00 | API implementation (most complex) |
+| qa-dev contract | $2.00 | Test suite |
+| Orchestrator | $1.00 | Setup contracts, monitor, handle failures |
+| Reserve | $1.00 | Retries when tests fail |
+
+**Key insight:** With reactive pipelines, the orchestrator's budget is tiny — it only intervenes on failures. Most work happens autonomously.
+
+---
+
+## Quality Metrics: Why Transactional Beats Conversational
+
+| Metric | Conversational | Transactional (Team Hub v2) |
+|--------|---------------|---------------------------|
+| **Precision** | Degrades (summaries lose detail) | Stays consistent (artifacts are exact) |
+| **Traceability** | Poor (read conversation history) | Perfect (lineage graph) |
+| **Repeatability** | Impossible (can't replay) | Easy (snapshots + replay) |
+| **Self-healing** | Manual (human notices failures) | Automatic (reactive pipelines) |
+| **Context bloat** | Grows (messages pile up) | Constant (artifacts are versioned, not accumulated) |
+| **Coordination overhead** | High (orchestrator routes everything) | Low (peer-to-peer contracts) |
+
+**Example:**
+
+Conversational system after 10 iterations:
+```
+Orchestrator context: 50K tokens
+- Messages from all agents
+- Summaries of what was done
+- Repeated explanations
+- Lost precision from compression
+```
+
+Team Hub v2 after 10 iterations:
+```
+Orchestrator context: 5K tokens
+- Contract statuses
+- Artifact IDs
+- Pipeline logs
+- Full precision preserved in artifacts
+```
+
+---
+
+## The Pitch: Why This Wins
+
+> "Every multi-agent system relies on conversation. Agents talk, orchestrators summarize, quality degrades. Team Hub v2 replaces conversation with transactions. Agents publish versioned artifacts, create contracts for each other, and auto-resolve dependencies. The system heals itself when tests fail. You can rollback to any point and replay with different parameters. And data lineage tracks exactly how every output was derived. This is not incremental — this is a different paradigm. And because every Layer 3 feature requires Layer 2 to exist first, competitors can't bolt this on without rebuilding their entire coordination layer. That's the moat."