vox

Vox

Treat vox as an orchestration entry point, not a single TTS skill.

First switch to the skill root directory (the directory whereSKILL.md is located) before executing scripts, to avoid relative path errors.

Usage

1. First read references/intents.md, and determine which scenario the request belongs to.
2. Then read references/orchestration-matrix.md, and choose the minimal happy path for that scenario.
3. Only load the 1 playbook needed for the current scenario; do not read all playbooks into context.
4. Execute by scenario:
   • Light operation:profile、model status/path Execute the business command directly.
   • Heavy operation:ASR、TTS、pipeline First run bash scripts/ensure_model.sh ..., then execute the business command.
   • Installation/health check: prefer bash scripts/health_gate.sh; only use bash scripts/bootstrap.sh --check。
5. When the name, profile, or model is unclear, check the local state once first; do not guess.
6. After a failure, fall back by category according to env / model / input / runtime , and do not put broad-spectrum prechecks back into the main flow.
7. Before delivery, only enforce gates according to the matrix and references/checklist.md requirements; do not run extra doctor or health_gate。

Required files

• Scenario determination:references/intents.md
• Unified orchestration:references/orchestration-matrix.md
• Delivery gates:references/checklist.md
• Output templates:references/response-contract.md

Scenario files

• references/model-playbook.md: model query, paths, cache, explicit model preparation
• references/profile-playbook.md：profile list/create/add-sample
• references/asr-playbook.md: offline/streaming/microphone transcription
• references/tts-playbook.md：clone / custom / design
• references/pipeline-playbook.md: end-to-end ASR + TTS
• references/failure-loop.md: failure classification, retry, rule write-back

Execution hard rules

1. By default, do business first, then precheck.
2. Model preparation for heavy operations only goes through scripts/ensure_model.sh。
3. Only environment issues enter bootstrap.sh --check / bootstrap.sh。
4. When troubleshooting skill orchestration issues, prioritize static review and a single lightweight reproduction.
5. Do not perform stress tests, repeated heavy inference, or concurrent heavy tasks without authorization unless the user explicitly requests it.
6. When running examples or regression tests, output files must be written to /tmp or ~/.vox/outputs, not to the repository directory.
7. On failure, first provide an executable retry command, then write the failure log.

Common scripts

bash scripts/ensure_model.sh <model-id|asr-auto|tts-default|tts-custom-default|tts-design-default>
bash scripts/health_gate.sh [--require-file <...>]
bash scripts/bootstrap.sh --check
bash scripts/bootstrap.sh
bash scripts/log_failure.sh --stage "<stage>" --command "<cmd>" --error "<msg>" [--retry "<retry-cmd>"]
bash scripts/failure_digest.sh