npm - tlc-claude-code - Versions diffs - 0.6.0 → 0.6.2 - Mend

tlc-claude-code 0.6.0 → 0.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/PROJECT.md ADDED Viewed

@@ -0,0 +1,46 @@
+# TLC - Test Led Coding
+## Overview
+TLC is a Claude Code workflow that enforces test-driven development. It provides slash commands (`/tlc`, `/tlc:new-project`, `/tlc:init`, etc.) that guide developers to write tests before implementation.
+## Tech Stack
+- **Runtime:** Node.js
+- **Package:** npm (tlc-claude-code)
+- **Dashboard:** React + Ink (terminal UI)
+- **Testing:** Vitest
+- **Language:** TypeScript
+## Project Structure
+```
+TLC/
+├── bin/
+│   └── install.js       # CLI installer (npx tlc-claude-code)
+├── dashboard/
+│   └── src/
+│       ├── App.tsx      # Main TUI app
+│       ├── index.tsx    # Entry point
+│       └── components/  # UI panes (Chat, GitHub, Agents, etc.)
+├── *.md                 # Slash command definitions
+└── package.json         # npm package config
+```
+## Development Methodology: Test-Led Development
+This project uses TLC. All new implementation follows Red -> Green -> Refactor:
+1. **Red**: Write failing tests that define expected behavior
+2. **Green**: Write minimum code to make tests pass
+3. **Refactor**: Clean up while keeping tests green
+Tests are written BEFORE implementation, not after.
+## Test Framework
+- **Framework:** Vitest
+- **Run tests:** `cd dashboard && npm test`
+- **Watch mode:** `cd dashboard && npm run test:watch`
+- **Test directory:** `dashboard/src/` (co-located with source)
+- **Pattern:** `*.test.ts`, `*.test.tsx`

package/README.md CHANGED Viewed

@@ -30,23 +30,98 @@ No manual testing. No "does this work?" No vibes.
 ---
-## Quick Start
+## Getting Started
-```bash
-npx tlc-claude-code        # Install
+### New Project
+Starting from scratch? TLC guides you through everything.
+```
+/tlc:new-project
 ```
-Then in Claude Code:
+1. **Discuss requirements** — What are you building? Who uses it? What scale?
+2. **Choose stack** — TLC suggests tech based on your answers, you approve or adjust
+3. **Create roadmap** — Break work into phases
+4. **Build with tests** — Each phase: write tests first, then implement
+### Existing Project
+Have code already? TLC adds test coverage without disrupting your workflow.
+```
+/tlc:init
+```
+1. **Scan codebase** — TLC detects your stack, test framework, project structure
+2. **Find gaps** — Identifies files without tests, prioritizes critical paths
+3. **Write tests** — Adds tests one file at a time, starting with highest priority
+4. **Continue normally** — New features use test-first approach going forward
+### After Setup
+Once initialized, just run:
 ```
 /tlc
 ```
-That's it. One command. It knows what to do next.
+TLC knows where you are and what's next. No phase numbers to remember.
+---
+## Handling Untested Code
+Code comes from many sources. Not all of it has tests.
+### External PRs / Other Developers
+Someone pushes code without tests? TLC catches it.
+```
+> /tlc
+Found 3 new files without tests:
+  - src/api/webhooks.ts (added 2 days ago)
+  - src/utils/retry.ts (added 2 days ago)
+  - src/services/notify.ts (added yesterday)
+Add tests now? (Y/n)
+```
+TLC tracks what's tested. When new untested code appears, it flags it.
+### After "Vibe Coding" Sessions
+Built something fast without tests? No judgment. Run:
+```
+/tlc:coverage
+```
-Starting fresh? It asks what you're building.
-Have existing code? It finds untested files.
-Mid-project? It picks up where you left off.
+TLC scans everything, creates a prioritized backlog:
+```
+Coverage: 67% (24/36 files)
+Critical (no tests):
+  - src/auth/session.ts      ← security
+  - src/payments/charge.ts   ← money
+High priority:
+  - src/api/users.ts
+  - src/api/orders.ts
+Add to backlog and start? (Y/n)
+```
+### Continuous Coverage
+TLC integrates with your workflow:
+- **Before builds** — `/tlc:status` shows pass/fail counts
+- **Before releases** — `/tlc:coverage` ensures nothing slipped through
+- **Daily habit** — `/tlc` reminds you of untested code
 ---
@@ -56,10 +131,10 @@ Mid-project? It picks up where you left off.
 |---------|------|
 | `/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 |
