Axiomatic Reasoning for LLMs

Implementation Plan on TypeScript

1. Overview

This plan defines a technical framework for applying Deep Coding — a specification‑driven, human‑AI collaborative development methodology — to TypeScript projects. Deep Coding separates intent, structural specification, and implementation, then enforces generative conformance through automated validation gates. The plan translates five core principles into concrete TypeScript constructs, toolchain integrations, and phase‑based workflows.

All philosophical framing is replaced with executable technical procedures.

2. Core Principles (Technical Translation)

Original Principle TypeScript Technical Equivalent
Intent–Structure–Implementation Separation TypeScript interfaces (specification) + abstract classes (skeleton) + concrete classes (tissue)
Generative Conformance Interface implementation + tsc --strict + runtime schema validation (Zod)
Recursive Refinement with Fixed Premises Version‑controlled specification files + Git commits as phase checkpoints
Skeleton–Tissue Architecture Abstract classes (skeleton, manually maintained) + concrete classes (tissue, generated)
Inferential Information Density (Negentropy) Type density (exported types / lines) + absence of circular dependencies (dependency-cruiser)

3. Architecture Layers

Layer 0: Intent (Human)
   ↓
Layer 1: Structural Specification
   - OpenAPI / JSON Schema / TypeScript interfaces / Zod schemas
   - Stored in `specification/`
   ↓
Layer 2: Generation (Tooling + Optional AI)
   - OpenAPI Generator, json-schema-to-typescript, custom AST transformers
   - Output to `generated/`
   ↓
Layer 3: Validation Gates
   - `tsc --strict`, ESLint, dependency-cruiser, Zod runtime checks
   ↓
Layer 4: Tissue (Generated Code) + Skeleton (Manual Code)
   - Tissue: `tissue/` – business logic, concrete implementations
   - Skeleton: `skeleton/` – abstract classes, cross‑cutting concerns

4. Structural Specification Formats

Scope Format Tooling
API boundaries (REST) OpenAPI 3.0+ YAML openapi-typescript, orval
Data models JSON Schema @rxap/json-schema-to-typescript
Internal module contracts TypeScript interfaces tsc --noEmit
Runtime‑validated boundaries Zod schemas zod (inference + validation)
Full‑stack TypeScript tRPC (implicit spec) TypeScript compiler only

Selection rule: Prefer OpenAPI for external APIs, JSON Schema for shared data, interfaces for internal modules, Zod for runtime‑critical boundaries.

5. Validation Gates (Four Layers)

Layer Tool Command Fail Condition
Compile‑time TypeScript tsc --strict --noEmit Any type error
Lint‑time ESLint (custom rules) eslint . --rule 'no-restricted-imports: ["error", { patterns: ["skeleton/*"] }]' Tissue imports skeleton directly (inverse dependency)
Dependency dependency-cruiser depcruise src --config .dependency-cruiser.js Circular import or forbidden dependency direction
Runtime Zod + Jest zod.parse() in tests Schema validation fails

CI Integration: All gates must pass before merging. Generated code is re‑validated on every PR.

6. Skeleton–Tissue Pattern in TypeScript

6.1 Skeleton (Manual, Immutable)

// skeleton/GameLoopSkeleton.ts
export abstract class GameLoopSkeleton {
    run(): void {
        this.initialize();
        while (this.isRunning()) {
            this.update();
            this.render();
        }
        this.cleanup();
    }
    protected abstract initialize(): void;
    protected abstract update(): void;
    protected abstract render(): void;
    private isRunning(): boolean { /* ... */ }
    private cleanup(): void { /* ... */ }
}

6.2 Tissue (Generated or AI‑produced)

// tissue/GameLogic.ts (generated)
import { GameLoopSkeleton } from '../skeleton/GameLoopSkeleton';
export class GameLogic extends GameLoopSkeleton {
    protected initialize(): void { /* AI generated */ }
    protected update(): void { /* AI generated */ }
    protected render(): void { /* AI generated */ }
}

6.3 Enforcing Dependency Direction

// .dependency-cruiser.js
{
    forbidden: [{
        name: 'tissue-to-skeleton-inverse',
        from: { path: '^src/tissue' },
        to: { path: '^src/skeleton' }
    }]
}

7. Recursive Refinement Workflow

Each phase follows:

  1. Plan – Define changes to structural specification (OpenAPI, JSON Schema, interfaces).
  2. Approve – Human reviews specification delta.
  3. Generate – Run code generators (orval, json-schema-to-typescript, or AI prompt).
  4. Validate – Execute four validation gates (tsc, ESLint, depcruise, Zod tests).
  5. Commit – If all pass, commit new specification + generated code as fixed premise.
  6. Repeat – Next phase.

Rollback: Revert to previous commit of specification files, then regenerate.

8. TypeScript‑Specific Adaptations

Challenge TypeScript Solution
Structural typing (duck typing) accidental conformance Branded types: type UserId = string & { __brand: 'UserId' }
Async flow control in skeleton async template methods + explicit ExecutionContext passing
Single inheritance limitation Compose via interfaces + dependency injection (prefer over multiple inheritance)
Type erasure at runtime Zod schemas for runtime validation (dual source with interfaces)
Build pipeline (bundlers, transpilers) Run tsc --noEmit before bundling; never rely on Babel for type checking
External npm packages with no types Adapter pattern: wrap with interface + Zod schema in specification/adapters/

9. Implementation Checklist

10. Conclusion

Deep Coding on TypeScript is a technically executable methodology that replaces philosophical declarations with:

The plan is scoped to TypeScript projects with strict mode enabled. For event‑driven frameworks (React, Vue), replace “flow ownership” with “state transition contracts” (Zod‑validated state machines). External npm dependencies must be isolated behind adapter layers with explicit specifications.

All principles reduce to tool‑enforced rules and directory conventions — no philosophy required.

This site is open source. Improve this page.