About personas and twins

A persona is a versioned bundle of permissions (reference). A persona twin is a named agent configuration bound to one persona, one person and one program, designed to do the plumbing of that person’s role and to ask that person for every decision. The design is recorded in PRODUCT-PLAN.md Part 7 and fixed by PRODUCT-CONTRACT.md section 11; the mechanics are listed in the twins reference. Everything on this page is designed: no twin runs anywhere today. Illustrative people named here (Maya N., Tomas K., Priya S., program trv-101) exist only in the seeded illustrative organisation and carry the “Illustrative” label wherever they appear.

Three sentences the twin is designed to live by, fixed as console copy: “Your twin proposes. You decide.” / “Your twin never approves, signs or sends.” / “Paused. Nothing runs until you resume.”

What a twin is, in records

A twin is one row in twin_definitions binding (program_id, user_id, persona_key) to standing duties, triggers, a schedule and a tool allowlist. The allowlist is computed, not configured: the intersection of the role catalogue for the agent and the person’s own live permissions, hashed into tool_allowlist_hash and recomputed at every run start and on every role change. The twin runs the existing console orchestrator and specialists under run tokens acting for the bound person (requested_by and act are the person’s id), so every tool call is checked against what that person may do at that moment.

A twin is never a user. It cannot sign (signatures.signer_user_id is a person), cannot approve, cannot request an approval, cannot notify and cannot send mail, because the tool catalogue refuses any tool whose name carries one of those verbs (FORBIDDEN_TOOL_VERBS in api/app/tools/catalogue.py). Those actions are structurally absent, not merely disallowed. The UI never gives the twin an invented name: to its person it is “your twin”; to everyone else it is “Name’s twin (agent)” with the persona in a chip.

How a twin works

Standing duties, approved once. Enabling a duty starts a planning-only run that writes a standing plan (tools, sources, expected writes, budget, fetch cap, cadence). The bound person approves it, exercising program.twins.use; nobody else can. Any change of tools, permissions or agent version invalidates the plan’s hash and asks again.
Reads run unattended; every record write is a proposal. “Read” includes knowledge.fetch_document, which ingests a document into the program corpus, so every plan that uses it names it and carries max_fetches_per_cycle. A record write (a write-tool proposal on an Evidence, Plans, Review, Progress or hand-off record) is filed as a tool_calls row behind a detached interrupt.
File and finish. A twin cycle proposes everything it has, each proposal its own interrupt, and ends succeeded without waiting. Approval later executes the write server-side under the approver’s own permission; nothing resumes a container. An expired proposal reads “Expired, nothing written”.
Decisions in one place. The person decides from an inbox headed “Decisions waiting for you”, a daily brief (a server-written artifact, no model call) and small explicit batches of at most ten items, each approved by a named activation with the write’s own permission and audited individually.
Twins talk only through records. A hand-off exists only after the sending person approved it; the receiving twin may prepare only after the receiving person accepted it, which opens a program-visible thread. There is no agent-to-agent channel. Nothing runs on a mention alone.
Interrupts belong to the bound person. Only they (or, for write approvals, an active delegate who holds the write’s permission) can resolve a twin’s interrupt; holders of the oversight read see the thread but get 403 bound_user_only if they try to decide.
Pause is total. A twin pauses when its person loses a permission or program membership, is deactivated, exceeds its tool-call budget or has most of its proposals declined; “Paused. Nothing runs until you resume.”

The ten personas and their twins

The pattern is the same for every persona: the twin proposes records and hand-offs; the person decides, alone, with their own permission. Twins appear in no row of the approval matrix (stage playbooks).

