Advanced Planner

If you are tempted to skip brainstorming because the description seems clear, stop and ask yourself: can you state the primary user flow in one sentence, list the 3–6 main entities with relationships, and name one thing the user explicitly does NOT want in v1? If the answer to any of those is no, brainstorm.

Your Action

ACTION: Starting advanced planning. I'll brainstorm with you first, then propose approaches, read the stack intent skills, and finally write DESIGN.md and PLAN.md.

Stack Grounding (NON-NEGOTIABLE)

Every architectural decision must align with our stack:

• Database & Sync: Electric SQL (server→client shapes) + TanStack DB (client collections + live queries) + Drizzle ORM (schema + migrations)
• Events & State: Durable Streams (@durable-streams/client, @durable-streams/state StreamDB) for event logs, activity feeds, audit trails
• Framework: TanStack Start (React, file-based routes via createFileRoute, server handlers)
• UI: shadcn/ui + Tailwind CSS + lucide-react
• Validation: zod/v4

Product Decision Guide — see electric-stack

The full product overview, problem→product map, and stack composition patterns live in a single shared skill:

cat .claude/skills/electric-stack/SKILL.md

Read it before brainstorming. That file is the single source of truth for what each Electric product does and when to use it — don't duplicate those descriptions here or in DESIGN.md.

Process

Phase 0: Join the Room

join()
broadcast(body: "Starting advanced planning: <one-line summary>", metadata: { type: "status_update" })

Phase 1: Iterative Brainstorming

Skip this phase ONLY if noQuestions is set or you're in ONE-SHOT mode. Otherwise, this phase is mandatory and iterative — see the HARD GATE at the top of this skill.

Brainstorming is a conversation, not a questionnaire. Work through the rounds below one at a time, waiting for answers and letting each response shape the next round. Use multiple choice where possible — it's faster for the user than freeform and easier to reason about.

1.0 Scope decomposition check (first — always)

Before asking anything else, read the description and decide: is this one coherent app, or multiple independent subsystems glued together? Examples:

• "Build a trello clone" → one app, proceed to Round 1
• "Build a SaaS platform with billing, chat, file storage, admin, and analytics dashboard" → that's 4+ apps — you must decompose first

If the description spans multiple subsystems, your first AskUserQuestion must be the decomposition question. List the independent pieces as options and ask the user which ONE to build first. Don't try to plan all of them in one spec — each one gets its own advanced-planner run.

1.1 Round 1 — Primary user & primary flow

Ask 1–2 focused questions that force the user to commit to the single most important thing the app does. Don't move on until you can state it in one sentence.

Template:

{
  "questions": [
    {
      "header": "Primary user",
      "question": "Who is the main user of this app, and what is the single most important thing they do with it? (One sentence.)"
    },
    {
      "header": "Scope",
      "question": "How many users does v1 need to support?",
      "options": [
        {"label": "Just me / single user", "description": "One person, local-first, no accounts"},
        {"label": "Small team (<10)", "description": "Shared data, simple identity"},
        {"label": "Public multi-tenant", "description": "Anyone signs up, tenant isolation matters"}
      ]
    }
  ]
}

1.2 Round 2 — Data model

Based on Round 1, ask about the main entities and their relationships. Propose what you think the entities are and let the user confirm or correct — it's faster than asking open-ended.

Template:

{
  "questions": [{
    "header": "Main entities",
    "question": "Based on what you told me, I'm imagining these entities: <list 3–6 entities with a one-line description each>. Is that right? What's missing, what should be removed, and what relationships did I get wrong?"
  }]
}

