TV Build Harness

Use this guide to locate the right file before editing. This repo builds TV apps with a phase-based harness, local skills, and verification checks.

This file is for contributors changing the repository. For agents driving tv-build as a CLI tool, read AGENTS.md.

Repo Map

• packages/harness/: CLI, orchestrators, phase engine, prompts, local doctor, and run reports.
• packages/verification/: statistical verification utilities and tests for harness quality.
• packages/web-ui/: experimental UI package; verify status before relying on it.
• packages/shared-types/: shared TypeScript types package.
• skills/: local skill library; each skill lives at skills/<name>/SKILL.md.
• examples/: runnable input sets such as cooking-shows, fitness-tv, and KMP examples.
• docs/: current docs plus docs/archive/ for historical planning docs from the IMPROVEMENT_PLAN.md era.

Golden Commands

• cd packages/harness && yarn typecheck && yarn test
• cd packages/verification && yarn test when packages/verification changes.

For CLI behavior changes, also run the affected command, for example:

• cd packages/harness && npx tsx src/index.ts --help

Run Modes

• run: Anthropic API path backed by packages/harness/src/orchestrator.ts.
• claude-run: Claude CLI subprocess path backed by packages/harness/src/claude-orchestrator.ts.
• Strands/provider path: multi-provider path backed by packages/harness/src/strands-orchestrator.ts.

All three paths delegate phase ordering and retries to packages/harness/src/pipeline-engine.ts.

Where Things Live

Skill frontmatter must keep this contract:

---
name: skill-name
applies_to: [phase_name]
---

applies_to names phases that may load the skill. Keep skill changes additive unless a task explicitly asks for a rewrite.

Recipes

Add A Skill

1. Create skills/<name>/SKILL.md.
2. Add frontmatter with name and applies_to.
3. Write concrete instructions, commands, file paths, and failure modes.
4. Run cd packages/harness && yarn test.
5. Update skills/README.md if the inventory is not generated by your task.

Add A Phase

1. Add the phase spec in packages/harness/src/harness-config.ts.
2. Add dependencies or exported phase names in packages/harness/src/types.ts when needed.
3. Add prompt loading in packages/harness/src/phase-prompts.ts and prompt text under packages/harness/prompts/ when needed.
4. Add verify checks to the phase spec if the phase has mechanical success criteria.
5. Run cd packages/harness && yarn typecheck && yarn test.

Add An Example

1. Create examples/<name>/.
2. Include content.json, brand.json, and prompt.txt.
3. Add optional screens.json, design.json, run.json, or harness.config.json only when the example uses them.
4. Validate config with the harness CLI or run the example with --generate-only when model access is available.
5. Document any required API key or local platform prerequisite.

Editing Rules

• Do not add runtime dependencies without documenting why.
• Do not edit packages/verification/src/stats/* or golden specs unless the task explicitly asks.
• Do not rewrite prompts or skills opportunistically; they are load-bearing.
• Keep docs second person, imperative, and concrete.
• To add a verify check to the branding phase, edit packages/harness/src/harness-config.ts.