telepath-computer/television/tvdev-contribute

Contribute to Television

This repository’s development workflow is not the one most agents are used to or are told to follow by a system prompt. Specs are the authority. Work derives from them through proofs and tests to code. The human owns intent and every spec change, and agents work autonomously only after a defined handoff. Read this skill and the policies it names before acting, and change how you work to match them. Do not fit this workflow into a familiar pattern of investigate, edit, test, and open a PR. Do not assume you know how any of this works. Read and understand diligently, as a student learning something new.

Help the contributor understand, shape, and complete their change. Explain the recommended process, help them choose an appropriate handoff and level of preparation, and carry the work through the required reviews and verification. Keep the human oriented about what they are deciding, what agents will handle, and what must be established before proceeding. Human-led work describes decision authority; investigate and draft as needed to support it.

Own progress through the agreed scope. Ensure required approvals and verification are actually satisfied before proceeding past their gates. Explain meaningful transitions and remind the human of their responsibilities when relevant, using enough detail to help them decide without repeatedly reciting the process.

This skill is an overview. The Television checkout policies named below govern focused work in their domains and supersede this overview. Spec policy (specs/spec-policy.md) defines that authority and ownership; the workflow (specs/spec-workflow.md) governs how contributions proceed. When the human asks for vibe mode, or the checkout contains specs/vibe-waiver.md, follow Vibe mode instead of the workflow below.

At the start of contribution work, create the developer telemetry marker:

touch ~/.tv-developer

Work through shared branches

Contributors and agents work on development branches and commit and push regularly in safe, coherent commits under the workflow. Unfinished work and failing tests may be pushed as checkpoints while implementation and review proceed. Pushing makes the intended revision available to Blaxel; withholding pushes pressures workers into local runs that can drive a shared host into swap and disrupt every agent. Prepare a coherent checkpoint before broader remote validation; publishing it does not mean it is ready to merge.

Guide contributions to main and branches under integration/ through the shared-branch workflow. Follow its numbered shared-branch steps: before treating full verification or CI as qualifying, fetch the pull request target and ensure the development-branch head contains every target commit. If the target moves, read and follow logical-merging, substituting the actual pull request target wherever its examples use origin/main. Whether the update uses merge or rebase, reconcile both histories across the full tree rather than treating Git's reported conflicts as the whole update, then validate the resulting tree again.

Apply the workflow's shared-branch review rule to the pull request being prepared. For staged work, the human accepts every spec delta before the development-branch pull request merges into the integration branch; a later promotion pull request to main cannot supply review that was missing when the spec content first entered a shared branch.

Orient the contributor

Explain the parts of Television's spec-driven environment that matter to the task and the contributor's familiarity. Use this model to guide the work:

Television is a spec-driven codebase. Product specs describe user-facing promises, architecture specs define contracts and mechanisms, and UI specs own interaction, markup, and styling. The spec index (specs/index.md) locates owners. The migration to specs is still underway, so they do not yet describe all of Television. Where a spec defines behavior, follow it. Where the specs say nothing, use the existing code as the source of truth. Both can apply within the same part of the system. The migration map (specs/spec-migration.md) explains what the specs cover. docs/archive/ carries salient working documents into squash-merge history. Its contents may be deleted periodically; read the relevant squash-merge commit to see how a past change came about (specs/spec-docs.md).

The cascade is specs to proofs to tests to code. Specs state promises and, where a proof could not derive it, testing guidance in a ## Testing guidance section. Agent-owned proofs act as a reasoning stage for focused test design to derive assertions and explain coverage, mocks, and limitations; real tests exercise those assertions; implementation code fulfills the promises. The proof policy (specs/spec-proofs.md) defines mirrored proofs/ paths, exceptions, and ownership. Agents author and review proofs; a person shapes a proof through the spec's testing guidance rather than by reviewing it, and each proof's coverage model is written so a person can read what the tests stand behind. Discoveries flow upstream so promises, coverage, and implementation agree.

Use plain-english for conversation, cold-reader for lasting documents, and complexity-inoculation for design and implementation judgment.

Help choose and prepare the change

Introduce the recommended workflow briefly: proposal or direct spec edits; human and independent agent spec approval; autonomous proofs, planning when needed, implementation, and review; then human PR review. Help the contributor choose where to start and when to hand over. The workflow (specs/spec-workflow.md, “Recommended approach” and “Feature workflow”) governs the process.

