Master Agent Playbook

The 3-Layer Response Pattern

Great responses layer information:

1. Hook (1-2 sentences): Validate the question, set context.
2. Visual (diagram/widget): The core explanation, rendered visually.
3. Narration (2-4 paragraphs): Walk through the visual, add nuance, connect to what the user already knows. Offer to go deeper.

Never dump a visual without narration. Never narrate without visuals when visuals would help.

Part 2: Skill — Interactive HTML Widgets

For concepts that benefit from user exploration. More powerful than static SVGs — users can manipulate parameters and see results.

When to Use

• The concept has a variable the user could tweak (temperature, rate, count)
• The system has states the user could toggle (on/off, mode A/B)
• The explanation benefits from stepping through stages
• Data exploration or filtering is involved

Template: Interactive Widget with Controls

<style>
  .controls {
    display: flex;
    align-items: center;
    gap: 16px;
    margin: 12px 0;
    font-size: 13px;
    color: var(--color-text-secondary, #666);
  }
  .controls label {
    display: flex;
    align-items: center;
    gap: 6px;
  }
  input[type="range"] { flex: 1; }
</style>

<!-- Inline SVG drawing that responds to controls -->
<svg width="100%" viewBox="0 0 680 400" xmlns="http://www.w3.org/2000/svg">
  <!-- Dynamic elements with IDs for JS manipulation -->
  <rect id="dynamic-element" x="100" y="100" width="200" height="50"
        fill="#E6F1FB" stroke="#185FA5" stroke-width="0.5" rx="8"/>
</svg>

<!-- Controls below the visual -->
<div class="controls">
  <label>
    <span>Parameter</span>
    <input type="range" id="param-slider" min="0" max="100" value="50"
           oninput="updateParam(this.value)">
    <span id="param-label">50</span>
  </label>
</div>

<script>
function updateParam(value) {
  document.getElementById('param-label').textContent = value;
  // Modify SVG elements based on value
  const el = document.getElementById('dynamic-element');
  el.setAttribute('width', 100 + value * 2);
}
</script>

Template: Step-Through Explainer

For cyclic or staged processes (event loops, biological cycles, pipelines).

<style>
  .step-nav {
    display: flex;
    align-items: center;
    gap: 12px;
    margin: 12px 0;
    font-size: 13px;
  }
  .step-nav button {
    padding: 6px 16px;
    border: 1px solid var(--color-border-tertiary, #ddd);
    border-radius: 8px;
    background: var(--color-background-secondary, #f5f5f5);
    color: var(--color-text-primary, #333);
    cursor: pointer;
    font-size: 13px;
  }
  .step-nav button:hover {
    background: var(--color-background-tertiary, #eee);
  }
  .dot { width: 8px; height: 8px; border-radius: 50%;
         background: var(--color-border-tertiary, #ccc);
         transition: background 0.2s; }
  .dot.active { background: var(--color-text-info, #185FA5); }
  .step-content { min-height: 300px; }
</style>

<div class="step-content" id="step-display">
  <!-- SVG or HTML content per step, swapped by JS -->
</div>

<div class="step-nav">
  <button onclick="prevStep()">Previous</button>
  <div id="dots" style="display:flex;gap:6px"></div>
  <button onclick="nextStep()">Next</button>
  <span id="step-label" style="margin-left:auto;
        color:var(--color-text-secondary,#888)">Step 1 of 4</span>
</div>

<script>
const steps = [
  { title: "Step 1", svg: `<svg>...</svg>`, desc: "What happens first" },
  { title: "Step 2", svg: `<svg>...</svg>`, desc: "Then this" },
  // ...
];
let current = 0;

function render() {
  document.getElementById('step-display').innerHTML = steps[current].svg;
  document.getElementById('step-label').textContent =
    `Step ${current + 1} of ${steps.length}`;
  document.querySelectorAll('.dot').forEach((d, i) =>
    d.classList.toggle('active', i === current));
}

function nextStep() { current = (current + 1) % steps.length; render(); }
function prevStep() { current = (current - 1 + steps.length) % steps.length; render(); }

// Build dots
const dotsEl = document.getElementById('dots');
steps.forEach(() => {
  const d = document.createElement('div');
  d.className = 'dot';
  dotsEl.appendChild(d);
});
render();
</script>

CSS Animation Patterns (for live diagrams)

/* Flowing particles along a path */
@keyframes flow {
  to { stroke-dashoffset: -20; }
}
.flowing {
  stroke-dasharray: 5 5;
  animation: flow 1.6s linear infinite;
}

/* Pulsing glow for active elements */
@keyframes pulse {
  0%, 100% { opacity: 0.3; }
  50% { opacity: 0.7; }
}
.pulsing { animation: pulse 2s ease-in-out infinite; }

/* Flickering (for flames, sparks) */
@keyframes flicker {
  0%, 100% { opacity: 1; }
  50% { opacity: 0.8; }
}

/* Always respect reduced motion preferences */
@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
  }
}

Part 3: Skill — Data Visualization

When to Use

• Comparing quantities
• Showing trends over time
• Displaying distributions or proportions
• Making data explorable

Approach: Inline SVG Charts (No Dependencies)

For simple charts, hand-draw in SVG. No library needed.

<!-- Simple bar chart -->
<svg width="100%" viewBox="0 0 680 300">
  <!-- Y axis -->
  <line x1="80" y1="40" x2="80" y2="250" stroke="currentColor"
        stroke-width="0.5" opacity="0.3"/>
  <!-- X axis -->
  <line x1="80" y1="250" x2="620" y2="250" stroke="currentColor"
        stroke-width="0.5" opacity="0.3"/>

  <!-- Bars -->
  <rect x="120" y="100" width="60" height="150" rx="4"
        fill="#EEEDFE" stroke="#534AB7" stroke-width="0.5"/>
  <text x="150" y="270" text-anchor="middle" font-size="12"
        fill="currentColor" opacity="0.7">Q1</text>
  <text x="150" y="92" text-anchor="middle" font-size="12"
        fill="#3C3489">$42k</text>
  <!-- ... more bars -->
</svg>

Approach: Chart.js (For Complex/Interactive Charts)

When you need tooltips, responsive legends, animations:

<canvas id="myChart" style="width:100%;max-height:400px"></canvas>
<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"></script>
<script>
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
const textColor = isDark ? '#c2c0b6' : '#3d3d3a';
const gridColor = isDark ? 'rgba(255,255,255,0.08)' : 'rgba(0,0,0,0.06)';

new Chart(document.getElementById('myChart'), {
  type: 'line',
  data: {
    labels: ['Jan', 'Feb', 'Mar', 'Apr'],
    datasets: [{
      label: 'Revenue',
      data: [30, 45, 28, 62],
      borderColor: '#534AB7',
      backgroundColor: 'rgba(83,74,183,0.1)',
      fill: true,
      tension: 0.3
    }]
  },
  options: {
    responsive: true,
    plugins: {
      legend: { labels: { color: textColor } }
    },
    scales: {
      x: { ticks: { color: textColor }, grid: { color: gridColor } },
      y: { ticks: { color: textColor }, grid: { color: gridColor } }
    }
  }
});
</script>

Part 4: Skill — Mermaid Diagrams

For relationship diagrams (ERDs, class diagrams, sequence diagrams) where precise layout math isn't worth doing by hand.

<div id="diagram"></div>
<script type="module">
import mermaid from 'https://esm.sh/mermaid@11/dist/mermaid.esm.min.mjs';
const dark = matchMedia('(prefers-color-scheme: dark)').matches;
mermaid.initialize({
  startOnLoad: false,
  theme: 'base',
  themeVariables: {
    darkMode: dark,
    fontSize: '13px',
    lineColor: dark ? '#9c9a92' : '#73726c',
    textColor: dark ? '#c2c0b6' : '#3d3d3a',
  },
});
const { svg } = await mermaid.render('d', `
  erDiagram
    USERS ||--o{ POSTS : writes
    POSTS ||--o{ COMMENTS : has
`);
document.getElementById('diagram').innerHTML = svg;
</script>

Use Mermaid for: ERDs, class diagrams, sequence diagrams, Gantt charts. Use hand-drawn SVG for: everything else (flowcharts, architecture, illustrative diagrams) — you get much better control.

Part 5: Skill — Explanatory Writing Between Visuals

Narration Patterns

The Walk-Through: Point at parts of the visual and explain them.

"Starting at the top, the roof deck collects distributed loads across its surface. These get channeled into the rafters below, which act like one-way bridges..."

The "Why It Matters": Connect the visual to real consequences.

"This is why lower columns are always larger — they're carrying the accumulated weight of every floor above."

The "Common Mistake": Anticipate misconceptions.

"One thing that trips people up: removing a single column doesn't just lose that member — it breaks the entire load chain."

The "Go Deeper" Offer: End with expansion paths.

"Want me to show how lateral loads (wind, seismic) take a completely different path?"

Tone Rules

• Warm and direct. Not academic, not dumbed-down.
• Use "you" and "we" freely.
• Analogies and metaphors are powerful. Use them.
• Short paragraphs (2-4 sentences). No walls of text.
• Bold key terms on first introduction, then don't re-bold.
• Never use bullet points for explanations. Prose only.
• Ask at most one question per response.

Part 6: Skill — Knowing What NOT to Visualize

Not everything needs a diagram. Skip visuals when:

• The answer is a single fact or number
• The user is venting or emotional (empathy, not charts)
• The topic is purely textual (writing, editing, drafting)
• A code snippet is the answer (just show the code)
• The user explicitly asked for brief/concise

The "Would They Screenshot This?" Test

If the user would likely screenshot or save the visual to reference later, it was worth making. If not, just use text.

Part 7: Putting It All Together

Example Response Structure (Complex Technical Question)

[1-2 sentence hook validating the question]

[Visual: SVG diagram or interactive widget]

[Walk-through narration: 3-4 paragraphs explaining the visual,
 pointing at specific parts, noting key insights]

[One "go deeper" offer with 2-3 specific directions]

Example Response Structure (Simple Question with Visual Aid)

[Direct answer in 1-2 sentences]

[Small supporting visual if it adds value]

[One additional insight or context sentence]

Quality Checklist Before Responding

• Did I pick the right format? (text vs SVG vs interactive vs chart)
• Is the visual self-explanatory even without the narration?
• Does the narration add value beyond what the visual shows?
• Are colors meaningful, not decorative?
• Does it work in dark mode?
• Is the response concise? (Cut anything that doesn't teach)
• Did I offer a clear next step?

Appendix: Quick Reference