hermes-config/skills/self-hosting/shop-pro-quote/references/mass-port-delegation.md

Mass Port via Delegation

Pattern used on 2026-06-26 to port 6 pages from vanilla JS v1 to React v2 in one session.

Approach: Parallel Fan-Out

1. Infrastructure first — update types, routes, navigation yourself (quick edits, no delegation needed)
2. Dispatch all pages in parallel — 2 batches of 3 delegate_task calls
3. Each subagent gets: target file path, original source file paths, project context (types, existing patterns, PB collections), feature checklist
4. Subagents write the complete .tsx file — no partial work, no test cycle (speed over perfect TDD for bulk codegen)

Batch Structure

Wave 1 (dispatch together): Customers, RepairOrders, Appointments
Wave 2 (dispatch together): FinancialDashboard, Invoices, Settings

Per-Task Context Template

TASK: Build <file path>

ORIGINAL SOURCE: <v1 file paths with sizes>

PROJECT CONTEXT:
- React 19 + TypeScript + Vite + Tailwind CSS
- PocketBase backend at pb (import from '../lib/pocketbase')
- Types defined in ../types.ts — see <interfaces>
- Uses lucide-react for icons
- Existing pages for reference: Dashboard.tsx, QuoteGenerator.tsx

FEATURES TO IMPLEMENT:
1. Feature with specific behavior
2. ...

POCKETBASE COLLECTIONS:
- '<name>' collection with fields: <schema>

CODE PATTERNS TO FOLLOW:
- Import pb from '../lib/pocketbase'
- LoadingSpinner for loading state
- Error state with retry button
- Empty state with create CTA
- Modals for create/edit
- Tailwind dark mode patterns

Post-Dispatch

1. Build: npx vite build
2. Fix import errors — subagents may use wrong paths or import components that need providers (e.g. useToast needs ToastProvider wrapper)
3. Add ToastProvider — lazy-loaded pages that use useToast crash silently if ToastProvider isn't wrapping <Routes>
4. Lazy loading: use React.lazy() + <Suspense> to isolate page errors and enable code splitting
5. PB collections: subagents can't create collections without admin access. Create missing ones or handle gracefully with error states.

Pitfalls

• useToast crash: New pages using toast without ToastProvider → white screen with no error message. Always wrap <Routes> in <ToastProvider>.
• Broken sort field: Legacy PocketBase collections may lack created/updated system fields. Dashboard sort=-created returns 400. Patch built JS to use sort=-id.
• Double /api prefix: PocketBase SDK's buildURL adds /api/ to the path. Proxy must NOT blindly prepend another /api/.
• Refreshed browser snapshots: After navigation, refs change. Always re-snapshot before clicking nav links.
• Missing onClick handlers: Subagents frequently create buttons with text but no onClick — verify every button in generated code has an attached handler.
• AI function signature mismatches: Subagents may write UI code calling AI functions with different signatures than the actual ai.ts module. Always cross-check the handleAiWrite/handleGeneratePriorities/handleAiSuggest call signatures against the exports in src/lib/ai.ts.
• Wrong PB collection names: Original v1 code uses underscore names (repair_orders) but the PocketBase instance uses camelCase (repairOrders). Subagents copy the v1 name verbatim → query fails. Always verify collection names against the actual PB instance before dispatching.
• Lazy-loaded pages and providers: Pages wrapped in React.lazy() don't get providers from parent context if the provider is mounted after the lazy boundary. Mount <ToastProvider> and other context providers ABOVE <Suspense> in App.tsx.