tlc-claude-code 0.6.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jurgen Calleja
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# TLC
+
+**Test Led Coding. Tests before code. Automatically.**
+
+```bash
+npx tlc-claude-code
+```
+
+<p align="center">
+  <img src="assets/terminal.svg" alt="TLC" width="700">
+</p>
+
+---
+
+## The Problem
+
+You tell Claude to build something. It builds it. You test it manually. It's broken. You debug. Repeat.
+
+**That's backwards.**
+
+## The Solution
+
+TLC writes tests *before* code exists. Every feature has a spec. Every spec is executable. When the code works, you know — because the tests pass.
+
+```
+You describe → Tests are written → Code is implemented → Tests pass → Done
+```
+
+No manual testing. No "does this work?" No vibes.
+
+---
+
+## Quick Start
+
+```bash
+npx tlc-claude-code        # Install
+```
+
+Then in Claude Code:
+
+```
+/tlc
+```
+
+That's it. One command. It knows what to do next.
+
+Starting fresh? It asks what you're building.
+Have existing code? It finds untested files.
+Mid-project? It picks up where you left off.
+
+---
+
+## Commands
+
+| Command | What |
+|---------|------|
+| `/tlc` | **Smart entry point. Knows what's next.** |
+| `/tlc:new-project` | Start fresh. Discuss stack, scaffold. |
+| `/tlc:init` | Add TLC to existing code. |
+| `/tlc:coverage` | Find untested → write tests |
+| `/tlc:quick` | One-off task with tests |
+| `/tlc:status` | Pass/fail counts |
+
+---
+
+## What Makes This Different
+
+### 1. Tests First, Always
+
+Other workflows: plan → build → "hope it works"
+
+TLC: plan → **write failing tests** → build until tests pass
+
+The tests *are* the spec. No ambiguity.
+
+### 2. Smart Stack Selection
+
+Don't pick tech in a vacuum. TLC asks what you're building, who uses it, what scale — then suggests the right stack.
+
+```
+Building: Internal dashboard
+Scale: Small team
+Data: Simple CRUD
+
+→ Suggested: Next.js + SQLite + Vercel
+→ Why: Fast to build, cheap to host, fits your needs
+```
+
+### 3. Parallel Agents
+
+Up to 3 Claude instances working simultaneously. GitHub issues as task queue. Watch them go.
+
+```
+┌──────────────────────────────────────────────────────┐
+│ Agents                                               │
+│ [1] ● Working on #42: Auth flow                      │
+│ [2] ● Working on #43: User CRUD                      │
+│ [3] ○ Idle                                           │
+└──────────────────────────────────────────────────────┘
+```
+
+### 4. GitHub Integration
+
+Plans approved → issues created automatically. Tasks complete → issues closed. Full audit trail.
+
+### 5. Live Preview
+
+Docker container spins up. See your app as it's built. Not after.
+
+---
+
+## Dashboard (Coming Soon)
+
+```
+┌─────────────────────────────────┬──────────────────────┐
+│ Chat                            │ GitHub Issues        │
+│                                 │ #42 Auth flow    WIP │
+│ Building login endpoint...      │ #43 User CRUD        │
+│ ✓ Created tests/auth.test.ts    │ #44 Dashboard        │
+│ ✓ Tests failing (expected)      ├──────────────────────┤
+│ Implementing...                 │ Agents (2/3)         │
+│                                 │ [1] ● #42            │
+│                                 │ [2] ● #43            │
+│                                 │ [3] ○ Idle           │
+├─────────────────────────────────┼──────────────────────┤
+│ > add password reset flow       │ Tests: 23/23 ✓       │
+└─────────────────────────────────┴──────────────────────┘
+```
+
+TUI dashboard. Multiple panes. Real-time updates.
+
+---
+
+## Philosophy
+
+**Tests define behavior. Code makes tests pass.**
+
+- Tests written BEFORE code
+- Tests are the spec, not an afterthought
+- If it's not tested, it doesn't exist
+- Human verification still happens — tests catch logic errors, you catch "not what I meant"
+
+---
+
+## vs Other Approaches
+
+| Approach | Process | Result |
+|----------|---------|--------|
+| Vibe coding | Build → hope | Works until it doesn't |
+| Manual TDD | Write tests yourself | Slow, easy to skip |
+| **TLC** | Tests auto-generated first | Fast, guaranteed coverage |
+
+---
+
+## Install
+
+```bash
+npx tlc-claude-code
+```
+
+Options:
+- `--global` — Available everywhere
+- `--local` — This project only
+
+---
+
+## License
+
+MIT

