tlc-claude-code 0.6.1 → 0.6.2

package/PROJECT.md

@@ -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

@@ -227,6 +227,12 @@ Options:
 
 ---
 
+## See Also
+
+**Using GSD?** Check out [TDD Workflow](https://github.com/jurgencalleja/tdd) — same philosophy, integrates with GSD.
+
+---
+
 ## License
 
 MIT

package/bin/install.js

@@ -31,6 +31,7 @@ const COMMANDS = [
   'tlc.md',
   'new-project.md',
   'init.md',
+  'import-project.md',
   'coverage.md',
   'discuss.md',
   'plan.md',

package/dashboard/package.json

@@ -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

@@ -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

@@ -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

@@ -1,15 +1,22 @@
 {
   "name": "tlc-claude-code",
-  "version": "0.6.1",
+  "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

@@ -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.