Avoca — Internal

Appearance

Unknowns ​

A running checklist of questions that have surfaced during work on the Avoca engagement that are not yet answered or verified. As each one resolves, check it off and link to the doc / answer.

Many of these surfaced during the May 8 huddle with Jason (a coworker getting up to speed on a Salesforce-CRM equivalent project). The transcript exposed gaps in the mental model that no one had written down.

How to use

  • Each item is checkbox-style (- [ ] open, - [x] resolved with link).
  • When you find an answer, replace the checkbox with - [x] and add a → [link to the doc that explains it].
  • If a question turns out to be malformed or wrong, strike it through with ~~text~~ and note why.
  • This is the source of truth for "what do we still need to figure out" — not Slack scrollback.

Dev environment ​

  • [x] 🚨 BLOCKER — How does an FDE route in-call tool dispatches to their dev tunnel for a blueprint-managed multi-agent assistant? Resolved 2026-05-09. The mechanism already existed in main: every FunctionTool builds its server.url via buildUrl(this.path) (lib/voice-assistants/utils.ts), which reads process.env.NGROK_BASE_URL (defaults to https://app.avoca.ai). Setting NGROK_BASE_URL=<tunnel> in .env.local and re-running test-phone-sync writes per-tool URLs pointing at the FDE's tunnel into the squad. The trap that consumed half a day: assuming RESPONDER_COMMON_WORKFLOW_URL (which controls priority 2 — sub-agent assistant.server.url) was sufficient. It's not — Avoca's tools all carry priority-1 per-tool URLs that shadow priorities 2 and 3. Both env vars are needed. Documented in how-to/local-dev-env.md, vapi-squads.md, and gotchas.md F1. Blueprint editing remains a separate open question (next item).
  • [ ] Avoca's "blueprints" — confirmed in use for EAS. EAS's assistant Inbound Ponderosa declares Blueprint StraightAway Auto v11. This is Avoca's auto-shop agent template, likely deployed across multiple auto-shop clients. Open: where is the blueprint editor in Avoca admin, what does its config schema look like, and how is a dev variant created? Avoca's Vapi assistant serverUrl field is presumably generated from the blueprint, not authored independently — meaning blueprint edits are the canonical surface for K + L's prompt changes too.
  • [x] Where exactly does the dev tunnel URL go in the assistant config? Resolved 2026-05-09. The path is via Avoca's test-phone provisioning flow, not via direct edits to the prod assistant. Documented in how-to/local-dev-env.md.
  • [ ] When do you clone a Vapi assistant for dev work vs reuse a test team's existing assistant? EAS hasn't gone live so reuse works for now, but the general pattern isn't documented.
  • [ ] What's the canonical "staging team" pattern at Avoca? Some clients have <client>/staging teams. Are these conventional, or per-engagement? Do they hit prod database?
  • [ ] Test agent provisioning — how does an FDE get a dedicated dev/test assistant set up cleanly without manual Vapi+Avoca dance every time?

Vapi mental model ​

  • [ ] What are "squads" in Vapi? Saw them in the Vapi dashboard alongside Assistants and Workflows. Different orchestration model — when do you use squads?
  • [ ] Vapi "workflows" vs Vapi "assistants" — these are two different paradigms in Vapi's dashboard. EAS uses an assistant. When would you use a Vapi workflow instead?
  • [ ] System prompt structure — for EAS, the system prompt is one big monolith with embedded rule-section markers. Is this a per-team choice or the standard pattern? Is anyone using sectioned/composable prompts?
  • [ ] Runtime variable injection — Current Time and other runtime values are injected into the system prompt. Where in Vapi is this configured? ({{ }} template syntax? Vapi-specific feature?)

Avoca's prompt + agent surfaces ​

  • [ ] What does Avoca's blueprints feature do? Heard mentioned in a meeting as a way to set up agent interactions inside Avoca's admin instead of Vapi. Where does it live in the admin? When does it apply?
  • [ ] What does the Avoca admin's promptBuilder do? Saw the section but haven't dug in. Is it the canonical place to edit prompts, or a parallel surface to Vapi's system prompt field?
  • [ ] Sync direction: Avoca admin ↔ Vapi config — Jason was told it's one-way (Avoca admin writes to Vapi, Vapi-side edits don't propagate back). Verify, and document which fields specifically.
  • [ ] Phone number → assistant routing — where does this live? Vapi's "Phone Numbers" tab shows the inbound number → assistant mapping, but Sandy saw indications it's actually Avoca-side routing too. Which surface is canonical?

