tlc-claude-code 0.6.0

package/init.md

@@ -0,0 +1,219 @@
+# /tlc:init - Initialize TLC in Existing Project
+
+Add TLC workflow to an existing codebase. Analyzes what you have, identifies gaps, and offers to write tests for existing code.
+
+## When to Use
+
+- You have existing code without tests
+- You have existing code with some tests
+- You're joining a project mid-development
+- You want to adopt TLC on a "vibe coded" project
+
+This command will:
+1. Set up test infrastructure (if missing)
+2. **Analyze your existing code** to understand what it does
+3. **Identify untested modules** and critical paths
+4. **Ask if you want retrospective tests** written for existing code
+
+For brand new projects with no code, use `/tlc:new-project` instead.
+
+## Process
+
+### 1. Scan for Existing Code
+
+Check for source files:
+- `src/`, `lib/`, `app/`, `pkg/`, or root-level code files
+- `package.json`, `pyproject.toml`, `go.mod`, `Gemfile`, `Cargo.toml`
+
+If no code found, suggest running `/tlc:new-project` instead.
+
+### 2. Detect Stack
+
+| Indicator | Stack |
+|-----------|-------|
+| `package.json` + React/Next deps | Next.js / React |
+| `package.json` (no framework) | Node.js |
+| `pyproject.toml` / `requirements.txt` | Python |
+| `go.mod` | Go |
+| `Gemfile` | Ruby |
+| `Cargo.toml` | Rust |
+
+### 3. Scan for Existing Tests
+
+Look for test indicators:
+
+**Directories:**
+- `tests/`, `test/`, `__tests__/`, `spec/`
+
+**Files:**
+- `*_test.py`, `test_*.py`
+- `*.test.ts`, `*.test.js`, `*.spec.ts`, `*.spec.js`
+- `*_test.go`
+- `*_spec.rb`
+
+**Config files:**
+- `vitest.config.*`, `jest.config.*`, `pytest.ini`, `pyproject.toml` [tool.pytest]
+- `.rspec`, `spec/spec_helper.rb`
+
+### 4. Set Up Test Framework (if missing)
+
+If no tests found, set up based on detected stack:
+
+| Stack | Framework | Setup |
+|-------|-----------|-------|
+| Next.js / React | Vitest | `npm install -D vitest @testing-library/react` |
+| Node.js | Vitest | `npm install -D vitest` |
+| Python | pytest | `pip install pytest` or add to pyproject.toml |
+| Go | go test | Built-in, no setup needed |
+| Ruby | RSpec | `gem install rspec && rspec --init` |
+| Rust | cargo test | Built-in, no setup needed |
+
+Create config file and test directory structure.
+
+Add test scripts to package.json / pyproject.toml / Makefile:
+```json
+"scripts": {
+  "test": "vitest run",
+  "test:watch": "vitest"
+}
+```
+
+### 5. If Tests Already Exist
+
+- Skip framework setup
+- Note existing test patterns for consistency
+- Report: "Found existing test framework: [vitest/jest/pytest/etc]"
+- Report: "Found X existing test files"
+
+### 6. Analyze Existing Code Structure
+
+Scan the codebase and generate summary:
+- Main directories and their purpose
+- Key modules/components identified
+- Entry points (main files, API routes, etc.)
+- Dependencies and their roles
+
+### 7. Identify Untested Code
+
+Compare source files against test files to identify:
+- Modules/components with no corresponding tests
+- Key functions that lack test coverage
+- Critical paths (auth, payments, data mutations) without tests
+
+Present findings:
+```
+Code Coverage Analysis:
+
+Tested:
+  ✓ src/auth/login.ts (tests/auth/login.test.ts)
+  ✓ src/utils/format.ts (tests/utils/format.test.ts)
+
+Untested:
+  ✗ src/api/users.ts - CRUD operations, no tests
+  ✗ src/services/payment.ts - payment processing, no tests
+  ✗ src/components/Dashboard.tsx - main UI, no tests
+
+Critical paths without tests: 2 (auth, payments)
+```
+
+### 8. Offer Retrospective Test Writing
+
+Ask the user:
+
+```
+Would you like to write tests for existing code?
+
+1) Yes - prioritize critical paths first
+2) Yes - write tests for everything
+3) No - only use TLC for new features going forward
+```
+
+**If option 1 or 2 selected:**
+
+Create `.planning/BACKLOG.md` with test tasks:
+
+```markdown
+# Test Backlog
+
+## Critical (write first)
+- [ ] src/services/payment.ts - payment processing logic
+- [ ] src/api/auth.ts - authentication flows
+
+## High Priority
+- [ ] src/api/users.ts - user CRUD operations
+- [ ] src/middleware/validation.ts - input validation
+
+## Standard
+- [ ] src/utils/helpers.ts - utility functions
+- [ ] src/components/Dashboard.tsx - dashboard rendering
+```
+
+Then ask:
+```
+Start writing tests now, or save backlog for later?
+
+1) Start now - begin with critical paths
+2) Later - I'll run /tlc:build backlog when ready
+```
+
+**If "Start now":** Begin writing tests for the first critical path item using Red-Green-Refactor (but code already exists, so focus on capturing current behavior).
+
+### 9. Create or Update PROJECT.md
+
+If PROJECT.md doesn't exist, create it with:
+
+```markdown
+# [Project Name]
+
+## Overview
+[Inferred from code structure and README if present]
+
+## Tech Stack
+- [Detected stack]
+- [Key dependencies]
+
+## Project Structure
+[Generated from scan]
+
+## 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: [detected or installed]
+- Run tests: `[test command]`
+- Test directory: `[path]`
+```
+
+If PROJECT.md exists, append the TLC section only.
+
+### 10. Report Summary
+
+```
+TLC initialized for [project name]
+
+Stack: [detected]
+Test framework: [framework] (existing/newly configured)
+Test directory: [path]
+Existing tests: [count] files
+Untested files: [count] identified
+
+Next steps:
+- Run /tlc:build backlog to write tests for existing code
+- Run /tlc:discuss to plan new features with TLC
+- Run /tlc:quick for ad-hoc tasks with tests
+```
+
+## Usage
+
+```
+/tlc:init
+```
+
+No arguments needed. Auto-detects everything.