+| `/tlc:init` | Add TLC to existing codebase. |
+| `/tlc:coverage` | Find untested code, write tests. |
+| `/tlc:status` | Test pass/fail counts. |
+| `/tlc:quick` | One-off task with tests. |
 ---
@@ -73,7 +148,11 @@ TLC: plan → **write failing tests** → build until tests pass
 The tests *are* the spec. No ambiguity.
-### 2. Smart Stack Selection
+### 2. Catches Coverage Gaps
+New code without tests? TLC notices. External PRs? Flagged. Post-hackathon cleanup? Prioritized backlog ready.
+### 3. 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.
@@ -86,72 +165,56 @@ Data: Simple CRUD
 → Why: Fast to build, cheap to host, fits your needs
 ```
-### 3. Parallel Agents
+### 4. Works With Your Team
-Up to 3 Claude instances working simultaneously. GitHub issues as task queue. Watch them go.
+TLC doesn't require everyone to use it. You can:
+- Add TLC to a project others contribute to
+- Catch untested code from any source
+- Gradually improve coverage over time
-```
-┌──────────────────────────────────────────────────────┐
-│ Agents                                               │
-│ [1] ● Working on #42: Auth flow                      │
-│ [2] ● Working on #43: User CRUD                      │
-│ [3] ○ Idle                                           │
-└──────────────────────────────────────────────────────┘
-```
+---
-### 4. GitHub Integration
+## Workflow Examples
-Plans approved → issues created automatically. Tasks complete → issues closed. Full audit trail.
+### Solo Developer, New Project
-### 5. Live Preview
+```
+/tlc:new-project     → Discuss requirements, choose stack
+/tlc                 → Build phase 1 (tests first)
+/tlc                 → Build phase 2 (tests first)
+...
+/tlc:complete        → Tag release
+```
-Docker container spins up. See your app as it's built. Not after.
+### Team Project, Existing Codebase
----
+```
+/tlc:init            → Set up TLC, scan codebase
+/tlc:coverage        → Write tests for critical paths
+/tlc                 → Continue with test-first for new work
+```
-## Dashboard (Coming Soon)
+### After External Contributions
 ```
-┌─────────────────────────────────┬──────────────────────┐
-│ 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 ✓       │
-└─────────────────────────────────┴──────────────────────┘
+git pull             → Get latest changes
+/tlc                 → "Found 2 untested files. Add tests?"
+y                    → Tests written for new code
 ```
-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
+- Tests written BEFORE code (for new features)
+- Untested code gets flagged (for external contributions)
+- Coverage gaps get prioritized (for legacy code)
 - 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
@@ -159,11 +222,17 @@ npx tlc-claude-code
 ```
 Options:
-- `--global` — Available everywhere
+- `--global` — Available in all projects
 - `--local` — This project only
 ---
