claude-multi-session 1.0.0

package/STRATEGY.md

@@ -0,0 +1,179 @@
+# 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