Skip to main content
Synced from the repo — do not edit here

Canonical source: docs/claude/atlas-dealrunner-roadmap.md. This page is generated by docs/scripts/sync-handbook.mjs. Edit the source file in the repo; changes appear here on the next build.

Atlas Deal-Runner Roadmap — one engine, three counterparty types

Thesis (George, 2026-07-13): Sales, network-brokering, and fundraising are the same primitive: a multi-party, multi-step deal process — source targets → personalized outreach → back-and-forth qualify/negotiate → documents + diligence → close → track. Atlas therefore needs ONE "deal-runner" engine, proven on three progressively harder counterparty types. Each test hardens the same muscle and produces the proof asset the next test sells on.

References that anchor the thesis:

  • Boardy — AI superconnector; raised an $8M seed (and later its own fund) largely because investors were so impressed by the AI's utility that they asked to meet the team. Lesson: utility is the pitch — demonstrable autonomy beats slides.
  • CVC Capital Partners — used AI to run an M&A process: acquirer back-and-forth, due-diligence inquiries. Lesson: the interactive diligence loop is automatable.

Memory: project_atlas_dealrunner_roadmap. Related: docs/claude/agent-fleet.md, docs/claude/growth-suite-scoping.md, COO operator plan.

The engine (shared across all three tests)​

StageComponentStatus
Source & track counterpartiesGrowth CRM (growth_leads, functions_growth_crm.py)✅ exists (clinic leads)
Personalized outreachGrowth campaigns (email/SMS), Slack, AI call center (scoped)✅ partial
Qualify / negotiate (back-and-forth)Atlas conversational agent + deal record🔶 the core gap — conversations exist, deal-state machine doesn't
DocumentsContract packet: basis-functions/contract_templates/ (MSA + Order Form + BAA, variable-driven, branded) + render_packet()✅ built 2026-07-13
E-signDocuSign JWT integration (functions_docusign.py): auth ✅ proven, envelope send with anchor tabs 🔶 testing, webhook → provision ⬜🔶 in flight
MoneyStripe: subscriptions ✅; one-time/annual invoice + Products/Prices SKUs ⬜; Quotes (sign-and-pay) ⬜🔶 partial
Close → provisionadd_clinic + white-label config + set_custom_billing✅ pieces exist, not wired to signature event
OnboardOnboarding-intake checklist automation (send, track, ingest uploads, nudge)⬜ designed (from the Optimal email), not built
Diligence / Q&A from live dataCOO operator reads MRR/pipeline/engagement — READ only today🔶 read exists, respond doesn't

Design rule: every piece is built as a reusable engine stage, not a sales-only feature — Test 2 and Test 3 re-point the same stages at different counterparties.

Test 1 — Atlas runs a SALES process end-to-end (NOW)​

Definition of done: a clinic deal goes from growth_leads prospect → outreach → terms agreed → packet generated → DocuSign envelope sent + signed → Stripe invoice/subscription → clinic provisioned (incl. white-label config) → onboarding intake sent and tracked — with George approving at confirm-cards, not doing the steps.

Manual dry-run completed 2026-07-13: Optimal Performance LLC (Ryan Verchota) — $8,995 annual platform + $6,805 white-label annual = $15,800; packet generated from templates, invoice via Stripe, onboarding checklist emailed. Every step of the manual run is the spec for its automated counterpart.

Remaining build (tracked on the board under the epic):

  1. E-sign arm completion — envelope send test on demo → DocuSign Connect webhook (signed → deal state + provisioning trigger) → production Go-Live (needs ~20 demo API calls, then promote; swap authServer to account.docusign.com + prod IDs/key).
  2. Deal record + CRM wiring — deals (or extend growth_leads): terms schema (the variables.json fields) + state machine (draft → sent → signed → paid → provisioned → onboarding → live). Atlas fills terms from lead + conversation.
  3. Stripe money arm — standard Products/Prices SKUs (Core annual/monthly, white-label setup/maintenance); one-time invoice creation (annual-upfront, DRAFT for George to send); evaluate Stripe Quotes + DocuSign pay-on-sign connector for unified sign-and-pay.
  4. Onboarding-intake automation — the Optimal checklist as a structured intake: per-item tracker + upload slots, Atlas ingests as items arrive, nudges missing, marks onboarding complete; feeds provisioning config (branding, forms, services).
  5. Provision-on-signature — webhook → create clinic, apply white-label config, activate billing, kick onboarding. (Confirm-card gated until trust is earned.)

Proof metric: next real deal closed with ≤3 George touches (approve terms, approve send, countersign). Time-to-live from verbal-yes: < 1 week.

Test 2 — Clinician-network SUPERCONNECTOR (the moat)​

