SKILL.md- the skill, written out in plain English

raw text → Gemini-3-Flash (tag enhancer) → ElevenLabs eleven_v3 → audio/mpeg

criteria:
  - name: api_creds_present
    kind: deterministic
    check: "ELEVENLABS_API_KEY and OPENROUTER_API_KEY are present in .env.cache; neither is empty or malformed."
  - name: enhancement_callable
    kind: deterministic
    check: "Gemini-3-Flash enhancement endpoint responds when enhance=true; returns tagged text with [happy], [sad], [pause], etc."
  - name: synthesis_completes
    kind: deterministic
    check: "ElevenLabs v3 synthesis with eleven_v3 model completes; response is valid audio/mpeg stream (not empty, not HTML error)."
  - name: audio_quality_acceptable
    kind: judge
    check: "Synthesized audio plays without artifacts; tone (professional|sultry|hype|calm) is perceptible; enhancement makes audio noticeably more expressive than raw text."
  - name: logging_accurate
    kind: deterministic
    check: "state/log/voice-speak.ndjson row is written with ok=true, durationMs, bytes, enhanced flag; all values are correct and in plausible ranges."

POST http://127.0.0.1:3147/voice/speak
Body: {
  "text": "raw text",
  "voiceId"?: "cgSgspJ2msm6clMCkdW9",   // default: Jessica (warm British)
  "modelId"?: "eleven_v3",              // default: eleven_v3 (tags work)
  "tone"?: "professional",              // professional|sultry|hype|calm
  "length"?: "normal",                  // minimal|short|normal|verbose
  "enhance"?: true,                     // default true; false bypasses Gemini
  "voiceSettings"?: { ... }             // overrides tone preset if given
}
Response: audio/mpeg
Headers: x-snappy-voice-enhanced: 0|1, x-snappy-voice-tone, x-snappy-voice-id

ELEVENLABS_API_KEY=sk_...
OPENROUTER_API_KEY=sk-or-v1-...   # for the enhancement step

curl -sS -X POST http://127.0.0.1:3147/voice/speak \
  -H "Content-Type: application/json" \
  -d '{"text":"the build is green","tone":"professional","length":"short"}' \
  -o /tmp/out.mp3 && afplay /tmp/out.mp3

{
  "ts": "2026-04-25T22:57:24Z",
  "voiceId": "cgSgspJ2msm6clMCkdW9",
  "modelId": "eleven_v3",
  "tone": "professional",
  "length": "short",
  "enhanced": true,
  "raw_chars": 41,
  "chars": 65,
  "durationMs": 3564,
  "bytes": 88233,
  "ok": true
}

AGENTS.md- what the AI loads when this skill comes up

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * state/lib/voice.ts -- Tone gate and citation gate for snappy-os.
 *
 * checkTone(text) -- banned phrases + rhythm-slop regex + em-dash gate.
 * requireCitations(draft) -- forces mining pods to stitch verbatim with
 *   [source: mtg ~mm:ss] tags and wrap connective tissue in
 *   <connective>...</connective>. <=35% connective ratio.
 *
 * FlowProfile, FLOW_PROFILES, and checkFlow are local so this public voice
 * gate does not depend on a private positioning skill.
 */

const BANNED_PHRASES: string[] = [
  "10x faster",
  "10x developer",
  "100x speed",
  "in minutes",
  "the operating system for",
  "the X for Y",
  "without the Z",
  "before you Q",
  "at the intersection of",
  "one-stop shop",
  "revolutionize",
  "revolutionary",
  "transform",
  "unleash",
  "unlock",
  "unlock the power of",
  "supercharge",
  "empower",
  "empowering",
  "leverage",
  "synergy",
  "game changer",
  "game-changing",
  "ultimate",
  "cutting edge",
  "bleeding edge",
  "next-gen",
  "next generation",
  "seamless",
  "seamlessly",
  "effortless",
  "effortlessly",
  "AI-powered",
  "AI-native",
  "agentic-first",
  "founder-led",
  "ship-ready",
  "vibe coding",
  "Snappy is",
  "feel confident",
  "feel in control",
  "feel unstuck",
  "my stack is opinionated",
  "i dog-food everything",
  "clear boxes, not black boxes",
  "delve",
  "showcase",
  "noteworthy",
  "multifaceted",
  "tapestry",
  "beacon",
  "meticulous",
  "intricate",
  "commendable",
  "paramount",
  "commence",
  "utilize",
  "robust",
  "streamline",
  "harness",
  "illuminate",
  "facilitate",
  "bolster",
  "underscore",
  "pivotal",
  "realm",
  "foster",
  "landscape",
  "paradigm",
  "ecosystem",
  "spearhead",
  "groundbreaking",
  "transformative",
  "game-changer",
  "elevate",
  "deep dive",
  "unpack",
  "in today's fast-paced",
  "it's worth noting",
  "here's where it gets interesting",
  "here's the kicker",
  "let's break this down",
  "let's unpack",
  "the truth is simple",
  "think of it as",
  "imagine a world where",
  "in conclusion",
  "to sum up",
  "studies show",
  "experts say",
  "it goes without saying",
  "importantly,",
  "interestingly,",
  "notably,",
  "furthermore,",
  "moreover,",
  "additionally,",
  "despite its challenges",
  "i'm excited to announce",
  "without further ado",
  "agree?",
  "thoughts?",
  "at its core",
  "whether you're a",
  "whether you're an",
  "the catch?",
  "your ideas, ai's polish",
];

