Agent Implementation Spec: Money Story

Agent Name

money-story

1. Overview

The Money Story agent guides a user — advisor or client — through a structured reflective interview about their relationship with money across past, present, and future. It collects conversational responses to anchor questions, synthesizes them into a narrative, surfaces financial values and reflection prompts, and produces a persistent artifact. The agent supports two subject modes: the advisor running it on themselves, or the advisor sharing it with a client via link or portal. The session can be paused and resumed.

2. Entry Point

Trigger type: user_initiated
Trigger condition: User clicks the Money Story button in Purple Lydia (or follows a shared link in client mode)
Prerequisites: None — this agent runs in Purple Lydia with no CRM or external data required

Entry payload:

{
  subject_mode: &quot;advisor&quot; | &quot;client&quot;,   // selected at agent start
  session_id: string,                   // for pause/resume
  resuming: boolean                     // true if continuing a prior session
}

3. State Machine

State: `MODE_SELECT`

Purpose: Determine whether the session is for the advisor themselves or for a client.

User sees: > "Who is this Money Story for — you, or a client?" > [For me] [For a client]

Input expected: Single selection — advisor | client

Transitions:

On advisor selected → ORIENTATION
On client selected → CLIENT_SHARE (generate shareable link/portal access, then end advisor's session)

Side effects:

context.subject_mode set

State: `CLIENT_SHARE`

Purpose: Generate and deliver a shareable link or portal entry point so the client can run the exercise independently.

User sees: > A shareable link or instructions for directing the client to the portal.

Transitions:

On link generated → TERMINAL: link_delivered

Side effects:

Session record created for the client, pre-seeded with advisor reference
Advisor's session ends; client session begins independently when client follows link

Open question: Is this a link or a portal login? Resolved separately — see Section 14.

State: `ORIENTATION`

Purpose: Set expectations for the exercise — duration, tone, and intent — before any questions begin.

User sees: > Opening copy (verbatim or close to): > "Many people find this exercise expands their self-awareness, clarifies their goals, and helps them talk about money in a more meaningful way. This is not a quick exercise — expect it to take 20–30 minutes. The more you put in, the more you will get out of it. You can pause and return at any time."

Input expected: Acknowledgment / "Let's begin" — no substantive input collected here.

Transitions:

On acknowledgment → PART_1_PAST_PRESENT

State: `PART_1_PAST_PRESENT`

Purpose: Collect reflective responses to the six anchor questions about the user's financial past and present.

User sees: Questions delivered conversationally, one at a time (not as a list). Anchor questions in order:

When did you first become aware of money? How did it make you feel?
How was money talked about in your home while you were growing up?
What did you learn about money growing up that you still carry with you today?
How would you describe your relationship with money right now? What's working well? What feels challenging?
When it comes to your money, what do you worry about the most?
What would you most like to change about your financial life?

After all six anchors, the agent may ask a selection of supplementary questions based on response depth and detected gaps (see Section 5 — Background Processing).

Input expected: Free text responses. All six anchor questions are required to advance; supplementary questions are optional.

Transitions:

On all six anchor responses collected → PART_2_FUTURE
On session pause → TERMINAL: session_paused (state and all collected responses persisted)

Side effects:

context.past_present_responses[] populated per question
Background processing begins: narrative thread construction, emotional tone tracking

State: `PART_2_FUTURE`

Purpose: Collect reflective responses to forward-looking anchor questions.

User sees: Questions delivered conversationally:

What role do you want money to play in your life?
What kind of financial legacy do you want to leave for your family?
What do you want to teach your children or grandchildren about money?
As you think about your future retirement, what kind of life do you hope to be living, and what feelings does that bring up for you?

Input expected: Free text. All four anchor questions required to advance.

Transitions:

On all four future responses collected → DEBRIEF_CHOICE
On session pause → TERMINAL: session_paused

Side effects:

context.future_responses[] populated
Background processing updated with future data

State: `DEBRIEF_CHOICE`

Purpose: Let the user choose what they want to receive: a reflection experience, a summary and insight document, or both.

User sees: > "Would you like to reflect on your storytelling process, receive a summary and insight document, or both?" > [Reflect] [Summary & Insights] [Both]

Input expected: Single selection

Transitions:

On reflect → REFLECTION
On summary → SYNTHESIS
On both → REFLECTION (then SYNTHESIS after)

Side effects:

context.debrief_choice set

State: `REFLECTION`

Purpose: A brief closing conversation about the experience of telling the story — not about the content of the story.

User sees: Four prompts in sequence:

What was it like to tell your story in this way?
Did anything surprise you?
Reflecting on your story, what is one thing you want to make a priority going forward?
Is there someone in your life who should hear parts of your story?

Then closing copy: > "You've always been the author of your Money Story, even when it didn't feel that way. The difference now is that you can see it more clearly. Like any good story, it grows with you. Come back as your life changes, your thinking shifts, or your goals evolve. There are a lot of blank pages ahead, and they're yours to write."

Input expected: Free text responses. Optional — user may skip.

Transitions:

If debrief_choice == "both" → SYNTHESIS
Otherwise → TERMINAL: complete

Side effects:

context.reflection_responses[] populated

State: `SYNTHESIS`

Purpose: The agent generates the summary and insight document from all collected responses.

User sees: A structured output document containing:

A single overarching narrative summary of the money story (past + present + future arc)
Three summary statements — one each for past, present, and future
Three financial values identified from the story
Three questions for further reflection (ponder points)

This is not a playback of what the user said. It is a synthesized interpretation.

Input expected: None during generation. After display: "Does this feel like an accurate reflection of your story?" [Yes] [No — I'd like to adjust something]

Transitions:

On confirmation → TERMINAL: complete
On revision request → re-prompt for specific section to revisit, regenerate that section, loop back to confirmation

Side effects:

Final synthesis document written to persisted output (see Section 7b)

State Flow Diagram

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

    MODE_SELECT{Mode Select}
    MODE_SELECT -- client --&gt; CLIENT_SHARE
    MODE_SELECT -- advisor --&gt; ORIENTATION

    CLIENT_SHARE --&gt; T_LINK([TERMINAL: link_delivered])

    ORIENTATION --&gt; PART1[Part 1: Past / Present]

    PART1 -- pause --&gt; T_PAUSED([TERMINAL: session_paused])
    PART1 -- all 6 anchors complete --&gt; PART2[Part 2: Future]

    PART2 -- pause --&gt; T_PAUSED
    PART2 -- all 4 anchors complete --&gt; DEBRIEF_CHOICE

    DEBRIEF_CHOICE{Debrief Choice}
    DEBRIEF_CHOICE -- reflect --&gt; REFLECTION
    DEBRIEF_CHOICE -- summary --&gt; SYNTHESIS
    DEBRIEF_CHOICE -- both --&gt; REFLECTION

    REFLECTION --&gt; BOTH_CHECK{both?}
    BOTH_CHECK -- yes --&gt; SYNTHESIS
    BOTH_CHECK -- no --&gt; T_COMPLETE([TERMINAL: complete])

    SYNTHESIS --&gt; CONFIRM{Synthesis\nconfirmed?}
    CONFIRM -- yes --&gt; T_COMPLETE
    CONFIRM -- no, revise --&gt; SYNTHESIS

Terminal states:

complete — full run finished, outputs produced and persisted
session_paused — user stopped mid-flow; all responses saved, resumable
link_delivered — advisor flow complete; client session created separately

4. State / Context Model

context: {
  // Control
  subject_mode: &quot;advisor&quot; | &quot;client&quot;
  session_id: string
  current_state: string
  debrief_choice: &quot;reflect&quot; | &quot;summary&quot; | &quot;both&quot;

  // Part 1 — Past/Present
  past_present_responses: [
    { question_id: string, question_text: string, response: string }
  ]

  // Part 2 — Future
  future_responses: [
    { question_id: string, question_text: string, response: string }
  ]

  // Reflection
  reflection_responses: [
    { question_id: string, response: string }
  ]

  // Derived (see Section 5)
  narrative_summary: string
  past_summary: string
  present_summary: string
  future_summary: string
  financial_values: string[3]
  ponder_points: string[3]
  emotional_tone_profile: object

  // Session state
  completed_at: timestamp | null
  paused_at: timestamp | null
  resumed_from: string | null       // state name where session was paused
}

Required fields to advance to PART_2_FUTURE: all six past_present_responses populated. Required fields to advance to DEBRIEF_CHOICE: all four future_responses populated. Required fields to produce synthesis: all past_present_responses + all future_responses.

5. Background Processing

Narrative Thread Construction

Builds from: past_present_responses, future_responses Updates: Incrementally as responses come in; finalized when SYNTHESIS state is entered Output: narrative_summary, past_summary, present_summary, future_summary Used for: SYNTHESIS state output document

The LLM constructs a synthesized interpretation — not a playback. It identifies arc, tension, and themes across the three time periods.

Financial Values Extraction

Builds from: Full response set Updates: Once, at synthesis time Output: financial_values[3] — three values that define or characterize the story (e.g., security, generosity, independence) Used for: SYNTHESIS output document

Ponder Points Generation

Builds from: Full response set + identified values Updates: Once, at synthesis time Output: ponder_points[3] — three questions for continued reflection; framed for client use in advisor-client conversations Used for: SYNTHESIS output document

Supplementary Question Selection

Builds from: past_present_responses as they come in — depth of response, detected gaps Updates: After each anchor response in PART_1_PAST_PRESENT Output: A ranked list of supplementary questions to surface (from the extended question bank) Used for: Deciding whether to ask follow-on questions after the six anchors, and which ones

Emotional Tone Profile

Builds from: All responses Updates: Incrementally Output: emotional_tone_profile — internal signal tracking dominant emotional themes (fear, hope, shame, pride, etc.) detected across responses Used for: Not surfaced directly to user; available for future analytics and for coaching the advisor on their own emotional relationship with money

6. LLM Interaction Model

Prompt strategy: Multi-step; separate LLM calls per state. The synthesis step uses a structured output prompt.
System prompt scope: Base system prompt stays constant (Lydia tone/persona); state-specific instructions injected per call
Context injection: Full response context injected at synthesis time. During questioning, only prior responses in the current part are included to keep the conversation feeling natural rather than like a review

Structured output: Synthesis state produces structured JSON:

{
  &quot;narrative_summary&quot;: &quot;...&quot;,
  &quot;past_summary&quot;: &quot;...&quot;,
  &quot;present_summary&quot;: &quot;...&quot;,
  &quot;future_summary&quot;: &quot;...&quot;,
  &quot;financial_values&quot;: [&quot;...&quot;, &quot;...&quot;, &quot;...&quot;],
  &quot;ponder_points&quot;: [&quot;...&quot;, &quot;...&quot;, &quot;...&quot;]
}

Fallback behavior: If synthesis LLM call returns malformed output, retry once with stricter format instruction. If still malformed, surface narrative summary only and flag the structured fields as unavailable.

7. Outputs

7a. User-Facing Output

Money Story Summary & Insight Document

Format: Structured document
Rendered as: Inline in chat + downloadable (PDF or copy-to-clipboard)
Sections:
- Overarching narrative summary
- Past / present / future summary statements
- Three financial values
- Three ponder points
Audience: Advisor-facing when run in advisor mode; client-facing when run via shared link. Ponder points are explicitly framed for bringing back to an advisor conversation in client mode.

Reflection Closing Copy

Format: Conversational prose
Rendered as: Inline in chat, not saved as artifact
Audience: Whoever ran the session

7b. Persisted Output

Destination	Data written	Triggers downstream
Session record / memory layer	Full `context` object including all responses and synthesis output	Available to advisor prep agents (e.g., introductory meeting, monitoring) if client completed it
Advisor profile	`financial_values`, `emotional_tone_profile` (advisor mode only)	No immediate trigger; available for future Compass/coaching workflows
Client record (Integrated Lydia only)	Synthesis document, `financial_values`, `ponder_points`	Could trigger meeting prep agent to surface ponder points before next meeting

Note: In Purple Lydia, persistence is to the session/memory layer only. CRM write-back requires Integrated Lydia.

7c. Pause State Persistence

The full context object is persisted at any pause point, including which state was active and which questions had been answered. On resume, the agent re-enters at the saved state and acknowledges the prior session: > "Welcome back. You left off at [part]. Ready to continue?"

8. Loop and Retry Logic

Satisfaction condition for PART_1: All six anchor questions answered (non-empty response)
Satisfaction condition for PART_2: All four future anchor questions answered
Satisfaction condition for SYNTHESIS: User confirms the synthesis feels accurate
Retry — skipped anchor: If a user skips or gives a one-word non-response, agent gently re-prompts once: "Take your time with this one — even a short answer is fine." If still minimal, accept and move on.
Retry — synthesis revision: User can flag any section of the synthesis for revision. Agent re-asks targeted follow-up for that section, regenerates that section only, and returns to confirmation. Max two revision cycles before accepting the output as-is.
Loop limit: No looping on questions — each anchor asked at most twice. Supplementary questions are opportunistic, never required.
Partial completion: Full pause/resume supported at any point after ORIENTATION.

9. Branching Logic

Decision point: MODE_SELECT Condition: subject_mode == "client" Branch A: Generate shareable link / portal entry → advisor session ends Branch B: Proceed to ORIENTATION for advisor self-session Default: N/A — explicit selection required

Decision point: DEBRIEF_CHOICE Condition: User selection Branch A (reflect): Go to REFLECTION, skip SYNTHESIS Branch B (summary): Skip REFLECTION, go to SYNTHESIS Branch C (both): REFLECTION then SYNTHESIS Default: If no selection, default to both

Decision point: After six anchor responses in PART_1_PAST_PRESENT Condition: Response depth / gap detection from background processing Branch A: Agent surfaces 1–2 supplementary questions before advancing Branch B: Agent advances directly to PART_2_FUTURE Default: Advance without supplementary questions if depth signal is ambiguous

Decision point: SYNTHESIS confirmation Condition: User flags synthesis as inaccurate Branch A: Targeted revision loop (max 2 cycles) Branch B: User confirms → proceed to terminal Default: Accept after 2 revision cycles regardless

10. External Integrations

System	Operation	Data	Required / Optional	Purple Lydia	Integrated Lydia
Memory / session store	read + write	full context, pause/resume	required	yes	yes
CRM (e.g., Conquest)	write	synthesis doc, financial values, ponder points	optional	no	yes
Client portal	deliver	shareable link for client mode	optional	no	yes
PDF export	generate	synthesis document	optional	yes	yes

Degraded behavior (Purple Lydia): No CRM write. Synthesis document available inline and as download only. Client share mode depends on link delivery mechanism being resolved (see Section 14).

11. Error States and Edge Cases

Condition	Agent behavior
User provides no response after two prompts	Accept empty, mark question as skipped, advance
User pauses mid-question (session timeout)	Persist current state; on return, re-ask the in-progress question
Synthesis LLM call fails or is malformed	Retry once; if still failing, surface narrative summary only with note that structured insights are unavailable
User requests restart mid-session	Confirm intent, then reset context and return to `ORIENTATION`; prior session archived not deleted
Client link expires or is invalid	Surface a message to contact their advisor for a new link
User asks to skip the entire debrief	Accept — session completes without output artifact; context still persisted

12. Guardrails and Safety Checks

The agent must not interpret, judge, or editorialize individual responses during the questioning states — it asks and acknowledges, it does not analyze in real time
The synthesis must not use language that implies clinical assessment (no references to trauma, disorder, diagnosis)
The synthesis framing is narrative and values-based, not therapeutic
Ponder points must be framed as open questions, never as directives or implicit criticisms
If a user's response surfaces acute distress (financial crisis, expressions of hopelessness), the agent acknowledges warmly and notes that Lydia is not a substitute for professional guidance; it does not continue pressing the question sequence
emotional_tone_profile is internal only — never surfaced verbatim to the user

13. Observability

Log all state transitions with timestamps
Log each LLM call: prompt, injected context length, response, latency
Log synthesis revision cycles: how many, which sections flagged
Session completion rate by state (where do users drop off?)
Debrief choice distribution (reflect / summary / both)
Thumbs up/down on synthesis document
Whether a paused session was ever resumed (resume rate)

14. Open Questions

Question	Priority	Owner
Client share: shareable link vs. client portal login — which is the delivery mechanism, or both?	High	BP / Tyler
Can the synthesis document be uploaded to the client record in Conquest or another CRM client portal?	High	Tyler
Should advisor-mode `emotional_tone_profile` feed into Compass coaching workflows? If so, when and how?	Medium	Joy / Meghaan
Do we want structured data extraction (gender, generation, SES trajectory) for research purposes? If yes, what fields and with what consent flow?	Medium	BP / Joy
Does the agent ask any opt-in research questions during the reflection state (e.g., "How does seeing your story change how you think about your clients?")?	Low	BP
What is the advisor training / Amplify session that teaches advisors how to debrief a client's Money Story? Is that content surfaced inside Lydia?	Medium	Joy
Is there a `FCR` (Funded Contentment Roadmap) agent that the Money Story feeds into? If yes, the synthesis output and financial values should be explicitly designed as upstream input for it.	Medium	BP

Welcome to Money Story. Let's explore your relationship with money — past, present, and future.

Agent Implementation Spec: Money Story

Agent Name

1. Overview

2. Entry Point

3. State Machine

State: MODE_SELECT

State: CLIENT_SHARE

State: ORIENTATION

State: PART_1_PAST_PRESENT

State: PART_2_FUTURE

State: DEBRIEF_CHOICE

State: REFLECTION

State: SYNTHESIS

State Flow Diagram

4. State / Context Model

5. Background Processing

Narrative Thread Construction

Financial Values Extraction

Ponder Points Generation

Supplementary Question Selection

Emotional Tone Profile

6. LLM Interaction Model

7. Outputs

7a. User-Facing Output

7b. Persisted Output

7c. Pause State Persistence

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

State: `MODE_SELECT`

State: `CLIENT_SHARE`

State: `ORIENTATION`

State: `PART_1_PAST_PRESENT`

State: `PART_2_FUTURE`

State: `DEBRIEF_CHOICE`

State: `REFLECTION`

State: `SYNTHESIS`