tlc-claude-code 0.6.4 → 0.7.1

package/CLAUDE.md

@@ -0,0 +1,59 @@
+# CLAUDE.md - TLC Project Instructions
+
+## Planning System: TLC
+
+This project uses **TLC (Test-Led Coding)** for all planning and development.
+
+**DO NOT use Claude's internal task tools** (TaskCreate, TaskUpdate, TaskList) for project planning.
+
+Instead, use TLC's file-based system:
+
+| Purpose | TLC Location |
+|---------|--------------|
+| Project overview | `PROJECT.md` |
+| Roadmap & phases | `.planning/ROADMAP.md` |
+| Phase plans | `.planning/phases/{N}-PLAN.md` |
+| Task status | Markers in PLAN.md: `[ ]`, `[>@user]`, `[x@user]` |
+| Bugs/feedback | `.planning/BUGS.md` |
+| Test status | `.planning/phases/{N}-TESTS.md` |
+| Config | `.tlc.json` |
+
+## Before Starting Work
+
+Always run `/tlc:progress` or `/tlc` to understand current state.
+
+## Workflow Commands
+
+| Action | Command |
+|--------|---------|
+| See status | `/tlc` or `/tlc:progress` |
+| Plan a phase | `/tlc:plan` |
+| Build (test-first) | `/tlc:build` |
+| Verify with human | `/tlc:verify` |
+| Log a bug | `/tlc:bug` |
+| Claim a task | `/tlc:claim` |
+| Release a task | `/tlc:release` |
+| See team status | `/tlc:who` |
+
+## Test-First Development
+
+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.
+
+## After TLC Updates
+
+If TLC command files are updated, re-read them before executing. Check version in `package.json`.
+
+## Multi-User Collaboration
+
+When working with teammates:
+- Claim tasks before starting: `/tlc:claim`
+- Release if blocked: `/tlc:release`
+- Check team status: `/tlc:who`
+- Pull before claiming: `git pull`
+- Push after claiming: `git push`

package/README.md

@@ -1,6 +1,10 @@
 # TLC
 
