Ub Ts

UB TS

Overview

Use this skill to enforce latest stable TypeScript modern defaults and patterns across app and library codebases. Generate modern-only output for new code, and allow legacy retention only as a bounded migration exception.

Implement against the detected project TypeScript and runtime truth, but bias design toward forward-compatible migration rather than compatibility layers or legacy fallbacks.

Bundled Assets

This skill ships reusable tsconfig starter scaffolding and an optional ESLint flat-config starter under assets/, plus a deterministic helper under scripts/.

Use them when a repository wants this house-style starting point and does not yet have active TypeScript config of its own.

Load References On Demand

• Read references/ts-modern-patterns.md for archetype selection, tsconfig baselines, and modern typing patterns.
• Read references/ts-legacy-to-modern-migration.md for old-to-new migrations, banned patterns, and exception handling.
• Read references/ts-config-resolution.md when local TypeScript config

discovery, starter scaffolding, or optional ESLint support matters.

• Read references/task-bundle.md only when the target repository wants an

optional Task-based automation overlay for this skill's starter profile.

• Use scripts/scaffold_ts_baseline.py with assets/tsconfig-template/ and

assets/eslint-template/ when a target repository needs a deterministic starter instead of ad hoc config creation.

Skill Coordination

• Co-load this skill with ub-vuejs or ub-nuxt when TypeScript issues live

inside framework projects.

• Defer framework runtime, routing, and app-structure decisions to the sibling

skill that owns them.

Core Workflow

1. Detect the project archetype from package.json, lockfiles, runtime targets, build tooling, and existing tsconfig*.json files.
2. Choose module strategy that matches runtime truth:

• Node runtime: module as node20 or nodenext
• Bundler runtime: moduleResolution as bundler with module as esnext
• Library publishing: prefer Node-faithful resolution for compatibility checks
• Type-stripping runtime: enforce erasable TypeScript subset

1. Compare official guidance, repo truth, and observed code reality for

non-trivial or version-sensitive recommendations.

1. Surface OFFICIAL_CONFLICT when authoritative sources, repo truth, or live

code reality materially disagree on a non-trivial recommendation.

1. Surface UNVERIFIED when a non-trivial claim could not be confirmed in

official sources after targeted research.

1. Apply strict safety baseline and module hygiene defaults from references/ts-modern-patterns.md.
2. Implement modern type patterns first (satisfies, const type parameters, NoInfer, discriminated unions, explicit boundary typing).
3. Reject legacy output for new code and apply migration mapping from references/ts-legacy-to-modern-migration.md when touching existing code.
4. Validate with available typecheck, lint, tests, and build commands in the target project.
5. If a repository wants this baseline but lacks TypeScript config, scaffold

the bundled starter and explain the remaining repo-local adaptations.

Version & Research Policy

• Target the latest stable release of TypeScript.
• Detect the project's actual TypeScript version from package.json and lockfiles.
• Use web search to verify current best practices, API availability, and migration guidance against official TypeScript documentation.
• Treat repo truth as the gold implementation standard when deciding what can

actually ship safely in the current project.

• Treat official TypeScript docs as the preferred guidance baseline for

forward-looking design and migration-ready patterns.

• If official guidance and repo truth diverge materially on a non-trivial

recommendation, surface OFFICIAL_CONFLICT, implement the repo-safe path, and explain the migration path.

• If official sources disagree with each other on a non-trivial recommendation,

also surface OFFICIAL_CONFLICT instead of silently collapsing the disagreement.

• If a non-trivial claim cannot be confirmed in official sources after targeted

research, mark it UNVERIFIED or avoid presenting it as settled guidance.

• Keep conflict and uncertainty disclosure scoped to non-trivial,

version-sensitive, or contested guidance rather than trivial edits.

• Do not emit beta-only syntax unless the user explicitly requests it.
• When the project's installed version is behind latest stable, note the version gap and recommend an upgrade path.
• Inspect the host repository's AGENTS.md or equivalent instructions when

present for project-specific version policy and tooling; do not assume it contains this catalog's defaults.

• Do not hardcode version numbers in generated guidance — keep recommendations evergreen.

Freshness Review