package/install.sh

@@ -0,0 +1,65 @@
+#!/bin/bash
+# Install TLC - Test Led Coding for Claude Code
+# Usage: ./install.sh [--global | --local]
+
+set -e
+
+# Determine install location
+if [[ "$1" == "--global" || "$1" == "-g" ]]; then
+    INSTALL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/tlc"
+    echo "Installing globally to $INSTALL_DIR"
+elif [[ "$1" == "--local" || "$1" == "-l" ]]; then
+    INSTALL_DIR="./.claude/commands/tlc"
+    echo "Installing locally to $INSTALL_DIR"
+else
+    echo "TLC - Test Led Coding Installer"
+    echo ""
+    echo "Where would you like to install?"
+    echo "  1) Global (~/.claude/commands/tlc) - available in all projects"
+    echo "  2) Local (./.claude/commands/tlc) - this project only"
+    echo ""
+    read -p "Choice [1/2]: " choice
+
+    if [[ "$choice" == "2" ]]; then
+        INSTALL_DIR="./.claude/commands/tlc"
+    else
+        INSTALL_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}/commands/tlc"
+    fi
+fi
+
+# Create directory
+mkdir -p "$INSTALL_DIR"
+
+# Get script directory
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Copy command files
+cp "$SCRIPT_DIR/tlc.md" "$INSTALL_DIR/" 2>/dev/null || true
+cp "$SCRIPT_DIR/new-project.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/init.md" "$INSTALL_DIR/" 2>/dev/null || true
+cp "$SCRIPT_DIR/coverage.md" "$INSTALL_DIR/" 2>/dev/null || true
+cp "$SCRIPT_DIR/discuss.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/plan.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/build.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/verify.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/status.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/progress.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/complete.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/new-milestone.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/quick.md" "$INSTALL_DIR/"
+cp "$SCRIPT_DIR/help.md" "$INSTALL_DIR/"
+
+echo ""
+echo "TLC commands installed to $INSTALL_DIR"
+echo ""
+echo "Restart Claude Code to load new commands."
+echo ""
+echo "Quick Start:"
+echo "  /tlc              Smart entry point - knows what to do next"
+echo ""
+echo "Or use specific commands:"
+echo "  /tlc:new-project  Start new project"
+echo "  /tlc:init         Add TLC to existing code"
+echo "  /tlc:coverage     Find and fix test gaps"
+echo ""
+echo "Run /tlc:help for full command list."

package/new-milestone.md

