Agent Implementation Spec — Values & Vision Agent

> The canonical name used in code, routing, and the UI. Matches the product doc name.

1. Overview

The Values & Vision Agent is a client-facing conversational agent that guides clients through a structured exploration of their aspirational life vs. their current reality. It collects free-text responses across two mirrored phases (5 questions each), synthesizes them into a values-and-gap profile, and produces two artifacts: a client summary card and an advisor-facing analysis card. The agent is triggered after initial client onboarding and is designed to feed into downstream planning conversations. It incorporates user feedback on the synthesis to allow regeneration.

2. Entry Point

Trigger type: user_initiated (client-facing, likely launched by advisor invitation or client dashboard)
Trigger condition: Client record exists; no prior completed V&V session (or re-run explicitly requested by advisor)
Prerequisites: Client has been onboarded into Lydia; advisor has opted to run the agent with this client
Entry payload:
- client_id: string — database identifier
- advisor_id: string — responsible advisor identifier
- session_id: string — unique session identifier
- trigger_source: "advisor_invitation" | "client_dashboard"

3. State Machine

State: WELCOME

Purpose: Introduce the agent, set expectations, get opt-in consent. Explain the two-phase structure and the purpose of finding "the gap."

User sees:

Agent greeting with description of the exercise: two sets of questions about the life you want vs. the life you have
Explanation that there are no right answers and that the gap between the two is valuable information for financial planning
Quick-reply options: "Yes" / "No" / "I need more information"

Input expected:

Selection from quick replies (required)
If "I need more information" → explanation of purpose displayed, then re-prompt with "Yes" / "No"

Transitions:

On "Yes" → go to PHASE1_LIFE_YOU_WANT
On "No" → go to TERMINAL_ABANDONED
On "I need more information" + subsequent "Yes" → go to PHASE1_LIFE_YOU_WANT
On "I need more information" + subsequent "No" → go to TERMINAL_ABANDONED

Side effects:

session_started_at timestamp written
opted_in flag set to true/false

State: PHASE1_LIFE_YOU_WANT

Purpose: Collect the client's aspirational vision — where they'd live, how they'd spend time, who's with them, the role of money, and how they'd feel.

User sees:

Phase label: "The Life You Want"
Progress bar at 1/4
5 sequential questions, each with a hint/example below the input:
1. "Where are you living? What does a typical week look like?"
2. "How are you spending your time?"
3. "Who is in that picture with you?"
4. "What role does money play?"
5. "How do you feel — what's the one feeling you're most hoping to have?"
Each question shows a hint with an example answer pattern

Input expected:

Free text per question (required to proceed; 10-char minimum suggested, no hard limit in mockup)
Optional: user can type any length response

Transitions:

After all 5 responses collected → go to PHASE2_LIFE_YOU_HAVE

Side effects:

Each response written to context: p1_q1 through p1_q5
phase1_completed_at timestamp

State: PHASE2_LIFE_YOU_HAVE

Purpose: Mirror the same dimensions but for the client's current reality — where their time and energy actually goes.

User sees:

Phase transition message: "Hold onto that picture. Now I'm going to ask you about today."
Phase label: "The Life You Have"
Progress bar at 2/4
5 sequential questions:
1. "Where are you spending most of your time right now?"
2. "What are you doing less of than you want?"
3. "How would you describe your relationship with money right now?"
4. "What have you been waiting to do until money feels settled?"
5. "What would the people closest to you say about how you seem?"
Each with hint/example

Input expected:

Free text per question (required to proceed)

Transitions:

After all 5 responses collected → go to SYNTHESIS_PROCESSING

Side effects:

Each response written to context: p2_q1 through p2_q5
phase2_completed_at timestamp
All 10 raw responses available for LLM synthesis

State: SYNTHESIS_PROCESSING

Purpose: Show a processing state while the LLM analyzes responses and generates the synthesis output.

User sees:

Processing spinner card: "Listening to everything you shared…"

Input expected:

None (automated processing)

Transitions:

After processing completes (mockup uses 2.5s delay) → go to REFLECTION

Side effects:

