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 identifieradvisor_id: string — responsible advisor identifiersession_id: string — unique session identifiertrigger_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 writtenopted_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:
- "Where are you living? What does a typical week look like?"
- "How are you spending your time?"
- "Who is in that picture with you?"
- "What role does money play?"
- "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:
- "Where are you spending most of your time right now?"
- "What are you doing less of than you want?"
- "How would you describe your relationship with money right now?"
- "What have you been waiting to do until money feels settled?"
- "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:
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]) --> WELCOME
WELCOME{Welcome}
WELCOME -- "Yes" --> P1[PHASE1_LIFE_YOU_WANT]
WELCOME -- "Need more info + Yes" --> P1
WELCOME -- "No / Need more info + No" --> T_ABANDONED([TERMINAL: abandoned])
P1 --> P2[PHASE2_LIFE_YOU_HAVE]
P2 --> SYNTH[Synthesis Processing]
SYNTH --> REF[Reflection]
REF --> SC[Summary Close]
SC -- "No, just for me" --> T_COMPLETE([TERMINAL: complete])
SC -- "Share with advisor" --> AD[Advisor Delivery]
AD --> T_COMPLETE
REF -. "feedback triggers\nregeneration" .-> 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 // "Where are you living? What does a typical week look like?"
p1_q2: string // "How are you spending your time?"
p1_q3: string // "Who is in that picture with you?"
p1_q4: string // "What role does money play?"
p1_q5: string // "How do you feel — what's the one feeling you're most hoping to have?"
// Phase 2 — Life You Have (collected from user)
p2_q1: string // "Where are you spending most of your time right now?"
p2_q2: string // "What are you doing less of than you want?"
p2_q3: string // "How would you describe your relationship with money right now?"
p2_q4: string // "What have you been waiting to do until money feels settled?"
p2_q5: string // "What would the people closest to you say about how you seem?"
// 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's the gap between want and have
largest_gap_value: string // which value has the largest authenticity gap
crowding_out_factors: string // what'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 |