tlc-claude-code 0.6.0

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "tlc-claude-code",
+  "version": "0.6.0",
+  "description": "TLC - Test Led Coding for Claude Code",
+  "bin": {
+    "tlc-claude-code": "./bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "*.md",
+    "install.sh"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jurgencalleja/TLC.git"
+  },
+  "keywords": [
+    "claude",
+    "claude-code",
+    "tlc",
+    "test-led-coding",
+    "tdd",
+    "testing"
+  ],
+  "author": "Jurgen Calleja",
+  "license": "MIT"
+}

package/plan.md

@@ -0,0 +1,210 @@
+# /tlc:plan - Plan a Phase
+
+Research and create implementation plans with clear tasks.
+
+## What This Does
+
+1. Researches how to implement the phase
+2. Breaks work into discrete tasks
+3. Creates PLAN.md with actionable steps
+4. Prepares for test writing
+
+## Usage
+
+```
+/tlc:plan [phase_number]
+```
+
+If no phase number, auto-detect current phase from ROADMAP.md.
+
+## Process
+
+### Step 1: Load Context
+
+Read:
+- `.planning/ROADMAP.md` - phase goal
+- `.planning/phases/{N}-DISCUSSION.md` - implementation preferences
+- `PROJECT.md` - tech stack, constraints
+
+### Step 2: Research (if needed)
+
+For phases requiring external knowledge:
+- Look up library documentation
+- Check best practices
+- Identify patterns
+
+Create `.planning/phases/{N}-RESEARCH.md` with findings.
+
+### Step 3: Break Into Tasks
+
+Each task should be:
+- **Small** - completable in one focused session
+- **Testable** - has clear pass/fail criteria
+- **Independent** - minimal dependencies on other tasks
+
+```markdown
+## Task 1: Create user schema
+
+**Goal:** Define database schema for users table
+
+**Files:**
+- src/db/schema/users.ts
+
+**Acceptance Criteria:**
+- [ ] Schema has id, email, passwordHash, createdAt
+- [ ] Email is unique
+- [ ] Timestamps auto-populate
+
+**Test Cases:**
+- Schema validates correct user data
+- Schema rejects duplicate emails
+- Schema rejects missing required fields
+```
+
+### Step 4: Create Plan File
+
+Create `.planning/phases/{N}-PLAN.md`:
+
+```markdown
+# Phase {N}: {Name} - Plan
+
+## Overview
+
+{Brief description of what this phase delivers}
+
+## Prerequisites
+
+- [ ] {Any setup or prior work needed}
+
+## Tasks
+
+### Task 1: {Title}
+
+**Goal:** {What this accomplishes}
+
+**Files:**
+- {files to create/modify}
+
+**Acceptance Criteria:**
+- [ ] {Testable criterion 1}
+- [ ] {Testable criterion 2}
+
+**Test Cases:**
+- {Test description 1}
+- {Test description 2}
+
+---
+
+### Task 2: {Title}
+
+...
+
+## Dependencies
+
+{Task dependencies if any - e.g., Task 3 requires Task 1}
+
+## Estimated Scope
+
+- Tasks: {N}
+- Files: {N}
+- Tests: ~{N} (estimated)
+```
+
+### Step 5: Review Plan
+
+Present plan summary:
+
+```
+Phase 2: User Dashboard - Plan
+
+Tasks: 4
+1. Create dashboard layout component
+2. Implement data fetching hook
+3. Build stat cards
+4. Add loading/error states
+
+Estimated tests: 12
+
+Proceed with this plan? (Y/n)
+```
+
+Allow refinement if needed.
+
+### Step 6: Save and Continue
+
+```
+Plan saved to .planning/phases/{N}-PLAN.md
+
+Ready to build?
+1) Yes, run /tlc:build (writes tests first)
+2) No, I'll build later
+```
+
+## Task Guidelines
+
+**Good tasks:**
+```
+Task: Create login API endpoint
+- POST /api/auth/login
+- Validates email/password
+- Returns JWT token
+- Handles invalid credentials
+```
+
+**Bad tasks:**
+```
+Task: Build auth system  <- too big
+Task: Add login          <- too vague
+```
+
+## Example Output
+
+```markdown
+# Phase 1: Authentication - Plan
+
+## Overview
+
+User registration and login with JWT tokens.
+
+## Tasks
+
+### Task 1: Create user schema
+
+**Goal:** Database schema for users
+
+**Files:**
+- src/db/schema/users.ts
+- src/db/migrations/001_users.sql
+
+**Acceptance Criteria:**
+- [ ] Has id, email, passwordHash, createdAt, updatedAt
+- [ ] Email unique constraint
+- [ ] Password hashed with bcrypt
+
+**Test Cases:**
+- Schema accepts valid user data
+- Schema rejects duplicate email
+- Password is hashed, not plain text
+
+---
+
+### Task 2: Registration endpoint
+
+**Goal:** POST /api/auth/register
+
+**Files:**
+- src/api/auth/register.ts
+- src/lib/auth/password.ts
+
+**Acceptance Criteria:**
+- [ ] Creates user with hashed password
+- [ ] Returns user without password
+- [ ] Rejects existing email with 409
+- [ ] Validates email format
+
+**Test Cases:**
+- Register with valid data returns user
+- Register with existing email returns 409
+- Register with invalid email returns 400
+- Password stored as hash
+```

package/progress.md

