parallel-fullstack-scaffold

Parallel Full-Stack Scaffold

When to Use

• Building a new complete web app (10+ files) from a spec or plan
• DB schema already exists (or is well-defined)
• Design system / color tokens are specified
• You want speed over incremental review (scaffold first, fix later)

vs. subagent-driven-development: That skill is sequential task-by-task with review loops. This skill is "blast out the whole app in parallel, then build-test-fix." Better for greenfield scaffolds; worse for incremental features on existing codebases.

Prerequisites

Before delegating, gather ALL context yourself: 1. DB schema — Run \d table_name for every relevant table. Get column names, types, FKs. 2. Sample data — Query a few rows from key tables so subagents write realistic code. 3. Design tokens — Colors, fonts, spacing, component patterns. 4. Screen list — Every screen with its elements, data sources, and user flows. 5. API endpoints — Full list with query params, joins needed, response shapes. 6. Existing infra — Check for pre-existing nginx configs, PM2 processes, repos.

The Split: 3 Parallel Workstreams

Workstream 1: Frontend (all screens + components)

Largest workstream. Provide: - Complete file list with paths - Full DB schema (so hooks/types are correct) - Design system tokens - Screen-by-screen specs with every UI element - API endpoint signatures (so hooks call the right paths) - State management structure

Workstream 2: Backend (API server)

• Complete DB schema with column types
• Every endpoint with SQL query logic
• Auth/CORS requirements
• Static file serving + SPA catch-all
• Express 5 gotchas (/{splat} not )

Workstream 3: Config + Assets (build config, PWA, icons)

Smallest/fastest. Usually finishes first. - Vite config with aliases and proxy - index.html with meta tags - PWA manifest + service worker - Icon generation (SVG → PNG via ImageMagick) - .gitignore

Context Tips for Subagents

Be exhaustive. Subagents have NO conversation history. Include: - Every table schema with column names and types - All 3 locations, all reservation statuses, all class types — real data - Full color palette with hex codes - Every screen element described explicitly - Import paths and alias conventions (@/ → src/) - Specific library versions and API patterns

Don't say "see the plan file." Copy the relevant content into the context string. Subagents reading files burns iterations.

After Delegation

1. Check file output

find src -name "*.tsx" -o -name "*.ts" -o -name "*.css" | sort

2. Build test immediately

npx vite build 2>&1 | tail -30

Build errors reveal missing imports, type issues, bad paths. Fix these directly — don't re-delegate.

3. Start server + smoke test

pm2 start npx --name app -- tsx server.ts
curl localhost:PORT/api/health
curl -o /dev/null -w "%{http_code}" localhost:PORT/

4. Visual verification

Use browser_navigate + browser_vision to check each screen looks correct.

5. Fix forward

Small issues (wrong import, missing type, bad query) — fix directly with patch. Large issues (missing screen, broken API) — delegate a focused fix subagent.

Pitfalls

• Subagent credit/token limits: The frontend workstream is huge (20+ files). It may hit limits. Check what was written and fill gaps manually. The subagent usually writes files in order, so check the last few in the list.
• Duplicate context: Both frontend and backend subagents need the DB schema. That's fine — duplication is better than missing context.
• File conflicts: If two subagents both try to write vite.config.ts or index.html, one wins. Assign config files to exactly one workstream (usually Workstream 3).
• PM2 duplicates: If a prior session already created a PM2 process with the same name, you'll get duplicates. Check pm2 list first and delete stale processes.
• Approval system: Terminal delete commands may trigger approval prompts. Scaffold in /tmp and copy, or write files directly without deleting first.
• Express 5 catch-all: ALWAYS use /{*splat} not * for SPA routes. This is the #1 deployment bug.
• DB password: Double-check the password in server.ts matches the actual DB password. Subagents may use the wrong one from context.

Efficiency

Typical timing for a 12-screen React + Express app: - Workstream 3 (config): ~2 min - Workstream 2 (API): ~5-6 min
- Workstream 1 (frontend): ~6-8 min - Build + deploy + test: ~3 min - Total: ~10-12 min wall clock (parallel)

vs. sequential: ~30-40 min

When NOT to Use

• Adding features to an existing app (use subagent-driven-development)
• Small apps (< 5 files) — just write them directly
• Apps requiring complex business logic — need incremental testing
• When you don't have the DB schema yet — scaffold the DB first