LLM call triggered to generate synthesis text, value tags, gap analysis
Derived fields computed: value_tags, gap_description, synthesis_text
Deep value analysis performed: classification against 16-value framework with gap detection (Y/N per value)

State: REFLECTION

Purpose: Present the synthesis to the client and invite reflection/feedback that can update the output.

User sees:

Agent message describing the noticed gap between desired and current life
Highlighted text contrasting aspirational elements (amber) vs. current obstacles (red)
Free-text input: "Is there anything about that gap that feels particularly true right now?"
Input has a placeholder hint; pressing Enter with empty text uses a canned value

Input expected:

Free text (optional — can skip with empty input)

Transitions:

On user input → go to SUMMARY_CLOSE
(Future: reflection input could trigger regeneration of the synthesis before proceeding)

Side effects:

reflection_text stored in context
This reflection SHOULD be fed back into a revised synthesis (feedback.md requirement: "ensure that the user's feedback after the summary is taken into account to generate a new one")

State: SUMMARY_CLOSE

Purpose: Deliver the final artifacts — client summary card + offer to share with advisor.

User sees:

Agent thank-you message
Client Summary card ("Your Values & Vision Summary") containing:
- The Life You Want section
- What's Getting in the Way Right Now section
- The Gap Worth Talking About section
- What You Value Most section (with value tags, gap-tagged items in red)
- "Bring This Into Your Next Conversation" section with a key question
- Action buttons: Download, Email Me
Agent asks: "Would you also like to share it with your advisor?"
Quick-reply options: "Yes, share with my advisor" / "No, just for me"

Input expected:

Selection from quick replies (required)

Transitions:

On "No, just for me" → go to TERMINAL_COMPLETE (client-only mode)
On "Yes, share with my advisor" → go to ADVISOR_DELIVERY

Side effects:

Summary card rendered in chat
session_completed flag set (partial)

State: ADVISOR_DELIVERY

Purpose: Show the advisor-facing analysis card and finalize the session.

User sees:

