clearctx 3.0.0

package/STRATEGY.md

@@ -0,0 +1,485 @@
+# Multi-Session Strategy Guide
+
+This guide teaches Claude Code WHEN and HOW to use the multi-session tools effectively.
+Place this content in your project's `CLAUDE.md` or reference it as a system prompt.
+
+---
+
+## When to Use Multi-Session
+
+### DO delegate when:
+- **Task has 3+ independent parts** — build login, signup, and reset in parallel
+- **Task is too large for one context** — full feature implementation with tests
+- **You need different models for different subtasks** — haiku for simple lookups, opus for architecture
+- **You want to try multiple approaches** — fork and compare
+- **Task involves risky operations** — delegate with safety limits instead of doing it directly
+
+### DON'T delegate when:
+- **Task is small** — a few lines of code, a quick fix
+- **Task needs tight coordination** — changes that must happen atomically across files
+- **You're just reading/exploring** — use Read, Grep, Glob directly
+
+---
+
+## Decision Framework
+
+```
+Is the task simple (< 5 minutes, < 3 files)?
+  → YES: Do it yourself. No delegation needed.
+  → NO: Continue...
+
+Can the task be split into independent parts?
+  → YES: Delegate each part in parallel.
+  → NO: Delegate as one task, use continue_task for corrections.
+
+Does the task need special safety limits?
+  → YES: Use delegate_task with max_cost and max_turns.
+  → NO: Use spawn_session + send_message for direct control.
+```
+
+---
+
+## Task Decomposition
+
+When breaking a large task into subtasks:
+
+1. **Identify independent pieces** — parts that don't depend on each other
+2. **Identify dependencies** — part B needs part A's output
+3. **Assign models** — haiku for simple, sonnet for standard, opus for complex
+4. **Set budgets** — split total budget proportionally
+
+**Example: "Build the authentication system"**
+```
+Independent (run in parallel):
+  - child-1 (sonnet): "Build login endpoint with JWT"
+  - child-2 (sonnet): "Build signup endpoint with validation"
+  - child-3 (sonnet): "Build password reset with email tokens"
+
+Dependent (run after all above complete):
+  - child-4 (sonnet): "Write integration tests for auth system"
+```
+
+---
+
+## Model Selection Guide
+
+| Task Type | Model | Why |
+|-----------|-------|-----|
+| Simple lookups, counting, listing | haiku | Fast and cheap |
+| Standard code edits, bug fixes | sonnet | Good balance |
+| Architecture decisions, complex refactoring | opus | Best reasoning |
+| Code review, analysis | sonnet | Good enough |
+| Writing tests | sonnet | Reliable |
+
+---
+
+## Budget Allocation
+
+When delegating a complex task with a total budget:
+
+| Allocation | Percentage | Purpose |
+|------------|-----------|---------|
+| Main work | 60% | The core implementation |
+| Tests | 20% | Writing and running tests |
+| Reserve | 20% | Corrections, follow-ups, retries |
+
+**Example:** $5 total budget for 3 parallel tasks
+- Each task gets $1.00 (60% = $3.00 total)
+- Tests task gets $1.00 (20%)
+- Reserve $1.00 for corrections (20%)
+
+---
+
+## The Correction Loop
+
+After EVERY delegation, evaluate the result:
+
+```
+1. delegate_task → get result
+2. Read result.status:
+   - "completed" → Read result.response, evaluate quality
+   - "failed" → Read result.error, decide: retry or different approach
+   - "cost_exceeded" → Budget was too low. Increase or reduce scope.
+   - "turns_exceeded" → Task too complex. Break it down further.
+3. Is the result good?
+   - YES → finish_task
+   - NO → continue_task with specific corrections
+   - HOPELESS → abort_task, try a different approach
+```
+
+### Writing Good Corrections
+
+**Bad correction:** "Fix it"
+**Good correction:** "The login function is missing password hashing. Add bcrypt hashing before saving to database. Use 12 salt rounds."
+
+Be specific about:
+- WHAT is wrong
+- WHERE in the code
+- HOW to fix it
+
+---
+
+## Parallel Coordination
+
+When running multiple child sessions that work on related code:
+
+1. **Spawn all independent tasks** in parallel
+2. **Wait for all results**
+3. **Evaluate each result** independently
+4. **Send corrections** to any that need fixing (in parallel)
+5. **If task B needs output from task A**, read A's result and include relevant details in B's context
+
+**Example:**
+```
+# Step 1: Parallel delegation
+delegate_task(name="auth-api", task="Build auth endpoints")
+delegate_task(name="auth-ui", task="Build login screen")
+
+# Step 2: Read results
+# auth-api completed: "Created /api/login and /api/register"
+# auth-ui completed but used wrong endpoint path
+
+# Step 3: Correct auth-ui with info from auth-api
+continue_task(name="auth-ui", message="The API endpoint is /api/login not /login. Update the fetch URL.")
+```
+
+---
+
+## Session Recovery
+
+If a conversation ends and you start a new one:
+
+1. **Always check for existing sessions first:** `list_sessions`
+2. **Resume important sessions:** `resume_session`
+3. **Clean up finished work:** `delete_session` for completed tasks
+4. **Sessions persist across conversations** — the data is saved to disk
+
+---
+
+## Safety Presets Quick Reference
+
+| Preset | Use When |
+|--------|----------|
+| `read-only` | Analyzing code, gathering information, code review |
+| `review` | Same as read-only |
+| `edit` | Normal development work (DEFAULT — use this most of the time) |
+| `full` | Trusted tasks that need unrestricted access (use sparingly) |
+| `plan` | Exploring architecture, planning (no file modifications) |
+
+---
+
+## Anti-Patterns (What NOT to do)
+
+1. **Don't delegate trivial tasks** — overhead of spawning a session isn't worth it for simple fixes
+2. **Don't use `full` preset by default** — use `edit` and escalate only if needed
+3. **Don't ignore failed results** — always check status and handle errors
+4. **Don't set budgets too low** — a realistic task needs $0.50-2.00, complex tasks need more
+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."