Refacil:read Spec

refacil:read-spec — Spec reader (TTS)

Play a Markdown spec aloud in the local browser using on-device TTS. The CLI parses the file(s), stores a short-lived session on the broker, and opens /read-spec.

Prerequisites: sdd profile from refacil-prereqs/SKILL.md.

CLI (always use this)

Single file mode:

refacil-sdd-ai read-spec --file  [--lang es] [--voice M3] [--speed 1]

Folder mode (all SDD artifacts for a change in one browser panel with sidebar):

refacil-sdd-ai read-spec --change  [--select ] [--lang es] [--voice M3] [--speed 1]

• --change : loads all .md files from refacil-sdd/changes// in order: proposal.md → design.md → tasks.md → specs.md → (others alphabetically). Opens a sidebar for navigation between files.
• --select : pre-selects a specific file in the sidebar (default: proposal.md).
• --file and --change are mutually exclusive.

Defaults: lang=es, voice=M3, speed=1.

Post-propose flow (CA-24)

The listen option is presented as option B in the /refacil:propose Step 3 review menu — handled directly by that skill. When the user selects B, run:

refacil-sdd-ai read-spec --change 

Language is auto-detected from the artifact content (no --lang flag needed). After playback, re-present the Step 3 review menu so the user can approve or request adjustments.

On-demand — archived specs only (CA-25)

When there are no active folders under refacil-sdd/changes/ (except archive/):

1. Ask which archived spec folder under refacil-sdd/specs/.
2. Run read-spec --file refacil-sdd/specs//spec.md (verify the folder exists first).

On-demand — active changes (CA-26)

When there are active folders under refacil-sdd/changes/:

1. List the active change names.
2. Ask the user which change to listen to (and optionally which file to start from).
3. Run:

refacil-sdd-ai read-spec --change  [--select ]

If the user specifies a particular file (e.g. "I want to hear specs.md"), add --select specs.md.

On-demand — active changes and archived (CA-27)

When both active changes and refacil-sdd/specs/ exist:

1. Ask: open change or archived spec?
2. List names from the chosen location.
3. For a change: run read-spec --change (with optional --select).
4. For archived: refacil-sdd/specs//spec.md → run read-spec --file .

Rules

• Never send spec content to remote TTS APIs; only the CLI + local browser run.
• If the path or change folder is missing, report clearly (CR-11, CR-12) — do not run the CLI silently.
• --file must stay inside the project root (the CLI enforces this).
• --change and --file are mutually exclusive — never pass both.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Erikole21
• Source: Erikole21/refacil-sdd-ai
• License: MIT

Install and usage instructions live in the source repository linked above.