OpenParable
Skip to content
← Back to skills

Porting 1 Intake

Development
porting-1-intake

Porting 1 Intake is an Agent Skill for development published in the handy-computer/transcribe.cpp repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

First stage for a new speech-model port. Produces reports/porting/<family>/<variant>/intake.json, drafts the family capability table, seeds the golden manifest skeleton, and clears Preflight Gate A.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/handy-computer/transcribe.cpp/blob/HEAD/.claude/skills/porting-1-intake/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/porting-1-intake, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

porting-1-intake

First stage of the porting pipeline. Creates the intake packet, fills the human-judgment fields, drafts the family doc's capability table, and clears Preflight Gate A.

Preconditions

  • User provided: a Hugging Face URL or org/name, a stable family key (e.g. parakeet, whisper), a variant name (e.g. parakeet-tdt-0.6b-v2, whisper-base).
  • Working directory is the transcribe.cpp repo root.
  • uv is installed.
  • $TRANSCRIBE_MODELS_DIR is set (see the parent CLAUDE.md).

Workflow

Copy and track this checklist:

Intake progress:
- [ ] Step 1: Run scripts/intake.py inspect (mechanical draft)
- [ ] Step 2: Fill human-judgment fields via research. If they cannot be found then ask.
- [ ] Step 3: Schema-validate the intake.json
- [ ] Step 4: Run Preflight Gate A
- [ ] Step 5: Pre-fill family doc draft from intake
- [ ] Step 6: Seed golden manifest skeleton
- [ ] Step 7: Sign-off review

Step 1: Mechanical draft (execute)

uv run scripts/intake.py inspect \
  --repo <org/name> \
  --family <family> \
  --variant <variant> \
  --out reports/porting/<family>/<variant>/intake.json

This writes a draft with mechanical fields populated (hf_revision, config, dtype distribution, frontend, tokenizer summary, capabilities) and null-valued human-judgment fields.

If the family is already ported (there is a prior reports/porting/<family>/<other-variant>/intake.json): read the prior intake and carry its reference_framework, reference_rationale, architecture_pattern, and known_risks forward as defaults.

Step 2: Human-judgment fields

Fill these fields from research. Ask only when the answer cannot be found or a decision needs user sign-off. See docs/porting/1a-intake.md for field semantics.

  1. Reference framework choice.: The reference implementation should always be the source of truth. If there is not one, this is a red flag and must immediately be told to the human.

  2. Architecture pattern. One of encoder-transducer, encoder-decoder, audio-llm, encoder-ctc. The script's config.architecture_candidates is a heuristic starting point. If it doesn't fit, propose a new pattern and have the user accept it based on your research of the architecture.

  3. Acceptance dataset. Default: LibriSpeech test-clean. Capture any publisher-reported score in upstream_benchmarks when available for context, but downstream gates use the measured Oracle reference baseline, not the publisher score. For models not supporting English LibriSpeech is NOT a valid target. This must be flagged and become a hard stop for the time being.

  4. Known risks. List critical risks that affect later stages (frontend/tokenizer ambiguity, custom attention masks, streaming, long-sequence behavior, input-length or memory behavior, dtype quirks, etc.). Include hard architectural caps, soft trained windows, output-token caps, chunking/streaming behavior, and whether context/memory knobs are meaningful or intentionally ignored when they are relevant. One risk per entry. Do not ask the user about routine or low-impact observations.

  5. Capability validation table. Draft one row per advertised capability in docs/porting/families/<family>.md, fill Target, and leave Status: TODO for Stage 4. Target is one of:

    • MUST PASS — in scope; Stage 4 is obligated to make the row resolve to PASS.
    • OUT OF SCOPE — <reason> — explicitly deferred for this port; Stage 4 may resolve it to SKIP or ACCEPTED GAP. The reason names what would bring it back in scope.

    Forced MUST PASS: explicit-language transcription, auto/no-hint transcription, offline batch, and streaming when capabilities.streaming: true. All other targets require user sign-off. Stage 4 fills Status and may not downgrade a MUST PASS row without the user re-signing. Capabilities the runtime cannot observe still get OUT OF SCOPE rows so the gap stays visible.

If scripts/intake.py reported intake_gaps, resolve or explicitly accept any gap affecting dtype, frontend, tokenizer IDs, architecture pattern, or reference framework.

Step 3: Schema validation (execute)

