TV Build Agent Guide

This file is for agents driving tv-build as a tool. For contributors editing this repository, read CLAUDE.md.

TV Build turns a small input directory into a generated TV app through planned phases, prompts, skills, verification checks, logs, reports, and replay.

Authoring Loop

Use this loop when a human asks you to create a TV app input set.

cd packages/harness
npx tsx src/index.ts schema --json
npx tsx src/index.ts init my-inputs
npx tsx src/index.ts validate my-inputs --json
npx tsx src/index.ts claude-run my-inputs --plan --json
# Show the human the plan, expected platforms, and that execution is uncapped.
npx tsx src/index.ts claude-run my-inputs --detach --yes --json
npx tsx src/index.ts status <runId> --json
npx tsx src/index.ts logs <runId>

Required Files

• content.json: catalog title, description, categories, videos, and featured ids.
• brand.json: brand name, colors, font, logo, and splash paths.
• prompt.txt: the human's app-specific intent and constraints.

Optional files:

• design.json: layout, focus, spacing, tile, and mood preferences.
• screens.json: explicit navigation and screen tree.
• run.json: target platforms and run settings.
• harness.config.json: custom template, phases, models, checks, and token budget.

Inspect exact contracts with:

npx tsx src/index.ts schema content --json
npx tsx src/index.ts schema brand --json
npx tsx src/index.ts schema config --json

Validation

Run validation until errors is empty.

npx tsx src/index.ts validate my-inputs --json

Warnings do not block a run, but you should address them before asking for confirmation when they affect quality:

• sparse_rail: add at least 3 items to each rail.
• too_many_rails: reduce or group rails.
• brand_contrast: improve foreground/background contrast.
• missing_prompt: add prompt.txt.
• non_https_url: use HTTPS or local placeholder assets.
• instruction_like_content: move app-building instructions out of content.json and into prompt.txt.

Plan Gate

Always show the human the plan and state that monetary cost is tracked but uncapped before launching a live run.

npx tsx src/index.ts claude-run my-inputs --plan --json

Do not run without --yes after confirmation. In JSON mode, detached runs require it.

npx tsx src/index.ts claude-run my-inputs --detach --yes --json

There is no monetary cost cap. Monitor status and logs, report accumulated cost, and use abort only when the human asks or the run is clearly wrong.

Status Loop

Detached runs return:

{"schemaVersion":1,"command":"detach","runId":"abcd1234","pid":12345,"out":".../out/abcd1234"}

Poll status:

npx tsx src/index.ts status abcd1234 --json

Read logs:

npx tsx src/index.ts logs abcd1234
npx tsx src/index.ts logs abcd1234 --follow

Abort only when the human asks or the run is clearly wrong:

npx tsx src/index.ts abort abcd1234 --json

Never edit files under out/. They are generated artifacts, logs, reports, and checkpoints.

After The Run

When the human asks for a change scoped to one concern, prefer refine over a full rerun.

npx tsx src/index.ts refine <runId> --phase branding "warmer palette, larger hero cards" --plan --json
# Show the human the phase, instruction, verify checks, and seed.
npx tsx src/index.ts refine <runId> --phase branding "warmer palette, larger hero cards" --yes --json

Use refine for phase concerns such as branding, content, screens, creative UI, and navigation. It amends the current app state; it does not rewind to the old phase commit. Never refine without showing the plan. On exit 2, report the failed checks and stop.

For an Android TV target, show the Android lifecycle plan before touching a device:

npx tsx src/index.ts android <runId> --setup-agent --plan --json
# After human confirmation:
npx tsx src/index.ts android <runId> --setup-agent --require-android-cli \
  --build --install --launch --test --yes --json

--setup-agent runs android init and verifies the Android CLI skill. Prefer android describe, android run, android layout, and android screen capture. Use Gradle only to build the APK. Use ADB only for device discovery, boot status, D-pad input, and Logcat, where Android CLI has no equivalent. Prefer --start-emulator <name> over the emulator binary. Report android-handoff.json, and do not change Gradle tasks, device selection, package metadata, or fallback without a new plan. Read docs/android-cli-workflow.md before an Android presentation or live validation.

Exit Codes

JSON Events

Long-running commands emit NDJSON on stdout when --json is set. Every line has schemaVersion: 1.

Events:

• run_start
• phase_start
• verify_failed
• phase_message
• tokens
• iteration
• phase_complete
• run_complete

Short commands emit one JSON object: schema, init, validate, doctor, status, and abort.

Errors use:

{"schemaVersion":1,"error":{"code":"...","message":"...","hint":"..."}}

Gotchas

Schemas cannot tell whether the content density feels good on a TV. Use validation warnings and examples as the quality floor.

Schemas cannot guarantee brand colors are legible in every generated layout. Treat contrast warnings as real.

Put structured catalog facts in content.json. Put taste, audience, product goals, and constraints in prompt.txt.