tlc-claude-code 0.6.4 → 0.7.0

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

@@ -70,107 +70,224 @@ TLC knows where you are and what's next. No phase numbers to remember.
 
 ---
 
-## Handling Untested Code
+## Team Collaboration
 
-Code comes from many sources. Not all of it has tests.
+TLC supports distributed teams with built-in coordination.
 
-### External PRs / Other Developers
+### Task Claiming
 
-Someone pushes code without tests? TLC catches it.
+Prevent duplicate work when multiple engineers use Claude Code:
 
+```bash
+/tlc:claim 2        # Reserve task 2
+/tlc:release 2      # Release if blocked
+/tlc:who            # See who's working on what
 ```
-> /tlc
 
-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)
+Task status tracked in PLAN.md:
+```markdown
+### Task 1: Create schema [x@alice]     ← completed by alice
+### Task 2: Add validation [>@bob]      ← bob is working
+### Task 3: Write tests [ ]             ← available
+```
 
-Add tests now? (Y/n)
+### Bug Tracking
+
+QA and engineers can log bugs via CLI or web UI:
+
+```bash
+/tlc:bug "Login fails with + symbol in email"
 ```
 
-TLC tracks what's tested. When new untested code appears, it flags it.
+Bugs tracked in `.planning/BUGS.md`, committed to git.
 
-### After "Vibe Coding" Sessions
+### Dev Server
 
-Built something fast without tests? No judgment. Run:
+Launch a mini-Replit experience for your team:
 
+```bash
+/tlc:server
 ```
-/tlc:coverage
-```
 
-TLC scans everything, creates a prioritized backlog:
+- **Live preview** — Your app embedded in dashboard
+- **Real-time logs** — App output, test results, git activity
+- **Bug submission** — Web form with screenshot capture
+- **Task board** — Who's working on what
+
+Share URL with QA/PO: `http://192.168.1.x:3147`
 
+---
+
+## Test Quality
+
+### Quality Scoring
+
+Measure and improve test quality:
+
+```bash
+/tlc:quality
 ```
-Coverage: 67% (24/36 files)
 
-Critical (no tests):
-  - src/auth/session.ts      ← security
-  - src/payments/charge.ts   ← money
+- Coverage percentage (lines, branches, functions)
+- Edge case detection (null, empty, boundaries)
+- Mutation testing score
+- Prioritized recommendations
+
+### Edge Case Generation
 
-High priority:
-  - src/api/users.ts
-  - src/api/orders.ts
+AI-generated edge case tests:
 
-Add to backlog and start? (Y/n)
+```bash
+/tlc:edge-cases src/auth/login.ts
 ```
 
-### Continuous Coverage
+Generates tests for null inputs, boundaries, unicode, security patterns.
+
+### Auto-Fix
 
-TLC integrates with your workflow:
+Automatic repair of failing tests:
 
-- **Before builds** — `/tlc:status` shows pass/fail counts
-- **Before releases** — `/tlc:coverage` ensures nothing slipped through
-- **Daily habit** — `/tlc` reminds you of untested code
+```bash
+/tlc:autofix
+```
+
+- Analyzes failure reason
+- Attempts fix with reasoning
+- Retries up to max attempts
+- Reports what it couldn't fix
 
 ---
 
 ## Commands
 
+### Core
+
 | 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:discuss` | Shape implementation approach. |
+| `/tlc:plan` | Create task plan. |
+| `/tlc:build` | Write tests → implement → verify. |
+| `/tlc:verify` | Human acceptance testing. |
+
+### Quality & Testing
+
+| Command | What |
+|---------|------|
 | `/tlc:status` | Test pass/fail counts. |
+| `/tlc:coverage` | Find untested code, write tests. |
+| `/tlc:quality` | Test quality scoring and analysis. |
+| `/tlc:edge-cases` | Generate edge case tests. |
+| `/tlc:autofix` | Auto-fix failing tests. |
+| `/tlc:config` | Configure test frameworks. |
+
+### Team Collaboration
+
+| Command | What |
+|---------|------|
+| `/tlc:claim` | Reserve a task. |
+| `/tlc:release` | Release a claimed task. |
+| `/tlc:who` | See who's working on what. |
+| `/tlc:bug` | Log a bug or feedback. |
+| `/tlc:server` | Start dev server with dashboard. |
+
+### CI/CD & Integration
+
+| Command | What |
+|---------|------|
+| `/tlc:ci` | Generate CI/CD pipelines (GitHub Actions, GitLab, etc.) |
+| `/tlc:issues` | Sync with issue trackers (GitHub, Jira, Linear). |
+| `/tlc:docs` | Generate API docs, architecture, onboarding guides. |
+
+### Multi-Tool & Deployment
+
+| Command | What |
+|---------|------|
+| `/tlc:export` | Export rules for Cursor, Copilot, Continue, Cody. |
+| `/tlc:deploy` | VPS deployment with branch previews. |
+
+### Utility
+
+| Command | What |
+|---------|------|
 | `/tlc:quick` | One-off task with tests. |
+| `/tlc:complete` | Tag release. |
+| `/tlc:new-milestone` | Start next version. |
+| `/tlc:progress` | Check current state. |
 
 ---
 
-## What Makes This Different
+## Test Framework
+
+TLC defaults to the **mocha ecosystem**:
+
+| Library | Purpose |
+|---------|---------|
+| mocha | Test runner |
+| chai | Assertions |
+| sinon | Mocks/stubs/spies |
+| proxyquire | Module mocking |
+
+### Configuration
+
+Configure frameworks in `.tlc.json`:
+
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "chai", "sinon", "proxyquire"],
+    "run": ["mocha"]
+  }
+}
+```
 
