coding-typescript

---

name: coding-typescript description: Write TypeScript code that's type-safe and tested. Use when coding TypeScript or implementing features. allowed-tools: Read, Write, Bash, Glob, Grep, Edit

<accessing_skill_files> When this skill is invoked, Claude Code provides the base directory in the loading message:

CopyBase directory for this skill: {skill_dir}

Use this path to access skill files:

• References: {skill_dir}/references/
• Workflows: {skill_dir}/workflows/

IMPORTANT: Do NOT search the project directory for skill files. </accessing_skill_files>

<essential_principles> NO MOCKING. DEPENDENCY INJECTION. BEHAVIOR ONLY. TEST FIRST.

• Use dependency injection, NEVER mocking frameworks
• Test behavior (what the code does), not implementation (how it does it)
• Run all verification tools before declaring completion
• Type safety first: strict: true, no any without justification

</essential_principles>

<testing_methodology> For complete testing methodology, invoke /testing-typescript skill.

The /testing-typescript skill provides:

• Detailed test level selection criteria
• Dependency injection patterns (NO MOCKING)
• Behavior-only testing approach
• Test organization for debuggability
• Test graduation workflow

Quick Reference - Testing Levels:

NO MOCKING — Use Dependency Injection Instead:

Copy// ❌ FORBIDDEN: Mocking
vi.mock("execa", () => ({ execa: vi.fn() }));

// ✅ REQUIRED: Dependency Injection
interface CommandDeps {
  execa: typeof execa;
}

it("GIVEN valid args WHEN running THEN returns success", async () => {
  const deps: CommandDeps = {
    execa: vi.fn().mockResolvedValue({ exitCode: 0 }),
  };

  const result = await runCommand(args, deps);

  expect(result.success).toBe(true); // Tests behavior
});

</testing_levels>

<context_loading> BEFORE ANY IMPLEMENTATION: Load complete specification context.

If working on a specs-based work item (story/feature/capability):

1. Invoke specs:understanding-specs FIRST with the work item identifier
2. If context ingestion fails: ABORT - do not proceed until all required documents exist
3. If context ingestion succeeds: Proceed with implementation using loaded context

The specs:understanding-specs skill ensures:

• All specification documents exist (capability/feature/story specs)
• All requirements documents exist (PRD/TRD at appropriate levels)
• All architectural decisions (ADRs) are read and understood
• Complete hierarchical context is loaded (Product → Capability → Feature → Story)

Example invocation:

Copy# By work item path
specs:understanding-specs capability-10_cli/feature-20_commands/story-30_build

# By story name
specs:understanding-specs story-30_build

If specs:understanding-specs returns an error: The error message will specify which document is missing and how to create it. Create the missing document before proceeding with implementation.

If NOT working on specs-based work item: Proceed directly to implementation mode with provided spec. </context_loading>

<two_modes> You operate in one of two modes depending on your input:

Determine your mode from the input, then follow the appropriate workflow. </two_modes>

<core_principles>

1. Spec Is Law: The specification is your contract. Implement exactly what it says.

2. Test-Driven Development: Write tests first or alongside code. Tests prove correctness.

3. Type Safety First: Use strict TypeScript with strict: true. No any without justification.

4. Self-Verification: Before declaring "done," run tsc, eslint, and vitest yourself.

5. Humility: Your code must pass review. Write code that will survive adversarial review.

6. Clean Architecture: Dependency injection, single responsibility, no circular imports, no deep relative imports.

</core_principles>

<reference_index>

</reference_index>

<workflows_index>

</workflows_index>

<what_not_to_do> Never Self-Approve: Always submit for review.

Never Skip Tests: Write tests first. No exceptions.

Never Ignore Type Errors:

Copy// WRONG
const result = someFunction(); // @ts-ignore

// RIGHT
const result: ExpectedType = someFunction();

Never Hardcode Secrets:

Copy// WRONG
const API_KEY = "sk-1234567890abcdef";

// RIGHT
const API_KEY = process.env.API_KEY;
if (!API_KEY) throw new Error("API_KEY required");

Never Use Deep Relative Imports:

Before writing any import, ask: "Is this a module-internal file (same module, moves together) or infrastructure (lib/, tests/helpers/, shared/)?"

Copy// WRONG: Deep relatives to stable locations — will REJECT in review
import { helper } from "../../../../../../tests/helpers/tree-builder";
import { Logger } from "../../../../lib/logging";
import { Config } from "../../../shared/config";

// RIGHT: Configure path aliases in tsconfig.json
import { Logger } from "@lib/logging";
import { Config } from "@shared/config";
import { helper } from "@test/helpers/tree-builder";

Depth Rules:

• ./sibling — ✅ OK (same directory, module-internal)
• ../parent — ⚠️ Review (is it truly module-internal?)
• ../../ or deeper — ❌ REJECT (use path alias)

Configure tsconfig.json:

Copy{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@/*": ["src/*"],
      "@test/*": ["tests/*"],
      "@lib/*": ["lib/*"]
    }
  }
}

</what_not_to_do>

<tool_invocation>

Copy# Type checking
npx tsc --noEmit

# Linting
npx eslint src/ test/
npx eslint src/ test/ --fix

# Testing
npx vitest run --coverage

</tool_invocation>

<success_criteria> Your implementation is ready for review when:

• Spec fully implemented
• All functions have type annotations
• All public functions have JSDoc
• Tests exist for all public functions
• tsc passes with zero errors
• eslint passes with zero errors
• All tests pass
• Coverage ≥80% for new code
• No TODOs/FIXMEs unaddressed
• No console.log statements
• No hardcoded secrets

Your code will face an adversarial reviewer with zero tolerance. Write code that will survive that scrutiny. </success_criteria>