# IndexedDB Migration Specification

## Part 1: How Jazz Uses IndexedDB
- Database schema (coValues, sessions, transactions stores)
- Transaction queuing pattern
- Entity caching layer
- Session-based conflict resolution

## Part 2: Current SQLite Architecture Analysis
- sql.js WASM setup
- Existing sync protocol
- Pain points and limitations

## Part 3: Migration Plan (4 Phases)
- Phase 1: Core IndexedDB utilities
- Phase 2: Composables layer
- Phase 3: Cross-tab sync
- Phase 4: Cleanup and testing

## Part 4: Implementation Checklist
- [ ] idb-helpers.ts
- [ ] useIndexedDB.ts
- [ ] useSessionTracking.ts
- ... (14 items total)
```

**Key insight**: The spec becomes the source of truth. It's a document Claude can reference during implementation, ensuring consistency across all tasks.
It also becomes a Pin that we can use if something went wrong during implementation.

## Phase 3: Spec Refinement via Interview

Before implementation, I wanted to ensure the spec was solid. I used Claude's `AskUserQuestion` tool:

### The Prompt

<Prompt>
use the ask_user_question tool do you have any questions regarding
@docs/indexeddb-migration-spec.md before we implement it we want
to improve the specs
</Prompt>

Claude asked clarifying questions:
- Should we support migration from existing SQLite data?
- What's the preferred conflict resolution strategy?
- Should cross-tab sync use BroadcastChannel or SharedWorker?

After answering, I requested Vue-specific improvements:

<Prompt>
we want to use provide and inject you have access to the source
code of pinia spin up multiple subagents how they do it so we can
use same patterns
</Prompt>

Claude researched Pinia's patterns and updated the spec with:
- Symbol-based injection keys
- Provider composables with fallback patterns
- Proper cleanup on unmount

## Phase 4: Implementation with Task Delegation

This is where the new **Claude Code Task System** shines. (If you're unfamiliar with subagents and how they work in Claude Code, my <InternalLink slug="claude-code-customization-guide-claudemd-skills-subagents">customization guide</InternalLink> covers the fundamentals.)

### The Prompt

<Prompt>
implement @docs/indexeddb-migration-spec.md use the task tool and
each task should only be done by a subagent so that context is
clear after each task do a commit before you continue you are the
main agent and your subagents are your devs
</Prompt>

### Understanding Claude Code's Task System

Claude Code's task systeminspired by [Beads](https://github.com/beads-ai/beads), Steve Yegge's distributed git-backed issue trackersolves two critical problems with AI coding agents:

**Agent Amnesia**: Starting a new session mid-task loses all progress unless you manually document remaining work.

**Context Pollution**: A full context window makes the agent drop discovered bugs instead of tracking them.

The previous todo list lived in session memory and vanished on restart. The new task system persists tasks to disk, making them shareable across sessions and subagents.

### How Tasks Persist

Tasks are stored in `.claude/tasks/{session-id}/` as JSON files:

```json
{
  "id": "task-1",
  "subject": "Create idb-helpers.ts",
  "description": "Implement IndexedDB promise wrappers...",
  "status": "pending | in_progress | completed",
  "blocks": ["task-3", "task-4"],
  "blockedBy": ["task-0"]
}
```

### The Four Task Tools

| Tool | Purpose |
|------|---------|
| `TaskCreate` | Create a new task with subject, description, and dependencies |
| `TaskUpdate` | Update status (pending → in_progress → completed) or modify dependencies |
| `TaskList` | View all tasks, their status, and what's blocked |
| `TaskGet` | Get full details of a specific task including description |

### Task System Architecture

<Figure
  src={taskOrchestrationImg}
  alt="Task Orchestration: Main Session orchestrator connects to Task List in .claude/tasks/, which delegates to Subagent 1, 2, and 3 each with fresh context. Below shows a dependency graph with Wave 1 (T1, T2, T3 in parallel), Wave 2 (T4, T5, T6 dependent), and Wave 3 (T7)"
  caption="Task orchestration with dependency-aware parallel execution"
/>

### Why Subagents + Tasks = Context Efficiency

By delegating each task to a subagent, the main session stays leanit only handles orchestration (creating tasks, tracking progress, committing). Each subagent gets a fresh context window focused entirely on its specific task, reads what it needs, implements, and returns. This means the main agent won't run out of context even for larger refactors with dozens of tasks.

For truly massive projects spanning days or weeks, a full autonomous agent like [Ralph](https://ghuntley.com/ralph/) would be more appropriate. Ralph is elegantly simplea bash loop that feeds a markdown file into Claude Code repeatedly:

<Figure
  src={ralphArchitectureImg}
  alt="Ralph Architecture: A bash loop (while :; do cat PROMPT.md | claude-code ; done) where PROMPT.md feeds into Claude Code which produces output, and the loop continues indefinitely"
  caption="Ralph's stateless architecture using markdown as persistent memory"
/>

The key difference: Ralph executes each iteration in a completely new Claude session, using the markdown file as the only persistent memory. This makes it truly stateless and capable of running for days.

This spec-driven approach hits a middle ground: subagents get fresh context but the main orchestrator maintains state within a single session. Structured enough to maintain coherence, flexible enough to handle complexity, without the setup overhead of a full autonomous system.

### The Execution Flow

<Figure
  src={orchestratorFlowImg}
  alt="Main Agent Orchestrator flow: TaskCreate spawns Subagent 1 which implements and returns, then TaskUpdate marks complete and commits, then TaskCreate spawns Subagent 2 with dependencies, repeating for all tasks"
  caption="The orchestrator delegates each task to a subagent with atomic commits"
  size="medium"
/>

### Why This Pattern Works

1. **Context isolation**: Each subagent starts fresh, reading only what it needsno accumulated cruft
2. **Persistent progress**: Tasks survive session restarts; pick up where you left off
3. **Dependency-aware parallelism**: Claude identifies which tasks can run concurrently
4. **Atomic commits**: Every task = one commit, making rollbacks trivial
5. **Spec as contract**: Subagents reference the spec, ensuring consistency

### Backpressure: Let the System Catch Mistakes

One crucial element that makes atomic commits powerful: [backpressure](https://banay.me/dont-waste-your-backpressure/). Instead of manually reviewing every change, set up pre-commit hooks that run tests, linting, and type checking automatically.

```bash