@@ -0,0 +1,172 @@
+# /tlc:new-milestone - Start Next Version
+
+Begin the next milestone after completing the previous one.
+
+## What This Does
+
+1. Gathers requirements for next version
+2. Creates new roadmap with phases
+3. Prepares for development
+
+## Usage
+
+```
+/tlc:new-milestone [name]
+```
+
+Example:
+```
+/tlc:new-milestone v2.0
+```
+
+## Process
+
+### Step 1: Check Previous Milestone
+
+Verify previous milestone is complete:
+- All phases verified
+- Git tag exists
+- Files archived
+
+If not complete:
+```
+Previous milestone not complete.
+
+Run /tlc:complete first.
+```
+
+### Step 2: Name the Milestone
+
+If not provided:
+```
+What's the next version?
+
+1) v2.0 (major - breaking changes)
+2) v1.1 (minor - new features)
+3) v1.0.1 (patch - bug fixes)
+4) Custom name
+
+>
+```
+
+### Step 3: Gather Requirements
+
+```
+What's new in {version}?
+
+Describe the main goals for this milestone:
+>
+```
+
+Follow-up questions:
+```
+Any specific features planned?
+-
+-
+-
+
+Breaking changes from v1.0?
+
+Target timeline?
+```
+
+### Step 4: Create Roadmap
+
+Based on requirements, create phases:
+
+```
+Milestone: v2.0
+
+Proposed phases:
+
+1. API v2 - New endpoint structure
+2. Dashboard Redesign - Updated UI
+3. Team Features - Multi-user support
+4. Performance - Caching, optimization
+
+Look good? (Y/n/adjust)
+```
+
+### Step 5: Save Roadmap
+
+Create `.planning/ROADMAP.md`:
+
+```markdown
+# Roadmap - v2.0
+
+## Overview
+
+{Description of milestone goals}
+
+## Phases
+
+### Phase 1: API v2
+Restructure API endpoints for v2 compatibility.
+
+### Phase 2: Dashboard Redesign
+Update UI with new design system.
+
+### Phase 3: Team Features
+Add multi-user support and permissions.
+
+### Phase 4: Performance
+Implement caching and optimize queries.
+
+## Timeline
+
+Target: {date}
+
+## Notes
+
+{Any constraints or considerations}
+```
+
+### Step 6: Update PROJECT.md
+
+Add new milestone section:
+```markdown
+## Current Milestone: v2.0
+
+Goal: {description}
+
+Phases: 4
+Status: Not started
+```
+
+### Step 7: Ready to Build
+
+```
+✅ Milestone v2.0 created!
+
+Roadmap: .planning/ROADMAP.md
+Phases: 4
+
+Start with /tlc to begin Phase 1.
+```
+
+## Example
+
+```
+> /tlc:new-milestone
+
+Previous milestone v1.0 complete ✓
+
+Version name? > v2.0
+
+What's new in v2.0?
+> Adding team features and redesigning the dashboard
+
+Breaking changes? > API endpoints will change
+
+Proposed phases:
+1. API v2 - New structure
+2. Dashboard Redesign
+3. Team Features
+4. Migration Tools
+
+Proceed? (Y/n) > y
+
+✅ v2.0 roadmap created!
+
+Run /tlc to start Phase 1.
+```

package/new-project.md

