TOML Generator — Core Skill (Detect → Route → Mirror Updates)

Design happens during REFACTORING, not during coding. See: references/tdd.md

What this skill MUST do

1. Detect the project language(s) and framework(s).
2. Route to the correct rule references in references/**.
3. Generate and maintain a toml/ folder that mirrors architecture.
4. On ANY user code change: immediately and automatically update impacted TOML files and indexes.

Step 0 — Always start from TOML first (token efficiency)

On follow-ups or re-runs:

• Check if toml/INDEX.toml exists.
  • If YES → read it first, then read relevant toml/**/*.toml. Only open source files if TOML is missing/outdated or user explicitly asks.
  • If NO → skip to Step 1 (first-time generation).

Never block on missing TOML — always fall forward to generation.

Step 1 — Detect language & framework (MANDATORY)

Work through signals in order. Stop at first confident match.

Language detection

TypeScript (check first):

• tsconfig.json exists, OR
• typescript in package.json dependencies/devDependencies, OR
• .ts or .tsx files exist outside test folders (*.test.*, *.spec.*, __tests__/)

JavaScript (fallback):

• .js or .jsx files exist in non-test folders, AND
• none of the TypeScript signals above are present

Mixed TS+JS project (both signals present):

• Treat as TypeScript project overall
• Per-file: if file is .ts/.tsx → apply TS rules; if .js/.jsx → apply JS rules
• Never apply TS rules to .js files or vice versa

Additional JS signals (do not ignore):

• babel.config.js or .babelrc exists → JS project confirmed
• jsconfig.json exists → JS project with path aliases

Framework detection

React:

• react in dependencies, OR
• .jsx or .tsx files exist, OR
• JSX syntax (<Component, return () found in files

Next.js (check after React):

• next in dependencies, OR
• /app or /pages directory exists with route-like file patterns

Node server:

• express, fastify, koa, hapi, or @nestjs/core in dependencies, OR
• Entry files like server.ts, app.ts, index.ts exist in a server/ or api/ folder

See:

• references/routing.md
• references/javascript/detect.md
• references/typescript/detect.md

Step 2 — Route to ruleset (MANDATORY)

Select exactly one primary ruleset + optional add-ons.

Primary ruleset

Add-on rules (stack on top of primary)

• Next.js + TS → references/typescript/nextjs.md
• Next.js + JS → references/javascript/nextjs.md
• Node server + TS → references/typescript/node.md
• Node server + JS → references/javascript/node.md

See: references/routing.md

Step 3 — Generate/Update TOML mirror (MANDATORY)

Path mapping rule (never flatten): path/to/File.ext → toml/path/to/File.toml

Every TOML file MUST include:

• [metadata] — name, type, path, description
• [properties] — interface contract (props/params/returns/exports)
• [context] — architectural positioning

See: references/index-format.md

Step 4 — Incremental updates (MANDATORY — triggers on every user code change)

When to trigger

This step runs automatically whenever the user:

• Pastes modified source code
• Says "I updated X", "I added Y", "I deleted Z", "I renamed A to B"
• Shares a diff or patch
• Makes ANY code change visible in the conversation

Do NOT wait for the user to ask "update the TOML". Detect the change and update immediately.

What to update per change type

Outdated detection

Treat a TOML as outdated if ANY of:

• TOML file is missing
• metadata.source.generated_at is older than the user's stated change date
• metadata.source.source_hash mismatches (if hash is tracked)
• Exported interface or classification visibly changed

Minimal safe update (when diff is unavailable)

If only a file list is provided (no diff):

• Regenerate TOML for those files only
• Do not touch others

If a diff/patch is provided:

• Update TOML focusing only on exported interface changes:
  • New or removed exports
  • Changed prop/param contracts
  • Changed dependencies (imports)
  • Changed architectural role

See: references/diff-update.md

Step 5 — Keep indexes in sync (MANDATORY)

After any generation or update, always sync both:

• toml/INDEX.md — human-readable list
• toml/INDEX.toml — machine-readable index

Sync checklist:

• Every toml/**/*.toml has a [[files]] entry in INDEX.toml
• Every [[files]] entry points to an existing TOML file
• No orphan entries after deletions or moves
• No orphan TOML files after deletions

See: references/index-format.md

Default scope rules

Default scan: .

Include (do not skip): src/ shared/ lib/ libs/ packages/ apps/ server/ api/ services/ utils/ scripts/

Never skip a folder solely because it is named api.

Exclude: node_modules/ .git/ dist/ build/ .next/ out/ coverage/ Also exclude: assets, style-only files (.css, .scss), test files.

Non-negotiables

• Never include source code in TOML.
• Never flatten the folder hierarchy.
• Never write trivial descriptions — focus on WHAT + WHY + interface + architectural role.
• Never skip [context].
• For JS files, prefer unknown with a clear description over guessing a wrong type.
• For mixed TS+JS projects, apply per-file language rules — never cross-apply.

Design happens during REFACTORING, not during coding. See: references/tdd.md