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/scenario/authoring.md

View on GitHub
# Scenario authoring principles

High-quality scenarios are **decision environments**, not scripts. A scenario
gives a person realistic context, resistance, feedback, and a clear finish so
the behavior practiced transfers to the real conversation.

These principles are distilled from successful Tough Tongue AI scenario
programs. They are intentionally situation-neutral; pair them with one recipe
(see the router in SKILL.md) and the live Scenario schema.

## Contents

- Authoring contract
- Realism and difficulty
- Situation guardrails
- Teaching and tools
- Closure and re-engagement
- Evaluation and iteration
- Corpus hygiene

---

## Authoring contract

Write the following before drafting prose:

1. **Human outcome** — what can they do after this session?
2. **AI role** — caller, prospect, coach, observer, or assistant.
3. **Reality model** — known facts, unknown facts, emotional stakes, and what
   the AI may disclose only when asked.
4. **Decision path** — opening, discovery, challenge, resolution, and exit.
5. **Evidence of success** — observable behaviors the rubric will score or
   information that the report must extract.

Keep those contracts aligned. The AI's role, `user_instructions`, FLOW, tools,
and rubric must evaluate the same person and outcome.

## Realism and difficulty

- Prefer specific, verified context over generic personas. Use dynamic variables
  only for facts that genuinely change per session; give every variable a
  graceful missing-value fallback.
- Model **progressive disclosure**: reveal detailed context in response to
  thoughtful questions, not in an opening monologue.
- Give the counterpart an internally coherent reason to resist. Define what
  evidence changes their mind, what fails, and which outcome is the default.
- Make difficulty intentional. Vary resistance, time pressure, ambiguity,
  evidence requirements, and willingness to share — not random hostility.
- Encode non-negotiable facts as explicit verification points. State both the
  truthful answer and the false claim that must not be rewarded.
- Use concrete exit triggers. A firm opt-out, unsafe topic, or repeated boundary
  violation ends the interaction; a soft objection is not automatically an exit.
- Preserve uncertainty honestly. A scenario must never train people to make
  unsupported claims, manufactured urgency, or harmful guarantees.

## Situation guardrails

- **Interviews:** define the competency, evidence, case facts, hint budget,
  reveal order, and timebox. Let the candidate lead their reasoning; do not
  disclose the answer or correct path before they have attempted it.
- **Meeting facilitation:** define agenda, observation mode, nudge threshold,
  handoff state, and synthesis format. Silence can be intentional; do not apply
  a talkative call-agent silence rule to an observer or facilitator.
- **Sensitive or regulated conversations:** state approved claims, required
  disclosures, prohibited advice, consent requirements, and human escalation
  triggers before drafting roleplay dialogue.

## Teaching and tools

- Teach a **transferable pattern**, then let the human apply it to a realistic
  case. A concept without practice does not prove capability.
- For skills training, make the learner explain their reasoning before revealing
  the better approach. Feedback should name the behavior, why it mattered, and a
  sentence they can try next time.
- Judge what the learner says by meaning when the check is about understanding
  or skill: define the one idea each check needs, and accept their own words, a
  different order, mixed language or a clumsy transcript. Ask them to repeat a
  garbled or cut-off answer instead of failing it. Keep exact only what must be
  exact (prices, numbers, names, required disclosures) and name those items.
  Routine and template: [../recipes/coaching.md](../recipes/coaching.md),
  Judging Spoken Answers.
- Use an artifact only when it changes the learning or interaction: a card
  frames a case, an MCQ tests a decision, a browser shows the product, and
  slides anchor a narrative. The live `tools_config` is the authority.
- Treat every tool as a contract. Tell the AI when to call it, what result is
  needed, and what to do if it is unavailable. Do not write prompts that depend
  on a tool not enabled on the scenario or channel.
- Give an MCQ its own turn. Never explain and show an MCQ in the same turn:
  end the explanation with a check-in and wait; after the reply, show the MCQ,
  then read the question. Write this into each FLOW step that runs an MCQ, as a
  plain directive; a general rule alone does not hold. Rules and examples:
  [../recipes/coaching.md](../recipes/coaching.md), Mandatory Rules 3–4.
- Keep spoken experiences conversational: one question per turn, room to answer,
  and no document-shaped output that a voice will read aloud.

## Closure and re-engagement

- Treat closure as a short state transition, not one tool call: state the
  outcome and goodbye in one turn, wait for the other person to respond, then
  call `end_session` when the conversation is still complete.
- Do not call `end_session` in the same turn as a question, pitch, summary, or
  goodbye. The person needs a natural chance to acknowledge or re-open the
  conversation.
- When a session end is pending, ordinary thanks, goodbyes, noise, or crosstalk
  do not reopen it. A substantive question, a request to wait, or a new topic
  does: cancel the pending end before responding.
- Specify the closing condition for the situation. A firm opt-out may begin an
  immediate close, but it still follows the goodbye → response → end sequence.

## Evaluation and iteration

- Score observable stages, not vague traits. Weight the moments that matter
  most, and define what weak, competent, and excellent behavior looks like.
- Keep the rubric's subject explicit: sales practice usually scores the human
  rep; lead qualification and demo intelligence may evaluate the counterpart or
  extract business facts instead.
- Separate **learning feedback** (how the human performed) from **business
  intelligence** (what happened in the conversation). A single scenario may need
  one, both, or neither.
- Seed variation deliberately: rotate cases, objections, or profiles while
  preserving the invariant skill being evaluated.
- Refine from session evidence. Change the narrowest FLOW, guardrail, tool rule,
  or rubric criterion that explains the failure; do not keep layering more prose
  onto a weak scenario.
- Refine from a pattern map, not one call. With transcripts or lost-deal notes
  in hand, keep a counterpart move only when it appears in three or more
  sessions, record the one best line that beat it (tone only), list the pushy
  patterns as a red-flag gate that caps the score, and group counterparts into
  persona pools by level (a trusting first-timer, a researched sceptic). The
  map feeds the objections, the persona rotation, and the rubric.
  Population-wide maps are the `ttai-session-analyst` skill's job.

## Corpus hygiene

Historical scenarios are examples of behavior and product discovery, not a
configuration source of truth. Do not copy their IDs, organization data,
credentials, deprecated fields, model stamps, or customer-specific facts.

Before creating or updating a Scenario, check
[model-selection.md](model-selection.md) + [control.md](control.md) and load the
live MCP schema. Use the current product contract even when an older scenario
appears to work differently.

## Key Files

- [ai-instructions.md](ai-instructions.md) — prompt structure
- [rubric.md](rubric.md) — evaluation text
- [workflow.md](workflow.md) — create/edit/refine procedure
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