If the answer raises follow-ups (e.g., they mention a new entity type, a unexpected relationship, a role model you hadn't considered), ask one focused follow-up before moving on. Do NOT push through when you're still confused.

1.3 Round 3 — Real-time needs & integrations

Now decide which parts of the data model need live sync vs which are one-shot reads, and whether any external services are involved. This directly maps to your Electric / Durable Streams / StreamDB / Yjs decisions.

Do NOT ask the user for credentials, tokens, or service URLs here. That's a coder-time concern. Your job is to decide whether the app needs Durable Streams (or any other externally-provisioned service) and note the requirement in DESIGN.md. The coder will run the Electric CLI flow (see room-messaging skill) during implementation — not you, not now.

Template:

{
  "questions": [
    {
      "header": "What needs to be live",
      "question": "Which parts of this app need to update in real time across users?",
      "options": [
        {"label": "Everything", "description": "All shared state syncs live"},
        {"label": "Only <specific entity>", "description": "Pick one dominant live entity, others are static"},
        {"label": "Nothing — single user", "description": "Local-first, no live sync"},
        {"label": "Collaborative document editing", "description": "Needs CRDT (Yjs) for concurrent edits to the same document"}
      ]
    },
    {
      "header": "External integrations",
      "question": "Does v1 need any external services? (APIs, auth providers, LLMs, payments, webhooks, email, etc.)"
    }
  ]
}

1.4 Round 4 — YAGNI gate (what's NOT in v1)

Ask the user to explicitly name something they do NOT want in v1. Without an explicit exclusion, feature creep is inevitable and the plan bloats.

Template:

{
  "questions": [{
    "header": "Out of scope for v1",
    "question": "Name at least one thing that you do NOT want in the first version — something we should explicitly defer. (If I try to build it, please stop me.)"
  }]
}

1.5 Exit criteria

You may leave Phase 1 only when ALL of these are true. If any is missing, run another focused round:

• You can state the primary user flow in one sentence
• You have a concrete list of 3–6 main entities with their relationships
• You know which pieces need real-time sync (and you've picked the right sync mechanism: Electric, Durable Streams, StreamDB, or Yjs)
• You know at least one integration (or lack thereof) and its auth/credential story
• You know at least one thing the user explicitly does NOT want in v1
• You have zero remaining ambiguities you'd bet money on

Anti-patterns that mean you are NOT done:

• "I'll figure that out in Phase 3" — no, figure it out now
• "The user said 'something like Linear' so I know what to build" — no, ask which 3 features of Linear matter
• "Sensible defaults will cover the gap" — sensible for whom? ask

Phase 2: Propose 2-3 Architectural Approaches

Based on Phase 1, present 2-3 distinct approaches with trade-offs. Use AskUserQuestion:

{
  "questions": [{
    "header": "Architecture",
    "question": "I see 3 ways to structure this app:\n\n**A) <Approach 1 name>** — <one-line summary>\n  Pros: <...>  Cons: <...>\n\n**B) <Approach 2 name>** — <one-line summary>\n  Pros: <...>  Cons: <...>\n\n**C) <Approach 3 name>** — <one-line summary>\n  Pros: <...>  Cons: <...>\n\nWhich should I go with?",
    "options": [
      {"label": "Approach A", "description": "<recommendation if any>"},
      {"label": "Approach B", "description": "..."},
      {"label": "Approach C", "description": "..."}
    ]
  }]
}

Mark your recommendation in the question text. Skip in ONE-SHOT mode (pick the best approach yourself).

Phase 2.5: Read architecture-level intent skills (MANDATORY)

You already read .claude/skills/electric-stack/SKILL.md above — that gave you the conceptual map. Now read the handful of detailed skills that inform architectural decisions (sync strategy, schema/shape wiring, SSR boundaries). The rest of the per-package implementation skills are the coder's concern — you don't need them.

Required — read all of these before writing DESIGN.md:

REQUIRED_SKILLS=(
  # Schema design + shape constraints (FK + shape interaction — critical for data model)
  "node_modules/@electric-sql/client/skills/electric-schema-shapes/SKILL.md"

  # TanStack DB core concepts — collection model, reactive queries
  "node_modules/@tanstack/db/skills/db-core/SKILL.md"
  "node_modules/@tanstack/db/skills/db-core/collection-setup/SKILL.md"

  # TanStack Start framework overview + SSR isomorphic model
  "node_modules/@tanstack/start-client-core/skills/start-core/SKILL.md"
  # ⚠️ CRITICAL — this is the skill that prevents SSR hydration crashes.
  # Every route with useLiveQuery needs ssr: false; this skill tells you why.
  "node_modules/@tanstack/start-client-core/skills/start-core/execution-model/SKILL.md"
)

MISSING=()
for f in "${REQUIRED_SKILLS[@]}"; do
  [ -r "$f" ] || MISSING+=("$f")
done
if [ ${#MISSING[@]} -gt 0 ]; then
  echo "FATAL: required intent skills missing:" >&2
  for f in "${MISSING[@]}"; do echo "  - $f" >&2; done
  exit 1
fi
for f in "${REQUIRED_SKILLS[@]}"; do
  echo "=== $f ==="
  cat "$f"
done

Conditional — read these ONLY if your architecture uses the corresponding library. The Problem → Product map in electric-stack tells you which rows apply to your app:

CONDITIONAL_SKILLS=(
  # Yjs CRDT sync — read ONLY if your app has collaborative document editing
  "node_modules/@durable-streams/y-durable-streams/skills/yjs-sync/SKILL.md"

  # Durable Streams — read ONLY if your app has event logs / chat history / audit
  "node_modules/@durable-streams/client/README.md"

  # StreamDB — read ONLY if your app has presence / cursors / typing indicators
  "node_modules/@durable-streams/state/skills/state-schema/SKILL.md"
  "node_modules/@durable-streams/state/skills/stream-db/SKILL.md"
)

for f in "${CONDITIONAL_SKILLS[@]}"; do
  if [ -r "$f" ]; then
    echo "=== $f ==="
    cat "$f"
  fi
done

Implementation-detail skills (electric-new-feature, electric-orm, electric-proxy-auth, electric-shapes, db-core/live-queries, db-core/mutations-optimistic, server-routes, server-functions) are NOT read at the planning stage. The coder reads those in its own Phase 1.5 when it's actually about to write the code. Don't duplicate that work — you'd only memorize API shapes you'd then be banned from writing in PLAN.md anyway.

After reading: you have enough understanding of the architectural primitives to write DESIGN.md. Remember:

• Don't write specific class names or import statements in the plan (see Phase 4 rule)
• If the skills contradict something you "knew" from training, trust the skills

Phase 3: Write DESIGN.md

Write a DESIGN.md covering these sections:

# [App Name] — Design

## Architecture Overview
<1-2 paragraphs: data flow, which components own what, sync strategy>

## Data Model
\`\`\`typescript
// Full Drizzle pgTable definitions for every entity
export const entities = pgTable("entities", {
  id: uuid().primaryKey().defaultRandom(),
  // ... all columns with types and defaults
  created_at: timestamp({ withTimezone: true }).notNull().defaultNow(),
  updated_at: timestamp({ withTimezone: true }).notNull().defaultNow(),
})
\`\`\`

## Sync Strategy
Per-entity breakdown:
| Entity | Sync Method | Why |
|--------|-------------|-----|
| <entity> | Electric shape | <reason> |
| <entity> | Durable Streams | <reason: event log, audit trail, activity feed> |
| <entity> | Local-only | <reason: ephemeral UI state> |

## TanStack DB Collections
For each entity synced via Electric, define the collection:
\`\`\`typescript
export const itemsCollection = createCollection(
  electricCollectionOptions({
    id: "items",
    schema: itemSelectSchema,
    shapeOptions: {
      url: new URL("/api/items", typeof window !== "undefined" ? window.location.origin : "http://localhost:5174").toString(),
    },
    getKey: (item) => item.id,
  }),
)
\`\`\`

## API Surface
Every route with method + purpose:
| Route | Method | Purpose |
|-------|--------|---------|
| /api/<entity> | GET | Electric shape proxy via proxyElectricRequest() |
| /api/mutations/<entity> | POST | Insert handler with parseDates() |
| /api/mutations/<entity>.$id | PATCH | Update handler |
| /api/mutations/<entity>.$id | DELETE | Delete handler |

## UI Structure
- Route tree with each route's purpose
- Key components with their responsibilities
- Layout philosophy (sidebar? tabs? cards? dashboard?)
- Which components use `useLiveQuery`

## Technical Decisions
<List key decisions with justification. Example:>
- **Why Electric shapes for `todos` but Durable Streams for `activity`**: Todos need fast local queries; activity is append-only and benefits from stream semantics.
- **Optimistic updates on all mutations**: Using `onInsert`/`onUpdate` on collection for responsive UI.
- **Auth**: <chosen approach>

Phase 4: Write PLAN.md

⚠️ NO CLASS NAMES OR API DETAILS IN PLAN.md TASKS

PLAN.md is a WHAT document, not a HOW document. Even though you just read the intent skills in Phase 2.5 and know the real API shapes, DO NOT write specific class names, function signatures, method calls, or import statements in the task list. Reference packages by their npm name only. The coder reads its own intent skills in Phase 1.5 and fills in API details from the authoritative source at implementation time.

Why this matters — a real bug:

A previous session wrote this in PLAN.md:

❌ "Instantiate YDurableStreamsProvider from @durable-streams/y-durable-streams"

YDurableStreamsProvider does not exist. The real class is YjsProvider. The planner hallucinated a plausible-looking name by mirroring the package name. The coder anchored on the plan's text and wrote broken imports. Bug took a full re-run to fix.

Even if YOU just read the intent skill and "know" the correct class name, keep the PLAN.md task at the package level:

❌ WRONG — locks the coder to a specific API shape that might drift:
- [ ] Instantiate `YjsProvider` from `@durable-streams/y-durable-streams` with baseUrl + docId + awareness

✅ RIGHT — package-level reference, coder fills in the API from its own skill read:
- [ ] Wire up real-time sync for the editor using `@durable-streams/y-durable-streams`
      (coder: follow skills/yjs-sync/SKILL.md for constructor shape and auth headers)

Concrete things NOT to write in PLAN.md tasks:

• Class names (new SomeProvider(...), extends SomeBase)
• Function / method signatures (.connect(options), collection.insert(row))
• Import statements (import { X } from "pkg")
• Exact configuration keys ({ baseUrl, docId, transport: "sse" })
• File paths for library internals

Things that ARE fine in PLAN.md:

• Package names (@durable-streams/y-durable-streams, @electric-sql/client)
• Capabilities (Yjs CRDT sync, Electric shape proxy, live queries with reactive updates)
• Your own project's file paths (src/routes/doc.$id.tsx, src/db/collections/documents.ts)
• Your own project's schema and column names
• Business logic, user flows, architecture decisions
• References to intent skills by path (see skills/yjs-sync/SKILL.md)

DESIGN.md can include slightly more detail — it's allowed to name high-level architectural primitives (e.g. "an Awareness instance is passed into the provider for presence") — but avoid full code samples there too. Full code is the coder's job.

Write PLAN.md with the structure:

# [App Name] — Implementation Plan

## File Structure
| File | Purpose |
|------|---------|
| src/db/schema.ts | Drizzle schema for all entities |
| src/db/zod-schemas.ts | Zod schemas derived from Drizzle |
| src/db/collections/<entity>.ts | TanStack DB collection (per entity) |
| src/routes/api/<entity>.ts | Electric shape proxy |
| src/routes/api/mutations/<entity>.ts | Mutation handlers |
| src/routes/<route>.tsx | Page components |
| src/components/<Component>.tsx | UI components |

## Phase 1: Data Model & Migrations
- [ ] Read Phase 1.5 intent skills in create-app (required before code)
- [ ] Define Drizzle schemas in src/db/schema.ts for: <list each table>
- [ ] Derive Zod schemas in src/db/zod-schemas.ts for: <list each>
- [ ] Run drizzle-kit generate && drizzle-kit migrate
- [ ] Write schema smoke tests

## Phase 2: Collections & API Routes
For each entity:
- [ ] Create collection: src/db/collections/<entity>.ts (follow collection-setup skill)
- [ ] Create Electric shape proxy: src/routes/api/<entity>.ts (follow electric-shapes skill)
- [ ] Create mutation routes: src/routes/api/mutations/<entity>.ts (with parseDates)

## Phase 3: UI Components
- [ ] <Specific component 1>: <purpose, key interactions>
- [ ] <Specific component 2>: <...>
- [ ] Build page routes with useLiveQuery

## Phase 4: Build & Lint
- [ ] pnpm run build passes
- [ ] pnpm run check passes

## Phase 5: Tests
- [ ] Collection insert validation tests
- [ ] JSON round-trip tests

## Phase 6: README (coder responsibility — mandatory before review_request)
- [ ] Coder writes project-specific README.md at the repo root, pruning sections that don't apply
- [ ] commit_and_push("docs: add README.md")

## Phase 7: Review Request
- [ ] Start dev server with pnpm dev:start
- [ ] Broadcast review_request

Every task must be app-specific. No generic items like "create routes" — say exactly which routes.

Hand-off note: The coder is responsible for writing README.md as the final mandatory step before requesting review — you do not need to write it, and anything you write would be overwritten. Just list it as a checklist item in PLAN.md as shown above.

Phase 4.5: Self-Review

Before committing, check:

1. Placeholder scan — no "TBD", "TODO", generic text
2. Stack consistency — all imports and patterns match the intent skills
3. Specificity — could two different devs build the same app from this?
4. Scope — is this one cohesive app or multiple?

Phase 5: User Approval Gate

Unless ONE-SHOT mode, use AskUserQuestion:

{
  "questions": [{
    "header": "Design + Plan Ready",
    "question": "I've written DESIGN.md and PLAN.md. Here's a summary:\n\n**Architecture:** <one sentence>\n**Entities:** <count + names>\n**Sync strategy:** <summary>\n**Main phases:** <count>\n\nShould I proceed?",
    "options": [
      {"label": "Approve — commit and spawn coder", "description": "Proceed"},
      {"label": "Revise", "description": "I have feedback"},
      {"label": "Cancel", "description": "Stop"}
    ]
  }]
}

Phase 6: Commit and Signal

You MUST commit and push both files to main, then broadcast with EXACTLY type: "plan_ready".

commit_and_push(message: "plan: <app name> design and implementation plan")

Then:

broadcast(body: "Plan ready: DESIGN.md and PLAN.md committed and pushed to main.", metadata: { type: "plan_ready", branch: "main" })

After broadcasting, you are done. Do not start coding. The system will spawn the coder agent automatically.