How to Build the Family Health Agent

From category thesis to working software: how I would actually build the Family Health Agent, what I would prompt first in Claude Code, and how to avoid rebuilding the same provider-patient-centric mistakes the industry has already made once.

This is a companion piece to From the Family Health Manager to the Family Health Agent: HealthVault 2030. The first essay makes the category argument. This one is about execution. If the Family Health Agent is real, what exactly is it? What should version one actually do? How do we build it without quietly drifting back into the old patient-provider-centric worldview? And if you sat down with Claude Code tomorrow morning, what sequence of prompts would get you to a serious first prototype rather than a charming demo that collapses the moment it touches reality?

TL;DR: The Family Health Agent should not be built as a magical general-purpose chatbot for healthcare. It should be built as a role-specific managerial system for the Family Health Manager: a patient-authorized, family-delegated product that tracks what was supposed to happen, what actually happened, what got dropped, and what needs to happen next. The first commercial wedge is specialty therapy access, where budgets already exist for prior authorization support, benefits investigation, refill management, and navigation. The first technical principle is simple: deterministic workflows and structured state first, LLM assistance second.

This post is longer than a normal “how to build” note because the product is not trivial. We are not just building a nicer app. We are trying to turn one of the most important hidden managerial roles in healthcare into software, while preserving delegated authority, respecting patient control, and operating across the messy rails we actually have rather than the elegant ones we wish we had.

If I were building this tomorrow

If I were starting tomorrow, I would not begin by trying to build “AI for healthcare” in the abstract. I would start with a narrower and much more concrete thesis: there are roles in the healthcare system that are fundamentally managerial roles, and the Family Health Manager is one of the most important of them. The product should therefore be designed not as a synthetic clinician, and not as a general-purpose health assistant, but as a software manager for that role.

That sounds like a subtle distinction until you try to build it. A synthetic clinician wants diagnostic authority, medical reasoning, and clinical action. A software manager wants memory, follow-through, escalation, permissions, and state. One is about expertise. The other is about keeping care from quietly falling apart between institutions. The Family Health Agent belongs in the second category.

That distinction has practical consequences immediately. It means the center of the system is not the chart, and not the provider, and not a consumer dashboard for the lone motivated patient. The center is the household role that is actually doing the work. The core data structure is therefore not “patient + provider” but household + delegated authority + longitudinal task state. If you get that wrong, everything built on top of it will feel clever and still fail in the real world.

So if I were doing this in Claude Code, I would start by forcing the system to understand the role, the permissions, and the workflow state before I asked it to generate a single pixel of user interface.

The Claude Code sequence I would actually use

If I were using Claude Code to take this from thesis to prototype, I would not start with one giant magical prompt. I would start with a sequence. The sequence matters because it determines what the system thinks the product actually is.

Prompt 1 — extract the product thesis from the essays
Read the attached essays on the Family Health Manager and Family Health Agent. Extract the product thesis, user roles, economic buyers, core workflows, constraints, trust requirements, and system objects. Produce a concrete v1 concept focused on specialty therapy access and household coordination. Do not describe a general-purpose medical AI assistant. Describe a role-specific managerial system.

Prompt 2 — define the domain model around the household, not the chart
Create a domain model in TypeScript for Household, Person, Relationship, RoleAssignment, DelegationGrant, ConsentPolicy, LegalAuthority, HealthTask, HealthEvent, Medication, PriorAuthCase, Referral, Appointment, DocumentArtifact, EscalationRule, TimelineEntry, and ActionAdapter. Explain why each object exists. Assume that delegated authority, age transitions, and changing family structure are first-class design problems.

Prompt 3 — enforce family-manager-centric permissioning
Design the authorization model for a Family Health Agent. Do not assume one patient, one record, one owner. Support a Family Health Manager, multiple delegated helpers, bounded permissions, revocation, expiration, age-18 transitions, powers of attorney, guardianship, and audit trails. Produce both the data model and the business rules.

Prompt 4 — scaffold the codebase
Create a monorepo with a Next.js web app, a backend service, a workflow engine package, and a shared domain package. Use TypeScript throughout. Use Postgres as the system of record. Store structured state relationally and artifacts as JSONB where needed. Include a clear README and a seed script for one realistic demo household.

Prompt 5 — build the Household Health Graph and Delegation Ledger first
Implement APIs and UI for adding household members, assigning Family Health Manager roles, granting delegated authority, revoking authority, and handling age-based permission transitions. Include a timeline of delegation changes and full audit logging.

Prompt 6 — build the Longitudinal Care Timeline
Create a working timeline that can ingest mock events from provider, payer, and pharmacy systems. Events should include appointments, orders, labs, prescriptions, prior auth states, denials, approvals, follow-up deadlines, refill requests, and travel-related continuity issues. Display expected next steps, unresolved work, and state changes over time.