@@ -0,0 +1,136 @@
+# /tlc:progress - Where Am I?
+
+Show current project state and what to do next.
+
+## What This Does
+
+Scans project state and presents:
+1. Current milestone and phase
+2. What's done, what's next
+3. Test status
+4. Suggested action
+
+## Usage
+
+```
+/tlc:progress
+```
+
+## Process
+
+### Step 1: Check Project Exists
+
+Look for:
+- `PROJECT.md` - project exists
+- `.planning/ROADMAP.md` - has roadmap
+
+If neither exists:
+```
+No project found.
+
+Run /tlc:new-project to start, or /tlc:init to add TLC to existing code.
+```
+
+### Step 2: Parse Roadmap
+
+Read `.planning/ROADMAP.md` and identify:
+- Total phases
+- Completed phases (marked `[x]` or `[completed]`)
+- Current phase (marked `[>]` or `[current]`)
+- Pending phases
+
+### Step 3: Check Current Phase State
+
+For the current/next phase, check what exists:
+
+| File | Meaning |
+|------|---------|
+| `{N}-DISCUSSION.md` | Discussed |
+| `{N}-PLAN.md` | Planned |
+| `{N}-TESTS.md` | Tests written |
+| `{N}-VERIFIED.md` | Human verified |
+
+### Step 4: Run Tests
+
+Execute test suite and capture:
+- Total tests
+- Passing
+- Failing
+- Skipped
+
+### Step 5: Present Status
+
+```
+Project: My App
+Milestone: v1.0
+
+Progress: ████████░░░░ 3/5 phases
+
+Completed:
+  ✓ Phase 1: Project Setup
+  ✓ Phase 2: Authentication
+  ✓ Phase 3: User Dashboard
+
+Current:
+  → Phase 4: Reports (planned, not built)
+
+Pending:
+  ○ Phase 5: Settings
+
+Tests: 47 total | 45 passing | 2 failing
+
+Suggested: /tlc:build 4
+```
+
+### Step 6: Suggest Next Action
+
+Based on state:
+
+| State | Suggestion |
+|-------|------------|
+| No discussion | `/tlc:discuss {N}` |
+| Discussed, no plan | `/tlc:plan {N}` |
+| Planned, no tests | `/tlc:build {N}` |
+| Tests failing | Fix failures, then `/tlc:build {N}` |
+| Tests passing, not verified | `/tlc:verify {N}` |
+| Verified | Move to next phase |
+| All phases done | `/tlc:complete` |
+
+Or just:
+```
+Run /tlc to continue.
+```
+
+## Example Output
+
+```
+> /tlc:progress
+
+╭─────────────────────────────────────╮
+│ My App - v1.0                       │
+╰─────────────────────────────────────╯
+
+Phases: ████████░░░░ 3/5 complete
+
+  ✓ 1. Project Setup
+  ✓ 2. Authentication
+  ✓ 3. User Dashboard
+  → 4. Reports (ready to build)
+  ○ 5. Settings
+
+Tests: 47 passing | 2 failing
+
+Next: /tlc:build 4 (or just /tlc)
+```
+
+## Compact Mode
+
+For quick checks:
+```
+> /tlc:progress
+
+Phase 4/5: Reports
+Status: Planned
+Tests: 47/49 passing
+Next: /tlc:build
+```

package/quick.md

@@ -0,0 +1,52 @@
+# /tlc:quick - Quick Task with Tests
+
+For ad-hoc tasks that don't need full phase planning, but still deserve tests.
+
+## What This Does
+
+1. **Ask what you want to do**
+2. **Write a failing test** for it
+3. **Implement** to pass the test
+4. **Verify** test passes
+
+Lighter weight than `/tlc:build`, but still test-first.
+
+## Usage
+
+```
+/tlc:quick
+```
+
+## Example
+
+```
+User: /tlc:quick
+
+Claude: What do you want to do?
+
+User: Add a dark mode toggle to settings
+
+Claude: Writing test...
+
+Created: tests/settings/dark-mode.test.ts
+- toggles dark mode on click
+- persists preference to localStorage
+- applies dark class to document
+
+Running test... ❌ Failing (expected)
+
+Implementing...
+
+Running test... ✅ Passing
+
+Done. Dark mode toggle added with test coverage.
+```
+
+## When to Use
+
+- Bug fixes
+- Small features
+- Config changes
+- One-off tasks
+
+For anything bigger, use the full flow: `/tlc:plan` → `/tlc:build` → `/tlc:verify`

package/status.md

@@ -0,0 +1,65 @@
+# /tlc:status - Check Test Status
+
+Quick check on test status for current or specified phase.
+
+## Usage
+
+```
+/tlc:status [phase_number]
+```
+
+If no phase specified, shows overall test status.
+
+## Process
+
+1. **Detect test framework** (Vitest, Jest, pytest, etc.)
+2. **Run the test suite**
+3. **Report results** with next action
+
+## Output Examples
+
+**All tests passing:**
+```
+Test Status
+───────────
+✅ 18 passing, 0 failing, 0 errors
+
+Ready for: /tlc:verify
+```
+
+**Some failing:**
+```
+Test Status
+───────────
+🔄 12 passing, 6 failing, 0 errors
+
+Failing:
+• tests/auth.test.ts: login rejects invalid password
+• tests/auth.test.ts: login returns httpOnly cookie
+• tests/session.test.ts: session expires after timeout
+...
+
+Action: Fix implementation or run /tlc:build to retry
+```
+
+**Tests erroring:**
+```
+Test Status
+───────────
+⚠️ 10 passing, 0 failing, 3 errors
+
+Errors:
+• tests/auth.test.ts:45 - Cannot find module '../src/auth'
+• tests/session.test.ts:12 - TypeError: x is not a function
+
+Action: Fix test errors before continuing
+```
+
+**No tests found:**
+```
+Test Status
+───────────
+No tests found.
+
+Run /tlc:build to write tests and implement.
+```

package/tlc.md

@@ -0,0 +1,217 @@
+# /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.