uv run python -c "import json, jsonschema; \
  s=json.load(open('docs/porting/families/_intake-schema.json')); \
  d=json.load(open('reports/porting/<family>/<variant>/intake.json')); \
  jsonschema.validate(d, s); print('OK')"

If validation fails, fix the intake in place and re-run. Do not proceed with a schema-invalid intake.

Step 4: Preflight Gate A (execute)

uv run scripts/preflight.py --family <family> --variant <variant> --gate A

Gate A cross-checks declared intake values against the reference framework's config/preprocessor/tokenizer files. If it fails, the intake and the reference disagree on something load-bearing — fix the intake or the declaration and re-run.

Step 5: Family doc draft (execute)

If docs/porting/families/<family>.md does not exist yet, create it by copying _template.md and filling the Identity, References, and Artifacts sections from the intake. Leave the Commands section with real uv run invocations for this family.

[ -f docs/porting/families/<family>.md ] || \
  cp docs/porting/families/_template.md docs/porting/families/<family>.md

Step 6: Golden manifest skeleton (execute)

Seed tests/golden/<family>/<variant>.manifest.json with the identity fields derived from intake. This is a skeleton — porting-2-oracle completes it with reference.entrypoint, frontend, tokenizer_summary, capabilities, and the per-family case set the dumper actually runs (typically samples/jfk.wav plus any extra audio the family wants). Writing the skeleton now lets later stages reference manifest.source_model and manifest.variant without having to re-derive them.

# uv run python -c '...'
import json, pathlib
intake = json.loads(pathlib.Path("reports/porting/<family>/<variant>/intake.json").read_text())
skel = {
    "schema": "transcribe-golden-manifest-v1",
    "family": intake["family"],
    "variant": intake["variants"][0]["name"],
    "source_model": {"hf_repo": intake["hf_repo"], "hf_revision": intake["hf_revision"]},
    "expected_dtype": intake["dtype"]["expected"],
    "dtype_source": intake["dtype"]["source"],
    "_skeleton": True,  # porting-2-oracle removes this when filling the rest
}
out = pathlib.Path(f"tests/golden/{intake['family']}/{intake['variants'][0]['name']}.manifest.json")
out.parent.mkdir(parents=True, exist_ok=True)
out.write_text(json.dumps(skel, indent=2))

Step 7: Sign-off

Report to the user:

  • Path to the intake.json.
  • Path to the family doc draft.
  • Preflight Gate A result.
  • Any unresolved intake_gaps.
  • Whether the acceptance dataset is LibriSpeech or an alternate (name it).
  • The Capability Validation table, row by row, with your proposed Target for each. Ask the user to confirm or amend every Target that is not a forced MUST PASS (the transcribe rows, streaming, and batch are forced). This per-row in/out-of-scope confirmation is the contract Stage 4 implements against — a MUST PASS row Stage 4 cannot satisfy is a blocker, an OUT OF SCOPE row may resolve to SKIP / ACCEPTED GAP. Do not treat this as a row-count summary; the user must sign off the scope of each capability here.

Do not commit. The user authors the commit manually after reviewing.

Postconditions

  • reports/porting/<family>/<variant>/intake.json exists and validates against docs/porting/families/_intake-schema.json.
  • All four human-judgment fields (reference_framework, reference_rationale, architecture_pattern, known_risks) are filled.
  • Acceptance dataset is captured in upstream_benchmarks — LibriSpeech test-clean by default, or an explicit alternate for non-English models. Any publisher-reported score is context only; downstream gates use the measured Oracle reference baseline.
  • docs/porting/families/<family>.md exists as a draft and includes a ## Capability Validation table with one row per advertised capability; every row has its Target filled (MUST PASS or OUT OF SCOPE — <reason>, user-signed for non-forced rows) and Status: TODO. Rows for capabilities the runtime cannot observe are marked OUT OF SCOPE so they may resolve to SKIP at Stage 4.
  • tests/golden/<family>/<variant>.manifest.json exists as a skeleton (identity fields only, _skeleton: true).
  • Preflight Gate A is green.

Pointers (read, not execute)

  • docs/porting/1a-intake.md — full field semantics for intake.json
  • docs/porting/families/_intake-schema.json — authoritative schema
  • docs/porting/families/_template.md — family doc starting shape
  • docs/porting/0-porting.md — architecture pattern reference
  • Existing intakes: reports/porting/parakeet/*/intake.json, reports/porting/cohere/*/intake.json, reports/porting/qwen3_asr/*/intake.json — use as shape references for a new family