Prompt 7 — implement the deterministic manager loop
Build a task-management engine that compares expected state to actual state and creates tasks when something is missing, delayed, denied, unresolved, or forgotten. Use explicit rules and state machines. Do not use an LLM to decide the workflow. The LLM can summarize or draft, but it cannot be the source of truth for state transitions.

Prompt 8 — model the rails we actually have
Create adapter interfaces for payer, provider, pharmacy, and portal workflows. Assume the real world contains brittle SMART app registration, prior-auth APIs, portal workflows, asynchronous notifications, and partial data access. The product should work as an overlay on top of the non-agent stack we actually have, not assume a fully agent-native infrastructure.

Prompt 9 — encode Josh Mandel’s reality, not an interoperability fantasy
Implement asynchronous workflow support for delayed tasks, provider-affirmed routing where needed, approval gates, re-check loops, and explicit status models for “pending,” “denied,” “needs human approval,” and “unknown.” Design for rough rails, not elegant rails.

Prompt 10 — build the first wedge workflow
Implement a specialty-therapy-access workflow: benefits investigation status, prior authorization packet assembly, specialty pharmacy handoff, refill gap detection, travel transfer support, and therapy-start tracking. Use one realistic oncology or immunology household journey as the demo case.

Prompt 11 — add bounded action adapters
Implement bounded actions for document drafting, packet assembly, reminder generation, scheduling nudges, pharmacy transfer preparation, and escalation. Require explicit human approval where authority boundaries demand it. Produce an audit trail for every action.

Prompt 12 — add LLM assistance only where it helps
Add LLM assistance for summarization, drafting prior-auth cover notes, explaining task status in plain English, and classifying unstructured messages into structured updates. Keep the workflow engine deterministic and auditable.

Prompt 13 — instrument ROI and buyer metrics
Add metrics for time-to-therapy, dropped-task count, prior-auth cycle time, refill gap rate, unresolved follow-up count, manual touches avoided, and estimated coordination cost replaced. Build a buyer-facing dashboard showing how the product substitutes for manual navigation labor.

Prompt 14 — add trust, review, and compliance surfaces
Create user-visible audit logs, approval queues, consent receipts, delegation history, and “why did the system do this?” explanations. The Family Health Agent should be accountable in the managerial sense, not mysterious in the chatbot sense.

Prompt 15 — generate the demo household
Create one realistic household with a Family Health Manager, a patient on specialty therapy, a secondary helper, a provider, a payer, and a pharmacy workflow. Seed it with a delayed prior auth, a refill gap, an unscheduled follow-up, and an age-related permission transition so the prototype demonstrates why the role matters.

What those prompts are trying to preserve

The most important thing those prompts are trying to preserve is the original HealthVault insight: healthcare is usually managed not by “the patient” in isolation, but by someone inside the household performing managerial labor under delegated authority. That means the Family Health Agent cannot be built on top of a provider-patient-centric permission model and then patched later with a few sharing settings. That would just be the old mistake with newer branding.

The product has to understand from the beginning that households change, roles change, authority changes, and responsibility shifts. Children turn eighteen. Parents age into needing help. Spouses share and then unshare responsibilities. Adult children step in. Legal authorities appear. Other people fall away. In a real product, those are not edge cases. They are the job.

That is why the Family Health Manager insight has to live in the core data structures. The Household Health Graph, the Delegation Ledger, the Consent Engine, and the Longitudinal Care Timeline are not optional architecture diagrams. They are what makes the product faithful to the problem it is trying to solve.

How this connects to the rails we actually have

If the first essay made the argument, Josh Mandel’s recent infrastructure work made something else clearer: the Family Health Agent does not need a fantasy future in which every institution becomes perfectly interoperable before the product can work. It needs a strategy for operating across the messy non-agent stack we actually have.

That means the build should assume a world of portals, prior-auth APIs, payer rules, asynchronous notifications, specialty pharmacy workflows, partial FHIR access, brittle SMART registrations, and all the contractual and technical fine print that still makes health-tech integration feel like a contact sport. The point is not to avoid standards. The point is to use standards where they help, work around them where they don’t, and design the product so that managerial value can appear before the whole system becomes elegant.

In product terms, that means building an adapter layer. The Family Health Agent should not assume every rail is symmetrical or complete. It should assume payer data arrives in one shape, provider events in another, pharmacy events in a third, and patient or household artifacts in yet another. The product’s job is to normalize just enough to manage state without requiring the whole healthcare ecosystem to agree on one ontology first.

This is also where the product stops being a cute demo and starts becoming real. If it cannot operate across the messy rails, it is not a Family Health Agent. It is an interface concept.

Why this is not a trivial build

The easiest mistake here would be to underestimate the build and overestimate the LLM. This is not a weekend chatbot wrapped around some medical PDFs. It is a system that has to manage authority, maintain state over time, survive partial information, handle asynchronous workflows, respect consent, expose an audit trail, and remain comprehensible to a human who is already overwhelmed.

