tlc-claude-code 1.8.2 → 1.8.4

package/.claude/commands/tlc/audit.md

@@ -34,17 +34,24 @@ const { auditProject, generateReport } = require('./lib/standards/audit-checker'
 
 Run `auditProject(projectPath)` which executes:
 
-| Check | What It Finds |
-|-------|---------------|
-| Standards Files | Missing CLAUDE.md or CODING-STANDARDS.md |
-| Flat Folders | Files in src/services/, src/interfaces/, src/controllers/ |
-| Inline Interfaces | `interface X {` inside *.service.ts files |
-| Hardcoded URLs | http:// or https:// URLs in code |
-| Hardcoded Ports | `const port = 3000` patterns |
-| Magic Strings | `=== 'active'` comparisons without constants |
-| Flat Seeds | Seed files in src/seeds/ instead of src/{entity}/seeds/ |
-| Missing JSDoc | Exported functions without `/**` comments |
-| Deep Imports | `../../../` style imports (3+ levels) |
+| Check | What It Finds | Severity |
+|-------|---------------|----------|
+| Standards Files | Missing CLAUDE.md or CODING-STANDARDS.md | error |
+| Flat Folders | Files in src/services/, src/interfaces/, src/controllers/ | error |
+| Inline Interfaces | `interface X {` inside *.service.ts or *.controller.ts files | error |
+| Inline Constants | `const X =` hardcoded values inside service/controller files | warning |
+| Hardcoded URLs | http:// or https:// URLs in code | error |
+| Hardcoded Ports | `const port = 3000` patterns | error |
+| Magic Strings | `=== 'active'` comparisons without constants | warning |
+| Flat Seeds | Seed files in src/seeds/ instead of src/{entity}/seeds/ | warning |
+| Missing JSDoc | Exported functions without `/**` comments | warning |
+| Deep Imports | `../../../` style imports (3+ levels) | warning |
+| **Oversized Files** | Files exceeding 1000 lines (warn at 500) | error/warning |
+| **Overcrowded Folders** | Folders with >15 files directly inside (warn at 8) | error/warning |
+| **`any` Type Usage** | `any` type annotations in TypeScript files | error |
+| **Missing Return Types** | Exported functions without explicit return type | warning |
+| **Missing Parameter Types** | Function parameters without type annotations | error |
+| **Weak tsconfig** | `strict: true` not enabled in tsconfig.json | warning |
 
 ### Step 3: Generate Report
 
@@ -80,15 +87,27 @@ Status: {PASSED | FAILED}
 TLC Audit Results
 ═══════════════════════════════════════════════════════════════
 
-Status: ✗ FAILED (12 issues found)
-
-Standards Files:    ✓ PASSED
-Flat Folders:       ✗ 3 issues
-Inline Interfaces:  ✗ 2 issues
-Hardcoded URLs:     ✗ 4 issues
-Magic Strings:      ✗ 2 issues
-JSDoc Coverage:     ✗ 1 issue
-Import Style:       ✓ PASSED
+Status: FAILED (18 issues found)
+
+  STRUCTURE
+  Standards Files:      PASSED
+  Flat Folders:         3 issues
+  Overcrowded Folders:  2 issues (controllers/ has 22 files)
+  Oversized Files:      1 issue  (csp.controller.ts: 2,041 lines)
+
+  TYPES & INTERFACES
+  Inline Interfaces:    2 issues
+  Inline Constants:     3 issues
+  any Type Usage:       5 issues
+  Missing Return Types: 4 issues
+  Missing Param Types:  2 issues
+  Weak tsconfig:        PASSED
+
+  CODE QUALITY
+  Hardcoded URLs:       4 issues
+  Magic Strings:        2 issues
+  JSDoc Coverage:       8 issues (42% of exports undocumented)
+  Import Style:         PASSED
 
 Report saved to: .planning/AUDIT-REPORT.md
 

package/.claude/commands/tlc/build.md

@@ -692,6 +692,11 @@ git diff --name-status main...HEAD
 1. **Test Coverage** - Every implementation file has a test file
 2. **TDD Compliance** - Commits show test-first pattern (score ≥ 50%)
 3. **Security Scan** - No hardcoded secrets, eval(), innerHTML, etc.
+4. **File Size** - No file exceeds 1000 lines (warning at 500+)
+5. **Folder Size** - No folder exceeds 15 files (warning at 8+)
+6. **Strict Typing** - No `any` types in new/changed files
+7. **Return Types** - All exported functions have explicit return types
+8. **Module Structure** - Files grouped by domain entity, not by type
 
 **Review output:**
 
@@ -702,6 +707,10 @@ git diff --name-status main...HEAD
 Test Coverage: ✅ 5/5 files covered
 TDD Score: 75% ✅
 Security: ✅ No issues
+File Sizes: ✅ All under 1000 lines
+Folder Sizes: ✅ All under 15 files
+Strict Typing: ✅ No `any` found
+Return Types: ✅ All exports typed
 
 Verdict: ✅ APPROVED
 ───────────────────────────────
@@ -721,6 +730,18 @@ TDD Score: 25% ❌ (target: 50%)
 Security: ❌ 1 high severity issue
 └── Hardcoded password in src/config.js
 
+File Sizes: ⚠️ 1 file over limit
+└── src/api/users.controller.ts (1,247 lines) → split by feature
+
+Strict Typing: ❌ 3 `any` types found
+├── src/api/users.controller.ts:45 → define interface
+├── src/api/users.controller.ts:89 → use `unknown`
+└── src/services/email.ts:12 → define `EmailOptions` interface
+
+Return Types: ⚠️ 2 exported functions missing return types
+├── src/utils/helpers.ts:getConfig() → add `: AppConfig`
+└── src/utils/helpers.ts:parseInput() → add `: ParsedInput`
+
 Verdict: ❌ CHANGES REQUESTED
 
 ⚠️ Phase cannot complete until issues are fixed.
@@ -730,7 +751,10 @@ Verdict: ❌ CHANGES REQUESTED
 **Actions on failure:**
 1. Add missing test files
 2. Fix security issues
-3. Re-run `/tlc:build {phase}` to retry
+3. Split oversized files (>1000 lines) into focused sub-modules
+4. Replace `any` types with proper interfaces or `unknown`
+5. Add explicit return types to all exported functions
+6. Re-run `/tlc:build {phase}` to retry
 
 **CRITICAL: Phase is NOT complete until review passes.**
 

package/.claude/commands/tlc/cleanup.md

@@ -12,6 +12,10 @@ Automatically fix all coding standards violations. No prompts - just fixes every
    - Extracts inline interfaces to types/ files
    - Replaces magic strings with constants
    - Adds missing JSDoc comments
+   - **Splits oversized files** (>1000 lines) into focused sub-modules
+   - **Organizes overcrowded folders** (>15 files) into domain subfolders
+   - **Replaces `any` types** with proper interfaces or `unknown`
+   - **Adds missing return types** to exported functions
 4. Commits after each module/entity
 5. Reports results when done
 
@@ -101,6 +105,72 @@ export function getUser(id: string): User { }
 export function getUser(id: string): User { }
 ```
 
+#### Oversized Files (>1000 lines)
+```
+// Before: csp.controller.ts (2,041 lines)
+// Analyze the file's responsibilities and split by feature:
+
+// After:
+modules/csp/
+  controllers/
+    policy.controller.ts      # Policy CRUD routes
+    report.controller.ts      # Violation report routes
+    directive.controller.ts   # Directive management routes
+  csp.routes.ts               # Thin route registration
+  csp.service.ts              # Shared business logic
+```
+
+**Split strategy:**
+1. Count exported functions/methods and group by feature
+2. Create a controller/service per feature group
+3. Keep a thin "facade" file that re-exports or registers all routes
+4. Move shared helpers to a utils file within the module
+
+#### Overcrowded Folders (>15 files)
+```
+// Before: controllers/ with 22 files
+// Group by domain:
+
+// After:
+modules/
+  auth/       # auth.controller.ts, auth.service.ts
+  user/       # user.controller.ts, user.service.ts
+  billing/    # payment.controller.ts, invoice.controller.ts
+  catalog/    # product.controller.ts, category.controller.ts
+```
+
+#### `any` Type Replacement
+```typescript
+// Before
+function processData(data: any): any {
+  return data.items;
+}
+
+// After
+interface ProcessInput {
+  items: unknown[];
+}
+
+function processData(data: ProcessInput): unknown[] {
+  return data.items;
+}
+```
+
+**Strategy:** Read how the variable is used, infer the shape, create an interface.
+
+#### Missing Return Types
+```typescript
+// Before
+export function calculateTotal(items: CartItem[]) {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+
+// After
+export function calculateTotal(items: CartItem[]): number {
+  return items.reduce((sum, item) => sum + item.price, 0);
+}
+```
+
 ### Step 4: Commit After Each Module
 
 After fixing all issues in an entity/module:

package/.claude/commands/tlc/plan.md

@@ -17,6 +17,12 @@ Research and create implementation plans with clear tasks.
 - **Error boundaries**: Where can failures occur? How are they handled?
 - **Data flow**: How does data enter, transform, and exit the system?
 
+### Code Quality Gates
+- **File size limit**: No file should exceed 1000 lines. Plan splits for large modules.
+- **Folder limit**: No folder should exceed 15 files. Plan domain subfolders.
+- **Strict typing**: Plan interfaces upfront — no `any` types, explicit return types.
+- **Module structure**: Group by domain entity (NestJS-style), not by file type.
+
 ### Task Breakdown
 - **Vertical slices**: Each task delivers testable, visible progress
 - **Risk-first**: Tackle unknowns and integrations early
@@ -61,6 +67,13 @@ Each task should be:
 - **Small** - completable in one focused session
 - **Testable** - has clear pass/fail criteria
 - **Independent** - minimal dependencies on other tasks
+- **Standards-compliant** - won't produce files >1000 lines or folders >15 files
+
+**Before finalizing tasks, check:**
+1. Will any planned file exceed 1000 lines? → Split into sub-modules
+2. Will any folder exceed 15 files? → Plan domain subfolders
+3. Are all interfaces defined? → Add `interfaces/` directory per module
+4. Are types explicit? → Plan typed interfaces, not `any`
 
 #### Task Status Markers (Multi-User)
 
@@ -82,12 +95,15 @@ Use `/tlc:claim` to claim a task, `/tlc:release` to release one.
 **Goal:** Define database schema for users table
 
 **Files:**
-- src/db/schema/users.ts
+- src/modules/user/interfaces/user.interface.ts
+- src/modules/user/user.repository.ts
 
 **Acceptance Criteria:**
 - [ ] Schema has id, email, passwordHash, createdAt
 - [ ] Email is unique
 - [ ] Timestamps auto-populate
+- [ ] All types explicit (no `any`)
+- [ ] Exported functions have return types
 
 **Test Cases:**
 - Schema validates correct user data

package/.claude/commands/tlc/review-pr.md

@@ -42,6 +42,7 @@ Same checks as `/tlc:review`:
 - Test coverage for changed files
 - TDD compliance (commit order)
 - Security scan
+- **Coding standards** (file size, folder size, strict typing, return types, module structure)
 
 ### Step 4: Generate PR Comment
 
@@ -53,12 +54,17 @@ Same checks as `/tlc:review`:
 | Test Coverage | ✅ All files covered |
 | TDD Score | ✅ 75% |
 | Security | ✅ No issues |
+| File Sizes | ✅ All under 1000 lines |
+| Folder Sizes | ✅ All under 15 files |
+| Strict Typing | ✅ No `any` types |
+| Return Types | ✅ All exports typed |
 
 ### Summary
 
 - 8 files changed (5 impl, 3 tests)
 - 4 commits analyzed
 - No security vulnerabilities detected
+- All coding standards met
 
 ### Verdict: ✅ APPROVED
 
@@ -134,6 +140,12 @@ TDD Score: 0% ❌
 Security: ⚠️ 1 medium severity issue
 └── console.log with sensitive data
 
+Coding Standards: ❌ 4 issues
+├── src/auth/login.js (1,247 lines) → split by feature
+├── src/auth/login.js:45 → `any` type found
+├── src/auth/login.js:89 → `any` type found
+└── src/config.js:getConfig() → missing return type
+
 Posting review...
 
 ─────────────────────────────────
@@ -145,6 +157,9 @@ See: https://github.com/org/repo/pull/43#review-123457
 Required actions:
 1. Add/update tests for modified files
 2. Remove console.log with sensitive data
+3. Split oversized file (>1000 lines)
+4. Replace `any` types with proper interfaces
+5. Add return types to exported functions
 ─────────────────────────────────
 ```
 

package/.claude/commands/tlc/review.md

@@ -112,6 +112,65 @@ Scan diff for common security issues:
 
 **Fail if:** Any HIGH severity issues found.
 
+### Step 5b: Coding Standards Check
+
+Scan all changed/added files for coding standards violations:
+
+#### File Size Check
+```bash
+# For each changed implementation file
+wc -l <file>
+# >1000 lines = ERROR, 500-1000 = WARNING
+```
+
+#### Folder Size Check
+```bash
+# For each folder containing changed files
+ls <folder> | wc -l
+# >15 files = ERROR, 8-15 = WARNING
+```
+
+#### Strict Typing Check
+```bash
+# Scan changed .ts/.tsx files for `any` type
+grep -n ': any' <file>
+grep -n 'as any' <file>
+grep -n '<any>' <file>
+# Any match = ERROR
+```
+
+#### Return Type Check
+```bash
+# Scan changed .ts/.tsx files for exported functions missing return types
+# Pattern: export function name(params) {   (no : ReturnType before {)
+grep -n 'export function.*)[[:space:]]*{' <file>
+grep -n 'export const.*=.*=>.*{' <file>
+# Missing return type on exported function = WARNING
+```
+
+#### Module Structure Check
+```
+# Flag flat folder anti-patterns in changed files:
+# - src/services/ with >5 unrelated services → should be modules/{entity}/
+# - src/controllers/ with >5 controllers → should be modules/{entity}/
+# - src/interfaces/ at project root → should be per-module interfaces/
+```
+
+**Standards results in report:**
+```
+Coding Standards:
+  File Sizes: ✅ All under 1000 lines
+  Folder Sizes: ✅ All under 15 files
+  Strict Typing: ❌ 3 `any` types found
+  ├── src/api/users.controller.ts:45
+  ├── src/api/users.controller.ts:89
+  └── src/services/email.ts:12
+  Return Types: ⚠️ 2 missing on exports
+  Module Structure: ✅ Domain-grouped
+```
+
+**Fail if:** Any `any` types in new code, or files >1000 lines.
+
 ### Step 6: Invoke External Providers (Codex, Gemini)
 
 **CRITICAL: This step runs automatically when providers are configured.**
@@ -220,6 +279,9 @@ Invoking Codex (GPT-5.2) for review...
 - ✅ All changed files have tests
 - ✅ TDD score: 75%
 - ✅ No security issues detected
+- ✅ All files under 1000 lines
+- ✅ No `any` types
+- ✅ All exports have return types
 
 ## Statistics
 

package/.claude/commands/tlc/tlc.md

@@ -16,10 +16,185 @@ See `/tlc:build` for the complete engineering standards checklist.
 
 ## What This Does
 
-Launches the TLC dashboard - a visual interface showing project state, phases, tests, and next actions.
+Detects project state, checks for TLC version upgrades, and launches the dashboard. If a newer TLC version is installed than the project has configured, it automatically upgrades config and commands before proceeding.
 
 ## Process
 
+### Step 0: Check TLC Version (Upgrade Detection)
+
+**Run this BEFORE anything else.** Compare installed TLC version against the project's `.tlc.json` version.
+
+```bash
+# Get installed TLC version
+installedVersion=$(node -e "
+  try {
+    const p = require('tlc-claude-code/package.json');
+    console.log(p.version);
+  } catch(e) {
+    // Try global
+    const { execSync } = require('child_process');
+    try {
+      const v = execSync('npm list -g tlc-claude-code --json 2>/dev/null', { encoding: 'utf-8' });
+      console.log(JSON.parse(v).dependencies['tlc-claude-code'].version);
+    } catch(e2) { console.log('unknown'); }
+  }
+" 2>/dev/null)
+
+# Get project TLC version from .tlc.json
+projectVersion=$(node -e "
+  try {
+    const c = require('./.tlc.json');
+    console.log(c.tlcVersion || '0.0.0');
+  } catch(e) { console.log('0.0.0'); }
+" 2>/dev/null)
+```
+
+**If `installedVersion` > `projectVersion`:**
+
+Show upgrade notice and apply automatically:
+
+```
+─────────────────────────────────────────────────────
+ TLC UPGRADE DETECTED
+─────────────────────────────────────────────────────
+
+Installed: v{installedVersion}
+Project:   v{projectVersion}
+
+New in this version:
+  {list new features — see Version Features Map below}
+
+Applying upgrade...
+```
+
+Then execute the upgrade steps:
+
+#### Step 0.1: Merge New Config Sections into .tlc.json
+
+Read the project's `.tlc.json`. For each new config section introduced since `projectVersion`, **add it ONLY if it doesn't already exist**. Never overwrite existing user settings.
+
+```javascript
+// Pseudo-code for config merge
+const config = JSON.parse(fs.readFileSync('.tlc.json'));
+
+// Add new sections only if missing
+if (!config.router) {
+  config.router = {
+    providers: {},
+    capabilities: {}
+  };
+  console.log('  + Added: router (LLM provider routing)');
+}
+
+if (!config.dashboard) {
+  config.dashboard = {
+    port: 3147,
+    auth: false
+  };
+  console.log('  + Added: dashboard config');
+}
+
+if (!config.docs) {
+  config.docs = {
+    autoSync: false,
+    screenshots: []
+  };
+  console.log('  + Added: docs automation config');
+}
+
+// Update version stamp
+config.tlcVersion = installedVersion;
+
+fs.writeFileSync('.tlc.json', JSON.stringify(config, null, 2));
+```
+
+#### Step 0.2: Update CLAUDE.md Command Dispatch
+
+Read the project's `CLAUDE.md`. Check if the command dispatch table exists. If new commands were added since `projectVersion`, append them to the table.
+
+**How to detect:** Read `.claude/commands/tlc/*.md` directory listing from the installed TLC package. Compare against the dispatch table entries in the project's `CLAUDE.md`. Add any missing rows.
+
+**Never remove or reorder existing entries.** Only append new ones.
+
+#### Step 0.3: Sync Command Files
+
+The `.claude/commands/tlc/` directory should already be up-to-date if the user ran `tlc` (the CLI installer). But verify:
+
+```bash
+# Check if commands are current
+installedCommandCount=$(ls node_modules/tlc-claude-code/.claude/commands/tlc/*.md 2>/dev/null | wc -l)
+projectCommandCount=$(ls .claude/commands/tlc/*.md 2>/dev/null | wc -l)
+
+if [ "$installedCommandCount" -gt "$projectCommandCount" ]; then
+  echo "  + Syncing new commands to .claude/commands/tlc/"
+  cp node_modules/tlc-claude-code/.claude/commands/tlc/*.md .claude/commands/tlc/
+fi
+```
+
+#### Step 0.4: Detect New LLM Providers
+
+If the `router` section was just added (or is empty), scan for available CLI tools:
+
+```bash
+which claude  >/dev/null 2>&1 && echo "claude detected"
+which codex   >/dev/null 2>&1 && echo "codex detected"
+which gemini  >/dev/null 2>&1 && echo "gemini detected"
+```
+
+If providers are detected but `router.providers` is empty, offer to configure:
+
+```
+LLM providers detected: claude, codex
+
+Configure multi-model routing? (Y/n)
+```
+
+If yes, populate `router.providers` with detected CLIs and default capability mappings.
+
+If no, skip — user can run `/tlc:llm config` later.
+
+#### Step 0.5: Report and Continue
+
+```
+─────────────────────────────────────────────────────
+ UPGRADE COMPLETE
+─────────────────────────────────────────────────────
+
+Updated .tlc.json:
+  + router (LLM provider routing)
+  + dashboard config
+  + docs automation config
+  ~ tlcVersion: 0.0.0 → 1.8.2
+
+Synced:
+  + 3 new commands added
+  + CLAUDE.md dispatch table updated
+
+Configure LLM routing now? → /tlc:llm config
+Configure dashboard?       → /tlc:dashboard
+
+Continuing to dashboard...
+─────────────────────────────────────────────────────
+```
+
+Then continue to Step 1 (launch dashboard) as normal.
+
+**If versions match:** Skip this step silently. No output.
+
+#### Version Features Map
+
+This map tells the upgrade which config sections to add based on version ranges. Update this when new features ship.
+
+| Since Version | Config Section | Default Value | Description |
+|---|---|---|---|
+| 1.5.0 | `router` | `{ providers: {}, capabilities: {} }` | LLM multi-model routing |
+| 1.5.0 | `enterprise` | `{ enabled: false }` | Enterprise features toggle |
+| 1.7.0 | `docs` | `{ autoSync: false, screenshots: [] }` | Documentation automation |
+| 1.8.0 | `dashboard` | `{ port: 3147, auth: false }` | Dashboard configuration |
+| 1.8.2 | `dashboard.compose` | `"docker-compose.tlc.yml"` | Standalone dashboard compose file |
+
+---
+
 ### Step 1: Launch Dashboard
 
 Run the TLC dashboard:

package/CODING-STANDARDS.md

@@ -588,6 +588,141 @@ Refs: #456
 
 ---
 
+## 18. File Size Limits
+
+Large files are a code smell. They indicate a class or module is doing too much.
+
+| Threshold | Action |
+|---|---|
+| **< 300 lines** | Ideal. No action needed. |
+| **300-500 lines** | Acceptable. Review if it can be split. |
+| **500-1000 lines** | Warning. Should be split into focused sub-modules. |
+| **> 1000 lines** | Violation. MUST be split before merging. |
+
+### How to Split
+
+**Controllers with many routes:**
+```
+# Bad: csp.controller.ts (2,000+ lines)
+# Good: Split by resource/feature:
+modules/csp/
+  controllers/
+    policy.controller.ts      # CRUD for policies
+    report.controller.ts      # CSP violation reports
+    directive.controller.ts   # Directive management
+  csp.routes.ts               # Route registration (thin)
+```
+
+**Services with many methods:**
+```
+# Bad: user.service.ts (1,500 lines)
+# Good: Split by responsibility:
+modules/user/
+  services/
+    user-auth.service.ts      # Login, register, password reset
+    user-profile.service.ts   # Profile CRUD, avatar, preferences
+    user-admin.service.ts     # Admin operations, ban, role changes
+  user.service.ts             # Thin facade re-exporting sub-services
+```
+
+---
+
+## 19. Folder Overcrowding
+
+Too many files in one folder makes navigation difficult. Organize into subfolders by domain.
+
+| Threshold | Action |
+|---|---|
+| **< 8 files** | Fine as-is. |
+| **8-15 files** | Consider grouping into subfolders. |
+| **> 15 files** | MUST be organized into subfolders. |
+
+```
+# Bad: 25 files dumped in controllers/
+controllers/
+  auth.controller.ts
+  user.controller.ts
+  payment.controller.ts
+  invoice.controller.ts
+  product.controller.ts
+  ... (20 more)
+
+# Good: Organized by domain
+modules/
+  auth/auth.controller.ts
+  user/user.controller.ts
+  billing/
+    payment.controller.ts
+    invoice.controller.ts
+  catalog/
+    product.controller.ts
+```
+
+---
+
+## 20. Strict Typing
+
+TypeScript without strict types is just JavaScript with extra steps.
+
+### Rules
+
+1. **No `any` type** - Use `unknown` and narrow, or define a proper interface.
+2. **No implicit `any`** - Enable `noImplicitAny` in tsconfig.
+3. **All functions must have explicit return types** - Not just exported functions.
+4. **All parameters must be typed** - No untyped function parameters.
+5. **Prefer `interface` over `type`** for object shapes - Easier to extend.
+6. **Use `strict: true`** in tsconfig.json.
+
+```typescript
+// Bad: Missing types, implicit any
+function processData(data) {
+  const result = data.items.map(item => item.value);
+  return result;
+}
+
+// Good: Explicit types everywhere
+interface DataPayload {
+  items: Array<{ value: number }>;
+}
+
+function processData(data: DataPayload): number[] {
+  return data.items.map((item) => item.value);
+}
+```
+
+```typescript
+// Bad: any type
+function handleResponse(response: any): any {
+  return response.data;
+}
+
+// Good: Proper types
+interface ApiResponse<T> {
+  data: T;
+  status: number;
+}
+
+function handleResponse<T>(response: ApiResponse<T>): T {
+  return response.data;
+}
+```
+
+### tsconfig.json Requirements
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noImplicitAny": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true
+  }
+}
+```
+
+---
+
 ## AI Instructions
 
 When generating code:
@@ -605,6 +740,10 @@ When generating code:
 11. **Always** add JSDoc to public members
 12. **Always** create index.ts with barrel exports
 13. **Always** verify build passes after changes
+14. **Never** let files exceed 1000 lines - split into sub-modules
+15. **Never** let folders exceed 15 files - organize into subfolders
+16. **Never** use `any` type - use `unknown` or proper interfaces
+17. **Always** add explicit return types to functions
 
 ### Cleanup Tasks
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "1.8.2",
+  "version": "1.8.4",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc": "./bin/tlc.js",

package/server/index.js

@@ -57,6 +57,7 @@ const EXTERNAL_APP_PORT = parseInt(process.env.TLC_APP_PORT || '5000');
 // State
 let appProcess = null;
 let appPort = 3000;
+let appIsDocker = false; // true when app is Docker-managed (no local process)
 let wsClients = new Set();
 const logs = { app: [], test: [], git: [] };
 const commandHistory = [];
@@ -485,6 +486,19 @@ async function startApp() {
 
   appPort = project.port;
   addLog('app', `Detected: ${project.name}`, 'info');
+
+  // Docker-managed apps: don't spawn, just proxy
+  if (project.type === 'docker') {
+    appIsDocker = true;
+    addLog('app', `App is Docker-managed — proxying to port ${appPort}`, 'info');
+    if (project.url) {
+      addLog('app', `App URL: ${project.url}`, 'info');
+    }
+    addLog('app', 'TLC will not spawn the app. Use Docker to manage it.', 'info');
+    broadcast('app-start', { port: appPort });
+    return;
+  }
+
   addLog('app', `Command: ${project.cmd} ${project.args.join(' ')}`, 'info');
   addLog('app', `Port: ${appPort}`, 'info');
 
@@ -673,7 +687,7 @@ app.get('/api/status', (req, res) => {
   const plan = parsePlan(PROJECT_DIR);
 
   res.json({
-    appRunning: appProcess !== null,
+    appRunning: appProcess !== null || appIsDocker,
     appPort,
     testsPass: plan.testsPass || 0,
     testsFail: plan.testsFail || 0,
@@ -1087,7 +1101,7 @@ app.get('/api/health', (req, res) => {
       heapUsed: memUsage.heapUsed,
       heapTotal: memUsage.heapTotal,
     },
-    appRunning: appProcess !== null,
+    appRunning: appProcess !== null || appIsDocker,
     appPort,
   });
 });
@@ -1486,7 +1500,7 @@ function getHealthData() {
     memory: memUsed,
     cpu: Math.min(cpuPercent, 100),
     uptime: process.uptime(),
-    appRunning: appProcess !== null,
+    appRunning: appProcess !== null || appIsDocker,
     appPort: appPort
   };
 }

package/server/lib/project-detector.js

@@ -10,6 +10,33 @@ function detectProject(projectDir) {
   if (fs.existsSync(tlcConfigPath)) {
     try {
       const config = JSON.parse(fs.readFileSync(tlcConfigPath, 'utf-8'));
+
+      // Check devServer config (Docker-managed apps)
+      if (config.devServer) {
+        if (config.devServer.type === 'docker') {
+          return {
+            name: 'Docker-managed (' + (config.devServer.containerName || 'docker') + ')',
+            type: 'docker',
+            cmd: null,
+            args: [],
+            port: config.devServer.port || config.devServer.internalPort || 5000,
+            healthCheck: config.devServer.healthCheck || null,
+            url: config.devServer.url || null
+          };
+        }
+        // Non-docker devServer with explicit start command
+        if (config.devServer.startCommand) {
+          const parts = config.devServer.startCommand.split(' ');
+          return {
+            name: 'Custom (.tlc.json devServer)',
+            cmd: parts[0],
+            args: parts.slice(1),
+            port: config.devServer.port || 3000
+          };
+        }
+      }
+
+      // Legacy: check server config
       if (config.server?.startCommand) {
         const parts = config.server.startCommand.split(' ');
         return {