tlc-claude-code 0.6.0

package/complete.md

@@ -0,0 +1,160 @@
+# /tlc:complete - Complete Milestone
+
+Archive current milestone and tag the release.
+
+## What This Does
+
+1. Verifies all phases complete
+2. Runs full test suite
+3. Creates git tag
+4. Archives milestone files
+5. Prepares for next version
+
+## Usage
+
+```
+/tlc:complete
+```
+
+## Process
+
+### Step 1: Check All Phases Complete
+
+Read `.planning/ROADMAP.md` and verify:
+- All phases marked `[x]` or `[completed]`
+- All phases have `{N}-VERIFIED.md`
+
+If incomplete:
+```
+Cannot complete milestone.
+
+Incomplete phases:
+  - Phase 4: Reports (not verified)
+  - Phase 5: Settings (not built)
+
+Run /tlc to continue building.
+```
+
+### Step 2: Run Full Test Suite
+
+```bash
+npm test
+```
+
+- ✅ All pass → Continue
+- ❌ Any fail → Block completion
+
+```
+Cannot complete milestone.
+
+3 tests failing:
+  - user.test.ts: login timeout
+  - api.test.ts: invalid response
+
+Fix tests before completing.
+```
+
+### Step 3: Confirm Completion
+
+```
+Milestone: v1.0
+
+Summary:
+  - 5 phases completed
+  - 47 tests passing
+  - All phases verified
+
+Ready to tag release? (Y/n)
+```
+
+### Step 4: Create Git Tag
+
+```bash
+git tag -a v1.0 -m "Release v1.0
+
+Phases:
+- Phase 1: Authentication
+- Phase 2: User Dashboard
+- Phase 3: Reports
+- Phase 4: Settings
+- Phase 5: Admin Panel
+
+Tests: 47 passing"
+```
+
+### Step 5: Archive Milestone
+
+Move planning files:
+```
+.planning/
+├── archive/
+│   └── v1.0/
+│       ├── ROADMAP.md
+│       ├── phases/
+│       │   ├── 1-PLAN.md
+│       │   ├── 1-VERIFIED.md
+│       │   └── ...
+│       └── SUMMARY.md
+└── (clean for next milestone)
+```
+
+Create `.planning/archive/v1.0/SUMMARY.md`:
+```markdown
+# v1.0 Release Summary
+
+Released: {date}
+Tag: v1.0
+
+## Phases
+
+1. Authentication - User login, registration, sessions
+2. User Dashboard - Main interface, data display
+3. Reports - Export, PDF generation
+4. Settings - User preferences
+5. Admin Panel - User management
+
+## Stats
+
+- Total tests: 47
+- Duration: {X days/weeks}
+- Commits: {N}
+
+## Notes
+
+{Any release notes}
+```
+
+### Step 6: Complete
+
+```
+✅ Milestone v1.0 complete!
+
+Tag created: v1.0
+Files archived to .planning/archive/v1.0/
+
+Next steps:
+1) Push tag: git push origin v1.0
+2) Start next version: /tlc:new-milestone v2.0
+```
+
+## Example
+
+```
+> /tlc:complete
+
+Checking milestone status...
+
+✅ All 5 phases verified
+✅ 47 tests passing
+
+Ready to complete v1.0? (Y/n) > y
+
+Creating tag v1.0...
+Archiving planning files...
+
+✅ Milestone v1.0 complete!
+
+Push to remote? (Y/n) > y
+
+Done! Start v2.0 with /tlc:new-milestone
+```

package/coverage.md

