10 — Our Agents vs Best Practice

This is the action page. It maps Maverick / Elena / Bruno today to the patterns documented in sections 02-09 and identifies the specific changes needed.

Summary table

Maverick — specific changes

Architectural change: move into Agent Studio

Today Maverick is a 920-line custom orchestrator in lib/search/orchestrator.ts. It does: 1. Load Redis session → detect pushback → extract 8 signals (Gemini JSON call) → guard intent 2. Merge signals into Redis → analyze discovery state → emit signals event 3. Load Atlas map → build retrieval query → run Algolia search → emit sources 4. Build prompt with dossier → stream Gemini response → parse discovery/handoff tags 5. Process metadata → emit final event → persist telemetry

Most of this can move into Agent Studio: - Step 1 (signal extraction): Becomes a client_side tool capture_user_signals that the agent calls. Round-trip: agent generates structured signal extraction → frontend persists to Redis → returns merged state. OR: signals stay as a separate Gemini JSON call OUTSIDE Agent Studio if performance demands it; pass the result into Maverick's completion request as part of the user message context. - Step 2 (discovery analysis): Becomes prompt instructions. The Multi-Intent Handling section in the AskAI prompt skeleton handles "what do I do given the current state." - Step 3 (retrieval): Becomes Maverick's algolia_search_index tool with 6-8 indices. - Step 4 (prompt building + streaming): Native to Agent Studio — POST /completions with stream=true. - Step 5 (metadata + telemetry): Becomes either a client-side post-processing layer or moves into Agent Studio's conversation persistence + sendUsage.

After this move, orchestrator.ts shrinks from 920 lines to maybe 80-150 lines (the parts that stay code: signal storage in Redis, telemetry shipping). Most of the 920 lines becomes prompt content + tool config.

Specific prompt changes

1. Strip the persona theatre. Maverick's "Vibrant, Energetic, Witty" voice descriptions are decorative. Brand voice lives in frontend (avatar, name display). Keep Maverick's role definition ("Senior AE, value-selling, no code") because that DOES change behavior — but state it once in systemPrompt, not three times across instructions.
2. Strip the analogy_canvas opener requirement. It's a custom output tag for the first turn only. Either (a) make it a render_opening_hook tool, or (b) drop it as a feature. The mandatory-on-first-turn behavior is fragile and the opening hook tradition can move into a frontend default greeting.
3. Add information guard to systemPrompt. Today Maverick has Directive 3 (grounding) but no injection defense. Add the standard guard block from §03.
4. Replace <discovery_pivot> with platform suggestions. config.suggestions.enabled: true produces follow-up suggestions natively. Drop the custom XML.
5. Strip the markdown indentation rules. "2 spaces NOT 4 spaces" etc. — frontend's markdown renderer handles this. The prompt shouldn't fight code-fence rendering with indentation pedantry.
6. Move handoff to a tool call. <specialist_handoff specialist="ELENA"> → handoff_to_specialist({ target: "elena" | "bruno", scope_summary: "..." }). Tool schema enforces structure. Frontend renders the handoff card via layoutComponent. Cleaner than prompt-tag protocol.

Elena — specific changes

Output: XML tags → tools

The 9 XML sections become 3-4 tools (per §05). Concretely:

