tlc-claude-code 1.5.3 → 1.5.4

package/.claude/commands/tlc/import-project.md

@@ -0,0 +1,246 @@
+# /tlc:import-project - Import Multi-Repo Architecture
+
+Scan multiple GitHub repositories, analyze test coverage, create unified project view.
+
+## What This Does
+
+1. Clones private repos to temp directory (shallow clone)
+2. Detects stack & test framework per repo
+3. Runs coverage analysis per repo
+4. Generates unified coverage report
+5. Creates multi-service PROJECT.md
+6. Identifies critical untested paths across all services
+
+## When to Use
+
+- Inheriting a multi-repo microservices codebase
+- Verifying "coverage is good" claims
+- Managing multiple services as one TLC project
+- Onboarding to unfamiliar architecture
+
+## Prerequisites
+
+- GitHub CLI authenticated: `gh auth status`
+- Access to all repos: `gh repo list {org} --limit 100`
+
+## Process
+
+### Step 1: Gather Repos
+
+Ask user for repos. Accept:
+- GitHub org name (scan all repos)
+- Comma-separated repo URLs
+- Path to file with repo list
+
+```bash
+gh repo list {org} --json name,url --limit 100
+```
+
+### Step 2: Clone Each Repo (Shallow)
+
+For each repo:
+```bash
+gh repo clone {owner}/{repo} .tlc-scan/{repo} -- --depth=1
+```
+
+### Step 3: Detect Stack Per Repo
+
+Check for indicators:
+| File | Stack |
+|------|-------|
+| package.json | Node.js |
+| pyproject.toml | Python |
+| go.mod | Go |
+| Cargo.toml | Rust |
+
+Check for test framework:
+| Indicator | Framework |
+|-----------|-----------|
+| vitest.config.* | Vitest |
+| jest.config.* | Jest |
+| pytest.ini / [tool.pytest] | pytest |
+| *_test.go | go test |
+
+### Step 4: Run Coverage Per Repo
+
+Execute framework-specific coverage:
+- **Node.js (vitest):** `npm test -- --coverage --reporter=json`
+- **Node.js (jest):** `npm test -- --coverage --json`
+- **Python:** `pytest --cov --cov-report=json`
+- **Go:** `go test -coverprofile=coverage.out ./...`
+
+Parse coverage reports:
+- Node.js: `coverage/coverage-final.json`
+- Python: `coverage.json`
+- Go: parse `coverage.out`
+
+### Step 5: Identify Untested Critical Paths
+
+Scan for keywords indicating critical code:
+- **Auth:** login, logout, session, token, password, oauth, jwt
+- **Payments:** payment, billing, charge, stripe, invoice
+- **Data mutations:** create, update, delete, save
+- **Security:** validate, sanitize, permission, role
+
+Flag any file with these keywords that lacks corresponding test.
+
+### Step 6: Generate Unified Report
+
+Create `.planning/COVERAGE-REPORT.md`:
+
+```markdown
+# Coverage Report - Multi-Service Architecture
+
+Generated: {timestamp}
+
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Repos | 12 |
+| Avg Coverage | 67% |
+| Critical Gaps | 4 |
+
+## Per-Service Coverage
+
+| Service | Stack | Coverage | Tests | Critical Gaps |
+|---------|-------|----------|-------|---------------|
+| auth-service | Node.js | 87% | 45 | 0 |
+| payment-service | Node.js | 23% | 8 | 2 (charge, refund) |
+| user-service | Python | 91% | 112 | 0 |
+| notification-svc | Node.js | 0% | 0 | 1 (send) |
+
+## Critical Gaps (Priority Order)
+
+### 1. payment-service/src/charge.ts
+- Handles: Credit card charging
+- Risk: Money handling with no tests
+- Action: Write tests for charge flow
+
+### 2. payment-service/src/refund.ts
+- Handles: Refund processing
+- Risk: Money handling with no tests
+- Action: Write tests for refund flow
+
+...
+```
+
+### Step 7: Create Multi-Service PROJECT.md
+
+Create `.planning/PROJECT.md`:
+
+```markdown
+# {Project Name} - Multi-Service Architecture
+
+## Overview
+
+{Inferred from repo names and README files}
+
+## Services
+
+### auth-service
+- **Path:** github.com/{org}/auth-service
+- **Stack:** Node.js + Express
+- **Test Framework:** Vitest
+- **Coverage:** 87%
+- **Role:** Authentication & session management
+
+### payment-service
+- **Path:** github.com/{org}/payment-service
+- **Stack:** Node.js + Stripe
+- **Test Framework:** Jest
+- **Coverage:** 23%
+- **Role:** Payment processing
+
+...
+
+## Architecture
+
+```
+[API Gateway]
+    |-- [Auth Service] --> [User DB]
+    |-- [User Service] --> [User DB]
+    |-- [Payment Service] --> [Stripe API]
+    +-- [Notification Service] --> [Email/SMS]
+```
+
+## Development Methodology: Test-Led Development
+
+All services follow TLC. New code requires tests first.
+
+## Next Steps
+
+1. Fix critical coverage gaps (see COVERAGE-REPORT.md)
+2. Run `/tlc:coverage` per service for detailed backlog
+3. Use `/tlc` for new features
+```
+
+### Step 8: Create Test Backlog
+
+Create `.planning/BACKLOG.md`:
+
+```markdown
+# Test Backlog - Multi-Service
+
+## Critical (Security/Money)
+
+- [ ] payment-service: src/charge.ts
+- [ ] payment-service: src/refund.ts
+- [ ] auth-service: src/password-reset.ts (if untested)
+
+## High Priority (Core Business Logic)
+
+- [ ] user-service: src/registration.ts
+- [ ] order-service: src/checkout.ts
+
+## Standard
+
+- [ ] notification-svc: all files (0% coverage)
+```
+
+### Step 9: Cleanup
+
+Remove temp directory:
+```bash
+rm -rf .tlc-scan/
+```
+
+### Step 10: Report Summary
+
+```
+Import complete for {org}
+
+Repos scanned: 12
+Total coverage: 67% average
+
+Critical findings:
+  - payment-service: 23% coverage (handles money!)
+  - notification-svc: 0% coverage
+
+Files created:
+  .planning/PROJECT.md
+  .planning/COVERAGE-REPORT.md
+  .planning/BACKLOG.md
+
+Next: Run /tlc:build backlog to write tests for critical gaps
+```
+
+## Usage
+
+```bash
+# Scan entire GitHub org
+/tlc:import-project myorg
+
+# Scan specific repos
+/tlc:import-project myorg/auth-service,myorg/payment-service
+
+# Scan from file
+/tlc:import-project --file repos.txt
+```
+
+## Notes
+
+- Requires `gh` CLI authenticated with access to private repos
+- Shallow clones only (--depth=1) to minimize bandwidth
+- Temp files cleaned up after scan
+- Re-run anytime to update coverage report

