/ts-coder

name: ts-coder
description: "Implement and refactor production TypeScript/TSX, strict types, APIs, and migrations."
requires:
  programs: []
  harness:
    - {slot: 4.shell, need: required}
    - {slot: 4.file-read-write, need: required}

TypeScript Coder

Every development task has a finite budget including setup, tests, and reporting. Before running tests, estimate duration from available timings and identify the changed behavior or directly affected consumer. If timing is unknown, state an estimate; do not build a timing system or run a preliminary suite. Full evaluation, unit, integration, or repository suites require the owner's explicit request, never a skill, PRD, review, or default command. Remove checks that neither prove the requested main function nor expose its defects. Repeat only after a relevant change or failure. Every new security check requires the owner's explicit approval for that specific check; remove auxiliary security, assertion, hash, or bookkeeping blockers of useful work.

Write TypeScript that fits the current repository, stays small, and is easy to verify. Local repo instructions add project-specific detail; they do not weaken these rules.

Boundaries

• **No backward compatibility by default.** No legacy paths, compatibility wrappers, migration shims, dual-format support, or fallback behavior unless explicitly requested. A published external contract is the only exception, and only when the user or repo instructions confirm it is published.
• **Read before writing.** Runtime and package manager from local files (`package.json`, lockfiles, `tsconfig*`); the target file, its exports, direct callers, shared helpers, and tests. Reuse source-of-truth schemas/types instead of duplicating shapes.
• **Official docs for third-party behavior.** Before changing a dependency version, or using a third-party API, SDK, CLI, or service in a way neither the PRD nor existing code already shows, read its current official documentation; for a version change, read the release notes between the two versions. Name the page and version in the report. When a PRD governs the work and lacks or contradicts that fact, add it to the PRD's execution notes.
• **Surgical changes.** Touch only files the task needs. No unrequested options/flags/configurability, no new helpers that duplicate existing utilities, no formatting churn, renames, or opportunistic cleanup.
• **Deterministic code for deterministic decisions.** Routing, retries, status handling, validation, and parsing belong in code, never in a model call.
• **Conflicting local patterns:** pick one source of truth (by authority, recency, test coverage), state the choice, flag the other for cleanup — never blend into a third style.
• State uncertainty that affects behavior, public API, data shape, or migration semantics before coding, and decide the verification command before coding.

Standards

• `unknown` + narrowing over `any`. Type guards or schema validation over assertions; a narrow assertion only at a validated boundary, with a short comment. No non-null assertions — narrow with control flow or fail early.
• Exported functions explicitly typed. Named exports unless the repo or framework requires default exports.
• Discriminated unions where impossible states matter; `as const satisfies` for literal maps that need exhaustiveness.
• Functions under ~50 lines, max 3 indentation levels; extract only when it clarifies real complexity.
• Validate external boundaries with the repo's existing parser/schema library (`zod`, `valibot`, generated types, or local validators). Fail clearly — no fallback behavior that hides invalid state.
• Clean up timers, listeners, subscriptions, and abort controllers in `finally` or explicit teardown.
• Keep fixed-format parsing and protocol literals in code; use existing translation resources only for text that requires localization. Reuse the repository's configuration approach rather than introducing a configuration or translation system for an ordinary change.

Migrations

Hard cut by default: replace the old path rather than running old and new together. No compatibility aliases, duplicate parsing, legacy env names, or fallback resolution unless explicitly requested. For a published package, inspect its actual external contract and the owner's settled instruction. Preserve that contract unless a breaking change is authorized. Resolve routine implementation choices directly; ask only if a new fact requires an owner decision, and continue independent work. Preserve unrelated local modifications and user work; never rewrite history or reset files to make a migration easier.

Verification

Narrowest relevant checks first, broader when the change touches shared behavior:

1. Typecheck the edited package. 2. Run focused tests for changed behavior. 3. Lint/format only through the repo's existing commands. 4. For shared/public behavior, check the changed behavior and directly affected consumers. Never expand to a package-wide or workspace-wide test suite without an explicit human request.

Every "done" claim must trace to a command actually run this session; if a check fails, report the failure with its output — never report done with errors outstanding.

Delivery

Report: what changed and why; the compatibility decision if the task touched public API, data formats, env/config names, or migration behavior; the verification commands actually run and their results; any remaining conflict or cleanup item intentionally not changed.