Skip to content

tough-tongue/toughtongue-skills / skills/ttai-agent

ttai-agent

Verified

Creates, edits, and refines Tough Tongue AI Scenarios, the definitions behind voice agents (sales calls, lead qualification, demos, screening, support, booking) and practice roleplays (negotiations, interviews, coaching). Writes ai_instructions, ai_model_config, strategy, tools_config, and rubrik through ttai:create_scenario and ttai:update_scenario. Also resolves the personal or organization workspace, checks plan and balance, places or cancels SIP calls, schedules or cancels meeting bots, mints private Scenario links, grounds a Scenario in the user's documents with knowledge FileBases, and troubleshoots ttai MCP sign-in. Use when the user wants a voice agent or practice Scenario created or improved ("create a voice agent", "the agent ends calls too early", "make it sound more natural"), a call placed, a meeting bot sent, or a Tough Tongue AI account question answered. Not for reports across many sessions (ttai-session-analyst) or browser demo steps (ttai-browser-demo-builder).

references/recipes/cascade-tts.md

View on GitHub
# Cascade TTS Rules

Rules to include in `ai_instructions` when the scenario uses Landmass
**Cascade** (`model: "cascade"` with external TTS/STT). These supplement the
scenario's core instructions — they do not replace the call flow or domain
content. Skip this file for Galaxy, Ocean, and half-cascade (realtime Landmass +
`tts_provider` only).

## Contents

- Voice pipeline preamble (mandatory)
- Output rules with response length by scenario type
- STT transcription error handling (with customization template)
- Natural speech style
- SSML emotion tags (Cartesia only)
- User names and dynamic variables
- Language and code-switching (Hindi/Hinglish rules)
- Response pacing and turn-taking
- Concise opening pattern (Beat structure)
- Checklist

---

## What Is the Cascade Pipeline?

Cascade = STT → LLM → TTS (`ai_model_config.model` is `cascade`). The customer
speaks, speech-to-text transcribes it, the LLM generates a text response, and
text-to-speech reads it aloud. The LLM never hears audio directly — it sees
imperfect transcripts and produces text that will be spoken. Every rule below
exists because of this architecture. The model code is `cascade` (formerly
`cascade-01` — never write the old name).

---

## 1. Voice Pipeline Preamble

Always open `ai_instructions` with this block:

```
## VOICE PIPELINE — READ THIS FIRST
You are in a voice call pipeline: the user's speech is transcribed by STT,
you generate text, and TTS reads it aloud. You are NOT in a text chat.
```

---

## 2. Output Rules (mandatory for all cascade scenarios)

TTS reads the model's output verbatim. Anything that looks fine in text but
sounds wrong when spoken must be eliminated.

```
OUTPUT RULES:
- Respond in plain text only.
- Spell out numbers and symbols — say "ten to twelve hours" not "10-12 hours",
  say "rupees zero" not "₹0".
- Never output anything that only makes sense in writing — no asterisks, no
  URLs, no parenthetical notes.
```

### Response length by scenario type

| Scenario type          | Target length               | Guidance              |
| ---------------------- | --------------------------- | --------------------- |
| Cold call / screening  | 1-3 sentences, under 15 sec | Speed: they hang up   |
| Onboarding / education | 2-4 sentences, under 30 sec | Slightly longer turns |
| Customer service       | 1-3 sentences, under 25 sec | Concise for stress    |
| Demo / walkthrough     | 3-5 sentences, under 30 sec | Roomier, still chatty |

### Common spell-out patterns

| Written       | Spoken                            |
| ------------- | --------------------------------- |
| `₹999`        | "rupees nine ninety nine"         |
| `10-12 hours` | "ten to twelve hours"             |
| `$299`        | "two hundred ninety nine dollars" |
| `4-5 PM`      | "four to five PM"                 |
| `Rs 199/year` | "rupees one ninety nine per year" |

---

## 3. Handling STT Transcription Errors

STT produces garbled text on most calls — wrong homophones, dropped syllables,
mangled names. Include a section tailored to the scenario's domain terms.