package/.claude/commands/tlc/init.md

@@ -0,0 +1,443 @@
+# /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. TLC defaults to mocha for JavaScript/TypeScript:
+
+| Stack | Framework | Setup |
+|-------|-----------|-------|
+| Next.js / React / Node.js | Mocha + Chai + Sinon | `npm install -D mocha chai sinon proxyquire` |
+| 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.
+
+For JavaScript/TypeScript, create `.mocharc.json`:
+```json
+{
+  "extension": ["js", "ts"],
+  "spec": "test/**/*.test.{js,ts}",
+  "require": ["ts-node/register"],
+  "timeout": 5000
+}
+```
+
+Create `.tlc.json`:
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "chai", "sinon", "proxyquire"],
+    "run": ["mocha"]
+  },
+  "testCommand": "npm test",
+  "testDirectory": "test"
+}
+```
+
+Add test scripts to package.json:
+```json
+"scripts": {
+  "test": "mocha",
+  "test:watch": "mocha --watch"
+}
+```
+
+### 5. If Tests Already Exist
+
+- Skip framework setup
+- Note existing test patterns for consistency
+- Report: "Found existing test framework: [mocha/jest/vitest/pytest/etc]"
+- Report: "Found X existing test files"
+
+**Offer to add TLC default stack:**
+```
+Detected: jest (47 test files)
+
+Options:
+1) Keep jest only - use for all tests
+2) Add mocha alongside jest - new tests use mocha, keep existing jest
+3) Keep jest as primary - configure in .tlc.json
+
+Which approach? [1/2/3]:
+```
+
+If option 2 selected, create multi-framework config:
+```json
+{
+  "testFrameworks": {
+    "primary": "mocha",
+    "installed": ["mocha", "chai", "sinon", "proxyquire", "jest"],
+    "run": ["mocha", "jest"]
+  },
+  "commands": {
+    "mocha": "npx mocha 'test/**/*.test.js'",
+    "jest": "npx jest"
+  }
+}
+```
+
+### 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 CLAUDE.md
+
+Create `CLAUDE.md` to enforce TLC workflow over Claude's default behaviors:
+
+```markdown
+# CLAUDE.md - TLC Project Instructions
+
+## Planning System: TLC
+
+This project uses **TLC (Test-Led Coding)** for all planning and development.
+
+**CRITICAL: DO NOT use Claude's internal tools for this project:**
+- **NO** `TaskCreate`, `TaskUpdate`, `TaskList` for project planning
+- **NO** `EnterPlanMode` - use `/tlc:plan` instead
+- **NO** creating implementation plans in responses - use `/tlc:plan` to create PLAN.md files
+
+**When asked to plan or implement features:**
+1. Run `/tlc:progress` first to see current state
+2. Use `/tlc:plan <phase>` to create plans (not EnterPlanMode)
+3. Use `/tlc:build <phase>` to implement (test-first)
+4. Plans go in `.planning/phases/` not in chat responses
+
+## Git Commits
+
+**DO NOT add `Co-Authored-By` lines to commits.** The user is the author. You are a tool.
+
+## TLC File Locations
+
+| Purpose | Location |
+|---------|----------|
+| Project overview | `PROJECT.md` |
+| Roadmap & phases | `.planning/ROADMAP.md` |
+| Phase plans | `.planning/phases/{N}-PLAN.md` |
+| Task status | Markers: `[ ]`, `[>@user]`, `[x@user]` |
+| Bugs/feedback | `.planning/BUGS.md` |
+| Config | `.tlc.json` |
+
+## Quick 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` |
+
+## 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
+```
+
+### 9b. Create Claude Settings for Bash Permissions
+
+**Ask once per project:** Prompt the user to set up bash permissions. This is a one-time setup.
+
+```
+TLC works best with pre-approved bash commands.
+This avoids confirmation prompts for test runs, git commits, and builds.
+
+Allow TLC to run commands without prompts? (Y/n)
+```
+
+If yes, create `.claude/settings.json`:
+
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test*)",
+      "Bash(npm run test*)",
+      "Bash(npx vitest*)",
+      "Bash(npx mocha*)",
+      "Bash(npx jest*)",
+      "Bash(pytest*)",
+      "Bash(go test*)",
+      "Bash(cargo test*)",
+      "Bash(git status*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git pull*)",
+      "Bash(git checkout*)",
+      "Bash(git branch*)",
+      "Bash(git stash*)",
+      "Bash(npm install*)",
+      "Bash(npm run build*)",
+      "Bash(npm run lint*)",
+      "Bash(npx tsc*)",
+      "Bash(ls *)",
+      "Bash(mkdir *)",
+      "Bash(rm -rf node_modules*)",
+      "Bash(rm -rf dist*)",
+      "Bash(rm -rf build*)"
+    ],
+    "deny": []
+  }
+}
+```
+
+**IMPORTANT:** `git push` is NOT included. Always ask before pushing to remote.
+
+If `.claude/settings.json` already exists, merge the permissions (don't overwrite user's existing config).
+
+### 10. 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.
+
+### 11. Set Up Documentation (Optional)
+
+If the project doesn't have docs automation:
+
+```
+Documentation Automation
+
+TLC can automatically maintain your docs:
+  • Update version references on push
+  • Sync to GitHub Wiki
+  • Generate API documentation
+  • Capture app screenshots
+
+Set up documentation automation? (Y/n)
+```
+
+If yes, run `/tlc:docs setup`.
+
+### 12. Enterprise Features (Optional)
+
+After basic setup, offer enterprise features:
+
+```
+Enterprise Features (v1.4+)
+
+TLC includes enterprise-grade features for compliance and security:
+
+  • Audit logging - tamper-evident logs with SIEM export
+  • Zero-data-retention - HIPAA/PCI-DSS compliant ephemeral mode
+  • SSO integration - OAuth 2.0 and SAML 2.0 support
+  • Compliance tooling - SOC 2 Type II checklist and evidence
+
+Enable enterprise features? (Y/n)
+```
+
+If yes, add enterprise config to `.tlc.json`:
+
+```json
+{
+  "enterprise": {
+    "enabled": true,
+    "audit": {
+      "enabled": true,
+      "storage": ".tlc/audit/"
+    },
+    "compliance": {
+      "enabled": true,
+      "framework": "soc2"
+    }
+  }
+}
+```
+
+Then show:
+```
+Enterprise features enabled.
+
+Commands available:
+  /tlc:audit       - View and export audit logs
+  /tlc:retention   - Configure zero-data-retention
+  /tlc:sso         - Set up SSO providers
+  /tlc:compliance  - SOC 2 compliance dashboard
+```
+
+### 13. 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
+Docs automation: [enabled/skipped]
+Enterprise features: [enabled/skipped]
+
+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
+- Run /tlc:docs to update documentation
+```
+
+## Usage
+
+```
+/tlc:init
+```
+
+No arguments needed. Auto-detects everything.