@@ -0,0 +1,259 @@
+# /tlc:new-project - Start a New Project
+
+Initialize a new project with test-led development.
+
+## What This Does
+
+1. Gather requirements and context
+2. Suggest tech stack based on your needs
+3. Create roadmap
+4. Set up test infrastructure
+
+## Process
+
+### Step 1: Understand What You're Building
+
+Start by understanding the project:
+
+**Core purpose:**
+```
+What are you building? (1-2 sentences)
+```
+
+**Target users:**
+```
+Who uses this?
+
+1) Just me / internal tool
+2) Small team (<10 users)
+3) Startup scale (100-10K users)
+4) Growth stage (10K-100K users)
+5) Enterprise / high scale (100K+ users)
+```
+
+**Data characteristics:**
+```
+What kind of data?
+
+1) Simple CRUD - users, posts, etc.
+2) Relational - complex relationships, joins
+3) Document-oriented - flexible schemas
+4) Time-series - logs, metrics, events
+5) Graph - relationships are the data
+6) Minimal / stateless
+```
+
+**Real-time requirements:**
+```
+Do you need real-time features?
+
+1) No - standard request/response
+2) Some - notifications, live updates
+3) Heavy - chat, collaboration, streaming
+```
+
+**Existing constraints:**
+```
+Any constraints I should know?
+
+- Team experience (what languages/tools do you know?)
+- Existing infrastructure (AWS, GCP, on-prem?)
+- Budget considerations
+- Compliance requirements (HIPAA, SOC2, etc.)
+- Timeline pressure
+```
+
+### Step 2: Suggest Tech Stack
+
+Based on answers, suggest appropriate stack:
+
+**Example: Internal tool, small team, simple CRUD**
+```
+Suggested Stack:
+
+| Component | Recommendation | Why |
+|-----------|----------------|-----|
+| Language | TypeScript | Type safety, good tooling |
+| Framework | Next.js | Full-stack, fast to build |
+| Database | SQLite or Postgres | Simple, reliable |
+| Architecture | Monolith | No need for complexity |
+| Hosting | Vercel or Railway | Easy deploy, free tier |
+
+Alternatives to consider:
+- Python + FastAPI if more comfortable with Python
+- Supabase if you want auth + DB bundled
+```
+
+**Example: Growth stage SaaS, real-time, complex data**
+```
+Suggested Stack:
+
+| Component | Recommendation | Why |
+|-----------|----------------|-----|
+| Language | TypeScript | Type safety at scale |
+| Framework | Next.js + tRPC | Type-safe API layer |
+| Database | PostgreSQL | Reliable, scalable |
+| Cache | Redis | Sessions, real-time |
+| Architecture | Modular monolith | Scale when needed |
+| Hosting | Docker + K8s ready | Portable, scalable |
+
+Alternatives to consider:
+- Go if performance is critical
+- Microservices if team is large enough
+```
+
+**Example: High-performance API, minimal latency**
+```
+Suggested Stack:
+
+| Component | Recommendation | Why |
+|-----------|----------------|-----|
+| Language | Go or Rust | Performance, efficiency |
+| Framework | stdlib or Axum | Minimal overhead |
+| Database | PostgreSQL + Redis | Speed + reliability |
+| Architecture | Microservices | Scale independently |
+| Hosting | Kubernetes | Production-grade |
+```
+
+### Step 3: Confirm or Adjust
+
+```
+Does this stack work for you?
+
+1) Yes, proceed with this
+2) I'd prefer [language] instead
+3) Let's discuss alternatives
+```
+
+Allow user to override any decision with rationale captured.
+
+### Step 4: Record Decisions
+
+Create PROJECT.md with tech decisions:
+
+```markdown
+# Project Name
+
+## Overview
+[From step 1 discussion]
+
+## Tech Stack
+
+| Decision | Choice | Rationale |
+|----------|--------|-----------|
+| Language | TypeScript | Team familiarity |
+| Framework | Next.js | Full-stack, good DX |
+| Database | PostgreSQL | Relational data needs |
+| Architecture | Modular monolith | Start simple |
+| Hosting | Docker + Railway | Easy CI/CD |
+
+## Constraints
+- Timeline: MVP in 4 weeks
+- Team: Solo developer
+- Budget: Minimal hosting costs
+```
+
+### Step 5: Create Roadmap
+
+Based on the project scope, break into phases:
+
+**Phase breakdown approach:**
+- Each phase = one coherent feature or component
+- Phase should be completable in focused work
+- Phase has clear "done" criteria
+
+**Example phases for a SaaS app:**
+```
+Phase 1: Project Setup
+  - Initialize repo, dependencies
+  - Set up test framework
+  - Create base configuration
+
+Phase 2: Authentication
+  - User registration
+  - Login/logout
+  - Session management
+
+Phase 3: Core Feature
+  - Main functionality
+  - Data models
+  - API endpoints
+
+Phase 4: User Dashboard
+  - UI components
+  - Data display
+  - User settings
+```
+
+Create `.planning/ROADMAP.md`:
+
+```markdown
+# Roadmap - v1.0
+
+## Overview
+{From project discussion}
+
+## Phases
+
+### Phase 1: Project Setup
+Initialize project with chosen stack and test infrastructure.
+
+### Phase 2: Authentication
+User registration, login, and session management.
+
+### Phase 3: {Core Feature}
+{Description based on project goals}
+
+### Phase 4: {Next Feature}
+{Description}
+
+## Milestone
+Target: v1.0 MVP
+```
+
+### Step 6: Append TLC Conventions
+
+```markdown
+## Development Methodology: Test-Led Development
+
+This project uses TLC. All 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 based on stack]
+- Run: `npm test` / `pytest` / `go test`
+```
+
+### Step 7: Set Up Project Structure
+
+Scaffold based on chosen stack:
+
+```
+project/
+├── src/
+├── tests/
+├── .env.example
+├── docker-compose.yml
+├── Dockerfile
+├── [package.json | pyproject.toml | go.mod]
+├── [vitest.config.ts | pytest.ini]
+└── PROJECT.md
+```
+
+## Usage
+
+```
+/tlc:new-project
+```
+
+Interactive flow that:
+1. Understands what you're building
+2. Suggests appropriate tech
+3. Lets you adjust
+4. Creates roadmap
+5. Sets up tests