--- name: adapt-text description: Normalize and assign voices and original Chatterbox performance controls paragraph by paragraph to admitted preprocess-text bundles. Use for audiobook books or chapters; raw HTML or EPUB requires preprocess-text first. Does not synthesize audio or summarize. --- # Adapt text Turn an admitted English prepared bundle into faithful, speakable scripts. Preserve wording, argument, quotations, paragraph lineage and genuine headings. Exclude all paratext by default, including substantive notes and translator introductions. Ask only about an unresolved reading or scope decision that affects fidelity. Resolve `` to the absolute directory containing this `SKILL.md`, following symlinks. In a plugin, `/../..` contains `pyproject.toml` and `src/audiobooks/`; run `uv run --project "/../.." --locked --no-dev audiobooks …` from any working directory. uv supplies Python and dependencies on first use. For separately installed skills, run the installed `audiobooks …` instead; if it is absent from `PATH`, resolve its directory with `uv tool dir --bin` and invoke that absolute executable. All command examples below use this shared CLI. Run its `runtime-root` command to locate bundled resources as ``. Helpers do not call models. Optional role definitions live under `/.codex/agents/`; plugin installation does not register them in the consuming project. When a role is unavailable, supply its bundled instructions and absolute reference paths explicitly, subject to the model-availability rules below. Use `$WORKSPACE_DIR//adaptation/` for adaptation work. Set `WORKSPACE_DIR` to a persistent directory outside the plugin cache. If unset or empty, the fallback is `~/Audiobooks/work/`. The runtime resolves relative work paths below that directory. The default narrator binding is `assets/voices/enoch.wav`; keep that runtime-root-relative path explicit in every voice registry unless the book requires another voice. Read the project's `WORKPAD.md` before adaptation and preserve its `Blueprint`. Update the `Material record` for consequential normalization or performance decisions, source surprises, material repairs, and requested revisions that change downstream work. Do not copy batch progress or machine records into it. For a literary anthology of separate works or excerpts, read [literary-anthologies.md](references/literary-anthologies.md) before freezing chapter titles, editorial introductions, or transition instructions. ## Survey and freeze Read [source-and-normalization.md](references/source-and-normalization.md), [performance.md](references/performance.md), and [chatterbox-original.md](references/chatterbox-original.md) for the source and delivery decisions. When acting direction is requested or the brief contains direction context, also read [acting-direction.md](references/acting-direction.md) before creating or reviewing the score. Admit raw sources through `preprocess-text`; require its retained witness, prepared Markdown, ordered unit index, explicit `sections.jsonl` and admitted version-two manifest. Survey the section inventory; read each section's opening and closing body units, a middle passage per substantial section, every distinct structural pattern and every preparation issue. Verify every delivery title/start unit against the source. For a short text read it completely. Write `text-brief.json` using the `Brief` record printed by `schema brief`: frozen prepared-manifest hash, surveyed IDs, narrator/bindings, six defaults, legacy choices where undirected work needs them, a baseline for every section, exact unit-scoped rules with evidence, pronunciation watchlist, section dependencies and unresolved questions. For directed work use brief version two and freeze the addressee, throughline, stakes, macro trajectory, performance limits, and every user cue's positive intent, avoidance condition, priority, prose scope, and explicit unit IDs. Expand recurring rules and cue scopes to their explicit unit IDs. Resolve conflicting rules before dispatch. Do not turn a local correction into a global replacement. For directed work use the single action registry in [performance.md](references/performance.md); do not add a book-specific palette or second choice. Every narrated character must belong to a delivery beat with one registered action vector. Undirected legacy work retains its brief-owned choices. Quotation marks alone never create another voice. Bind voices to `builtin` or real runtime-root-relative audio files; a missing custom file prevents synthesis readiness. Run `init