+## See Also
+**Using GSD?** Check out [TDD Workflow](https://github.com/jurgencalleja/tdd) — same philosophy, integrates with GSD.
+---
 ## License
 MIT

package/bin/install.js CHANGED Viewed

@@ -25,12 +25,13 @@ ${c.cyan}  ████████╗██╗     ██████╗
      ╚═╝   ╚══════╝ ╚═════╝${c.reset}
 `;
-const VERSION = '0.6.0';
+const VERSION = '0.6.1';
 const COMMANDS = [
   'tlc.md',
   'new-project.md',
   'init.md',
+  'import-project.md',
   'coverage.md',
   'discuss.md',
   'plan.md',

package/dashboard/package.json ADDED Viewed

@@ -0,0 +1,34 @@
+{
+  "name": "tdd-dashboard",
+  "version": "0.1.0",
+  "description": "TUI dashboard for TDD workflow",
+  "type": "module",
+  "bin": {
+    "tdd-dashboard": "./dist/index.js"
+  },
+  "scripts": {
+    "dev": "tsx src/index.tsx",
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "dockerode": "^4.0.2",
+    "ink": "^5.0.1",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
+    "react": "^18.3.1"
+  },
+  "devDependencies": {
+    "@types/dockerode": "^3.3.31",
+    "@types/node": "^22.10.0",
+    "@types/react": "^18.3.12",
+    "ink-testing-library": "^4.0.0",
+    "memfs": "^4.56.10",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  }
+}

package/help.md CHANGED Viewed

@@ -1,115 +1,99 @@
-# /tlc:help - Test-Led Development Commands
-## Quick Start
-```
-/tlc
-```
-That's it. Detects where you are, tells you what's next.
----
-## All Commands
-### The Smart One
-| Command | What It Does |
-|---------|--------------|
-| `/tlc` | **Context-aware entry point. Knows what to do next.** |
-### Setup
-| Command | What It Does |
-|---------|--------------|
-| `/tlc:new-project` | Start new project (discusses stack, creates roadmap) |
-| `/tlc:init` | Add TLC to existing code |
-| `/tlc:coverage` | Find untested code, write tests |
-### Build (rarely needed directly)
-| Command | What It Does |
-|---------|--------------|
-| `/tlc:discuss` | Shape implementation approach |
-| `/tlc:plan` | Create task plan |
-| `/tlc:build` | Write tests → implement → verify |
-| `/tlc:verify` | Human acceptance testing |
-### Utility
-| Command | What It Does |
-|---------|--------------|
-| `/tlc:status` | Test pass/fail counts |
-| `/tlc:quick` | One-off task with tests |
-| `/tlc:complete` | Tag release |
-| `/tlc:new-milestone` | Start next version |
----
-## Workflow
-**Simple version:**
-```
-/tlc                    <- just keep running this
-```
-**Detailed version:**
-```
-/tlc:new-project        New project
-    ↓
-/tlc                    Guides you through each phase:
-                        → discuss → plan → build → verify
-    ↓
-/tlc:complete           Tag release
-```
----
-## What `/tlc` Does
-Checks project state and presents ONE action:
-```
-> /tlc
-Phase 2: User Dashboard
-Status: Planned, not built
-4 tasks ready. Tests will be written first.
-→ Build phase 2? (Y/n)
-```
-Or if you have untested code:
-```
-> /tlc
-Found 3 files without tests:
-  - src/utils/format.ts
-  - src/api/health.ts
-  - src/middleware/auth.ts
-Add tests? (Y/n)
-```
----
-## Philosophy
-**Tests define behavior. Code makes tests pass.**
-- Tests written BEFORE code
-- Tests are the spec, not afterthought
-- Human verification still happens
-- No phase numbers to remember
----
-## Installation
-```bash
-npx tlc-claude-code
-```
-Lives in `.claude/commands/tlc/`
+# /tlc:help - Test-Led Development Commands
+## Quick Start
+```
+/tlc
+```
+Launches the visual dashboard. Detects where you are, shows what's next.
+---
+## All Commands
+### The Smart One
+| Command | What It Does |
+|---------|--------------|
+| `/tlc` | **Visual dashboard. Context-aware. Knows what to do next.** |
+### Setup
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:new-project` | Start new project (discusses stack, creates roadmap) |
+| `/tlc:init` | Add TLC to existing code |
+| `/tlc:import-project` | Import multi-repo microservices architecture |
+| `/tlc:coverage` | Find untested code, write tests |
+### Build (rarely needed directly)
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:discuss` | Shape implementation approach |
+| `/tlc:plan` | Create task plan |
+| `/tlc:build` | Write tests → implement → verify |
+| `/tlc:verify` | Human acceptance testing |
+### Utility
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:status` | Test pass/fail counts |
+| `/tlc:quick` | One-off task with tests |
+| `/tlc:complete` | Tag release |
+| `/tlc:new-milestone` | Start next version |
+---
+## Workflow
+**Simple version:**
+```
+/tlc                    <- just keep running this
+```
+**Detailed version:**
+```
+/tlc:new-project        New project
+    ↓
+/tlc                    Guides you through each phase:
+                        → discuss → plan → build → verify
+    ↓
+/tlc:complete           Tag release
+```
+---
+## What `/tlc` Does
+Launches a visual terminal dashboard showing:
+- Project overview and current phase
+- Test status (pass/fail counts)
+- Available actions
+Navigate with keyboard, select actions directly from the UI.
+Falls back to text mode if dashboard unavailable.
+---
+## Philosophy
+**Tests define behavior. Code makes tests pass.**
+- Tests written BEFORE code
+- Tests are the spec, not afterthought
+- Human verification still happens
+- No phase numbers to remember
+---
+## Installation
+```bash
+npx tlc-claude-code
+```
+Lives in `.claude/commands/tlc/`

package/import-project.md ADDED Viewed

@@ -0,0 +1,246 @@
+# /tlc:import-project - Import Multi-Repo Architecture
+Scan multiple GitHub repositories, analyze test coverage, create unified project view.
+## What This Does
+1. Clones private repos to temp directory (shallow clone)
+2. Detects stack & test framework per repo
+3. Runs coverage analysis per repo
+4. Generates unified coverage report
+5. Creates multi-service PROJECT.md
+6. Identifies critical untested paths across all services
+## When to Use
+- Inheriting a multi-repo microservices codebase
+- Verifying "coverage is good" claims
+- Managing multiple services as one TLC project
+- Onboarding to unfamiliar architecture
+## Prerequisites
+- GitHub CLI authenticated: `gh auth status`
+- Access to all repos: `gh repo list {org} --limit 100`
+## Process
+### Step 1: Gather Repos
+Ask user for repos. Accept:
+- GitHub org name (scan all repos)
+- Comma-separated repo URLs
+- Path to file with repo list
+```bash
+gh repo list {org} --json name,url --limit 100
+```
+### Step 2: Clone Each Repo (Shallow)
+For each repo:
+```bash
+gh repo clone {owner}/{repo} .tlc-scan/{repo} -- --depth=1
+```
+### Step 3: Detect Stack Per Repo
+Check for indicators:
+| File | Stack |
+|------|-------|
+| package.json | Node.js |
+| pyproject.toml | Python |
+| go.mod | Go |
+| Cargo.toml | Rust |
+Check for test framework:
+| Indicator | Framework |
+|-----------|-----------|
+| vitest.config.* | Vitest |
+| jest.config.* | Jest |
+| pytest.ini / [tool.pytest] | pytest |
+| *_test.go | go test |
+### Step 4: Run Coverage Per Repo
+Execute framework-specific coverage:
+- **Node.js (vitest):** `npm test -- --coverage --reporter=json`
+- **Node.js (jest):** `npm test -- --coverage --json`
+- **Python:** `pytest --cov --cov-report=json`
+- **Go:** `go test -coverprofile=coverage.out ./...`
+Parse coverage reports:
+- Node.js: `coverage/coverage-final.json`
+- Python: `coverage.json`
+- Go: parse `coverage.out`
+### Step 5: Identify Untested Critical Paths
+Scan for keywords indicating critical code:
+- **Auth:** login, logout, session, token, password, oauth, jwt
+- **Payments:** payment, billing, charge, stripe, invoice
+- **Data mutations:** create, update, delete, save
+- **Security:** validate, sanitize, permission, role
+Flag any file with these keywords that lacks corresponding test.
+### Step 6: Generate Unified Report
+Create `.planning/COVERAGE-REPORT.md`:
+```markdown
+# Coverage Report - Multi-Service Architecture
+Generated: {timestamp}
+## Summary
+| Metric | Value |
+|--------|-------|
+| Total Repos | 12 |
+| Avg Coverage | 67% |
+| Critical Gaps | 4 |
+## Per-Service Coverage
+| Service | Stack | Coverage | Tests | Critical Gaps |
+|---------|-------|----------|-------|---------------|
+| auth-service | Node.js | 87% | 45 | 0 |
+| payment-service | Node.js | 23% | 8 | 2 (charge, refund) |
+| user-service | Python | 91% | 112 | 0 |
+| notification-svc | Node.js | 0% | 0 | 1 (send) |
+## Critical Gaps (Priority Order)
+### 1. payment-service/src/charge.ts
+- Handles: Credit card charging
+- Risk: Money handling with no tests
+- Action: Write tests for charge flow
+### 2. payment-service/src/refund.ts
+- Handles: Refund processing
+- Risk: Money handling with no tests
+- Action: Write tests for refund flow
+...
+```
+### Step 7: Create Multi-Service PROJECT.md
+Create `.planning/PROJECT.md`:
+```markdown
+# {Project Name} - Multi-Service Architecture
+## Overview
+{Inferred from repo names and README files}
+## Services
+### auth-service
+- **Path:** github.com/{org}/auth-service
+- **Stack:** Node.js + Express
+- **Test Framework:** Vitest
+- **Coverage:** 87%
+- **Role:** Authentication & session management
+### payment-service
+- **Path:** github.com/{org}/payment-service
+- **Stack:** Node.js + Stripe
+- **Test Framework:** Jest
+- **Coverage:** 23%
+- **Role:** Payment processing
+...
+## Architecture
+```
+[API Gateway]
+    |-- [Auth Service] --> [User DB]
+    |-- [User Service] --> [User DB]
+    |-- [Payment Service] --> [Stripe API]
+    +-- [Notification Service] --> [Email/SMS]
+```
+## Development Methodology: Test-Led Development
+All services follow TLC. New code requires tests first.
+## Next Steps
+1. Fix critical coverage gaps (see COVERAGE-REPORT.md)
+2. Run `/tlc:coverage` per service for detailed backlog
+3. Use `/tlc` for new features
+```
+### Step 8: Create Test Backlog
+Create `.planning/BACKLOG.md`:
+```markdown
+# Test Backlog - Multi-Service
+## Critical (Security/Money)
+- [ ] payment-service: src/charge.ts
+- [ ] payment-service: src/refund.ts
+- [ ] auth-service: src/password-reset.ts (if untested)
+## High Priority (Core Business Logic)
+- [ ] user-service: src/registration.ts
+- [ ] order-service: src/checkout.ts
+## Standard
+- [ ] notification-svc: all files (0% coverage)
+```
+### Step 9: Cleanup
+Remove temp directory:
+```bash
+rm -rf .tlc-scan/
+```
+### Step 10: Report Summary
+```
+Import complete for {org}
+Repos scanned: 12
+Total coverage: 67% average
+Critical findings:
+  - payment-service: 23% coverage (handles money!)
+  - notification-svc: 0% coverage
+Files created:
+  .planning/PROJECT.md
+  .planning/COVERAGE-REPORT.md
+  .planning/BACKLOG.md
+Next: Run /tlc:build backlog to write tests for critical gaps
+```
+## Usage
+```bash
+# Scan entire GitHub org
+/tlc:import-project myorg
+# Scan specific repos
+/tlc:import-project myorg/auth-service,myorg/payment-service
+# Scan from file
+/tlc:import-project --file repos.txt
+```
+## Notes
+- Requires `gh` CLI authenticated with access to private repos
+- Shallow clones only (--depth=1) to minimize bandwidth
+- Temp files cleaned up after scan
+- Re-run anytime to update coverage report

package/package.json CHANGED Viewed

@@ -1,15 +1,22 @@
 {
   "name": "tlc-claude-code",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
-    "tlc-claude-code": "./bin/install.js"
+    "tlc-claude-code": "./bin/install.js",
+    "tlc-dashboard": "./dashboard/dist/index.js"
   },
   "files": [
     "bin/",
+    "dashboard/dist/",
+    "dashboard/package.json",
     "*.md",
     "install.sh"
   ],
+  "scripts": {
+    "build": "cd dashboard && npm run build",
+    "prepublishOnly": "npm run build"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/jurgencalleja/TLC.git"

package/tlc.md CHANGED Viewed

@@ -1,217 +1,197 @@
-# /tlc - Smart Entry Point
-One command. Context-aware. Tells you what to do next.
-## What This Does
-Detects project state and suggests the right action. No memorizing commands.
-## Process
-### Step 1: Detect Project State
-Check what exists:
-```
-□ PROJECT.md exists?
-□ .planning/ directory exists?
-□ .planning/ROADMAP.md exists?
-□ Test framework configured? (vitest.config.*, pytest.ini, etc.)
-□ Test files exist?
-□ Source files exist?
-```
-### Step 2: Route Based on State
-**No PROJECT.md → New or Init**
-```
-No project detected.
-1) Start new project (/tlc:new-project)
-2) Add TLC to existing code (/tlc:init)
-```
-**PROJECT.md exists, no roadmap → Need Planning**
-```
-Project exists but no roadmap.
-Let's break your project into phases.
-What's the first feature to build?
-```
-Then create ROADMAP.md with phases based on discussion.
-**Roadmap exists → Check Phase Status**
-Parse ROADMAP.md to find:
-- Completed phases: `[x]` or `[completed]`
-- Current phase: `[>]` or `[in progress]` or `[current]`
-- Next pending phase: first without marker
-### Step 3: Determine Current Phase Action
-For the current/next phase, check what exists:
-```
-Phase {N}: {Name}
-□ DISCUSSION.md exists? (.planning/phases/{N}-DISCUSSION.md)
-□ PLAN.md exists? (.planning/phases/{N}-*-PLAN.md)
-□ Tests written? (.planning/phases/{N}-TESTS.md or test files)
-□ Implementation done? (check if tests pass)
-□ Verified? (.planning/phases/{N}-VERIFIED.md)
-```
-### Step 4: Present Contextual Action
-Based on phase state, show ONE clear action:
-**Phase not discussed:**
-```
-Phase 2: User Dashboard
-Ready to discuss implementation approach.
-→ Continue? (Y/n)
-```
-Then run discuss flow.
-**Discussed but not planned:**
-```
-Phase 2: User Dashboard
-Discussion complete. Ready to create task plan.
-→ Continue? (Y/n)
-```
-Then run plan flow.
-**Planned but no tests:**
-```
-Phase 2: User Dashboard
-Plan ready. 4 tasks to implement.
-Next: Write tests, then build.
-→ Continue? (Y/n)
-```
-Then run build flow (tests first).
-**Tests written, not implemented:**
-```
-Phase 2: User Dashboard
-Tests ready (12 tests, all failing - expected).
-Next: Implement to make tests pass.
-→ Continue? (Y/n)
-```
-Then run implementation.
-**Implemented, not verified:**
-```
-Phase 2: User Dashboard
-Tests passing (12/12 ✓)
-Next: Human verification.
-→ Continue? (Y/n)
-```
-Then run verify flow.
-**Phase complete:**
-```
-Phase 2: User Dashboard ✓ Complete
-Moving to Phase 3: Reports
-→ Continue? (Y/n)
-```
-### Step 5: Check for Untested Code
-If project has source files without tests:
-```
-Found 5 files without tests:
-  - src/utils/helpers.ts
-  - src/api/users.ts
-  - src/services/email.ts
-  ...
-Add tests for existing code? (Y/n)
-```
-If yes, run `/tlc:coverage` flow.
-### Step 6: All Phases Complete
-```
-All phases complete! 🎉
-Milestone ready for release.
-1) Tag release (/tlc:complete)
-2) Start next milestone (/tlc:new-milestone)
-3) Check test coverage (/tlc:coverage)
-```
-## Examples
-**Fresh directory:**
-```
-> /tlc
-No project detected.
-What would you like to do?
-1) Start new project
-2) Add TLC to existing code
-```
-**Mid-project:**
-```
-> /tlc
-Phase 2: User Dashboard
-Status: Planned, not built
-4 tasks ready. Tests will be written first.
-→ Build phase 2? (Y/n)
-```
-**Has untested code:**
-```
-> /tlc
-Phase 3: Reports [current]
-Also found: 3 files without test coverage
-  - src/utils/format.ts
-  - src/api/health.ts
-  - src/middleware/auth.ts
-1) Continue with Phase 3
-2) Add tests to existing code first
-```
-## Usage
-```
-/tlc
-```
-No arguments. Auto-detects everything.
-## Why This Exists
-Instead of remembering:
-- `/tlc:discuss 2`
-- `/tlc:plan 2`
-- `/tlc:build 2`
-- `/tlc:verify 2`
-Just run `/tlc`. It knows where you are.
+# /tlc - Smart Entry Point
+One command. Context-aware. Visual dashboard.
+## What This Does
+Launches the TLC dashboard - a visual interface showing project state, phases, tests, and next actions.
+## Process
+### Step 1: Launch Dashboard
+Run the TLC dashboard:
+```bash
+# If in TLC repo (development)
+cd dashboard && npm run dev
+# If installed globally
+tlc-dashboard
+```
+The dashboard shows:
+- Project overview (from PROJECT.md)
+- Phase progress (from ROADMAP.md)
+- Test status (pass/fail counts)
+- Available actions
+### Step 2: Fallback to Text Mode
+If the dashboard cannot be launched (not installed, dependencies missing), fall back to text-based status:
+Check what exists:
+```
+□ PROJECT.md exists?
+□ .planning/ directory exists?
+□ .planning/ROADMAP.md exists?
+□ Test framework configured? (vitest.config.*, pytest.ini, etc.)
+□ Test files exist?
+□ Source files exist?
+```
+### Step 3: Route Based on State (Text Fallback)
+**No PROJECT.md → New or Init**
+```
+No project detected.
+1) Start new project (/tlc:new-project)
+2) Add TLC to existing code (/tlc:init)
+```
+**PROJECT.md exists, no roadmap → Need Planning**
+```
+Project exists but no roadmap.
+Let's break your project into phases.
+What's the first feature to build?
+```
+Then create ROADMAP.md with phases based on discussion.
+**Roadmap exists → Check Phase Status**
+Parse ROADMAP.md to find:
+- Completed phases: `[x]` or `[completed]`
+- Current phase: `[>]` or `[in progress]` or `[current]`
+- Next pending phase: first without marker
+### Step 4: Determine Current Phase Action
+For the current/next phase, check what exists:
+```
+Phase {N}: {Name}
+□ DISCUSSION.md exists? (.planning/phases/{N}-DISCUSSION.md)
+□ PLAN.md exists? (.planning/phases/{N}-*-PLAN.md)
+□ Tests written? (.planning/phases/{N}-TESTS.md or test files)
+□ Implementation done? (check if tests pass)
+□ Verified? (.planning/phases/{N}-VERIFIED.md)
+```
+### Step 5: Present Contextual Action
+Based on phase state, show ONE clear action:
+**Phase not discussed:**
+```
+Phase 2: User Dashboard
+Ready to discuss implementation approach.
+→ Continue? (Y/n)
+```
+Then run discuss flow.
+**Discussed but not planned:**
+```
+Phase 2: User Dashboard
+Discussion complete. Ready to create task plan.
+→ Continue? (Y/n)
+```
+Then run plan flow.
+**Planned but no tests:**
+```
+Phase 2: User Dashboard
+Plan ready. 4 tasks to implement.
+Next: Write tests, then build.
+→ Continue? (Y/n)
+```
+Then run build flow (tests first).
+**Tests written, not implemented:**
+```
+Phase 2: User Dashboard
+Tests ready (12 tests, all failing - expected).
+Next: Implement to make tests pass.
+→ Continue? (Y/n)
+```
+Then run implementation.
+**Implemented, not verified:**
+```
+Phase 2: User Dashboard
+Tests passing (12/12)
+Next: Human verification.
+→ Continue? (Y/n)
+```
+Then run verify flow.
+**Phase complete:**
+```
+Phase 2: User Dashboard - Complete
+Moving to Phase 3: Reports
+→ Continue? (Y/n)
+```
+### Step 6: Check for Untested Code
+If project has source files without tests:
+```
+Found 5 files without tests:
+  - src/utils/helpers.ts
+  - src/api/users.ts
+  - src/services/email.ts
+  ...
+Add tests for existing code? (Y/n)
+```
+If yes, run `/tlc:coverage` flow.
+### Step 7: All Phases Complete
+```
+All phases complete!
+Milestone ready for release.
+1) Tag release (/tlc:complete)
+2) Start next milestone (/tlc:new-milestone)
+3) Check test coverage (/tlc:coverage)
+```
+## Usage
+```
+/tlc
+```
+No arguments. Auto-detects everything. Launches dashboard when available.
+## Why This Exists
+Instead of remembering:
+- `/tlc:discuss 2`
+- `/tlc:plan 2`
+- `/tlc:build 2`
+- `/tlc:verify 2`
+Just run `/tlc`. It knows where you are.