Caller identification + pre-call hooks ​

  • [ ] Pre-call customer lookup hooks — Jason mentioned existing hooks that look up the customer from the caller-id phone before the agent starts speaking. Where do these live in the avoca-next code? When do they fire?
  • [ ] Phone-to-customer collision — when a phone number changes hands (caller's number used to belong to a different AutoOps customer), the agent confidently identifies the wrong person ("the agents are calling me Natalie"). What's the disambiguation strategy?
  • [ ] Caller's timezone vs team's timezone — agent currently uses the team's timezone for all timestamps it speaks. Should it explicitly say "Mountain time" / "Eastern time" to disambiguate when the caller may be on a trip?
  • [ ] getTeamTimezone source — confirmed pulls from team config in Supabase. Verify how AutoOps's clientId-→timezone mapping is set; is it always present, or some teams missing?

Post-call extraction ​

  • [ ] Exact sequence of post-call workflow steps — webhook arrives → ??? → AutoOps mutation → email. The summarizer + classifier sit in the middle. What's the order, what's pre-built per-vertical vs per-CRM, what's customizable?
  • [ ] Summarizer prompt + extractor prompt — where do these live? Are they per-vertical (AUTO_SERVICE has its own), per-CRM (AutoOps has its own), or shared?

Testing surfaces ​

  • [ ] Hamming's exact role — regression testing? On-demand sims? Test-suite scheduling? All three? Sandy's mental model is "regression testing maybe also on-demand" but unverified.
  • [ ] Industry templates — does Avoca have per-industry agent templates (auto shop, plumbing, HVAC, garage doors, etc.)? Jason: "if it was like, say you were like maybe for you, honestly, I imagine they have multiple clients that are auto shops. So if you find out that some of the other clients, then you can come and search them in here and see how their agents are configured." Unverified.
  • [ ] The Test Suites tab in Vapi — Sandy saw test suites authored by Jordan. Is this the regression suite? Per-team or shared? When does it run?

CRM / AutoOps integration ​

  • [x] CRM customer→jobs lookup — was a blocker for getting off the in-call mirror sync. Resolved 2026-05-08: AutoOps added a customer filter on /clients/{clientId}/jobs requests, so we can fetch a single customer's jobs server-side without scanning the mirror. Triggered Plan J (sync migration).
  • [ ] Mirror readers besides the in-call lookup — autoOpsLookupCustomer + autoOpsGetJobs are the obvious ones. Audit needed: anything else in apps/web/lib/ reading from lib/autoops/sync/? Plan J's first step.
  • [ ] Idempotency-key support across all AutoOps endpoints — confirmed for book / reschedule / cancel. Verify others (e.g., customer-update, vehicle-add) if we ever need to call them.
  • [ ] 🛠 Tech debt — no admin UI for AutoOps team config. Every other CRM (ServiceTitan, HCP, Acculynx, Jobber) has a settings page at /team/[teamId]/integrations/crm/<vertical>/. AutoOps does not. autoops_team_configs + autoops_credentials are runtime-read but write-only via direct DB inserts (Kareem-driven). Surfaced 2026-05-20 during EAS replica setup, when Sandy needed a way to wire up testEAS-SouthPark. Fix would be a /team/[teamId]/integrations/crm/autoops/ page mirroring the other CRM pages: credentials/page.tsx for the enterprise-scoped api_key, plus a page.tsx for the per-team client_id / client_name / client_key / time_zone mapping. Likely worth a conversation with Kareem / Peter — this gap will keep showing up every time a new EAS shop (or any new AutoOps tenant) onboards.

Avoca architecture curiosities ​

  • [ ] Single Next.js app for everything — booking, dispatching, coach, dashboards, all under apps/web. Why? When does this stop scaling? Is there a planned split?
  • [ ] Staging database — does Avoca have a separate staging Supabase, or do all environments hit prod with team-scoped isolation? Implications for FDE testing.
  • [ ] Coda + canonical CRM docs — Kareem mentioned Coda exists for some integrations ("has Coda already been built for what you're building?"). Where is Avoca's Coda? Which CRMs have Coda docs?

Resolved / archived ​

(Move items here once they're checked off, with a 1-line summary of the answer + link.)

  • 2026-05-09 — FDE in-call tool dispatch routing. Two-surface gotcha: tool dispatches at priority 1 (per-tool server.url, controlled by NGROK_BASE_URL); workflow events at priority 2 (sub-agent assistant.server.url, controlled by RESPONDER_COMMON_WORKFLOW_URL). Both env vars required. → how-to/local-dev-env.md
  • 2026-05-09 — Where the dev tunnel URL goes in the assistant config. Via Avoca's test-phone provisioning + sync flow, not direct edits to the prod assistant. → how-to/local-dev-env.md
  • 2026-05-08 — CRM customer→jobs lookup. AutoOps added a customer filter on /clients/{clientId}/jobs. Triggered Plan J (sync migration).