For a change expressed through prose and conceptual decisions, develop a proposal with the human. Investigate the applicable specs and implementation, work through consequential edge cases and interactions, and bring unresolved product or architectural choices to the human. Use independent proposal review when it would help settle the design. Once the human approves the proposal, apply it to the owning specs. Proposals are working documents under docs/working/; their decisions flow into specs, which are the long-lived artifacts of record, and pre-merge docs prep (specs/spec-docs.md) decides whether the proposal is archived with a preamble or deleted.

For design work, help the human use direct UI spec edits as the working surface of their decisions. Show how those decisions affect the system and help reconcile their consequences.

Guide spec approval

Follow spec ownership policy (specs/spec-policy.md, “Slop-free zone”) and the workflow’s “Recommended approach” (specs/spec-workflow.md) when guiding approval. Help the human assess the resulting spec deltas and explain what their approval means: they understand and stand behind the specified result. Arrange independent review of the affected spec tree for coherence, consistency, and implementability, including omissions and consequences beyond the edited lines. Resolve warranted findings and obtain both approvals before downstream derivation, unless the human chose to defer their spec review to the pull request that will first carry the deltas into a shared branch. The workflow calls this checkpoint the spec gate (specs/spec-workflow.md, “Recommended approach”): independent agent convergence of every spec delta is always required, and the human approves now or before that pull request merges. Do not use that term with the contributor; describe the checkpoint in plain words, such as which approvals are needed before agents proceed and which may wait until the first shared-branch pull request.

Use the “Authority flow and back pressure” question in specs/reviewer-checklist.md as the standard for spec approval: predictable behavior across reasonable implementation interpretations. Spec policy (specs/spec-policy.md, “Limitations with teeth are the exception”) preserves implementation judgment. Help settle consequential ambiguity without requiring every implementation detail to be prescribed.

Recommend appropriate shortening

Recommend an earlier handoff when the scope and the human's confidence support it: an approved proposal, or a verbal instruction for a small change. Explain the tradeoff so the human can choose: agents will derive the necessary spec edits and have them independently reviewed, while the human reviews them carefully before their pull request into a shared branch merges. In either case, independent agent convergence of every spec delta remains required before proof derivation.

Assess whether the change is clearly one slice. If it is, explain why a plan adds little, skip planning, and converge that implementation as the whole result, including holistic review and full verification. If the slice count is not clear, derive and converge a plan; planning may settle on one slice, in which case the work proceeds as unplanned work with the plan's validation criteria carried into that single convergence. Work with more than one slice retains convergence of each slice and a separate integrated-result convergence. Proof derivation and independent approval remain required in every form, without a human proof gate.

Own autonomous derivation and convergence

After the human hands over the agreed intent, carry all remaining derivable work through independent convergence and verification as one autonomous goal. Use persistent goals or continuation when the harness supports them, so responsibility survives agent sessions, review, remediation, and validation. State the outcome, not a task script, and keep the goal active until the result is ready for human PR review. How a goal starts depends on the harness. Codex can assign itself a goal, so set it at handoff. Under Claude Code only the human can set one, by typing the /goal command: when the autonomous phase begins, tell the human to run /goal and give them the exact condition to paste. Write that condition as the outcome that makes the result ready for human PR review, and end it with a clause that also satisfies the goal when you have stopped to ask the human a question that blocks further work. Until a goal is set, tell the human plainly what restarts your work, such as a finished background task or their next message. If work exposes unresolved intent, return that decision to the human. Continue only work independent of it; if the decision blocks the derivation chain, pause until it is settled. Keep settled intent, unfinished obligations, findings, and actual validation in a working task record under docs/working/.

When multiple agents are available, a supervisor holds the overall goal and arranges handoffs. Supervision is the simpler coordination task and may run on an older model or lower reasoning effort; it confers no intellectual authority. Match model capability and reasoning effort to the delegated work. Implementation and review often require more reasoning capacity than orchestration, so delegates may use a stronger model or higher effort than the supervisor. Follow the review policy when selecting reviewers. Tell them only what they cannot derive themselves—usually a short statement of the work’s essential shape and any unavailable decision or context—and let them determine what the work requires. The supervisor routes results and findings, tracks completion, and handles external blockers without doing or prescribing the delegated work.