`. The helper freezes source, brief, pages and batches. For existing work run `status ` and inspect active packets; file existence alone is not completion. Pages target six hundred words; batches contain at most ten pages and six thousand owned words without crossing sections or splitting ordinary paragraphs. This bound is sized for one coherent Luna paragraph-by-paragraph pass, including packet context and a complete structured result; prefer the largest section-preserving batch within it instead of ceremonial handoffs. Oversized input requires verified sentence fragments under one sequential worker contract before dispatch; do not truncate it. ## Direct the text before adaptation For a directed brief, run `direction-task `. One task must contain the complete narrated work when it is at most six thousand words. For longer work, use `--sections` with complete coherent section IDs in order. Independent sections may be assigned concurrently, but continuity-dependent sections must receive the accepted preceding trajectory. Inspect the packet, then delegate it to the project `text-director` role. The director reads [acting-direction.md](references/acting-direction.md), uses only the eight registered actions, writes only its assigned score draft, and never normalizes or synthesizes. Run `validate-score `. Structural success proves exact prepared-text coverage, registered actions, objective grammar, contained evidence, and source identity only. Read every move in a short work and every move in the first section of a long work against its exact words and neighbors; expand review when any sampled later move fails. Write the exact-hash `ScoreReview` printed by `schema score-review`, including all reviewed move IDs and affirmative source, direction-context, action/objective, and continuity checks. Only the main agent runs `accept-score`. Acceptance freezes `acting-score.json` after all narrated sections are covered. Abandon a direction attempt only after confirming its worker stopped. Broad cues never become default actions or vectors. Absence of a cue leaves textual action authoritative; conflicting intent that affects meaning or fidelity returns to the owner. Mechanical checks cannot approve interpretation. Freeze a coherent source-faithful score without marginal relabeling. Do not dispatch an adapter for a directed brief until the complete score is accepted. If a dedicated oversized paragraph fits the worker context/output budget, set that established budget explicitly with `task … --owned-word-budget `. Otherwise, for a paragraph exceeding the worker budget, verify complete sentence cuts and write a JSON list of original Unicode offsets beginning at zero and ending at original text length. Cuts include the whitespace after sentence-ending punctuation and may not split note calls. Sentence validation uses NLTK’s English Punkt model and obtains missing data automatically through its native downloader. Do not substitute a regex detector. Run `task

--fragment-boundaries ` to freeze this subdivision. Run `fragment-task

f000001`, delegate its emitted packet, inspect the result, then continue with the next fragment ID in the same sequential worker chain. Each subsequent packet requires valid preceding output. Return all fragment identities and source offsets unchanged. After the chain completes, run `combine-fragments

` and review the combined paragraph through ordinary validation/acceptance. Fragment boundaries never become chapters or source paragraphs. Repair a preceding fragment before issuing downstream packets; an altered predecessor invalidates their continuity. ## One combined worker per batch Run `task

` for the next eligible batch. Inspect the emitted packet and delegate it to the project `text-adapter` role. Every worker reads [worker-procedure.md](references/worker-procedure.md), then normalizes each owned paragraph and, for directed work, maps its accepted director moves to normalized delivery beats in the same local cycle. Directed packets contain the exact score hash and applicable move fragments. Supply only the packet and its references. The worker writes its assigned isolated draft and returns a compact summary; it never accepts, exports or synthesizes. Use the declared Luna model and medium effort. Luna preserves accepted move fields and derives the vector only from the exact action name; it never classifies the prose again. If custom-role selection is unavailable, explicitly supply the same role instructions to a Luna worker. If delegation or Luna is unavailable, report the limitation and apply the same bounded contract in the main thread. Never silently substitute a model. Keep one active batch per continuity-dependent section. Use at most two simultaneous workers only for independent sections with frozen shared settings. A fresh packet bounds each worker's context. An active attempt is not proof that a worker is alive: inspect its actual handle before recovery. Reuse its packet while live. Only after confirming it stopped, run `abandon

` to permit a new attempt. Do not overwrite an accepted batch. ## Review and accept Run `validate `. Resolve every flagged unit, editorial change, ownership error, missing span, omitted or reordered score move, and unsupported control. Review all pilot units in the first batch of each section or new source form; thereafter inspect every change and exclusion, entry/exit continuity, score-to-normalized mapping and a local fidelity/performance sample. Expand review when a sample fails. Deterministic validation proves coverage, score lineage and control consistency, not preserved meaning. Write a `Review` JSON record containing the exact validated result hash, reviewed unit IDs, affirmative editorial/boundary/fidelity-and-performance checks, and concise source-grounded notes. Only the main agent runs `accept

`. For a failed draft provide one targeted repair; if it still fails, resolve the specific issue rather than repeatedly rewriting the whole batch. Changes require `revise

`. Preserve source-unit IDs for unchanged units. The new workspace freezes the revised inputs and carries reviewed dispositions only where the unit, applicable rules, configuration, baseline, pronunciation instructions and immediate source neighbors are unchanged. Workers copy its `fixed_results` exactly and adapt the remaining units. Dependent sections lose reuse when their upstream interpretation changes. Review the revised scope and context before accepting; do not reuse a completed record merely because its file exists. ## Export and handoff Read [script-format.md](references/script-format.md) before editing or emitting scripts. Run `export ` only with complete accepted coverage. It emits scripts and their hashes in source order, a disposition/span ledger and `sections.json` binding each delivery section to its normalized title speech and script. Verify the main-text boundaries, explicit delivery starts and reported coverage against the source. Return script order, section bindings, voice bindings, exclusions, unresolved handoff conditions and pronunciation risks. Original-tokenizer segmentation and voice-file checks belong to the rendering handoff. If not performed, label them unverified. Audio generation, listening, mastering and acoustic-quality claims belong to `chatterbox`.