@@ -0,0 +1,222 @@
+# /tlc:coverage - Analyze Test Coverage Gaps
+
+Scan existing code, identify what's untested, and offer to write retrospective tests.
+
+## When to Use
+
+- After `/tlc:init` to add tests to existing code
+- Anytime you want to improve test coverage
+- When joining a project to understand test gaps
+- After "vibe coding" a feature without tests
+
+## Process
+
+### 1. Detect Test Framework
+
+Identify the test setup:
+- Framework: vitest, jest, pytest, go test, rspec, cargo test
+- Test directory: `tests/`, `__tests__/`, `spec/`, etc.
+- Test patterns: `*.test.ts`, `*_test.py`, etc.
+
+If no test framework found, suggest running `/tlc:init` first.
+
+### 2. Scan Source Files
+
+Identify all source files:
+- `src/**/*`, `lib/**/*`, `app/**/*`, `pkg/**/*`
+- Exclude: node_modules, vendor, dist, build, .git
+
+Categorize by type:
+- **API/Routes**: files handling HTTP endpoints
+- **Services**: business logic modules
+- **Components**: UI components (React, Vue, etc.)
+- **Utils**: helper functions
+- **Models**: data structures, schemas
+- **Config**: configuration files (skip testing)
+
+### 3. Match Tests to Source
+
+For each source file, look for corresponding test:
+- `src/auth/login.ts` → `tests/auth/login.test.ts` or `src/auth/login.test.ts`
+- `lib/utils.py` → `tests/test_utils.py` or `tests/utils_test.py`
+- `pkg/api/handler.go` → `pkg/api/handler_test.go`
+
+### 4. Identify Critical Paths
+
+Flag high-priority untested code:
+- **Auth**: login, logout, session, token, password, oauth
+- **Payments**: payment, billing, charge, subscription, stripe, checkout
+- **Data mutations**: create, update, delete, save, remove
+- **Security**: validate, sanitize, permission, role, access
+
+### 5. Present Coverage Analysis
+
+```
+Test Coverage Analysis
+
+Source files: 24
+Test files: 8
+Coverage: 33% (8/24 files have tests)
+
+Tested:
+  ✓ src/utils/format.ts (src/utils/format.test.ts)
+  ✓ src/api/health.ts (tests/api/health.test.ts)
+  ... [list all]
+
+Untested - Critical:
+  ✗ src/services/payment.ts - Stripe integration, checkout flow
+  ✗ src/api/auth.ts - login, session management
+  ✗ src/middleware/auth.ts - JWT validation
+
+Untested - High Priority:
+  ✗ src/api/users.ts - user CRUD operations
+  ✗ src/services/email.ts - transactional emails
+
+Untested - Standard:
+  ✗ src/utils/helpers.ts - utility functions
+  ✗ src/components/Header.tsx - navigation component
+  ... [list all]
+```
+
+### 6. Offer Retrospective Test Writing
+
+Ask the user:
+
+```
+Would you like to write tests for existing code?
+
+1) Yes - critical paths only (fastest)
+2) Yes - critical + high priority
+3) Yes - everything untested
+4) No - just wanted the report
+```
+
+**If tests requested:**
+
+Create `.planning/TEST-BACKLOG.md`:
+
+```markdown
+# Test Backlog
+
+Generated: [date]
+Coverage before: 33% (8/24)
+
+## Critical (auth, payments, security)
+- [ ] src/services/payment.ts - Stripe integration
+- [ ] src/api/auth.ts - login/logout flows
+- [ ] src/middleware/auth.ts - JWT validation
+
+## High Priority (data mutations, core logic)
+- [ ] src/api/users.ts - CRUD operations
+- [ ] src/services/email.ts - email sending
+
+## Standard (utils, components, helpers)
+- [ ] src/utils/helpers.ts
+- [ ] src/components/Header.tsx
+```
+
+Then ask:
+```
+Start writing tests now?
+
+1) Yes - begin with first critical item
+2) No - I'll run /tlc:build backlog later
+```
+
+**If "Yes":**
+
+Write tests one file at a time with verification and commits.
+
+#### For each file in the backlog (sequentially):
+
+**a) Plan tests for this file**
+
+Read the source file and create test plan:
+```markdown
+## File: src/services/payment.ts
+
+### Exports:
+- createCharge(amount, customerId)
+- refundCharge(chargeId)
+- getPaymentHistory(customerId)
+
+### Test cases:
+| Function | Test | Type |
+|----------|------|------|
+| createCharge | creates charge for valid customer | happy path |
+| createCharge | rejects negative amount | edge case |
+| createCharge | handles Stripe API error | error |
+| refundCharge | refunds existing charge | happy path |
+| refundCharge | fails for invalid chargeId | error |
+```
+
+**b) Write test file**
+
+Create tests that capture current behavior:
+```typescript
+import { describe, it, expect } from 'vitest'
+import { createCharge, refundCharge } from '../src/services/payment'
+
+describe('createCharge', () => {
+  it('creates charge for valid customer', async () => {
+    const result = await createCharge(1000, 'cust_123')
+    expect(result.id).toBeDefined()
+    expect(result.amount).toBe(1000)
+  })
+
+  it('rejects negative amount', async () => {
+    await expect(createCharge(-100, 'cust_123'))
+      .rejects.toThrow()
+  })
+})
+```
+
+**c) Run tests for this file**
+
+```bash
+npm test -- tests/services/payment.test.ts
+```
+
+Verify:
+- ✅ Tests PASS (code already exists)
+- ❌ If tests fail, investigate — either test is wrong or found a bug
+
+**d) Commit this test file**
+
+```bash
+git add tests/services/payment.test.ts
+git commit -m "test: add payment service tests"
+```
+
+**e) Update backlog**
+
+Mark item complete in `.planning/TEST-BACKLOG.md`:
+```markdown
+- [x] src/services/payment.ts - payment processing logic ✅
+```
+
+**f) Move to next file**
+
+Repeat a-e for each file in the backlog.
+
+### 7. Report Summary
+
+```
+Coverage analysis complete.
+
+Before: 33% (8/24 files)
+Backlog created: .planning/TEST-BACKLOG.md
+  - Critical: 3 files
+  - High priority: 2 files
+  - Standard: 11 files
+
+Run /tlc:build backlog to start writing tests.
+```
+
+## Usage
+
+```
+/tlc:coverage
+```
+
+No arguments needed. Scans entire codebase.

