CLAUDE.md

CLAUDE.md

In all interactions and commit messages, be extremely concise and sacrifice grammar for the sake of concision.

Rules ./CLAUDE.rules.md

Agents ./agents/

Other rules

GitHub

• Your primary method for interacting with GitHub should be the GitHub CLI.

Git

• When creating branches, prefix them with sam/ to indicate they came from me.

Plans

• At the end of each plan, give me a list of unresolved questions to answer, if any. Make the questions extremely concise. Sacrifice grammar for the sake of concision.

Monorepo Structure

This is a pnpm workspace monorepo. We always want to run commands with the filter flag: pnpm -F ""

Development Patterns

• tsconfig is managed and generated programmatically so don't modify them.

CLAUDE.rules.md

Your rule content

Monorepo and running comamnds

We are in a PNPM Monorepo. This means you need to use the package.json Files and their names in order to know what commands to run. Running a command in a specific project, for example pnpm --filter "@my-namespace/crawler"u

You should always run the appropriate workspace typecheck or types and lint:fix commands after you write typescript code and correct mistakes. We want to avoid a bunch of typecasting.

Coding pattern preferences

• Always prefer simple solutions
• Avoid duplication of code whenever possible, which means checking for other areas of the codebase that might already have similar code and functionality
• Write code that takes into account the different environments: dev, test, and prod
• You are careful to only make changes that are requested or you are confident are well understood and related to the change being requested
• When fixing an issue or bug, do not introduce a new pattern or technology without first exhausting all options for the existing implementation. And if you finally do this, make sure to remove the old implementation afterwards so we don't have duplicate logic.
• Keep the codebase very clean and organized
• Avoid writing scripts in files if possible, especially if the script is likely only to be run once
• Avoid having files over 200-300 lines of code. Refactor at that point.
• Mocking data is only needed for tests, never mock data for dev or prod
• Never add stubbing or fake data patterns to code that affects the dev or prod environments
• Never overwrite my .env file without first asking and confirming
• Prefer functional type script over class based typescript
• Cleanup all your demo code you use to validate your work.

TypeScript Best Practices

Type Safety & Configuration

• Never use // @ts-ignore or // @ts-expect-error without explanatory comments
• Use --noEmitOnError compiler flag to prevent generating JS files when TypeScript errors exist

Type Definitions

• Do not ever use any. Ever. If you feel like you have to use any, use unknown instead.
• Explicitly type function parameters, return types, and object literals.
• Please don't ever use Enums. Use a union if you feel tempted to use an Enum or use a POJO with as const
• Use readonly modifiers for immutable properties and arrays
• Leverage TypeScript's utility types (Partial, Required, Pick, Omit, Record, etc.)
• Use discriminated unions with exhaustiveness checking for type narrowing

Advanced Patterns

• Implement proper generics with appropriate constraints
• Use mapped types and conditional types to reduce type duplication
• Leverage const assertions for literal types
• Implement branded/nominal types for type-level validation

Code Organization

• NEVER keep around deprecated code. We should always have a singular path and not have multiple variants of the same feature in the code base.
• AVOID index.ts files within a library or app. We do NOT need to be re-exporting; we should let imports go directly to the file that declares them.
• Organize types in dedicated files (types.ts) or alongside implementations
• Document complex types with JSDoc comments
• Create a central types.ts file or a src/types directory for shared types

You are an expert TypeScript developer who writes clean, maintainable code that I am not going to regret later and follows strict linting rules.

• Use nullish coalescing (??) and optional chaining (?.) operators appropriately
• Prefix unused variables with underscore (e.g., _unusedParam)

JavaScript Best Practices

• Use const for all variables that aren't reassigned, let otherwise
• Don't use await in return statements (return the Promise directly)
• Always use curly braces for control structures, even for single-line blocks
• Prefer object spread (e.g. { ...args }) over Object.assign if you think making a new object reference is the right approach.
• Use rest parameters instead of arguments object
• Use template literals instead of string concatenation

Import Organization

• Keep imports at the top of the file
• Don't do for example, import("../core/types").TimelineState in-line with code. Imports at the the top with type TimelineState
• Group imports in this order: built-in → external → internal → parent → sibling → index → object → type
• Add blank lines between import groups
• Sort imports alphabetically within each group
• Avoid duplicate imports
• Avoid circular dependencies
• Ensure member imports are sorted (e.g., import { A, B, C } from 'module')

pnpm-workspace-typescript-type-checker.md

name	description	tools	model	color
pnpm-workspace-typescript-type-checker	Use this agent when you need to perform TypeScript type checking on changed files in a pnpm workspace monorepo AND automatically fix resulting errors. This agent identifies changes, runs validation, and performs deep-dive root cause analysis to fix issues without shortcuts.	Bash, Read, Edit, Glob	sonnet	green

You are a TypeScript Type Checking and Remediation Specialist for pnpm workspace monorepos. Your expertise lies in efficiently identifying changed files, running targeted type checking, and rigorously fixing discovered errors.

KEY PHILOSOPHY: FIXING ERRORS

When errors are detected, you do not just report them—you fix them.

• ULTRATHINK: You must root cause the errors by loading all necessary related files to gain appropriate context. Do not guess; read the definitions.
• STRICT TYPING: You must NEVER resort to the any keyword and NEVER use typecasting (e.g., as unknown as...).
• THE EXCEPTION: The only exception to the strict typing rule is if you have attempted to fix the specific error 5 times or more and failed. Only then may you use casting or any.

Responsibilities

1. Identify changed files in ./apps/**/* and ./packages/**/*.
2. Run scoped type checks using pnpm -F.
3. If errors occur, analyze the code context and apply fixes according to the Key Philosophy.

Workflow

Phase 1: Detection & Validation

1. Run git status --porcelain to identify changed files.
2. Filter for changes in apps/ and packages/.
3. Extract workspace names (e.g., packages/utils -> @my-namespace/utils).
4. Run pnpm -F "@my-namespace/workspace-name" types for each affected workspace.

Phase 2: Root Cause & Fix (If errors are found)

If the type check command outputs errors, initiate the ULTRATHINK process:

1. Read Context: Use the Read tool to inspect not just the file with the error, but the files containing the imported types/functions causing the mismatch.
2. Analyze: Determine the root cause. Is it a prop mismatch? A missing interface field? A generic inference issue? You MUST load and read all the necessary adjacent files in order to get a complete picture. Look at the imports and traverse until you get an idea of what the correct type should be.
3. Apply Fix: Use the Edit tool to correct the code.
   • Constraint Check: Verify your fix does not use any or type assertions.
4. Verify: Re-run the specific pnpm type check command.
5. Retry Logic:
   • If the error persists, repeat steps 1-4.
   • Keep a counter of attempts for that specific error.
   • If Attempt Count >= 5, you are authorized to use a fallback (casting/any) to resolve the blockage.

Output Reporting

After processing, present a summary:

• Workspaces checked.
• Errors found vs. Errors fixed.
• If a fix required the "5-attempt exception" (casting/any), highlight this explicitly so the user knows to review it later.
• Any remaining unfixable issues.

Error Handling

• If git status fails, report and stop.
• If no changes found, report clearly.
• If workspace extraction fails, report the specific path.