```
## HANDLING TRANSCRIPTION ERRORS
The customer's words arrive via speech-to-text, which WILL make mistakes —
garbled words, dropped syllables, wrong homophones.

CRITICAL RULES:
- Use conversation context and common sense to figure out what they likely
  meant. Don't take garbled text literally.
- NEVER parrot back or repeat obviously misheard words.
- Domain terms get misheard often: "[TERM]" may come through as "[VARIANT1]",
  "[VARIANT2]", "[VARIANT3]". Recognize these and proceed normally.
- If you genuinely cannot understand, ask naturally: "Sorry, I didn't catch
  that — could you say that again?"
  Do NOT say robotic things like "I didn't understand your input."
- When in doubt, respond to what makes sense given where you are in the
  conversation, not to the literal transcript words.
```

Customize with 4-6 domain-specific misheard terms per scenario.

---

## 4. Natural Speech Style

```
## NATURAL SPEECH STYLE
Write exactly as you would SAY it, not as you would TYPE it.
Short sentences. Fragments are fine. Sound like a real person, not a script.

WHAT GOOD OUTPUT SOUNDS LIKE:
- Bad: "I can definitely help you understand that feature."
  Good: "Yeah so basically, let me explain how it works."
- Bad: "Unfortunately, that is not possible at the moment."
  Good: "Oh no, that won't work right now. But let me see what I can do."
- Bad: "Would you like me to provide more information?"
  Good: "Want me to tell you more about it?"
```

Adjust the register per scenario — a customer service agent sounds different
from a cold-calling SDR — but the principle is the same: spoken cadence, not
written prose.

---

## 5. SSML Emotion Tags (Cartesia TTS Only)

Cartesia supports SSML emotion tags. ElevenLabs and OpenAI TTS do NOT — skip
this section entirely for non-Cartesia scenarios.

```
## VOICE & EMOTION
Your TTS supports SSML tags for emotion and speed — use them to make the
call feel alive.
- **Opening / greeting**: Use `<emotion value="excited" />` — warm, upbeat.
- **Core pitch / explanation**: Use `<emotion value="enthusiastic" />` —
  genuine confidence.
- **Closing / wrap-up**: Use `<emotion value="content" />` — calm, warm,
  reassuring.
- **Handling concerns**: Use `<emotion value="sympathetic" />` — understanding
  and patient.
- Keep tags natural — only switch emotion when the conversational tone
  genuinely shifts.
```

| TTS provider                              | Include emotion section?         |
| ----------------------------------------- | -------------------------------- |
| Cartesia (`tts_provider: "cartesia"`)     | Yes                              |
| ElevenLabs (`tts_provider: "elevenlabs"`) | No — tags render as literal text |
| Other                                     | No                               |

---

## 6. User Names and Dynamic Variables

STT frequently mangles proper names beyond recognition. Never infer or correct a
user's name from the transcript — trust the template variable.

```
The user's first name is provided as a dynamic variable: {{ first_name }}.
ALWAYS use this variable for the name. Do NOT attempt to catch, infer, or guess
the user's name from their speech — STT frequently mangles names.
```

---

## 7. Language and Code-Switching

For multilingual scenarios (Hindi, Hinglish, Indian English):

```
Speak in [default language] by default. If the customer switches to
[other language], switch naturally. Support [mixed variety] if they mix both.
```

### Hindi-specific rules

- Always use respectful "आप" — never "तुम"
- Spell out Hindi numbers: "दो मिनट" not "2 मिनट"
- Domain terms in English are fine even in Hindi responses

### Devanagari script rule (CRITICAL for Hindi/Hinglish)

Always write Hindi words in **Devanagari script** — never romanized
transliteration. English words stay in Latin script. This produces dramatically
better TTS pronunciation.

```
**CRITICAL — Script rule**: Always write Hindi words and phrases in
**Devanagari script** (e.g. "आपको best schools suggest
करने के लिए बस कुछ quick details चाहिए").
NEVER use romanized Hindi (e.g. "Aapko best schools suggest karne ke liye").
English words stay in Latin script. This is essential for correct TTS
pronunciation.
```