package/discuss.md

@@ -0,0 +1,185 @@
+# /tlc:discuss - Discuss Phase Implementation
+
+Capture implementation preferences before planning.
+
+## What This Does
+
+Gathers your preferences for HOW a phase should be built through adaptive questioning. Saves decisions to guide planning and test writing.
+
+## Usage
+
+```
+/tlc:discuss [phase_number]
+```
+
+If no phase number, auto-detect current phase from ROADMAP.md.
+
+## Process
+
+### Step 1: Load Phase Context
+
+Read from `.planning/ROADMAP.md` to get:
+- Phase name and goal
+- What comes before (context)
+- What comes after (constraints)
+
+### Step 2: Adaptive Questioning
+
+Ask about implementation preferences. Adapt questions based on phase type.
+
+**For UI/Frontend phases:**
+```
+Layout approach?
+1) Component library (shadcn, MUI, etc.)
+2) Custom components
+3) Minimal styling (Tailwind only)
+
+State management?
+1) React state + context
+2) Zustand / Jotai
+3) Redux
+4) Server state only (React Query)
+
+Form handling?
+1) React Hook Form
+2) Formik
+3) Native forms
+```
+
+**For API/Backend phases:**
+```
+API style?
+1) REST
+2) tRPC
+3) GraphQL
+
+Validation approach?
+1) Zod schemas
+2) Yup
+3) Manual validation
+
+Error handling?
+1) Return error objects
+2) Throw exceptions
+3) Result types (Ok/Err)
+```
+
+**For Data/Database phases:**
+```
+Query approach?
+1) Raw SQL
+2) Query builder (Kysely, Knex)
+3) ORM (Prisma, Drizzle)
+
+Migration strategy?
+1) Schema-first (Prisma migrate)
+2) Code-first
+3) Manual SQL migrations
+```
+
+**For Auth phases:**
+```
+Auth provider?
+1) Custom (JWT + bcrypt)
+2) NextAuth / Auth.js
+3) Clerk / Auth0 / Supabase Auth
+
+Session storage?
+1) JWT in httpOnly cookie
+2) Database sessions
+3) Redis sessions
+```
+
+### Step 3: Capture Edge Cases
+
+```
+What edge cases should we handle?
+
+- Empty states?
+- Error states?
+- Loading states?
+- Offline behavior?
+- Rate limiting?
+```
+
+### Step 4: Capture Constraints
+
+```
+Any constraints or requirements?
+
+- Performance targets?
+- Accessibility requirements?
+- Browser support?
+- Mobile considerations?
+```
+
+### Step 5: Save Discussion
+
+Create `.planning/phases/{N}-DISCUSSION.md`:
+
+```markdown
+# Phase {N}: {Name} - Discussion
+
+## Implementation Preferences
+
+| Decision | Choice | Notes |
+|----------|--------|-------|
+| State management | Zustand | Simple, minimal boilerplate |
+| Form handling | React Hook Form | Good validation support |
+| API style | tRPC | Type-safe, good DX |
+
+## Edge Cases to Handle
+
+- [ ] Empty state when no data
+- [ ] Error toast on API failure
+- [ ] Optimistic updates for better UX
+
+## Constraints
+
+- Must work on mobile
+- Target 100ms API response time
+
+## Notes
+
+[Any additional context from discussion]
+```
+
+### Step 6: Confirm and Continue
+
+```
+Discussion saved to .planning/phases/{N}-DISCUSSION.md
+
+Ready to plan this phase?
+1) Yes, continue to /tlc:plan
+2) No, I'll plan later
+```
+
+## Example
+
+```
+> /tlc:discuss 2
+
+Phase 2: User Dashboard
+
+Let's discuss how to build this.
+
+State management approach?
+1) React state + context
+2) Zustand
+3) Server state only (React Query)
+
+> 3
+
+Data fetching?
+1) REST + fetch
+2) tRPC
+3) React Query + REST
+
+> 2
+
+[...continues until preferences captured...]
+
+Discussion saved.
+
+Ready to plan? (Y/n)
+```

package/help.md

@@ -0,0 +1,115 @@
+# /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/`