Goal: turn "hundreds of clinics" (a customer list) into a network whose value compounds: hiring matches, cross-specialty patient referrals, protocol/tips exchange, group buying leverage, benchmark insights.

Why Atlas wins here (vs Boardy): Boardy must interview people by phone to build profiles. Atlas already holds the network's data — each clinic's services, protocols, staffing, capacity, (de-identified) outcome patterns. Profiling is a query, not a conversation; conversations (Slack, in-app, call-center outbound) only fill the intent gaps ("looking to hire", "want referrals for X").

Build shape (scoping to firm up when Test 1 is proven):

  1. Needs/offers profile per clinic — auto-derived + conversationally enriched.
  2. Matching engine — needs ↔ offers across the network (hiring, referral, protocol expertise, equipment/group-buy), with consent + privacy boundaries (tenant isolation stays absolute; matches trade on metadata, never PHI).
  3. Brokering UX — Atlas makes the double-opt-in intro (Slack/email), tracks outcomes, learns which matches worked (continual-learning signal).
  4. Network effects instrumentation — measurable: intros made, accepted, value attributed. This number is a fundraise asset.

Blocked by Test 1 (deliberately): the deal-runner conversation/matching muscle and the trust model come from proving sales first.

Test 3 — Atlas runs an INVESTMENT process end-to-end (fundraise)​

Timing anchor: late-Oct 2026 raise (editorial calendar already times Product Hunt launches + press to it).

