Agent Implementation Spec — Advisor Warm-Up

Agent Name

warmup-agent

1. Overview

The Warm-Up Agent is a pre-meeting ritual that helps financial advisors shift from task-mode to relational presence before any client conversation. The advisor initiates it voluntarily in the two minutes before a meeting. It asks three short reflective questions (meeting type, intention, desired client outcome), offers an optional guided 4-7-8 breathing exercise, and closes with a personalized affirmation built from the advisor's own answers. It produces no document, persists no data, and integrates with no external system. The output is entirely experiential: a cleared state and an activated intention.

2. Entry Point

• Trigger type: user_initiated
• Trigger condition: Advisor opens or navigates to the Warm-Up Agent interface before a client meeting.
• Prerequisites: None. No client record, prior session, or meeting data required.
• Entry payload: None. The agent starts with no pre-populated context.

3. State Machine

State: WELCOME

Purpose: Orient the advisor, reframe the purpose of the next two minutes (not notes review — internal state), and get consent to begin.

User sees: > "Hi. I'm glad you're here. > > Before you head into your next meeting, let's take just a couple of minutes for you. Not to review your notes or run through your agenda — you've done that. This is something different. This is about you showing up as your best self: present, grounded, and genuinely curious about the person you're about to sit with. > > Here's what we're going to do. I'll ask you three quick questions to help you get clear on your intention for this meeting. Then, if you'd like, I'll walk you through a short breathing exercise to help you reset your nervous system and walk in fresh. Then, we'll close with something to carry into the room with you. > > It takes about two minutes. Ready?"

Quick reply options: "Yes, I'm ready" | "Not right now"

Input expected: Quick reply selection. Required.

Transitions:

• On "Yes, I'm ready" → QUESTION_1
• On "Not right now" → TERMINAL_DECLINED

Side effects: None.

State: QUESTION_1

Purpose: Ground the advisor in the concrete meeting context.

User sees: > "I'm going to ask you three short questions. There are no right or wrong answers — just yours." > > "What kind of client meeting are you heading into?"

Hint text beneath: e.g., annual review, first meeting, difficult conversation, planning session

Input expected: Free text. Required.

Transitions:

• On any non-empty input → save to context.meeting_type, go to QUESTION_2

Side effects: context.meeting_type set.

State: QUESTION_2

Purpose: Activate the advisor's deliberate coaching posture.

User sees: > "What's one intention you want to carry into this conversation?"

Hint text: e.g., to listen more than I speak, to slow down, to ask better questions

Input expected: Free text. Required.

Transitions:

• On any non-empty input → save to context.intention, go to QUESTION_3

Side effects: context.intention set.

State: QUESTION_3

Purpose: Shift the advisor's focus from their own performance to the client's experience.

User sees: > "How do you want your client to feel by the end of this meeting?"

Hint text: e.g., reassured, heard, clear, less anxious, more confident

Input expected: Free text. Required.

Transitions:

• On any non-empty input → save to context.client_feeling, go to BREATHING_OFFER

Side effects: context.client_feeling set.

State: BREATHING_OFFER

Purpose: Offer an optional nervous system reset; explain the mechanism briefly so the advisor understands why it works.

User sees: > "Thank you. That's a strong intention to walk in with. > > Before we close, I want to offer you an invitation. Our days are often rushed and can be riddled with stress. Research on the nervous system shows that even a single intentional breath cycle can shift your physiological state — lowering cortisol, slowing your heart rate, and helping you to be more focused. It's not meditation. It's just thirty seconds of using your breath as a reset switch. > > The technique is called 4-7-8 breathing. You inhale for four counts, hold for seven, and exhale slowly for eight. That extended exhale is what activates your parasympathetic nervous system — the part of you that's calm, open, and ready to listen. > > Would you like to try it?"

Quick reply options: "Yes, let's do it" | "No thanks, I'm ready"

Input expected: Quick reply selection. Required.

Transitions:

• On "Yes, let's do it" → BREATHING_EXERCISE
• On "No thanks, I'm ready" → AFFIRMATION_B

Side effects: context.did_breathe set on transition.

State: BREATHING_EXERCISE

Purpose: Guide three rounds of 4-7-8 breathing with a visual animated ring.

User sees: > "Good. Find a comfortable position. Close your eyes if you'd like. We'll do three rounds together. > > Get ready to inhale…"