[Today's XML output]
<specialist_handshake>...</specialist_handshake>  (or)
<specialist_summary>...</specialist_summary>
<specialist_report>
  <business_impact_roi>...</business_impact_roi>
  <implementation_steps>...</implementation_steps>
  <operational_gotchas>...</operational_gotchas>
  <project_handoff>...</project_handoff>
  [conditional: <analogy_canvas>, <customer_quote>, <code_intro>, <production_code>]
</specialist_report>

[After refactor — Hybrid (Shape C)]
Narrative text: brief recommendation + analogy + handoff statement
Tool calls (in parallel within one turn):
  • render_evidence_card(source, metric, driver_action_result)
  • render_implementation_plan(steps, links)
  • render_risk_list(risks: [{name, description, mitigation}])
  • render_code_block(language, code, explanation) — only if implementation question

Tools to define: 3 always-relevant + 1 conditional = 4 tools. Within the 3-5 ceiling.

Prompt: cut to ~50% size

• Remove all Unicode dividers
• Remove FORBIDDEN PHRASES block
• Remove NEGATIVE CONSTRAINTS block
• Remove "DEEP-DIVE ANSWER FRAMEWORK (SEE)" + "ANSWER STRUCTURE" overlap — pick one framework
• Remove markdown formatting rules
• Remove [HANDSHAKE] mode detection (make handshake a tool call OR drop the feature)
• Remove the EXECUTE MODE OUTPUT FORMAT XML spec (replaced by tool schemas)
• Add: AGENT ROLE (1 paragraph), RESPONSE GUIDELINES (5 bullets), DATA SOURCES (index list with descriptions), MULTI-INTENT HANDLING (which indices for which scenarios), TOOL USAGE PRIORITIES (when to call which render tool), ACTION LIMITATIONS, FALLBACK RULE
• Add systemPrompt with: AGENT IDENTITY (Solutions Engineer, no hex codes), HIERARCHY OF INSTRUCTIONS, INFORMATION GUARD

Target: ~800 words instructions + ~250 words systemPrompt = ~1,050 words total. Today: ~2,500 words.

Configuration

{
  "config": {
    "memory": { "enabled": true },
    "suggestions": { "enabled": true, "model": "gemini-2.5-flash-lite" },
    "widgetType": "chat",
    "useCache": true
  },
  "templateType": "askai"
}

Indices

After the index split (per §06), Elena's algolia_search_index tool gets 6-8 indices. Per-index searchParameters filter to the appropriate source types for Elena's role (heavy on docs, customer stories, blog, marketing; lighter on changelog).

Bruno — specific changes

Same structural changes as Elena, with these differences:

Tools

• 3-4 render tools, including render_architecture_diagram({ mermaid_source, description }) for the mandatory architecture diagram
• The Mermaid generation rules (8-15 nodes, parallel flows, subgraphs) move INTO the tool's schema description, not the prompt
• Other Bruno-specific tools: render_phased_roadmap({ phases: [...] }) for the 3-phase technical roadmap, render_scale_benchmarks({ metrics: [...] }) for hard numbers
• Strip the binary GO/NO-GO XML — make it a tool argument: render_recommendation({ verdict: "GO" | "NO_GO" | "CAUTION", feasibility, bottleneck })

Prompt

Strip the 80-line Mermaid syntax instructions from the prompt — move to the render_architecture_diagram tool's description and have the frontend layoutComponent validate and render. Tool schema can include constraints (mermaid_source validated against syntax rules at frontend time). The prompt becomes about WHEN to render an architecture diagram, not HOW to format Mermaid.

Indices

Same set as Elena, but Bruno's searchParameters.filters skews toward source_type:doc OR source_type:api OR source_type:guide OR source_type:changelog OR source_type:academy — same as today.

Cross-cutting decisions to make before refactor

These need to be locked before code/config changes:

Migration order

Recommended sequence (depends on R1-R6 research outputs for indices):

1. First (no platform research blocking): Strip persona theatre, Unicode dividers, FORBIDDEN PHRASES, redundant rules from Elena and Bruno prompts. Add information guard. Cut prompt size by ~50%. Test against current XML output (Shape D maintained for now). This is a pure-prompt refactor with no behavioral risk if XML output stays.

2. Second (frontend dependency): Define 3-4 render tools per agent (Elena, Bruno). Build layoutComponent for each. Update agent configs to add tools. Update prompts to call tools instead of emitting XML. Frontend swaps from XML parser to tool-driven rendering.

3. Third (platform features): Enable memory.enabled and suggestions.enabled. Replace Maverick's <discovery_pivot> with platform suggestions. Replace Redis conversation state with Agent Studio memory (keep Redis for 8-signal state).

4. Fourth (index split, depends on R1-R6): Split content into 6-8 source-type indices. Configure custom ranking, synonyms, rules per index. Update agent tool configs to list new indices. Update prompts' Multi-Intent Handling sections.

5. Fifth (Maverick into Agent Studio): Move Maverick's discovery + retrieval logic from orchestrator.ts into Agent Studio. Migrate handoff to tool call. Reduce orchestrator.ts to thin wrapper for telemetry + 8-signal Redis logic.

6. Sixth (cleanup): Delete the 350-line stream-adapter.ts (no longer needed once tools replace XML). Delete useSpecialist.ts and useChatStream.ts if frontend migrates to native <Chat> widget (per §12). Delete content-auditor logic that fights tool-structured output.

Each step is independent enough to ship + verify before starting the next. The first step (prompt cleanup with same XML output) is the lowest-risk highest-value first move.

What this section does NOT cover

• Specific tool schemas — see 02-tool-types and evidence/
• Index design rationale — see 06-multi-index-routing
• Frontend migration plan — see 12-ui-and-instantsearch
• Why we made these choices — see 04-agent-archetypes, 05-output-shape-decision, 09-evolution-deprecated-patterns