Orchestrating 16 Cursor subagents in a single session - what actually stuck

What a subagent is

Cursor (also Claude Code, Cline, Aider) can spawn subagents from a main agent. Each subagent gets an independent task prompt, independent context window, independent model instance. It can call tools, read files, write files. When done, it returns the result to the main agent, which integrates.

The critical property is parallelism. Four subagents running simultaneously - each for 30 minutes - the main agent gets 120 minutes of output in 30 real-time minutes.

Why I opened 16 that day

The project is datenix.xyz, a B2B data API. The main line was wiring Creem payment into a Cloudflare Worker. That's specific, technical, one-person-can-do work. But at the same time I needed to:

• Study Creem's full API (43 endpoints, 12 webhook types, various payload shapes)
• Compare Creem vs Stripe, decide which is primary
• Analyze existing worker code, decide integration point
• Design pricing tiers
• Write complete test suite
• Write admin CLI
• Write monitor script
• Rewrite the landing page (add Trust & Safety block, About page, Contact page, refund badges)
• Research KYC approval patterns (Creem's public case studies, rejection cases)
• Write launch runbook (post-KYC 6 commands)
• Write SESSION_HANDOFF (for the next agent to pick up)
• Decide if there's a fleet-layer abstraction worth building
• Decide whether to migrate to TypeScript

If I did all of this by myself, it's three days. If I gave it all to a single subagent, its context window would explode. Divide and conquer. Each subagent takes one focused task, uses the 4.7-fast model, completes in 30-40 minutes. Four in parallel gets me four 4000-5000-word deep-dive reports in about an hour.

Wave is my time unit

I organized subagents into waves of four. Reason:

• Four is not crowded - Cursor UI can display all four subagent statuses simultaneously
• Each wave completes → I review results → I decide the next wave → tight feedback loop
• Four waves = one full iteration (probe → design → build → close out)

Four waves that day:

• W48 - Probe Creem (full API reference / Stripe comparison / integration plan / pricing)
• W49 - Build (TypeScript providers / admin CLI + monitor / landing v4 / test suite)
• W50 - Close out (launch runbook / refactor plan / bootstrap enhancement / SESSION_HANDOFF consolidation)
• W51 - Deep-dive KYC (approval patterns / product allowability / landing polish / CN payout strategy)

Between waves, ~15-20 minutes of consolidation - stage each subagent's output into the project, check for conflicts.

Prompt is the only steering wheel a subagent has

Subagents have no short-term memory. Each spawn is a fresh context. It only has what's in the prompt. Bad prompt → subagent drifts.

My subagent prompt template goes like:

• Context (verified facts) · 5-10 lines telling it what's already confirmed, where the code lives, which env vars are set. This prevents it from guessing.
• Sister-project asset · 3-5 lines telling it what it can reuse from sibling projects. Prevents wheel reinvention.
• Goal · 1-2 paragraphs stating the deliverable.
• Deliver · Sections listing exactly what to produce, few hundred words each.
• Constraints · Explicit taboos, e.g. "never touch this file", "compact return 500-800 words", "no fabrication".
• Budget · 30-40 min. So it knows the time envelope.
• Write to · Explicit output path.

With this template, subagent drift rate is ~10%. When it drifts, root cause is usually my Context section wasn't specific enough - subagent guessed. Same principle as onboarding a new employee.

Reality check is the biggest cost I pay

The biggest risk with subagents is confident fabrication. That day's W52 wave, three of the four subagents came back with a "reality check" section - explicitly flagging where my brief didn't match what's on disk:

• W52-2: "KL isn't a kitchen brand - it's pickleball. 'Kitchen' = pickleball non-volley zone. All 30 SKUs, 100+ city pages, 30+ guides are pickleball accessories."
• W52-3: "SleepGuard's SPEC actually already committed to DTC silicone mouth-tape subscription. Your brief asking to choose SaaS/DTC/content is stale."
• W52-1: "DocStruct's 22 files exist but the business layer is all stubs. checkout points to a fake product_id, webhook has 4 TODOs, src/lib/ is empty on disk."

Each reality check is worth its weight in gold - prevents me from acting on a wrong assumption for the next 20 hours. My prompt explicitly demands: "read disk first, don't trust my brief, flag discrepancies immediately." This one line is probably the most important line in the subagent workflow.

Task-splitting experience

A wave of 4 subagents should be doing complementary, not competing, work:

• Complementary: one probes API, one compares competitors, one reads code, one designs pricing. Four fully non-overlapping directions. Four reports stitch together directly.
• Competing: All four asked to write "integration plan". Four plans come back. I have to merge, resolve conflicts. Time cost is higher.

Most of the wasted cycles I've paid for were competing-type assignments. Going forward, four positions per wave split by "probe / compare / build / consolidate" or "feature A / feature B / feature C / synthesis."

What the main agent must do

The main agent isn't just an orchestrator. It has several must-dos:

• Stage each wave's output into the project. Check syntax, path collisions, naming.
• Read what the subagent wrote - really read it. Once, W49-2's admin CLI had a small async-wrapping bug - main agent caught it in 5 minutes.
• Update handoff / TODO / DECISIONS so the next wave's subagent reads the latest reality. Easy to skip on long projects.
• Compact each wave's output. Subagent reports are 3000-5000 words. Fed straight into the next wave, context window buckles. Main agent must compress into 200-500 word summaries, pass only the key decisions to the next wave.
• Decide which subagent suggestions to adopt. W50-2 suggested "defer TypeScript refactor to Y1." Adopted. W49-2 suggested "add a KV cache layer." Not adopted - traffic hasn't warranted caching yet.

Is 16 in a day too many?

At the end of that day, main agent context was near full. Any more and I'd need to start a new session with resume. Rough estimate:

• Each subagent's compact return ~500-1000 tokens
• Main agent processing, plus own code edits, plus tool calls, plus token overhead per subagent ~3000-5000 tokens
• 16 subagents ~50,000-80,000 tokens in main context

Model with 200K context can fit another 20-30 subagents. But the more crowded main agent gets, the lower output quality. My current practical limit is 12-16 subagents per session. Beyond that, spin up a new session, have the fresh main agent resume from the handoff doc. This is why I obsessively write SESSION_HANDOFF at session end.

The counter-intuitive conclusion

The less code the main agent writes, the more the whole system produces. That day, I personally typed about 1000 lines. Subagents wrote the rest. But my time went into:

• Writing subagent prompts (500-800 words each × 4 = 2000-3000 words per wave)
• Reading returns (500-1000 words each)
• Staging files, syntax checks, running tests
• Deciding the next wave

This is more like a tech-lead's job, less like a developer's. I used to think AI tools' value was writing code for me. That day changed my mind - AI tools' real value might be letting me think about multiple things at once. A human brain runs one task. But a human can supervise four subagents.

Actual daily pattern this has become

When I hit a complex task now, I actively ask: "can this be split into 4 parallel subagents?"

• Customer reports 3 bugs. Old me: fix them sequentially. New me: spawn 3 subagents, each fixing one, main agent tests + consolidates. 3x throughput.
• Market research: "should datenix price at $X or $Y." Old me: hours of solo Googling. New me: 3 subagents - one on competitor pricing, one on user pain in target forums, one on unit economics. Main agent synthesizes decision.

The pattern is a perfect fit for one-person product work. Solo dev is fast but single-threaded, easy to miss things. With subagents, coverage is wider, decision quality is higher.

The slow-growing worry

Slight concern about becoming dependent on subagents to the point my own coding skill atrophies. I still write core logic personally - the 12-event webhook dispatcher, the HMAC validator, the D1 migration. Only peripheral work goes to subagents - tests, docs, admin CLI, research reports. And the main agent must read every line the subagent writes. Sign off. Otherwise, a production bug leaves you blind on where to start.

Solo product-building means your brain is the biggest asset. Tools amplify the brain, not replace it.

At end of that day, before shutting down, I wrote a 30 KB handoff document of the entire session timeline. Because I know - tomorrow morning, 60% of today's detail will be gone from my head. But the subagents won't forget, because they are that document.