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.
| System | Operation | Data | Required / Optional | Purple Lydia | Integrated Lydia |
|---|
| Calendar | read | upcoming meeting metadata | optional | no | possible unlock — auto-surface warm-up before scheduled meetings |
| CRM | read | client name | optional | no | possible unlock — personalize affirmation with client name |
| Advisor profile | write | session log, intention history | optional | no | possible unlock — longitudinal tracking of coaching posture |
11. Error States and Edge Cases
| Condition | Agent behavior |
|---|
| User submits empty text at Q1, Q2, or Q3 | Keep input active; do not advance. No error message shown. |
| User closes the app mid-breathing-exercise | Session lost; restarts from WELCOME on next open. No error state. |
| Breathing cycle interrupted (tab background, sleep) | Timer continues running in background if JS execution allows; if not, the cycle may desync. Consider resetting the cycle or showing a "Start again?" prompt. |
| User types a very long answer (e.g., paragraph) | Accept as-is. The affirmation interpolates the full text; if truncation is needed for display, trim at a reasonable character limit with ellipsis. |
| User asks Lydia a question during the flow | Not applicable in the scripted Purple Lydia implementation. In an LLM-backed version, the agent should stay on-flow and gently redirect: "Let's stay with the warm-up — you can come back to that after." |
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
| Question | Priority | Owner |
|---|
| Should meeting metadata (client name, meeting type) be injected from calendar at entry in Integrated Lydia? | Medium | Tyler |
| Is an LLM-generated affirmation in scope for any phase, or template-only permanently? | Medium | Tyler |
| Should any session data (even anonymous completion events) be logged for usage analytics? | Medium | Tyler |
| Should the breathing exercise support more or fewer than 3 rounds, or let the advisor choose? | Low | Tyler |
| Is partial-session resume (returning to mid-flow state) ever needed? | Low | Tyler |