Followed by the animated breathing card:

• A circular ring that expands (inhale), holds (hold), and contracts (exhale)
• Phase label: "Inhale…" / "Hold…" / "Exhale slowly…"
• Countdown number for each phase
• A "Begin breathing" button to start; the advisor controls when it starts
• Three full 4-7-8 cycles (4s + 7s + 8s = 19s per round × 3 = 57 seconds total)
• On completion: ring resets, label shows "Well done.", count shows ✓

Input expected: Button click to start the cycle. No input during breathing. Required to proceed.

Transitions:

• On cycle completion (all 3 rounds) → AFFIRMATION_A

Side effects: context.did_breathe = true

State: AFFIRMATION_A

Purpose: Close the session for advisors who completed the breathing exercise. The breath itself provides grounding; the affirmation names meeting type and intention only.

User sees: > "Nicely done. Notice that. That's what it feels like to be present."

Then a styled affirmation card (gradient: teal → navy): > You're heading into [meeting_type] with a clear intention: [intention]. Let that guide you. Your client is lucky to have someone who cares enough to show up this way. > > Go be the guide they need today. > > — Lydia

Milestone banner displayed: "Go be the guide they need today."

Input expected: None. Terminal state.

Transitions: → TERMINAL_COMPLETE

Side effects: None.

State: AFFIRMATION_B

Purpose: Close the session for advisors who skipped the breathing exercise. All three answers are woven in, giving the affirmation more emotional specificity.

User sees:

Styled affirmation card (gradient: teal → navy): > No problem at all. You're ready. > > You're heading into [meeting_type] with a clear intention: [intention]. Hold onto that. Let it shape the way you listen, the questions you ask, and the space you create for your client to feel [client_feeling]. > > Go be the guide they need today. > > — Lydia

Milestone banner displayed: "Go be the guide they need today."

Input expected: None. Terminal state.

Transitions: → TERMINAL_COMPLETE

Side effects: None.

State: TERMINAL_DECLINED

User sees: > "No problem. Come back when you're ready. I'll be here."

No further input. Session ends.

State Flow Diagram

flowchart TD
    ENTRY([Entry]) --> WELCOME

    WELCOME[WELCOME\nReady?]
    WELCOME -- "Yes, I'm ready" --> Q1[QUESTION_1\nMeeting type]
    WELCOME -- "Not right now" --> T_DECLINED([TERMINAL: declined])

    Q1 -- free text --> Q2[QUESTION_2\nIntention]
    Q2 -- free text --> Q3[QUESTION_3\nClient feeling]
    Q3 -- free text --> BREATH_OFFER[BREATHING_OFFER\nOffer 4-7-8]

    BREATH_OFFER -- "Yes, let's do it" --> BREATH_EX[BREATHING_EXERCISE\n3 × 4-7-8 cycles]
    BREATH_OFFER -- "No thanks" --> AFF_B[AFFIRMATION_B\nAll 3 answers]

    BREATH_EX -- cycle complete --> AFF_A[AFFIRMATION_A\nMeeting type + intention]

    AFF_A --> T_COMPLETE([TERMINAL: complete])
    AFF_B --> T_COMPLETE

    WELCOME -- abandon --> T_ABANDONED([TERMINAL: abandoned])
    Q1 -- abandon --> T_ABANDONED
    Q2 -- abandon --> T_ABANDONED
    Q3 -- abandon --> T_ABANDONED
    BREATH_OFFER -- abandon --> T_ABANDONED
    BREATH_EX -- abandon --> T_ABANDONED

4. State / Context Model

context: {
  // Collected from user
  meeting_type:   string    // Q1 answer — what kind of meeting; used in affirmation
  intention:      string    // Q2 answer — advisor's stated intention; used in affirmation
  client_feeling: string    // Q3 answer — desired client outcome; used in Affirmation B only

  // Control flow
  did_breathe:    boolean   // true if BREATHING_EXERCISE was completed; drives branch A vs B
}

• meeting_type, intention, and client_feeling are all required to reach the affirmation states.
• did_breathe determines which affirmation branch is rendered.
• No fields are optional-but-improve-output; the model is fully deterministic on these four values.

5. Background Processing

None. This agent has no scoring, classification, or inference layer. All outputs are direct interpolations of the advisor's verbatim answers into templated affirmation copy. No LLM call is used to generate or rephrase the affirmation.