-**Test Led Coding. Tests before code. Automatically.**
+[![npm version](https://img.shields.io/npm/v/tlc-claude-code.svg)](https://www.npmjs.com/package/tlc-claude-code)
+[![npm downloads](https://img.shields.io/npm/dm/tlc-claude-code.svg)](https://www.npmjs.com/package/tlc-claude-code)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+
+**Test Led Coding for Claude Code. Tests before code. Automatically.**
 
 ```bash
 npx tlc-claude-code
@@ -12,227 +16,266 @@ npx tlc-claude-code
 
 ---
 
-## The Problem
+## Why TLC?
 
 You tell Claude to build something. It builds it. You test it manually. It's broken. You debug. Repeat.
 
 **That's backwards.**
 
-## The Solution
-
 TLC writes tests *before* code exists. Every feature has a spec. Every spec is executable. When the code works, you know — because the tests pass.
 
 ```
-You describe → Tests are written → Code is implemented → Tests pass → Done
+You describe → Tests written → Code implemented → Tests pass → Done
 ```
 
 No manual testing. No "does this work?" No vibes.
 
 ---
 
-## Getting Started
+## Quick Start
 
 ### New Project
 
-Starting from scratch? TLC guides you through everything.
-
-```
+```bash
 /tlc:new-project
 ```
 
-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.
-
-```
+```bash
 /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
+### Then Just Run
 
-Once initialized, just run:
-
-```
+```bash
 /tlc
 ```
 
-TLC knows where you are and what's next. No phase numbers to remember.
+TLC knows where you are and what's next.
 
 ---
 
-## Handling Untested Code
+## Features
 
-Code comes from many sources. Not all of it has tests.
+### For Solo Developers
 
-### External PRs / Other Developers
+- **Test-first by default** — Claude writes tests before code
+- **Smart dashboard** — See progress, run actions
+- **Coverage gaps** — Find and fix untested code
+- **Auto-fix** — Automatically repair failing tests
 
-Someone pushes code without tests? TLC catches it.
+### For Teams
 
-```
-> /tlc
+- **Task claiming** — Prevent duplicate work across engineers
+- **Bug tracking** — QA submits bugs, engineers fix them
+- **Dev server** — Mini-Replit with live preview and logs
+- **Issue sync** — GitHub, Jira, Linear integration
 
-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)
+> **📄 [Team Workflow Guide](docs/team-workflow.md)** — How 3 engineers + PO + QA collaborate with TLC
 
-Add tests now? (Y/n)
-```
+### For Enterprise
 
-TLC tracks what's tested. When new untested code appears, it flags it.
+- **CI/CD pipelines** — GitHub Actions, GitLab, Azure, CircleCI
+- **VPS deployment** — Branch previews with auth & Slack webhooks
+- **Multi-tool export** — Works with Cursor, Copilot, Continue, Cody
 
-### After "Vibe Coding" Sessions
+---
 
-Built something fast without tests? No judgment. Run:
+## Commands
 
-```
-/tlc:coverage
-```
+| Command | What It Does |
+|---------|--------------|
+| `/tlc` | **Smart entry point — knows what's next** |
+| `/tlc:new-project` | Start new project with roadmap |
+| `/tlc:init` | Add TLC to existing codebase |
+| `/tlc:build` | Write tests → implement → verify |
+| `/tlc:coverage` | Find and fix untested code |
+| `/tlc:quality` | Test quality scoring |
+| `/tlc:autofix` | Auto-repair failing tests |
 
-TLC scans everything, creates a prioritized backlog:
+### Team Commands
 
-```
-Coverage: 67% (24/36 files)
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:claim` | Reserve a task |
+| `/tlc:who` | See who's working on what |
+| `/tlc:bug` | Log a bug |
+| `/tlc:server` | Start dev server with dashboard |
 
-Critical (no tests):
-  - src/auth/session.ts      ← security
-  - src/payments/charge.ts   ← money
+### Integration Commands
 
-High priority:
-  - src/api/users.ts
-  - src/api/orders.ts
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:ci` | Generate CI/CD pipeline |
+| `/tlc:issues` | Sync with GitHub/Jira/Linear |
+| `/tlc:export` | Export for Cursor/Copilot/etc |
+| `/tlc:deploy` | VPS deployment |
 
-Add to backlog and start? (Y/n)
-```
+[**See all commands →**](help.md)
 
-### Continuous Coverage
+---
 
-TLC integrates with your workflow:
+## Team Collaboration
 
-- **Before builds** — `/tlc:status` shows pass/fail counts
-- **Before releases** — `/tlc:coverage` ensures nothing slipped through
-- **Daily habit** — `/tlc` reminds you of untested code
+TLC supports distributed teams with git-based coordination.
 
----
+```markdown
+### Task 1: Create schema [x@alice]     ← completed by alice
+### Task 2: Add validation [>@bob]      ← bob is working
+### Task 3: Write tests [ ]             ← available
+```
 
-## Commands
+```bash
+/tlc:claim 2        # Reserve task 2
+/tlc:who            # See team status
+/tlc:server         # Start dashboard for QA
+```
 
-| Command | What |
-|---------|------|
-| `/tlc` | **Smart entry point. Knows what's next.** |
-| `/tlc:new-project` | Start fresh. Discuss stack, scaffold. |
-| `/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. |
+**📄 [Full Team Workflow Guide →](docs/team-workflow.md)**
 
 ---
 
-## What Makes This Different
-
-### 1. Tests First, Always
+## Dev Server
 
-Other workflows: plan → build → "hope it works"
+Launch a mini-Replit for your team:
 
-TLC: plan → **write failing tests** → build until tests pass
+```bash
+/tlc:server
+```
 
-The tests *are* the spec. No ambiguity.
+```
+Dashboard: http://localhost:3147
+Share:     http://192.168.1.x:3147
+```
 
-### 2. Catches Coverage Gaps
+- **Live preview** — Your app embedded in dashboard
+- **Real-time logs** — App, tests, git activity
+- **Bug submission** — Web form for QA
+- **Task board** — Who's working on what
 
-New code without tests? TLC notices. External PRs? Flagged. Post-hackathon cleanup? Prioritized backlog ready.
+---
 
-### 3. Smart Stack Selection
+## Test Quality
 
-Don't pick tech in a vacuum. TLC asks what you're building, who uses it, what scale — then suggests the right stack.
+### Quality Scoring
 
+```bash
+/tlc:quality
 ```
-Building: Internal dashboard
-Scale: Small team
-Data: Simple CRUD
 
-→ Suggested: Next.js + SQLite + Vercel
-→ Why: Fast to build, cheap to host, fits your needs
+- Coverage (lines, branches, functions)
+- Edge case detection
+- Mutation testing score
+
+### Edge Case Generation
+
+```bash
+/tlc:edge-cases src/auth/login.ts
 ```
 
-### 4. Works With Your Team
+AI-generated tests for null, boundaries, unicode, security.
+
+### Auto-Fix
+
+```bash
+/tlc:autofix
+```
 
-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
+Automatically repair failing tests with retry loop.
 
 ---
 
-## Workflow Examples
+## Test Framework
 
-### Solo Developer, New Project
+TLC defaults to **mocha + chai + sinon + proxyquire**.
 
-```
-/tlc:new-project     → Discuss requirements, choose stack
-/tlc                 → Build phase 1 (tests first)
-/tlc                 → Build phase 2 (tests first)
-...
-/tlc:complete        → Tag release
+Configure in `.tlc.json`:
+
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "chai", "sinon", "proxyquire"],
+    "run": ["mocha"]
+  }
+}
 ```
 
-### Team Project, Existing Codebase
+Also supports Jest, Vitest, and others via `/tlc:config`.
 
-```
-/tlc:init            → Set up TLC, scan codebase
-/tlc:coverage        → Write tests for critical paths
-/tlc                 → Continue with test-first for new work
-```
+---
 
-### After External Contributions
+## Architecture
 
 ```
-git pull             → Get latest changes
-/tlc                 → "Found 2 untested files. Add tests?"
-y                    → Tests written for new code
+PROJECT.md                    Project overview
+.planning/
+  ROADMAP.md                  Phases and progress
+  BUGS.md                     Bug tracker
+  phases/
+    1-PLAN.md                 Phase 1 tasks
+    2-PLAN.md                 Phase 2 tasks
+.tlc.json                     Configuration
 ```
 
 ---
 
-## Philosophy
+## Works With
 
-**Tests define behavior. Code makes tests pass.**
-
-- 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"
+| Tool | Support |
+|------|---------|
+| **Claude Code** | Native (slash commands) |
+| **Cursor** | Via `/tlc:export` → `.cursorrules` |
+| **GitHub Copilot** | Via `/tlc:export` → `.github/copilot-instructions.md` |
+| **Continue** | Via `/tlc:export` → `.continue/config.json` |
+| **Cody** | Via `/tlc:export` → `.cody/instructions.md` |
+| **Aider** | Via `/tlc:export` → `.aider.conf.yml` |
 
 ---
 
 ## Install
 
 ```bash
+# Interactive (choose global or local)
 npx tlc-claude-code
+
+# Global (all projects)
+npx tlc-claude-code --global
+
+# Local (this project only)
+npx tlc-claude-code --local
 ```
 
-Options:
-- `--global` — Available in all projects
-- `--local` — This project only
+Commands install to `.claude/commands/tlc/`
 
 ---
 
-## See Also
+## Documentation
 
-**Using GSD?** Check out [TDD Workflow](https://github.com/jurgencalleja/tdd) — same philosophy, integrates with GSD.
+- **[Help / All Commands](help.md)** — Complete command reference
+- **[Team Workflow](docs/team-workflow.md)** — Guide for teams (engineers + PO + QA)
+- **[Server Spec](server.md)** — Dev server documentation
+
+---
+
+## Philosophy
+
+**Tests define behavior. Code makes tests pass.**
+
+- Tests written BEFORE code
+- Untested code gets flagged
+- Coverage gaps get prioritized
+- Human verification still happens
 
 ---
 
 ## License
 
 MIT
+
+---
+
+<p align="center">
+  <sub>Built for <a href="https://claude.ai/code">Claude Code</a></sub>
+</p>