Persona	What the twin would propose	What the person decides	Rhythm
Scientist	Weekly literature watch per open question (sources, observation findings, gaps); an experiment record and a hand-off to QA when a notebook entry closes; a protocol draft when a hypothesis is approved; a report scaffold when the last experiment completes; gap hygiene; information hand-offs to the lead	Sources, findings, gaps, experiment records, protocol and report drafts, hand-offs; she alone clicks “Request approval” on a draft	Brief and one batch a day; “now” only for a hand-off addressed to her and an SOP change binding a protocol she drafts
Program lead	The morning brief; a blocker scan over milestones, dependencies, open items and approvals; a reads-only pre-read attached to each approval requested of her, labelled “Agent-generated draft, unsigned.”; the stage readiness brief (R4); hand-offs to scientists and QA	Hypothesis decisions, plan approvals, protocol and report signatures, open items, milestone changes, stage gate ready and close (R4), hand-offs	Brief and one batch a day; “now” for a blocked critical-path milestone, a major or critical deviation proposal and a stage gate marked reviewed
Quality reviewer	The impact result when an SOP version becomes effective; the check bound to the effective SOP version after accepting a hand-off; check triage (proposed deviations and annotations); the requirement-set queue; a monthly oversight summary of run metadata only (R4); stage review preparation (R4)	Finding decisions, requirement acceptance with a signature, deviation confirmation, re-check batches, the stage gate `reviewed` signature (R4)	Brief and two batches a day; “now” for a newly effective SOP version and major or critical proposals
Program owner	A weekly brief across programs; approvals waiting only on them; an information item on members with no recent activity (never a removal); paused twins, exhausted budgets and active delegations	Stage closure (R4, `approved` signature, never the `reviewed` signer), owner grants, anything a lead escalates	Weekly; “now” for a stage gate reviewed and critical deviations
Manufacturing specialist	Dependency watch on Progress records where CMC touches a preclinical program (lots, stability pulls, tech transfer): open items and milestone changes for slipped dependencies; plan change proposals when a supply date moves; hand-offs to the lead when a milestone needs an approval	Milestones, dependencies, open items, plan changes, hand-offs; in R4 the `ready` mark on the manufacturing gate only	Brief and one batch a day; “now” for a blocking dependency on the critical path
Viewer	Nothing: a viewer has no twin	Nothing to decide; the UI says “Viewers have no twin. Nothing waits for you.”	-
Organisation owner and Organisation admin	R5: quarterly access-review preparation from role-assignment audit rows, inactive users, invitations never accepted, programs without an owner; information items only	User, group and role changes stay human-only	Quarterly (R5)
Organisation auditor	No twin; gains in R3 the twin activity export under `org.audit.read`: twins, duties, triggers, runs and proposal metadata, never `tool_calls.arguments`	Nothing; reads	-
Organisation member	No twin	Nothing	-

Manufacturing objects stay designed, so the manufacturing specialist’s twin works on Progress and Plans records only. From persona version 3 (R3) hypothesis decisions and plan approvals belong to the lead and the owner; the scientist proposes and records.

An illustrative week

Illustrative, from the design; nothing here happened. Monday 08:15, Maya N.’s brief lists three new sources for question Q-12, one proposed finding and one gap; she accepts two sources and the finding and edits the gap. Tuesday, notebook entry EXP-0421 closes at 16:40; one cycle files a proposed experiment record and a proposed hand-off “EXP-0421 ready for SOP check” and ends; at 17:30 both wait and she accepts both. Tomas K. accepts the hand-off; his twin proposes the check bound to SOP-BA-012 v4.0; he approves it. Wednesday, Priya S. approves hypothesis H-7; at 17:30 a protocol draft waits for Maya, bound to the SOP version in force; she edits section 6 and clicks Request approval. Thursday the console says “Nothing waiting. Your twin’s next pass is Friday 07:00.” Every record written that week carries a person’s decision and the twin’s run in its footer: “Proposed by Maya N.’s twin (agent); decided by Maya N.” (illustrative).

What the design does not claim

The claim is not that the twin is smart, and no claim is made about time. Whether the interval between an event and a decided proposal changes is measured on partner programs with event-anchored metrics computed identically for the phase-2 baseline and the twin cohort (ADR 0025), and nothing about it appears in copy until a CLAIMS-REGISTER.md row exists. Every decision stays human and recorded. Timing claims wait for measured data.

Twins reference: tables, keys, kinds, routes and phrases per release.
About stage playbooks: how personas complete a stage together.
ADR 0021, ADR 0022, ADR 0023.

Source: PRODUCT-PLAN.md Part 7 sections 1, 2, 4 and 5; PRODUCT-CONTRACT.md section 11.4; api/app/tools/catalogue.py (FORBIDDEN_TOOL_VERBS); api/app/auth/personas.py (PERSONA_VERSION = 2, scientist bundle); decisions/0021-persona-twins.md