package/bin/install.js

@@ -0,0 +1,165 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+// ANSI color codes
+const c = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  cyan: '\x1b[36m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  magenta: '\x1b[35m',
+  white: '\x1b[37m',
+};
+
+const LOGO = `
+${c.cyan}  ████████╗██╗     ██████╗
+  ╚══██╔══╝██║    ██╔════╝
+     ██║   ██║    ██║
+     ██║   ██║    ██║
+     ██║   ███████╗╚██████╗
+     ╚═╝   ╚══════╝ ╚═════╝${c.reset}
+`;
+
+const VERSION = '0.6.0';
+
+const COMMANDS = [
+  'tlc.md',
+  'new-project.md',
+  'init.md',
+  'coverage.md',
+  'discuss.md',
+  'plan.md',
+  'build.md',
+  'verify.md',
+  'status.md',
+  'progress.md',
+  'complete.md',
+  'new-milestone.md',
+  'quick.md',
+  'help.md'
+];
+
+function getGlobalDir() {
+  const claudeConfig = process.env.CLAUDE_CONFIG_DIR || path.join(require('os').homedir(), '.claude');
+  return path.join(claudeConfig, 'commands');
+}
+
+function getLocalDir() {
+  return path.join(process.cwd(), '.claude', 'commands');
+}
+
+function printBanner() {
+  console.log(LOGO);
+  console.log(`  ${c.bold}TLC${c.reset} ${c.dim}v${VERSION}${c.reset}`);
+  console.log(`  ${c.white}Test Led Coding for Claude Code${c.reset}`);
+  console.log(`  ${c.dim}Tests before code, automatically${c.reset}`);
+  console.log('');
+}
+
+function log(msg) {
+  console.log(`  ${msg}`);
+}
+
+function success(msg) {
+  console.log(`  ${c.green}✓${c.reset} ${msg}`);
+}
+
+function info(msg) {
+  console.log(`  ${c.cyan}→${c.reset} ${msg}`);
+}
+
+// Standalone - no external dependencies needed
+
+function install(targetDir, installType) {
+  const commandsDir = path.join(targetDir, 'tlc');
+
+  // Create directory
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  // Copy command files
+  const sourceDir = path.join(__dirname, '..');
+  let installed = 0;
+  for (const file of COMMANDS) {
+    const src = path.join(sourceDir, file);
+    const dest = path.join(commandsDir, file);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+      installed++;
+    }
+  }
+
+  success(`Installed ${installed} commands to ${c.cyan}${commandsDir}${c.reset}`);
+  log('');
+  log(`${c.green}Done!${c.reset} Restart Claude Code to load commands.`);
+  log('');
+  log(`${c.bold}Quick Start:${c.reset}`);
+  log(`  ${c.cyan}/tlc${c.reset}              Smart entry point - knows what to do next`);
+  log('');
+  log(`${c.dim}Or use specific commands:${c.reset}`);
+  log(`  ${c.cyan}/tlc:new-project${c.reset}  Start new project`);
+  log(`  ${c.cyan}/tlc:init${c.reset}         Add TLC to existing code`);
+  log(`  ${c.cyan}/tlc:coverage${c.reset}     Find and fix test gaps`);
+  log('');
+  log(`Run ${c.cyan}/tlc:help${c.reset} for all commands.`);
+  log('');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  printBanner();
+
+  if (args.includes('--global') || args.includes('-g')) {
+    info(`Installing ${c.bold}globally${c.reset} to ~/.claude/commands/tlc`);
+    log('');
+    install(getGlobalDir(), 'global');
+    return;
+  }
+
+  if (args.includes('--local') || args.includes('-l')) {
+    info(`Installing ${c.bold}locally${c.reset} to ./.claude/commands/tlc`);
+    log('');
+    install(getLocalDir(), 'local');
+    return;
+  }
+
+  // Check if non-interactive
+  if (!process.stdin.isTTY) {
+    log(`${c.yellow}Non-interactive terminal detected, defaulting to global install${c.reset}`);
+    log('');
+    install(getGlobalDir(), 'global');
+    return;
+  }
+
+  // Interactive prompt
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  log('Where would you like to install?');
+  log(`  ${c.bold}1)${c.reset} Global ${c.dim}(~/.claude/commands/tlc)${c.reset} - available in all projects`);
+  log(`  ${c.bold}2)${c.reset} Local ${c.dim}(./.claude/commands/tlc)${c.reset} - this project only`);
+  log('');
+
+  rl.question('  Choice [1/2]: ', (answer) => {
+    rl.close();
+    console.log('');
+    if (answer === '2') {
+      info(`Installing ${c.bold}locally${c.reset}`);
+      log('');
+      install(getLocalDir(), 'local');
+    } else {
+      info(`Installing ${c.bold}globally${c.reset}`);
+      log('');
+      install(getGlobalDir(), 'global');
+    }
+  });
+}
+
+main();

