How ReacherX prepares an outreach plan

Grounding means giving the plan real information it can refer to. The system should not invent a social post or assume a messaging channel exists simply because that would make a neat plan.

Follow buildGroundedAutoPlanPrompt, parseAutoPlanTransportDraft, and validateAutoPlanDraftAgainstGrounding. They separate model-facing output from the application's accepted draft. Parsing valid JSON is only one check; the actions also need to fit the available context.

Save a plan through shared rules

convex/lib/outreachCore.ts owns createOutreachPlan. Before writing, it checks that the prospect belongs to the supplied workspace and user, verifies outreach eligibility, checks for an existing active plan, and validates task inputs.

This is an actual state choice in that function:

Review-required is the default, but an autonomous workspace behaves differently.

The single-active-plan rule also matters when two operations run close together. Updating an existing plan and creating another plan are different operations. Don't solve a duplicate-plan error by bypassing the check.

Keep selected people and instructions separate

For the user-selected batch path, start with convex/agents/tools/planBatch.ts and follow convex/lib/planBatchCore.ts. The user may give a shared instruction and different instructions for each selected person.

Those selections need real application IDs and workspace validation. A model-generated string that looks like a database ID is not proof of a valid selection. Trace the selection context and batch records rather than trusting names in the generated answer.

A batch can also have mixed outcomes. One person may already have a plan while another is ready for a new one. The UI should explain those results individually. “Batch failed” is not enough if some work succeeded.

Test the boundary that could send the wrong thing

Useful tests include a fabricated post reference, unavailable channel, duplicate plan, stale batch result, and instructions accidentally crossing between selected people. The repository's tests/plan-batch-core.test.ts and tests/agent-thread-target-selection.test.ts cover parts of that path.

Start with the user's batch-planning flow if you need to understand the controls before reading the code. Then follow outreach execution to see how an approved plan becomes durable work, waits for events, and reacts to replies.