The Boardy lesson applied: Tests 1 & 2 ARE the raise. The pitch is "this AI closed N clinics autonomously and operates a compounding clinician network" — investors meet the team because the machine impressed them. Test 3 automates the last mile:

  1. Investor targeting — thesis/stage/check-size matching (same matching engine as Test 2, different counterparty data).
  2. Outreach + scheduling — same outreach arm.
  3. Data room + interactive diligence — the CVC piece: Atlas answers diligence questions from live metrics (MRR, retention, network growth, cohort data). COO operator already reads these; the raise version responds with them — permissioned, logged, honest (no forward-looking fabrication; flag-don't-guess).
  4. Back-and-forth to close — term negotiation stays George-gated; Atlas runs process, follow-ups, document flow (the deal-packet engine with different papers).

Blocked by Tests 1–2 for proof, but the diligence-Q&A capability can be built earlier — it's also useful for customer security reviews (Trust Center synergy).

Sequencing rules​

  1. Finish Test 1 before building 2/3 — it de-risks the pattern and generates the proof the others sell on. (Exception: capture Test-2/3 signal cheaply when it's free — e.g. log clinic needs Atlas hears in support conversations.)
  2. Every stage ships confirm-card-gated first; autonomy is earned per stage via the existing goal-gate / earned-autonomy ratchet (#224 discipline applies here too).
  3. Outward-facing sends (outreach, envelopes, invoices, intros) NEVER go out without explicit approval until George flips a stage to autonomous.

Part II — Engineering it: from idea to robust system

The failure modes of "AI runs a deal" are known and boring: hallucinated terms, numbers drifting between artifacts, dropped threads, double-sends, negotiating outside authority, and answers invented under diligence pressure. Each gets a structural mitigation, not a prompt instruction. The manual Optimal dry-run already produced live specimens (the ACH email said $15,450 while the contract said $15,800 — number drift; the signer name was wrong in v1 — unvalidated fill). Design so these classes cannot recur.

II.1 The deal object — single source of truth​

deals/{dealId} (Firestore; camelCase):

counterpartyType: clinic | network_member | investor
leadRef, contacts[{name,email,role}]
state: sourced → contacted → engaged → terms_proposed → terms_agreed
       → docs_sent → signed → paid → provisioned → onboarding → live
       (terminal: lost{reason} · parked{until})
stateMeta: {enteredAt, staleAfterDays, nudgeCount, escalated}
terms: { ...exactly the variables.json schema... }        ← numbers live HERE only
negotiationEnvelope: {floorAnnual, ceilingDiscountPct, allowedAddons[],
                      achDiscountMax, requiresGeorge: [term names]}
artifacts: {docusignEnvelopeId, stripeInvoiceId, contractHashes{},
            onboardingIntakeRef, artifactTermsHash}
thread: subcollection [{ts, channel(email|slack|call|docusign|stripe),
                        direction, summary, raw ref, actor}]
approvals: [{action, decidedBy, decision, ts, confirmCardRef}]
autonomyLevel per stage: draft_only | confirm_card | autonomous

II.2 The seven invariants (what makes it robust)​

  1. One source of numbers. Every outward artifact — contract, invoice, email copy, Slack summary — renders from deal.terms. Nothing hand-typed. The $15,450/$15,800 drift class becomes structurally impossible. artifactTermsHash = sha256(terms) stamped on each artifact; mismatch = artifact void.
  2. Terms changes void artifacts. Any terms write after docs_sent invalidates envelope/invoice → regenerate + re-approve (the #219 definitionHash discipline, applied forward).
  3. Idempotent outward actions. Envelope send, invoice create, intro email: claim-transition (claim_transition(), #304) + dedup key ({dealId}_{artifactType}) — double-send impossible even under at-least-once triggers. (Same bug class we fixed in growth publish tonight.)
  4. Negotiation envelope. Atlas negotiates ONLY inside negotiationEnvelope; anything outside (price below floor, unusual term, any requiresGeorge field) → escalate with a drafted recommendation, never improvise. The envelope is set (and signed off) at terms_proposed.
  5. No deal silently stalls. Every state has staleAfterDays; a heartbeat sweep (reuse heartbeat_tasks) nudges (drafted, gated), then escalates to George after N nudges. A deal-runner's real superpower is perfect follow-up.
  6. Outward text passes fact gates. Claims-linter class checks on every counterparty-visible artifact: no invented capabilities, prices only from terms, no forward-looking promises (ship dates from a vetted list only).
  7. Autonomy is earned per stage per counterparty type. Everything starts draft_only/confirm_card; the earned-autonomy ratchet (#224 discipline, accept/edit/reject signal — capture already built for copilot confirm-cards) promotes stages individually. Kill switch (atlas_kill.py) covers all sends.

II.3 The missing hard piece: inbound conversation ingestion​

Everything filed so far automates OUTBOUND. The "back-and-forth" half — counterparty replies driving state — is the real unlock and the biggest gap:

  • A deal email identity (e.g. deals@ on the connected domain) + inbound webhook (extend functions_email_webhooks.py); thread-match on In-Reply-To + sender→contact → append to deal.thread.
  • Atlas classifies the reply (interested / question / objection / terms push / ready to sign) → proposes a state transition + DRAFTS the response (confirm-card). DocuSign Connect + Stripe webhooks feed the same thread, so the deal timeline is complete across channels.
  • Later: same ingestion powers Test 2 intros and Test 3 investor threads.

II.4 Evals and replay (trust needs receipts)​

  • Replay harness (tools/replay_deal.py): feed the recorded Optimal deal through the machine; assert generated artifacts byte-match (modulo dates) what we actually sent. Every schema change re-runs the replay. (Same pattern as the watchdog replay harnesses, #308.)
  • Synthetic deals in CI: monthly/annual, white-label on/off, discount, edited-terms-after-send (must void), out-of-envelope ask (must escalate), duplicate webhook delivery (must not double-provision).
  • Funnel metrics in the COO brief: touches-per-close (target ≤3), time-to-live from verbal yes (<1 week), stall rate, nudge→response rate, envelope→sign conversion. Autonomy promotions require metric evidence.

II.5 Test 2/3 robustness notes (design now, build later)​

  • Test 2: profile = needs[]/offers[] with EVIDENCE pointers (derived from ops data, enriched conversationally under an attention budget — max 1 ask per clinic/month). Match = structured filter first, LLM rationale + confidence second; double-opt-in with expiry; accepted/declined feeds learning. Privacy tiers: derived-metadata (matchable) / consented (shareable) / PHI (never). Cold-start NOW for free: log needs Atlas hears in support/ops conversations into network_signals — costs nothing, seeds the matcher.
  • Test 3: a facts registry with provenance {metric, value, asOf, sourceQuery} — diligence answers may ONLY cite registry entries; no number generation. Unanswerable → "will follow up" + tracked task. Every investor interaction lands in the deal thread. Bonus: the same registry powers customer security-review Q&A (Trust Center).

II.6 Build order (the actionable seed)​

  • Phase A (now): #334 deal object + invariants 1–3 + replay harness seeded from the Optimal deal · #333 webhook (Connect HMAC → thread + state) → then demo Go-Live checklist.
  • Phase B: #335 money arm (SKUs + draft invoice from terms) · #336 onboarding intake · staleness timers (invariant 5).
  • Phase C: inbound email ingestion (own issue) · negotiation envelope + escalation (invariant 4) · funnel metrics in COO brief.
  • Gate: run the NEXT real clinic deal through the machine end-to-end (confirm-card mode). Only after that: #337 Test-2 scoping graduates to build.

Part III — The revenue operator: plays, intelligence, and the optimizer

Part II makes actions SAFE (rails). Part III makes Atlas PROACTIVE — the layer George actually means by "runs the process": mining accounts and the network for opportunities and executing revenue motions end-to-end. Architecture: this is the observation engine pattern (scan → score → ground → card) pointed at revenue instead of clinical attention, executed through the Part-II rails.

III.1 The play catalog (each play = trigger → fit score → evidence → action → outcome)​

PlayTrigger (signal from live data)Action (via rails)
AdoptionFeature in their plan, unused (no scribe minutes; forms unconfigured)Activation nudge w/ their-data evidence — retention lever, precursor to upsell
UpsellUsage implies unmet need: manual claims volume → RCM; heavy client chat + no app → white-label; booking volume near cap → tierTailored pitch citing THEIR numbers ("~240 claims/mo processed manually → RCM would collect ~$X") → deal record (upsell type)
Provider matchClinic A hiring / needs coverage ↔ clinic B capacity or candidateDouble-opt-in intro (Test-2 matcher)
Cross-referClient needs service their clinic lacks ↔ network clinic offers itConsent-gated referral (metadata only, never PHI)
Referral askAccount health high (engagement, growth, tenure, support sentiment) + a recent WIN momentAsk for intros, timed to the win
Case studyStrong measurable outcomes + high satisfactionOffer case study (feeds growth content engine directly)
Advocate assistProspect deal stalled at engaged/terms + matched happy customer (specialty/size/geo similar = "referral fit")Offer advocate a bonus to join a call with the fence-sitter
Win-back / saveUsage decline, payment friction, sentiment dropSave motion BEFORE churn (same detectors, defensive)

Fundraise (Test 3) reuses the catalog: investor targeting = provider match; data-room follow-ups = adoption nudges; warm-intro hunting = referral ask pointed at the cap table/network.

III.2 Account intelligence (what feeds the plays)​

Per-account derived profile, refreshed by the analytics engine (rollups exist): featureAdoption{} (entitled vs used), volumeSignals{} (bookings, claims, chat, client growth), healthScore (engagement + growth + support sentiment + payment hygiene), winMoments[] (revenue record, great outcome, hiring success), networkNeeds/offers[] (Test-2 profile), referralFit{} (who they could credibly persuade: specialty/size/geo match). Every play proposal must cite specific evidence rows from this profile — the observation engine's "grounding" discipline; no vibes-based pitches.

III.3 Robustness mechanics for THIS layer​

  1. Evidence-grounded or it doesn't fire — a play with no citable account evidence is dropped, same as ungrounded observations are.
  2. Attention budget per account — plays COMPETE for limited asks (e.g. 1 revenue-motion contact per account per 2–4 weeks); highest expected-value play wins the slot; the rest queue. Prevents Atlas becoming a pest — the quickest way to burn the network.
  3. Cooldowns + memory of "no" — declined referral ask → 90-day cooldown; declined upsell → cooldown + record reason; never blind re-asks.
  4. Incentive envelope (Part-II invariant 4, applied to rewards): referral bonuses and discounts come from a George-approved menu with caps; A/B variants only from a pre-approved set. Atlas optimizes WITHIN the envelope.
  5. Consent + privacy tiers — cross-refers and case studies are explicit opt-in; behavioral analysis uses tenant-internal derived metadata; nothing client-identifying crosses tenants, ever.
  6. Outcome attribution on every play — sent/answered/accepted/converted/$ attributed, per play, segment, and incentive variant. No attribution = no learning = no optimizer.
  7. Same autonomy ladder — every play starts as a confirm-card to George ("Offer Monarch RCM — evidence: … — draft attached"); promotion to autonomous is per-play-type, earned via the ratchet on accept/edit rates.

III.4 The optimizer (Layer 3)​

With attribution flowing: A/B incentive structures ($ vs credit vs % vs charity), copy variants, timing (post-win vs periodic), reward size per segment. Guardrails: pre-approved variant sets, minimum sample gates, no per-individual price discrimination games — segment-level only. Weekly learning digest reports play win-rates + promotes/demotes plays. This is the compounding asset: the play catalog gets measurably better every month, and BY THE RAISE the metric "Atlas-attributed revenue per month" exists — the Boardy proof, quantified.

III.5 Build additions (filed under epic #332)​

  • Account-intelligence profile (detectors over existing analytics rollups) — powers adoption/upsell/referral-fit/health.
  • Play engine (catalog, attention budget, cooldowns, outcome attribution) — runs on observation-engine pattern + Part-II rails.
  • Referral & advocacy program (asks, advocate-assist w/ bonus, case-study pipeline, incentive envelope, A/B) — the human-network revenue arm. Sequencing: after Phase A/B rails; adoption+upsell detectors first (pure internal data, no network coordination), then referral/advocacy, then matcher.