package/build.md

@@ -0,0 +1,347 @@
+# /tlc:build - Build a Phase (Test-First)
+
+Write failing tests, then implement to make them pass.
+
+## What This Does
+
+1. **Write failing tests** for all tasks in the phase
+2. **Verify tests fail** (Red)
+3. **Implement code** one task at a time (Green)
+4. **Verify tests pass** after each task
+5. **Commit** after each passing task
+
+This is the core TLC command. Tests before code, one task at a time.
+
+## Usage
+
+```
+/tlc:build <phase_number>
+```
+
+## Process
+
+### Step 1: Load Plans
+
+Read all `.planning/phases/{phase}-*-PLAN.md` files for this phase.
+
+### Step 2: Detect Test Framework
+
+Check what's already set up:
+- `vitest.config.*` → Vitest
+- `jest.config.*` → Jest
+- `pytest.ini` or `pyproject.toml` with pytest → pytest
+- `spec/` directory → RSpec
+- None found → Set up based on PROJECT.md stack (see framework defaults below)
+
+### Step 3: Plan Tests for Each Task
+
+Before writing any tests, create a test plan for each task in the phase.
+
+For each task in the plan:
+
+1. **Read the task** — understand what behavior is being specified
+2. **Identify test cases:**
+   - Happy path (expected inputs → expected outputs)
+   - Edge cases mentioned in `<action>`
+   - Error conditions from `<verify>`
+3. **Create test plan entry**
+
+Create `.planning/phases/{phase}-TEST-PLAN.md`:
+
+```markdown
+# Phase {N} Test Plan
+
+## Task: {task-id} - {task-title}
+
+### File: tests/{feature}.test.ts
+
+| Test | Type | Expected Result |
+|------|------|-----------------|
+| user can log in with valid credentials | happy path | returns user object |
+| login rejects invalid password | error | throws AuthError |
+| login rejects empty email | edge case | throws ValidationError |
+
+### Dependencies to mock:
+- database connection
+- email service
+
+---
+
+## Task: {task-id-2} - {task-title-2}
+...
+```
+
+### Step 4: Write Tests One Task at a Time
+
+**For each task in the test plan, sequentially:**
+
+#### 4a. Write test file for this task
+
+Follow the project's test patterns. Test names should describe expected behavior:
+```
+✓ "user can log in with valid credentials"
+✓ "login rejects invalid password with 401"
+✗ "test login" (too vague)
+```
+
+**Vitest/Jest (TypeScript):**
+```typescript
+import { describe, it, expect } from 'vitest'
+import { login } from '../src/auth/login'
+
+describe('login', () => {
+  it('returns user object for valid credentials', async () => {
+    const result = await login('user@test.com', 'password123')
+    expect(result.user).toBeDefined()
+    expect(result.user.email).toBe('user@test.com')
+  })
+
+  it('throws AuthError for invalid password', async () => {
+    await expect(login('user@test.com', 'wrong'))
+      .rejects.toThrow('Invalid credentials')
+  })
+})
+```
+
+**pytest (Python):**
+```python
+import pytest
+from src.auth import login
+
+def test_login_returns_user_for_valid_credentials():
+    result = login("user@test.com", "password123")
+    assert result["user"]["email"] == "user@test.com"
+
+def test_login_raises_for_invalid_password():
+    with pytest.raises(AuthError, match="Invalid credentials"):
+        login("user@test.com", "wrong")
+```
+
+#### 4b. Run this test file
+
+```bash
+npm test -- tests/auth/login.test.ts   # vitest
+pytest tests/test_login.py              # pytest
+```
+
+Verify:
+- ✅ Tests execute (no syntax errors)
+- ✅ Tests FAIL (not pass, not skip)
+- ❌ If import errors, add mocks/stubs and retry
+
+#### 4c. Commit this test file
+
+```bash
+git add tests/auth/login.test.ts
+git commit -m "test: add login tests (red) - phase {N}"
+```
+
+#### 4d. Move to next task
+
+Repeat 4a-4c for each task in the test plan.
+
+**Critical Rules:**
+- Tests must be **syntactically valid** and **runnable**
+- Tests must **FAIL** because code doesn't exist yet
+- Tests must NOT **ERROR** from import issues — mock if needed
+- Do NOT write any implementation code
+- Do NOT skip or stub out the actual assertions
+- **One task at a time, verify, commit, then next**
+
+### Step 5: Verify All Tests Fail (Red)
+
+Run the full test suite:
+```bash
+npm test          # or vitest run, pytest, etc.
+```
+
+Check output:
+- ✅ All new tests executed (no syntax errors)
+- ✅ All new tests FAILED (not passed, not skipped)
+- ❌ If tests error on imports, add mocks and retry
+- ❌ If tests pass, something's wrong — investigate
+
+### Step 6: Create Test Summary
+
+Create `.planning/phases/{phase}-TESTS.md`:
+
+```markdown
+# Phase {N} Tests
+
+Generated: {timestamp}
+Status: ✅ All tests failing (Red)
+
+## Test Files
+
+| File | Tests | Status |
+|------|-------|--------|
+| tests/auth.test.ts | 4 | ❌ Failing |
+| tests/session.test.ts | 3 | ❌ Failing |
+
+## Test Output
+
+{test runner output showing failures}
+
+## Coverage Map
+
+| Test | Task |
+|------|------|
+| user can log in with valid credentials | 01-task-1 |
+| login rejects invalid password | 01-task-1 |
+| session persists across requests | 01-task-2 |
+```
+
+### Step 7: Execute Implementation (Green)
+
+Now implement the code to make tests pass. Work through each task sequentially:
+
+**For each task in the plan:**
+
+#### 7a. Read the task
+Review the task's:
+- Goal and expected behavior
+- Acceptance criteria
+- Test cases (now written and failing)
+
+#### 7b. Implement the code
+Write the minimum code needed to pass the tests:
+- Create files specified in the task
+- Follow existing project patterns
+- Reference the failing tests for exact expected behavior
+
+#### 7c. Run tests for this task
+```bash
+npm test -- tests/auth/login.test.ts   # specific file
+```
+
+- ✅ Tests pass → Continue
+- ❌ Tests fail → Fix implementation, retry
+
+#### 7d. Commit this task
+```bash
+git add src/auth/login.ts tests/auth/login.test.ts
+git commit -m "feat: {task-title} - phase {N}"
+```
+
+#### 7e. Move to next task
+Repeat 7a-7d for each task in the phase.
+
+**Critical Rules:**
+- Implement **one task at a time**
+- Run tests **after each task**
+- Commit **after each passing task**
+- Do NOT batch — sequential execution catches issues early
+
+### Step 8: Verify All Tests Pass (Green)
+
+After execution completes, run tests again:
+```bash
+npm test
+```
+
+Check output:
+- ✅ All tests PASS → Continue to verify
+- ❌ Some tests fail → Report which tasks need fixes
+
+### Step 9: Update Test Summary
+
+Update `.planning/phases/{phase}-TESTS.md`:
+
+```markdown
+Status: ✅ All tests passing (Green)
+
+## Final Test Output
+
+{test runner output showing all pass}
+```
+
+## Framework Defaults (for new projects)
+
+If no test framework detected, set up based on PROJECT.md:
+
+| Stack in PROJECT.md | Framework | Setup |
+|---------------------|-----------|-------|
+| Next.js, React, Vite | Vitest | `npm install -D vitest`, create `vitest.config.ts` |
+| Node.js, Express | Vitest | `npm install -D vitest`, create `vitest.config.ts` |
+| Python, FastAPI, Flask | pytest | `pip install pytest`, create `pytest.ini` |
+| Go | go test | Built-in, create `*_test.go` files |
+| Ruby, Rails | RSpec | `gem install rspec`, `rspec --init` |
+
+Default Vitest config:
+```typescript
+import { defineConfig } from 'vitest/config'
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node', // or 'jsdom' for React
+  },
+})
+```
+
+Default pytest.ini:
+```ini
+[pytest]
+testpaths = tests
+python_files = test_*.py
+python_functions = test_*
+```
+
+## Example Run
+
+```
+User: /tlc:build 1
+
+Claude: Loading phase 1 plans...
+Found 2 plans:
+- 01-01-PLAN.md: User authentication
+- 01-02-PLAN.md: Session management
+
+Checking test framework... Vitest detected.
+
+Writing tests for 01-01-PLAN.md...
+Created: tests/auth/login.test.ts (4 tests)
+Created: tests/auth/logout.test.ts (2 tests)
+
+Writing tests for 01-02-PLAN.md...
+Created: tests/session/session.test.ts (5 tests)
+
+Running tests...
+❌ 11 tests failing (expected - no implementation yet)
+
+Created 01-TESTS.md
+
+Implementing task 1/3: User login...
+✅ tests/auth/login.test.ts passing
+Committed: feat: user login - phase 1
+
+Implementing task 2/3: User registration...
+✅ tests/auth/register.test.ts passing
+Committed: feat: user registration - phase 1
+
+Implementing task 3/3: Session management...
+✅ tests/session/session.test.ts passing
+Committed: feat: session management - phase 1
+
+Running tests again...
+✅ 11 tests passing
+
+Phase 1 complete. Ready for /tlc:verify 1
+```
+
+## Error Recovery
+
+**Tests error instead of fail:**
+- Missing imports → Add mocks for dependencies
+- Syntax errors → Fix test code
+- Framework issues → Check config
+
+**Tests pass before implementation:**
+- Code already exists? Check if reimplementing
+- Tests too weak? Strengthen assertions
+- Wrong file paths? Check imports
+
+**Some tests fail after implementation:**
+- Report specific failures
+- Suggest running `/tlc:build {phase}` again to retry
+- Or manually fix and run `/tlc:status` to verify