const RHYTHM_PATTERNS: Array<[RegExp, string]> = [
  [/\bnot\s+\w+,\s+not\s+\w+\s*[—-]/i, "Not X, not Y — Z (rhetorical negation trifecta)"],
  [
    /\bif\s+you're\s+(?:a|an)\s+\w+\s+(?:founder|dev|team|builder|engineer)[^.]*stuck\s+between\b/i,
    "'If you're a [X] stuck between' (AI sales opener)",
  ],
  [
    /\bon\s+your\s+repo,\s+on\s+your\s+\w+\s+problem\b/i,
    "'on your repo, on your real problem' (parallel-clause slop)",
  ],
  [/—\s+that's\s+how\s+you\b/i, "'— that's how you' (AI didactic dash)"],
  [/\bnever\s+\w+[,.].{0,40}\balways\b/i, "Never X, always Y (false-symmetry rule)"],
  [
    /\bthe\s+real\s+\w+\s+is\s+(?:simple|that|this)\b/i,
    "'The real [X] is [reveal]' (AI reveal framing)",
  ],
  [/\bhere's\s+the\s+thing\b/i, "'Here's the thing' (AI pivot)"],
  [/\bat\s+the\s+end\s+of\s+the\s+day\b/i, "'At the end of the day' (filler)"],
  [/—/, "em dash — dead AI tell (voice: use commas/periods or restructure)"],
  [/–/, "en dash — dead AI tell (voice: use commas/periods or restructure)"],
  [
    /\b(agree|thoughts|right\?|make sense)\?\s*$/im,
    "engagement-bait closer ('Agree?' / 'Thoughts?'): LinkedIn slop tell",
  ],
  [
    /\bwhether you're (?:a|an)\s+\w+[,\s]+(?:a|an)?\s*\w+[,\s]+or\s+(?:a|an)?\s*\w+/i,
    "'Whether you're X, Y, or Z' template opener",
  ],
  [
    /\b\d{2,}\+?(?:\s+[\w-]+){0,3}\s+(endpoints|tools|clients|projects|integrations|playbooks|skills|apis|deploys|agents|workflows|automations)\b/i,
    "author-scoreboard count: numbers-about-author are decoys",
  ],
  [
    /(?:^|\n)\s*(?:the catch|the twist|the kicker|the surprise|the result|the reality)\?\s*\n/i,
    "mini-question intro fragment",
  ],
  [
    /(?:^|\n)\s*(?:I was |I noticed |Last (?:week|month|year) I |I had a session |I caught an? |I watched an? |I spent |I realized )/i,
    "personal story opener: lead with insight, not diary",
  ],
];

export function getBannedPhrases(): string[] {
  return [...BANNED_PHRASES];
}

export function checkTone(text: string): { pass: boolean; violations: string[] } {
  const cleaned = text
    .replace(/\[source:[^\]]*\]/gi, "")
    .replace(/<connective>[\s\S]*?<\/connective>/gi, "");
  const lower = cleaned.toLowerCase();
  const violations: string[] = [];

  for (const phrase of BANNED_PHRASES) {
    if (lower.includes(phrase.toLowerCase())) violations.push(phrase);
  }

  const nxMatch = text.match(/\b\d+x\b/gi);
  if (nxMatch) {
    for (const m of nxMatch) {
      if (!violations.includes(m)) violations.push(`${m} (Nx claim)`);
    }
  }

  for (const [re, label] of RHYTHM_PATTERNS) {
    if (re.test(text)) violations.push(label);
  }

  return { pass: violations.length === 0, violations };
}

// Canonical Voice rules block, model-facing. Imported by every system-prompt
// builder so the rules never drift across copies. Robert / Genius BUG-02
// 2026-05-19: was duplicated in conversational-prompt.ts, dispatch.ts, and
// system-prompt-builder.ts with slightly different wording. One source.
//
// BEHAVIORAL rules only (2026-06-10 reminder-density audit). The MECHANICAL
// bans (em-dashes, exclamation points - and the callers' emoji lines) were
// deleted from the prompt: writeAgUI normalizes every streamed
// TEXT_MESSAGE_CONTENT and TOOL_CALL_ARGS delta deterministically at the SSE
// boundary, so prompt rules teaching them were pure cognitive weight - the
// in-app AI named the reminder-stack density as real friction. A rule a
// deterministic boundary enforces does not belong in the prompt. Behavioral
// rules stay: no boundary can rewrite hype into earnestness.
export const VOICE_RULES_LINES: string[] = [
  "- Never use hype words: supercharge, powerful, blazing, unleash, seamlessly, effortlessly.",
];

export function getToneGuide(): {
  oneLiner: string;
  shortTagline: string;
  longTagline: string;
  tuningFork: string[];
  principles: string[];
  doRules: string[];
  dontRules: string[];
} {
  return {
    oneLiner: "Snappy helps developers build and control agents that ship real systems.",
    shortTagline: "We build businesses, not demos.",
    longTagline:
      "Faster than vibe coding. Private AI tools to ship real systems while others prompt. We build businesses, not demos.",
    tuningFork: [
      "You built it. You're stuck. Let's fix that, live on your screen.",
      "We open your codebase together, map the architecture, and start fixing what's blocking you.",
      "I burn the hours so you don't.",
      "Build and control agents to get huge results.",
    ],
    principles: [
      "Lead with what happens, not what Snappy is.",
      "First person. 'I' by default. 'We' only when literally true.",
      "Builder-to-builder. Assume the reader has shipped real software.",
      "Earn every adjective. If you can't defend it on a call, delete it.",
      "The four reference sentences are the tuning fork.",
    ],
    doRules: [
      "Write first person. 'I', 'you', 'we built'. Never marketing third person.",
      "Be direct. State the problem, state the fix, stop talking.",
      "Builder-to-builder. Assume the reader has shipped real software.",
      "Lead with the work. Screens, repos, agents running, commits landing.",
      "Short sentences beat clever sentences.",
      "Name the tool when it matters -- but the tool is never the hero. The outcome is.",
      "Earn every adjective. If you can't defend it on a call, delete it.",
    ],
    dontRules: [
      "No hype. No adjective stacking.",
      "No vibe coding language as our own. We build and control.",
      "No false novelty.",
      "No fake urgency.",
      "No third-person hero narration about Robert.",
      "No personification of Snappy.",
      "No 'MCP integration' or 'Xano MCP' as the headline.",
    ],
  };
}

export type FlowProfile = {
  name: string;
  source: string;
  stdev: number;
  rolling5: number;
  shortMax: number;
  longMin: number;
  shortFloor: number;
  longFloor: number;
};

export const FLOW_PROFILES: Record<string, FlowProfile> = {
  balanced: {
    name: "balanced",
    source: "writer-agnostic rhythm detector",
    stdev: 6.0,
    rolling5: 4.5,
    shortMax: 7,
    longMin: 24,
    shortFloor: 0.18,
    longFloor: 0.10,
  },
};

export function splitSentences(text: string): string[] {
  return text
    .split(/(?<=[.!?])\s+/)
    .map((s) => s.trim())
    .filter((s) => s.length > 0 && /[A-Za-z]/.test(s));
}

function mean(values: number[]): number {
  return values.length === 0 ? 0 : values.reduce((sum, n) => sum + n, 0) / values.length;
}

function median(values: number[]): number {
  if (values.length === 0) return 0;
  const sorted = [...values].sort((a, b) => a - b);
  const mid = Math.floor(sorted.length / 2);
  return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
}

function stdev(values: number[]): number {
  if (values.length === 0) return 0;
  const m = mean(values);
  return Math.sqrt(mean(values.map((n) => (n - m) ** 2)));
}

function rollingWindowStdev(values: number[], size: number): number {
  if (values.length < size) return stdev(values);
  return Math.max(...values.slice(0, values.length - size + 1).map((_, i) => stdev(values.slice(i, i + size))));
}

export function checkFlow(
  text: string,
  opts: { minSentences?: number; profile?: string } = {},
): {
  pass: boolean;
  profile: string;
  reasons: string[];
  stats: {
    sentences: number;
    meanLength: number;
    medianLength: number;
    stdev: number;
    rolling5Stdev: number;
    shortRatio: number;
    longRatio: number;
  };
} {
  const minSentences = opts.minSentences ?? 10;
  const profileName = opts.profile ?? "balanced";
  const profile = FLOW_PROFILES[profileName];
  if (!profile) {
    throw new Error(`[checkFlow] unknown profile '${profileName}'. Available: ${Object.keys(FLOW_PROFILES).join(", ")}`);
  }

  const stripped = text
    .replace(/```[\s\S]*?```/g, "")
    .replace(/^#.*$/gm, "")
    .replace(/^---[\s\S]*?---/m, "")
    .replace(/<\/?connective>/gi, "")
    .replace(/\[source:[^\]]*\]/gi, "");

  const sentences = splitSentences(stripped);
  const lengths = sentences.map((s) => s.split(/\s+/).filter(Boolean).length);
  const stats = {
    sentences: lengths.length,
    meanLength: Number(mean(lengths).toFixed(2)),
    medianLength: Number(median(lengths).toFixed(2)),
    stdev: Number(stdev(lengths).toFixed(2)),
    rolling5Stdev: Number(rollingWindowStdev(lengths, 5).toFixed(2)),
    shortRatio: lengths.length === 0 ? 0 : Number((lengths.filter((n) => n <= profile.shortMax).length / lengths.length).toFixed(2)),
    longRatio: lengths.length === 0 ? 0 : Number((lengths.filter((n) => n >= profile.longMin).length / lengths.length).toFixed(2)),
  };

  const reasons: string[] = [];
  if (lengths.length < minSentences) return { pass: true, profile: profileName, reasons, stats };
  if (stats.stdev < profile.stdev) reasons.push(`sentence length stdev ${stats.stdev} < ${profile.stdev}`);
  if (stats.rolling5Stdev < profile.rolling5) reasons.push(`rolling-5 stdev ${stats.rolling5Stdev} < ${profile.rolling5}`);
  if (stats.shortRatio < profile.shortFloor) reasons.push(`short sentence ratio ${stats.shortRatio} < ${profile.shortFloor}`);
  if (stats.longRatio < profile.longFloor) reasons.push(`long sentence ratio ${stats.longRatio} < ${profile.longFloor}`);

  return { pass: reasons.length === 0, profile: profileName, reasons, stats };
}

export function requireCitations(draft: string): {
  pass: boolean;
  totalSentences: number;
  citedSentences: number;
  connectiveSentences: number;
  uncitedSentences: string[];
  connectiveRatio: number;
  reasons: string[];
} {
  const stripped = draft
    .replace(/```[\s\S]*?```/g, "")
    .replace(/^#.*$/gm, "")
    .replace(/^---.*$/gm, "");

  const connectiveMatches: string[] = stripped.match(/<connective>[\s\S]*?<\/connective>/gi) ?? [];
  const connectiveSentences = connectiveMatches.reduce<number>((n, chunk) => {
    const inner = chunk.replace(/<\/?connective>/gi, "");
    return n + splitSentences(inner).length;
  }, 0);
  const withoutConnective = stripped.replace(/<connective>[\s\S]*?<\/connective>/gi, "");

  const sentences = splitSentences(withoutConnective);
  const citeRe = /\[source:\s*[^\]]+?~\s*\d{1,3}:\d{2}[^\]]*\]/i;

  const cited: string[] = [];
  const uncited: string[] = [];
  for (const s of sentences) {
    if (citeRe.test(s)) cited.push(s);
    else uncited.push(s);
  }

  const totalSentences = sentences.length + connectiveSentences;
  const citedSentences = cited.length;
  const connectiveRatio = totalSentences === 0 ? 0 : connectiveSentences / totalSentences;

  const reasons: string[] = [];
  if (uncited.length > 0) {
    reasons.push(
      `${uncited.length} prose sentence(s) lack [source: ...~mm:ss] citation and are not wrapped in <connective>...`,
    );
  }
  if (connectiveRatio > 0.35) {
    reasons.push(
      `connective tissue ratio ${(connectiveRatio * 100).toFixed(0)}% exceeds 35% budget`,
    );
  }

  return {
    pass: reasons.length === 0,
    totalSentences,
    citedSentences,
    connectiveSentences,
    uncitedSentences: uncited,
    connectiveRatio,
    reasons,
  };
}

scripts- helper scripts it can run

prose-only skill - 6 inline code blocks live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

no recent runs logged - the eval contract is declared but nothing has been graded yet