• Volatility: high
• Review recommendation: review on touch and during periodic maintenance, targeting a quarterly rhythm when practical.
• Trigger signals: TypeScript release changes, compiler-flag behavior shifts, new module-resolution guidance, or runtime-platform updates that affect tsconfig strategy.
• Enforcement: advisory only; freshness should inform review priority, not become a blocking requirement by itself.
• Stable core: runtime-faithful module strategy, strict typing, and explicit boundary modeling remain the durable guidance even when compiler defaults evolve.

Implementation Rules

Project Archetype and Modules

• Decide archetype before changing compiler options.
• Keep module settings runtime-faithful, not preference-driven.
• Keep moduleDetection as force unless a known compatibility constraint requires otherwise.

Import and Export Hygiene

• Keep verbatimModuleSyntax enabled.
• Use import type and export type for type-only symbols.
• Keep side-effect imports explicit and resolvable.

Type System Patterns

• Prefer satisfies to validate shapes without widening literals.
• Prefer const type parameters in reusable APIs that benefit from literal preservation.
• Use built-in NoInfer when inference must be constrained.
• Model state with discriminated unions when behavior depends on variants.
• Use unknown at trust boundaries, then narrow with validation.

Compiler Baseline

• Keep strict: true.
• Keep noUncheckedIndexedAccess: true.
• Keep exactOptionalPropertyTypes: true.
• Enable isolatedModules in toolchain-mixed repos.
• Enable isolatedDeclarations for declaration-heavy library workflows.
• Use noUncheckedSideEffectImports when side-effect imports are present.

Config Resolution And Scaffolding

Treat real project config as the source of truth:

1. inspect tsconfig*.json, eslint.config.*, package.json, and lockfiles

first when they exist

1. match local runtime, bundler, and package-manager truth before choosing a

starter

1. use the bundled tsconfig scaffold only when the repository lacks active

config and wants this house-style baseline

1. treat the ESLint starter as optional strong-default support for TS repos,

not as universal TypeScript policy

1. do not silently install dependencies or mutate CI as part of scaffolding

Tradeoff Handling

• Use the shared ub-quality decision-analysis baseline for major TypeScript

decisions.

• State TypeScript-specific pros and cons for each option, especially around

correctness, compatibility, DX, and migration cost.

• Default to the safest modern option unless user constraints indicate otherwise.

Legacy-Avoidance Guardrails

• Do not generate legacy experimental decorator patterns for new code.
• Do not generate namespace-centric architecture for new code.
• Do not rely on implicit type-only import elision.
• Do not use assertion-heavy shortcuts (as any, chained assertions) where narrowing is possible.
• Do not introduce legacy module ambiguity between ESM and CJS.

Migration-aware exception policy:

• Allow temporary legacy retention only for explicit compatibility constraints in existing code.
• Document exactly what is retained, why it is retained, and the concrete follow-up modernization step.
• Scope each exception narrowly and avoid introducing new dependency on retained legacy behavior.

Output Requirements

When generating or reviewing code, include:

1. Environment note: detected archetype, runtime target, and toolchain context.
2. Source truth note: detected project version/toolchain reality and any

material gap versus latest stable guidance.

1. Version note: TypeScript baseline and any intentional deviations.
2. Decision note: chosen module and compiler strategy with one alternative.
3. Tradeoff note: concise pros and cons for chosen path and rejected option.
4. Legacy note: removed legacy patterns or bounded exceptions with rationale.
5. Validation note: what checks were run and outcomes.
6. Conflict note when relevant: OFFICIAL_CONFLICT or UNVERIFIED with a

concise explanation and the implementation consequence.

When this skill is used to scaffold TypeScript config into another repository, also include:

1. which files were created or skipped
2. which archetype was chosen and one rejected alternative
3. which repo-local settings or dependencies still need adaptation
4. the exact next validation command to run

Completion Checklist

• Latest stable TypeScript modern baseline is enforced.
• Project archetype was detected before config or code changes.
• Module strategy matches runtime behavior.
• Strict safety flags are enabled intentionally.
• New code avoids legacy patterns.
• Any retained legacy pattern is documented with a migration path.
• Typecheck and relevant project validations were executed when available.
• Any material official-source conflict or unverified non-trivial guidance is

disclosed explicitly when relevant.

• Any scaffolded baseline was reported as a starter profile rather than silent

repo policy.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: robert-hoffmann
• Source: robert-hoffmann/uncle-bob
• License: MIT
• Homepage: https://robert-hoffmann.github.io/uncle-bob/

Install and usage instructions live in the source repository linked above.