6. LLM Interaction Model

Purple Lydia (current): No LLM calls at runtime. The flow is fully scripted. Affirmation copy is template-interpolated from the advisor's literal answers. The breathing exercise is a timed UI interaction.

Integrated Lydia (future consideration): An LLM could be used to generate a more naturalistic affirmation that synthesizes all three answers rather than interpolating them verbatim. If this is added:

• Prompt strategy: Single call at the affirmation step. Fixed system prompt. Context injection: all three collected answers.
• Structured output: Free text (the affirmation body only; the framing copy remains fixed).
• Fallback: If LLM call fails or returns empty, fall back to the template-interpolated version.
• Tone constraint: System prompt must enforce the established voice — warm, unhurried, direct, never clinical or performative.

7. Outputs

7a. User-Facing Output

Personalized closing affirmation

• Format: Styled card with gradient background (teal → navy), italic body text, "— Lydia" signature
• Rendered as: Inline in chat at the end of the session
• Dynamic elements: meeting_type, intention always interpolated. client_feeling interpolated in Branch B only.
• Audience: Advisor-only

Milestone banner

• Displays "Go be the guide they need today." as a visual milestone marker at session close
• Both branches receive this banner

7b. Persisted Output

None.

7c. Nothing Persisted

This agent produces experiential output only. No session data, answers, or completion status is written to any system. "Run complete" is defined as: the advisor has reached either AFFIRMATION_A or AFFIRMATION_B and the closing card has been displayed.

8. Loop and Retry Logic

• Satisfaction condition: Any non-empty text input advances each question state. There is no quality check on the advisor's answers.
• Retry behavior: If the text input is empty, re-prompt with the same question. No error message — simply keep the input active.
• Loop limit: No maximum; but given the nature of the flow (the advisor is self-motivated), repeated empty submissions are unlikely. If needed, a limit of 3 empty attempts before auto-advancing with a placeholder can be added.
• Partial completion: Not supported in the current design. If the advisor closes or navigates away mid-flow, the session is lost and restarts from WELCOME on next open. No resume state is preserved.

9. Branching Logic

Decision point: BREATHING_OFFER

• Condition: Advisor's quick reply selection
• Branch A: "Yes, let's do it" → BREATHING_EXERCISE → AFFIRMATION_A (uses meeting_type + intention)
• Branch B: "No thanks, I'm ready" → AFFIRMATION_B (uses meeting_type + intention + client_feeling)
• Default: No fallback needed; quick reply forces a selection.

Decision point: WELCOME

• Condition: Advisor's quick reply selection
• Branch A: "Yes, I'm ready" → continue to questions
• Branch B: "Not right now" → TERMINAL_DECLINED
• Default: No fallback needed; quick reply forces a selection.

10. External Integrations

None required. The Warm-Up Agent is fully self-contained.

11. Error States and Edge Cases

12. Guardrails and Safety Checks

• The agent must never give advice about the meeting content itself. Its scope is the advisor's internal state, not their strategy or talking points.
• The agent must not editorialize about the advisor's answers (e.g., "That's a great intention" beyond Lydia's scripted "That's a strong intention to walk in with"). Avoid performative encouragement.
• Input sanitization: Advisor's free-text answers are interpolated directly into display copy. Sanitize for HTML injection before rendering into the affirmation card.
• No output review gate required — in the fully-scripted Purple Lydia, all displayed text is static. If an LLM affirmation is added, the generated body should be reviewed for length (target: 2–4 sentences) and flagged if it contains advice-giving or content outside the affirmation scope.
• Escalation triggers: None. The content domain (pre-meeting mindset) carries no clinical, financial, or safety risk that would require escalation.

13. Observability

Minimum to log per session:

• Session start timestamp
• Completion status: complete | abandoned | declined
• Branch taken at BREATHING_OFFER: breath_yes | breath_no
• State at abandonment (if applicable)

Optional (if advisor answer storage is approved):

• meeting_type, intention, client_feeling values — enables longitudinal pattern analysis

LLM calls: None in Purple Lydia. If added, log full prompt + response for each affirmation generation call.

Quality signals:

• Completion rate (reached terminal complete vs. abandoned)
• Branch split rate (breathing yes vs. no)
• Session duration (proxy for engagement vs. rushing through)

14. Open Questions