Skip to content

Parallel AI-Agent Workflow for CreatorTrack (Briefing + 3-Agent Trial Plan)

URL: https://mkdocs.justinsforge.com/memory/handoffs/parallel-agent-creatortrack-workflow-2026-06-18/

Date: 2026-06-18 Author: [Claude Code] Goal: Run multiple AI agents in parallel on the one integrated CreatorTrack app, each with its own live preview, then merge cleanly. This briefing is the canonical design; the last section is a concrete 3-agent trial to run first.

1. The problem (why this is hard)

CreatorTrack is one integrated app, not separable products. The shell, the component kit, workspace.css, and the Postgres schema are shared ground. Most real features touch the sidebar and the DB. So "decompose into disjoint lanes" only goes so far: parallel agents will touch shared files and change the same schema concurrently. The tensions:

  • Isolation vs. integration: agents need separation while building, but the end product is one merged codebase + one DB.
  • Live-preview cost: each preview needs its own next dev server (~1.5-2 GB under load); dev servers are the memory hog.
  • Finite hardware: Finn is 32 GB total, shared across the whole fleet; Console (the dev VM) gets ~12 GB and that is effectively the entire dev budget.
  • Shared DB under concurrent schema change: multiple agents altering one schema, then reconciling into one live DB.

2. The model that actually works

Per-agent full worktree + own branch + own dev server + own database, then a serial, AI-reconciled merge.

Layer Mechanism Status today
Code isolation git worktree per agent at /home/justinwieb/forge-suite-wt/<branch>/ Working (e.g. mkt-colors)
Live preview one next dev per worktree on a unique port 306N, exposed via Cloudflare tunnel hostname Working (main = :3060 / dev.creatortrack.ai)
DB isolation each worktree points at its own Postgres DB (a TEMPLATE clone on CT 109) NOT wired yet (see gap)
Migrations SQL files in forge/data/workspace/migrations/, applied by forge_workspace_migrate.py (admin role; lifeos_app cannot run DDL) sequential numbering (0040 latest) = collision risk
Merge serial, AI-reconciled (not just git 3-way) manual

3. The hardware reality (32 GB total Finn)

The production fleet (Frigate, Plex/arr, AdGuard, n8n, CT 109, HA, immich, minecraft) already eats ~18-20 GB. Console's ~12 GB is the dev budget, and it can't grow without starving production.

Two reframes that change the math:

  1. Databases live on CT 109, not Console. TEMPLATE-clones share one Postgres instance's shared_buffers; in dev the data is tiny. They cost Console zero RAM. The only Console squeeze is next dev servers.
  2. Decouple agent-editing from preview-running. An agent (~0.5 GB) spends most of its time editing/reasoning, not rendering. A dev server is only needed when you watch or when the agent must visually verify.

Console budget at 12 GB: ~2 GB OS + N agents (0.5 GB) + M hot dev servers (1.5-2 GB). Practical: 5 agents editing, but only 2-3 hot previews, round-robined. Add 6-8 GB NVMe swap on Console so idle dev servers page out instead of OOM.

What more RAM buys: 64 GB = 5 comfortable always-on previews. 128 GB = RAM stops being the limit; bottleneck moves to CPU (Turbopack compile, MS-01 cores; real ceiling ~6-10 actively-building) and to merge throughput. 32 GB is the "do it well, just not all-on-screen-at-once" tier.

4. The merge is AI-reconciled, not git-mechanical (the real unlock)

Git's 3-way merge is line-based and has two failure modes on shared files: (a) conflict markers (visible), and (b) clean auto-merge that is semantically broken (both agents add a nav item on different lines; git keeps both with no warning; logic is now duplicated or the layout breaks). Git thinks it succeeded.

AI reconciliation catches both, including (b), by reading each branch's intent plus the full combined diff, not just the conflict markers. Same for migrations: read all sets, dedupe overlapping column adds, reorder for dependencies, emit one coherent ordered set.

