hermes-config/skills/software-development/subagent-driven-development/references/pocketbase-sequencing-pitfalls.md

PB Migration Sequencing Pitfalls (Subagent-Driven Development)

The Problem

When a plan involves creating/updating PocketBase collections AND frontend UI in the same batch, the frontend code inevitably references the new collection name. If the PB migration hasn't been applied yet, the frontend will:

• Type-check fine (no compile-time dependency on PB schema)
• Build fine (no import dependency)
• Crash at runtime with "Missing collection" errors

When This Happens

The standard batch-parallel pattern (delegate_task with independent goals) is susceptible because:

1. Subagent A creates pb_migrations/M25_new_collection.js
2. Subagent B writes pb.collection('newCollection').getList(...) in a UI component
3. Both execute in parallel — neither knows about the other
4. The PB migration still needs to be docker cp'd and migrate up applied
5. The frontend code is deployed, but the collection doesn't exist in PB yet

Mitigation Strategy

For the agent orchestrating the batch:

• Deploy PB migrations BEFORE dispatching frontend subagents. Wrap the sequence as:

  1. Write all PB migration files
  2. Copy to container and migrate up
  3. Verify success with docker exec / --dir check
  4. THEN dispatch frontend subagents

• If forced to parallelize (e.g., PB and frontend for different features are interleaved), add a guard in the frontend subagent's context: "The collection [name] already exists in PB — query it directly." Verify the collection exists first with a curl health check before dispatching.

• For deployment safety, add a try/catch around PB queries in new frontend code:

  try {
    const records = await pb.collection('newCollection').getFullList({...});
  } catch (err) {
    console.warn('[newCollection] not available yet');
    return [];
  }
  

Why This Is Tricky

Unlike module imports (which fail at build time), PB collection references are runtime API calls. The JS bundler doesn't know about them. In the SPQ-v2 project:

• All PB queries go through pb.collection('name').method()
• The collection name is a runtime string — no compile-time validation
• Missing collections produce a 404 response from PB, which the frontend may or may not handle gracefully