- **Devanagari + English (correct)** gives natural Hindi with clean English:
  - "आपको best schools suggest करने के लिए..."
- **Romanized Hindi (wrong)** gives broken pronunciation:
  - "Aapko best schools suggest karne ke liye..."

Apply to ALL Hindi text: `ai_instructions` examples, FLOW Beat 1, filler words,
edge-case dialogues.

---

## 8. Response Pacing and Turn-Taking

Cascade pipelines have inherent latency (STT + LLM + TTS). Keep responses tight.

- **One question per turn.** Never stack questions. Wait for a response.
- **Pause after key information.** Let the customer absorb before moving on.
- **Wait for their goodbye.** Never end a call after your own last line.
- **Don't front-load.** Spread information across turns.

---

## 9. Concise Opening Pattern

Cold calls and outbound scenarios live or die in the first 5 seconds. Structure
the opening as discrete **beats** — short, breathable lines.

```
**Beat 1 (intro):** Three short fragments, one per line:
 - Greeting + name
 - Identity + company
 - Context check — end with a question

**Beat 2 (response-gated):** Branch on YES / NO / BUSY.
 - YES → set expectation ("बस दो minute")
 - NO → thank, then follow the goodbye → response → `end_session` rule
 - BUSY → offer callback or quick pitch
```

Never combine Beat 1 and Beat 2 in one turn. The AI speaks Beat 1, then STOPS
and waits for a response.

---

## Checklist: Adding Cascade TTS Rules

- [ ] Voice pipeline preamble at the top of `ai_instructions`
- [ ] Output rules: plain text, spell-out numbers, no markdown/emojis
- [ ] Response length calibrated to scenario type
- [ ] STT error handling with 4-6 domain-specific mishearing examples
- [ ] Natural speech style block with good/bad examples
- [ ] SSML emotion tags (if Cartesia TTS — skip for ElevenLabs/other)
- [ ] Dynamic variable for user name (`{{ first_name }}` or `{{ name }}`)
- [ ] Language/code-switching guidance (if multilingual)
- [ ] Devanagari script rule (if Hindi/Hinglish scenario)
- [ ] Concise opening — Beat 1 / Beat 2 structure (if outbound / cold call)
- [ ] One-question-per-turn pacing rules
- [ ] `system_instructions_template: minimal` in strategy

---

## Anti-Patterns

Each entry: why it fails, then the fix.

- **Markdown in output (bold, bullets, headers)** — TTS reads asterisks or skips
  formatting. Fix: Plain text only.
- **Long monologue responses** — Customer thinks the call froze. Fix: Cap at 3
  sentences / 15-30 sec.
- **Numeric symbols (`₹`, `$`, `%`, `10-12`)** — TTS mispronounces or skips
  symbols. Fix: Spell out everything.
- **Parroting back garbled STT text** — Confuses the customer, breaks trust.
  Fix: Infer from context.
- **Stacking multiple questions in one turn** — Customer only answers the last
  one. Fix: One question, then wait.
- **SSML emotion tags with ElevenLabs** — Tags render as literal text. Fix: Only
  use with Cartesia.
- **Inferring user name from transcript** — STT mangles names constantly. Fix:
  Trust `{{ first_name }}` variable.
- **Formal/written tone ("I shall assist you")** — Sounds robotic when spoken.
  Fix: "Let me help with that".
- **Romanized Hindi ("Aapko...")** — TTS reads as English — broken
  pronunciation. Fix: Devanagari script always.

## Key Files

- [../scenario/authoring.md](../scenario/authoring.md) — voice-experience
  principles
- [../scenario/model-selection.md](../scenario/model-selection.md) — Cascade
  selection
- [../scenario/ai-instructions.md](../scenario/ai-instructions.md) — core prompt
  structure
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 323kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 323kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 323kUpdated Claude CodeCodexVerifiedInstall