-### 1. Tests First, Always
+### Multi-Framework Support
 
-Other workflows: plan → build → "hope it works"
+Projects can have multiple test frameworks:
 
-TLC: plan → **write failing tests** → build until tests pass
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "jest"],
+    "run": ["mocha", "jest"]
+  }
+}
+```
 
-The tests *are* the spec. No ambiguity.
+Use `/tlc:config` to manage frameworks.
 
-### 2. Catches Coverage Gaps
+---
 
-New code without tests? TLC notices. External PRs? Flagged. Post-hackathon cleanup? Prioritized backlog ready.
+## Handling Untested Code
 
-### 3. Smart Stack Selection
+### External PRs / Other Developers
 
-Don't pick tech in a vacuum. TLC asks what you're building, who uses it, what scale — then suggests the right stack.
+Someone pushes code without tests? TLC catches it.
 
 ```
-Building: Internal dashboard
-Scale: Small team
-Data: Simple CRUD
+> /tlc
 
-→ Suggested: Next.js + SQLite + Vercel
-→ Why: Fast to build, cheap to host, fits your needs
+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)
+
+Add tests now? (Y/n)
 ```
 
-### 4. Works With Your Team
+### After "Vibe Coding" Sessions
+
+Built something fast without tests? No judgment. Run:
+
+```
+/tlc:coverage
+```
 
-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
+TLC scans everything, creates a prioritized backlog.
 
 ---
 
@@ -186,21 +303,86 @@ TLC doesn't require everyone to use it. You can:
 /tlc:complete        → Tag release
 ```
 
-### Team Project, Existing Codebase
+### Team Project
 
 ```
-/tlc:init            → Set up TLC, scan codebase
-/tlc:coverage        → Write tests for critical paths
-/tlc                 → Continue with test-first for new work
+/tlc:server          → Start dev server
+/tlc:claim 1         → Claim task 1
+/tlc:build           → Build with tests
+git push             → Share progress
+/tlc:release         → Release when done
 ```
 
-### After External Contributions
+### QA Workflow
 
+1. Open dashboard: `http://192.168.1.x:3147`
+2. Test features in live preview
+3. Submit bugs via web form
+4. Verify fixes when ready
+
+---
+
+## Architecture
+
+### Planning Files
+
+| File | Purpose |
+|------|---------|
+| `PROJECT.md` | Project overview, tech stack |
+| `.planning/ROADMAP.md` | Phases and progress |
+| `.planning/phases/{N}-PLAN.md` | Task plans |
+| `.planning/BUGS.md` | Bug tracker |
+| `.tlc.json` | TLC configuration |
+| `CLAUDE.md` | Instructions for Claude |
+
+### Task Status Markers
+
+```markdown
+### Task 1: Create schema [ ]           ← available
+### Task 2: Add validation [>@alice]    ← claimed by alice
+### Task 3: Write tests [x@bob]         ← completed by bob
 ```
-git pull             → Get latest changes
-/tlc                 → "Found 2 untested files. Add tests?"
-y                    → Tests written for new code
-```
+
+---
+
+## Agents
+
+TLC uses specialized AI agents for different tasks. Most are invoked automatically.
+
+### Research Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `tlc-competitor-analyst` | Competitive analysis |
+| `tlc-market-researcher` | Market landscape |
+| `tlc-tech-researcher` | Framework evaluation |
+| `tlc-security-researcher` | Security best practices |
+
+### Build Agents
+
+| Agent | Purpose |
+|-------|---------|
+| `tlc-planner` | Create test-first plans |
+| `tlc-executor` | Execute Red → Green → Refactor |
+| `tlc-coverage-analyzer` | Find untested code |
+| `tlc-verifier` | Verify phase completion |
+
+---
+
+## Roadmap
+
+TLC v1.0 - Team Collaboration Release:
+
+- [x] **Phase 1:** Core Infrastructure (multi-user, bug tracking, server spec)
+- [x] **Phase 2:** Test Quality & Auto-Fix
+- [x] **Phase 3:** TLC Dev Server (mini-Replit)
+- [x] **Phase 4:** CI/CD Integration
+- [x] **Phase 5:** Issue Tracker Integration
+- [x] **Phase 6:** Team Documentation
+- [x] **Phase 7:** Multi-Tool Support (Cursor, Copilot, Continue, Cody)
+- [x] **Phase 8:** VPS Deployment Server (with auth & Slack webhooks)
+
+All command specs implemented. Server code in `server/` directory.
 
 ---
 
@@ -227,12 +409,6 @@ Options:
 
 ---
 
-## See Also
-
-**Using GSD?** Check out [TDD Workflow](https://github.com/jurgencalleja/tdd) — same philosophy, integrates with GSD.
-
----
-
 ## License
 
 MIT