Disclaimer: "Simulated for mockup purposes — this is what the advisor would receive."
Advisor Summary card containing:
- Values That Surfaced Most Strongly (with gap Y/N per value, plain-language explanations)
- All 16 Values table (full framework, showing which surfaced and which didn't)
- The Gap in Plain Language (largest authenticity gap, what's crowding it out)
- Financial Implication Worth Exploring
- One Question to Carry Into the Planning Conversation
Agent closing message
Milestone banner: "Values & Vision Complete"

Input expected:

None

Transitions:

Automatically → go to TERMINAL_COMPLETE

Side effects:

Advisor summary persisted to advisor's workspace/CRM
advisor_summary_delivered flag set
Both artifacts marked as delivered

Terminal States

TERMINAL_COMPLETE — Agent ran to completion. Client summary delivered. Advisor summary delivered if share was enabled. Session record finalized.
TERMINAL_ABANDONED — User declined to participate or exited mid-flow. Partial responses may be discarded or saved as draft depending on policy.

State Flow Diagram

flowchart TD
    ENTRY([Entry]) --&gt; WELCOME

    WELCOME{Welcome}
    WELCOME -- &quot;Yes&quot; --&gt; P1[PHASE1_LIFE_YOU_WANT]
    WELCOME -- &quot;Need more info + Yes&quot; --&gt; P1
    WELCOME -- &quot;No / Need more info + No&quot; --&gt; T_ABANDONED([TERMINAL: abandoned])

    P1 --&gt; P2[PHASE2_LIFE_YOU_HAVE]

    P2 --&gt; SYNTH[Synthesis Processing]

    SYNTH --&gt; REF[Reflection]

    REF --&gt; SC[Summary Close]
    SC -- &quot;No, just for me&quot; --&gt; T_COMPLETE([TERMINAL: complete])
    SC -- &quot;Share with advisor&quot; --&gt; AD[Advisor Delivery]
    AD --&gt; T_COMPLETE

    REF -. &quot;feedback triggers\nregeneration&quot; .-&gt; SYNTH

4. State / Context Model

context: {
  // Session metadata
  session_id: string
  client_id: string
  advisor_id: string
  started_at: timestamp
  opted_in: boolean

  // Phase 1 — Life You Want (collected from user)
  p1_q1: string      // &quot;Where are you living? What does a typical week look like?&quot;
  p1_q2: string      // &quot;How are you spending your time?&quot;
  p1_q3: string      // &quot;Who is in that picture with you?&quot;
  p1_q4: string      // &quot;What role does money play?&quot;
  p1_q5: string      // &quot;How do you feel — what&#39;s the one feeling you&#39;re most hoping to have?&quot;

  // Phase 2 — Life You Have (collected from user)
  p2_q1: string      // &quot;Where are you spending most of your time right now?&quot;
  p2_q2: string      // &quot;What are you doing less of than you want?&quot;
  p2_q3: string      // &quot;How would you describe your relationship with money right now?&quot;
  p2_q4: string      // &quot;What have you been waiting to do until money feels settled?&quot;
  p2_q5: string      // &quot;What would the people closest to you say about how you seem?&quot;

  // Reflection / feedback (collected from user after synthesis)
  reflection_text: string   // optional; can trigger regeneration

  // Derived — value classification
  value_tags: [              // list of surfaced values with gap status
    { name: string, gap: boolean, plain_language: string }
  ]
  all_16_values: [           // full framework; each with detected / not-detected + gap status
    { name: string, plain_language: string, detected: boolean, gap: boolean | null }
  ]

  // Derived — synthesis
  synthesis_text: string     // LLM-generated narrative summary
  gap_description: string    // what&#39;s the gap between want and have
  largest_gap_value: string  // which value has the largest authenticity gap
  crowding_out_factors: string   // what&#39;s blocking the desired life
  financial_implication: string  // financial planning angle on the gap
  key_question: string       // one question to carry into planning conversation

  // Derived — timestamps
  phase1_completed_at: timestamp
  phase2_completed_at: timestamp
  synthesis_generated_at: timestamp
  reflection_collected_at: timestamp
  session_completed_at: timestamp

  // Flags
  shared_with_advisor: boolean
}

Field requirements by state:

State	Required	Optional	Branching
WELCOME	`opted_in`	—	`opted_in = false` → abandoned
PHASE1	all `p1_q*`	—	—
PHASE2	all `p2_q*`	—	—
SYNTHESIS	all `p1_q`, `p2_q`	—	—
REFLECTION	—	`reflection_text`	If populated → triggers regeneration of synthesis
SUMMARY	—	—	`shared_with_advisor` → advisor card rendered
ADVISOR	—	—	—

5. Background Processing

Value Classification from Free Text

Builds from: All 10 phase 1 + phase 2 responses Updates: Once, at synthesis time (with possible regeneration after reflection) Output: Array of { name, gap, plain_language } items drawn from a 16-value framework Used for: Client summary "What You Value Most" section, advisor summary full values table, gap analysis

The 16-value framework:

Achievement, Affluence, Agency, Beholderism, Belonging, Belovedness, Cosmos, Eudemonia, Familycentrism, Luminance, Non sibi, Place, Radius, Scope, Voice, Workcentrism

Each value is classified as:

Detected (surfaced in client language) or Not Detected
Gap Y (aspiration exists but current reality doesn't match) or Gap N (no significant gap)

Gap Narrative Synthesis

Builds from: All phase 1 and phase 2 responses, value classification Updates: Once at synthesis, optionally regenerated after reflection Output: Structured synthesis with four sections:

"The Life You Want" — narrative summary of aspirational picture
"What's Getting in the Way Right Now" — narrative summary of current obstacles
"The Gap Worth Talking About" — synthesized gap analysis
"What You Value Most" — value tags with gap highlighting Used for: Client summary card, reflection prompt, advisor summary card

Financial Implication Inference

Builds from: Gap analysis, value classification, money-related responses (p1_q4, p2_q3) Updates: Once at synthesis Output: Short paragraph describing the financial planning angle of the gap Used for: Advisor summary card

6. LLM Interaction Model

Prompt strategy: Single synthesis pass after all 10 responses collected. The full set of responses is sent in a single LLM call with structured output format requested (JSON with synthesis sections, value classifications, gap analysis, financial implication, key question).
System prompt scope: Fixed system prompt establishing the agent's role (values discovery coach, not financial advisor). Output format instructions embedded.
Context injection: All 10 raw responses injected into the prompt. Reflection text can be injected for regeneration.
Structured output: The synthesis LLM call produces structured JSON. Value classification is a deterministic post-processing step (confidence threshold per value against keyword/semantic matching) that may be LLM-assisted or rule-based.
Fallback behavior: If LLM response is malformed, retry up to 2 times with error context. If empty, fall back to a templated synthesis with basic value extraction. If off-topic, log and show a default message.

7. Outputs

7a. User-Facing Output

Artifact	Format	Rendered	Dynamic	Audience
Client Summary card	Structured document card	Inline in chat	Full content generated from LLM; value tags from classification	Client-facing
Download button action	File (PDF or text)	Downloaded to device	Static copy of summary content	Client-facing
Email Me action	Email	Sent to client email	Copy of summary content	Client-facing
Milestone banner	Gradient banner	Inline in chat	Templated with status text	Client-facing
Advisor Summary card	Structured document card with tables	Inline in chat	All values/gap data dynamically generated	Advisor-only (may be client-visible depending on share setting)

7b. Persisted Output

Destination	Data Written	Triggers Downstream
Client profile	`values_vision_summary` (JSON blob with all derived fields), `session_completed_at`	May trigger planning-context update or advisor notification
Advisor workspace	`advisor_values_vision_report` (JSON blob with advisor summary fields)	May appear in advisor meeting prep view
Session log	Full session record with all raw responses and derived data	Analysis pipeline, quality evaluation

7c. Nothing Persisted

N/A — this agent produces substantive persisted output in all completion cases.

8. Loop and Retry Logic

Satisfaction condition for Phase 1/2: All 5 questions in the phase must receive a non-empty response. Mockup uses Enter to submit; empty input triggers a canned fallback.
Retry behavior: Each question waits for input indefinitely. No explicit retry logic in mockup — user can type anything, including one word. A minimum character threshold (e.g., 10 chars) should be enforced in implementation with a gentle re-prompt ("Could you tell me a bit more?").
Loop limit on questions: None per question. Each question is asked exactly once in the current flow.
Partial completion / pause: The 10 questions are sequential without branching within a phase. Session can be abandoned at any point. Mid-session pause and resume is not shown in mockup but should be supported via session state persistence.
Reflection → regeneration loop: Feedback.md states "ensure that the user's feedback after the summary is taken into account to generate a new one." This implies a loop: user provides reflection → synthesis is regenerated incorporating the feedback → updated summary is shown. The mockup shows the reflection input but does not implement regeneration. Implementation must support this loop with a limit (e.g., max 3 regeneration cycles).

9. Branching Logic

Decision point: WELCOME Condition: User's quick-reply selection Branch A: "Yes" → proceed to Phase 1 Branch B: "No" → abandon Branch C: "I need more information" → show explanation, re-prompt Default: N/A (user must select)

Decision point: SUMMARY_CLOSE Condition: User's share preference Branch A: "Yes, share with my advisor" → show advisor card, complete Branch B: "No, just for me" → complete without advisor card Default: N/A (user must select)

Decision point: REFLECTION Condition: Whether user provides non-empty reflection text Branch A: Empty → proceed to summary directly Branch B: Non-empty → should trigger regeneration of synthesis incorporating the feedback Default: Proceed to summary

10. External Integrations

System	Operation	Data	Required / Optional	Purple Lydia	Integrated Lydia
CRM	read	`client_id`, `advisor_id`	required	stub client + advisor	real record lookup
CRM	write	values/vision summary to client profile	optional (if share enabled)	no	yes
CRM	write	advisor report to advisor workspace	optional (if share enabled)	no	yes
Email	send	summary email to client	optional	no	yes

Integration fallback:

CRM unavailable at start → session cannot proceed (client identity required)
CRM unavailable at write → session completes but data is queued for retry; user sees success, advisor sees pending sync indicator
Email unavailable → Download action still works; email button shows error state

Purple Lydia behavior:

No CRM integration → session runs with in-memory client context; outputs displayed but not persisted
No email → email button hidden or disabled

11. Error States and Edge Cases

Condition	Agent behavior
User provides no input for N turns	Not shown in mockup. Re-prompt after 60s of inactivity; after 3 re-prompts, offer to save progress and return later
User types very short responses (1-2 words)	Mockup accepts any input. Implementation should accept short responses but may add a gentle "Could you tell me more about that?"
User provides nonsensical or off-topic responses	Accepted as-is; the synthesis will naturally de-emphasize irrelevant content. No explicit validation
LLM returns unexpected structure	Retry up to 2 times; fall back to templated output with basic text extraction
User explicitly asks to restart	No mechanism in mockup. Implementation should support a "Start over" command at any point, clearing context and returning to WELCOME
Agent reaches loop limit on regeneration	If user provides feedback and requests regeneration more than 3 times, lock with message: "We've refined this several times. Let's keep this version and you can revisit anytime."
Session interrupted (browser close, network drop)	Session state persisted; on re-entry, offer to resume from the last unanswered question

12. Guardrails and Safety Checks

What the agent must never say or do: Never give financial advice, never diagnose emotional or mental health conditions, never make guarantees about outcomes, never pressure the client to share more than they're comfortable with
Input validation: No technical input validation needed (free text). Profanity filter optional. PII detection recommended — flag if client types sensitive information (SSN, account numbers) and advise not to include
Output review gates: The synthesis and value classification are generated by LLM and shown directly to the client. A tone/safety check on the output should be applied before rendering (ensure no harsh or judgmental language about the client's current life)
Escalation triggers: If client expresses distress, self-harm language, or acute financial crisis, the agent should pause and flag for advisor review. The agent should respond with a caring message and make it clear the advisor will follow up

13. Observability

State transitions: Every state entry and exit logged with timestamp, session ID, and transition trigger
LLM calls: The synthesis LLM call (input: all 10 responses + reflection; output: structured JSON) logged with full input/output. Regeneration calls logged with version counter
Context fields in session record: All raw responses (p1_q1 through p2_q5), reflection text, value classification output, synthesis text, shared_with_advisor flag, abandoned/complete status, regeneration count
Quality signals: Completion rate (abandoned vs. complete), share rate, download/email click rate, session duration, average response length per question. Thumbs up/down on summary card for explicit satisfaction feedback

14. Open Questions

Question	Priority	Owner
Should reflection feedback trigger automatic regeneration of the synthesis, or require an explicit "Regenerate" button?	High	Product
What is the minimum character threshold per answer before re-prompting?	Medium	Product
Should abandoned sessions save partial responses as draft for later resumption?	Medium	Engineering
Is the 16-value framework fixed or should it evolve per advisor/client segment?	Low	Research
Should the advisor card be previewable by the client or strictly advisor-only?	Medium	Product
What is the exact trigger mechanism — advisor sends link, client sees in dashboard, or both?	High	Product
Download and Email actions — what exact format for download (PDF, text, image)?	Medium	Engineering
Is there a "refine" step where user can edit individual responses before final synthesis?	Low	Product

The Life You Want0 / 4

Hello. I'm Lydia. Before we get into anything financial, I want to ask you something different.

Agent Implementation Spec — Values & Vision Agent

1. Overview

2. Entry Point

3. State Machine

State: WELCOME

State: PHASE1_LIFE_YOU_WANT

State: PHASE2_LIFE_YOU_HAVE

State: SYNTHESIS_PROCESSING

State: REFLECTION

State: SUMMARY_CLOSE

State: ADVISOR_DELIVERY

Terminal States

State Flow Diagram

4. State / Context Model

5. Background Processing

Value Classification from Free Text

Gap Narrative Synthesis

Financial Implication Inference

6. LLM Interaction Model

7. Outputs

7a. User-Facing Output

7b. Persisted Output

7c. Nothing Persisted

8. Loop and Retry Logic

9. Branching Logic

10. External Integrations

11. Error States and Edge Cases

12. Guardrails and Safety Checks

13. Observability

14. Open Questions

Submit Feedback