That means the hard parts are not only model quality. They are event modeling, permissions, workflow state, escalation logic, bounded actions, adapter reliability, and user trust. The Family Health Agent has to know what happened, what was supposed to happen, who is allowed to do what, what still needs to happen, and when it has crossed a line that requires human intervention.

In other words, the product challenge is not “make the AI smarter.” The product challenge is “make the managerial system real.” That is why deterministic workflows and structured state have to come first.

For the more traditionally minded: a fuller PRD

Product name: Family Health Agent (category)
Product concept: software chief of staff for the Family Health Manager

Problem statement
Healthcare coordination is currently performed through fragmented manual labor across households, providers, pharmacies, payers, and support programs. The Family Health Manager carries the memory, follow-through, and escalation work needed to keep care moving. Existing software does not model this role well enough, and most institutional systems optimize for charts, claims, or prescriptions rather than household coordination.

Primary user
The Family Health Manager inside the household: often a parent, sometimes a spouse, often an adult child, occasionally the patient themselves, and sometimes a paid navigator or helper acting with delegated authority.

Economic buyer
First wedge: specialty therapy access programs, hub services, specialty pharmacy, and manufacturer support functions.
Second wave: Medicare Advantage plans, risk-bearing provider groups, and integrated systems.

Core jobs to be done

track what is supposed to happen next
detect what was dropped
follow up until the administrative work is resolved
route the right action to the right human at the right time
preserve delegated authority and patient control
turn the Family Health Manager from transport layer into supervisor

Design principles

family-manager centric, not provider-patient centric
patient-controlled and family-delegated
deterministic workflow engine first, LLM second
bounded actions, explicit authority, full audit trail
operate across messy rails, do not wait for elegant rails

Core product primitives

Household Health Graph — people, relationships, roles, delegated helpers
Delegation Ledger — who can act for whom, under what authority, in which contexts
Consent Engine — approvals, revocations, age transitions, guardianship, POA
Longitudinal Care Timeline — what happened, what was expected, what remains unresolved
Task State Machine — expected state vs actual state, turning gaps into work
Escalation Router — who needs to know what, when, and why
Action Adapters — drafting, scheduling, portal interactions, reminders, pharmacy support

Personas

Primary Family Health Manager — the parent, spouse, or adult child doing the work
Patient — the person whose care is being coordinated, with direct authority where appropriate
Secondary helper — another household member or delegated helper with bounded permissions
Navigation operator — a paid helper, access rep, or care manager working within formal boundaries
Program buyer — the specialty access leader, payer ops leader, or provider sponsor buying the software

v1 workflows

Prior Auth Manager — detect missing documents, draft packet, track status, escalate denials
Prescription Continuity Manager — detect refill gaps, support travel transfer, coordinate specialty pharmacy handoffs
Follow-Up Closure Manager — detect missing follow-ups, prompt scheduling, confirm completion
Transition Manager — handle age-18 transitions, role changes, guardianship updates, and delegated-authority updates

Integrations / rails strategy

payer APIs where available
provider portals and event feeds
pharmacy and specialty-pharmacy workflows
bounded adapter layer for brittle or partial integrations
artifact ingestion for forms, letters, denials, and other operational documents

Trust and governance requirements

patient-controlled by default
explicit delegated authority
every action logged
every outbound artifact reviewable
human approval for high-risk or permission-bound actions
visible audit trail and consent history

User experience surfaces

Household dashboard — the operational home screen for what changed, what is pending, and what needs approval
Timeline view — longitudinal event stream with expected-next-step logic
Delegation console — grants, revocations, age transitions, and legal authorities
Action center — draft, review, approve, escalate, and monitor bounded actions
Buyer dashboard — ROI, time-to-therapy, dropped tasks, and manual work replaced

Success metrics

time-to-therapy
prior authorization cycle time
refill gap rate
dropped-task rate
manual touches per patient journey
appeal resolution time
follow-up completion rate
household coordination burden
estimated coordination labor replaced

Non-goals for v1

diagnostic autonomy
prescribing autonomy
full replacement of EHRs, portals, or payer systems
a generic “ask me anything about your health” chatbot

System principle
Deterministic workflows and structured state first. LLM assistance second.

What not to build first

If this category is real, there are at least three seductive mistakes to avoid. The first is trying to build a synthetic doctor before you build a software manager. The second is trying to boil the ocean before you pick a wedge with funded coordination pain. The third is trying to use an LLM as the workflow engine rather than as an assistant to a workflow engine.

The Family Health Agent should not launch as a generalized health concierge for everyone. It should launch where the role is explicit, the manual work is expensive, and the benefit of not dropping tasks is easy to measure. That is why specialty therapy access is such a good first wedge. It is not because the problem is small. It is because the managerial role is unmistakable.