Consequence: this relaxes the disjoint-lane requirement. Agents CAN all touch the shell/css, because the merge step is semantic. But it requires:

  1. Each agent leaves a 3-5 line intent note on its branch (input to reconciliation).
  2. Integrator pulls all branches, collects conflicts and clean auto-merges.
  3. AI reviews the full combined diff against every intent (this is where silent-semantic bugs get caught; cannot be skipped).
  4. Migration sets collapsed into one ordered, deduped set.
  5. Validate end-to-end: fresh TEMPLATE clone, apply combined migrations, boot the app, one preview green. Per doctrine, reconciliation without a real run is "untested," not "merged."
  6. Promote to the dev DB + main.

Limit: one reconciliation wave safely holds ~5 overlapping branches. Past that, merge in waves. So the natural unit is 5 agents, and the bottleneck correctly lives at the merge.

5. The gap to close before true DB isolation

forge-suite/lib/secrets.ts forgeDataEnv() reads ~/.forge-secrets/forge-data.env directly and ignores process.env. So every worktree currently shares one workspace DB; concurrent schema changes fight. To isolate:

  1. Patch forgeDataEnv() so process.env.PGDATABASE (and friends) override the file value when set. Backward-compatible: unset = current behavior.
  2. Per-worktree .env.local (or exported PGDATABASE) names that worktree's DB clone.
  3. A clone helper: CREATE DATABASE ct_<branch> TEMPLATE creatortrack_dev_base; on CT 109, run with the admin role.
  4. Apply that branch's migrations against its own DB via forge_workspace_migrate.py pointed at PGDATABASE=ct_<branch>.

6. Concrete 3-agent trial plan

Target: validate the full loop (worktree -> own DB -> own preview -> AI merge) at small scale, without disturbing the live ct-build2_Opus48 session on main.

Ports / hostnames: main stays :3060/dev.creatortrack.ai. Trial agents use :3061/3062/3063 -> dev1/dev2/dev3.creatortrack.ai (tunnel hostnames via /cf-add).

Steps: 1. Patch lib/secrets.ts for env override (section 5.1). Commit on main (or a setup branch) so all worktrees inherit it. 2. Build scripts/forge_suite_agent_bootstrap.sh <branch> <port>: creates the worktree, clones ct_<branch> from creatortrack_dev_base, writes per-worktree env (PGDATABASE + PORT), npm ci if needed, applies migrations to the clone, starts next dev --webpack -p <port>, adds the tunnel hostname. 3. Seed creatortrack_dev_base once (clone of current workspace DB schema + minimal demo data). 4. Spawn 3 agents (/spawn opus), each with: its worktree path, its DB name, its preview URL, the intent-note requirement, and one task. 5. Let them build; watch dev1/2/3 round-robin (only 2 hot at once on 12 GB). 6. Merge wave: pull all 3 branches, AI-reconcile shared-file + migration conflicts, validate on a fresh clone, promote.

Decisions needed before running: (a) the 3 tasks, (b) whether to do full DB isolation now or run a code-only first pass (shared DB, only if the 3 tasks don't touch schema).

6b. Trial state (built 2026-06-19, PAUSED before agent spawn)

Plumbing built and proven end-to-end; agents not yet spawned (Console at ~2.1 GB available + swap engaged, ct-build2 live on main, so spawning held per Justin).

  • DONE: env-override patches (lib/secrets.ts, forge_workspace_db.py).
  • DONE: forge_suite_dev_base.sh + forge_suite_agent_bootstrap.sh written, executable, registered (reference_creatortrack_parallel_dev).
  • DONE: creatortrack_dev_base built (schema-only from lifeos + seeded, 6 workspaces).
  • DONE: 3 slots bootstrapped + verified serving HTTP 307 (login redirect = healthy):
  • agent-slash-commands , DB ct_agent_slash_commands , :3061 (slash commands + databases)
  • agent-gmail-integration , DB ct_agent_gmail_integration , :3062 (Gmail email integration)
  • agent-usage-tracking , DB ct_agent_usage_tracking , :3063 (page usage / records tracking)
  • Dev servers currently IDLED to free RAM for ct-build2. Restart any with bash ~/forge/scripts/forge_suite_agent_bootstrap.sh <branch> <port> (idempotent: reuses worktree + DB, just restarts the server).

To resume the trial: free memory (commit/quiesce ct-build2, or bump Console RAM), restart the slot servers, then /spawn opus one agent per slot with its worktree path + DB name + preview URL + the one task + the intent-note requirement.

7. Open items / next

  • Build scripts/forge_suite_agent_bootstrap.sh + a forge_suite_dev_supervisor.sh (keep N hot, start/stop by branch).
  • Patch lib/secrets.ts env override.
  • Decide the bare git remote (Finn git init --bare) to make multi-branch review/merge cleaner; forge-suite has no remote today.
  • Consider switching new migrations to timestamp prefixes during parallel waves to kill the 0041 collision.

8. 128 GB resume runbook (scale to 3 / 4 / 5 agents)

Justin bought 128 GB (2x64 GB DDR5 SO-DIMM) for Finn (MS-01). Works despite Intel's 96 GB official spec; expect a lower memory clock. This is the exact sequence to go from "plumbing paused" to N agents running.

Step 1 , hardware (one-time): - Install both 64 GB SO-DIMMs (MS-01 has 2 slots; replace both 16 GB sticks). - Flash the latest Minisforum BIOS BEFORE relying on it , 128 GB stability on the MS-01 depends on recent BIOS, or you risk memory-training no-boot. - Boot, confirm free -g on Finn shows ~125 GB.

Step 2 , give Console the headroom (on Finn host): Console is VM 103, balloon off, so a memory change needs a VM stop/start (a maintenance reboot , it kills sessions on Console, so do this deliberately). 

# on Finn:
qm set 103 -memory 65536      # 64 GB (or 49152 for 48 GB)
qm stop 103 && qm start 103   # apply (balloon off = restart required)
After 128 GB: host 128, VMs (Console 64 + HA 4) = 68, LXC fleet ~30 = ~98 committed, comfortable, no swap.

Step 3 , bring the slots back (on Console): Base DB creatortrack_dev_base persists. The 3 worktrees + DB clones persist. Just restart the dev servers (idempotent): 

bash ~/forge/scripts/forge_suite_agent_bootstrap.sh agent-slash-commands   3061
bash ~/forge/scripts/forge_suite_agent_bootstrap.sh agent-gmail-integration 3062
bash ~/forge/scripts/forge_suite_agent_bootstrap.sh agent-usage-tracking    3063

Step 4 , scale to 4 or 5 (add slots): 

bash ~/forge/scripts/forge_suite_agent_bootstrap.sh agent-<name4> 3064
bash ~/forge/scripts/forge_suite_agent_bootstrap.sh agent-<name5> 3065
Each prints its preview URL (http://100.97.43.104:), DB name, and migrate command.

Step 5 , spawn the agents: One /spawn opus per slot. Each prompt must include: the worktree path, the DB name (PGDATABASE=ct_), the preview URL, the ONE task, the brand/component rules, and the requirement to leave a 3-5 line intent note on its branch (input to the AI-reconciled merge, section 4). Migrations: timestamp-named files in forge/data/workspace/migrations/, applied with PGDATABASE=ct_<branch> python3 forge_workspace_migrate.py.

Capacity at 64 GB Console: 5 always-on hot previews + agents + integrator, all resident. Binding limit becomes CPU (Turbopack compile across many hot servers; ~6-10 actively-building ceiling on MS-01 cores) and merge-wave throughput (~5 overlapping branches per reconciliation), NOT RAM.

Merge when the wave is done (section 4): pull all branches, AI-reconcile shared-file + migration conflicts, validate combined migrations on a fresh creatortrack_dev_base clone, boot + preview green, then promote to lifeos + main.