tlc-claude-code 2.0.1 → 2.2.0

package/.claude/commands/tlc/e2e-verify.md

@@ -0,0 +1,214 @@
+# /tlc:e2e-verify - E2E Visual Verification
+
+When code is "done", verify it actually works by running e2e tests, taking screenshots, and checking logs. Trust but verify.
+
+## What This Does
+
+1. **Starts the dev server** (if not already running)
+2. **Runs Playwright e2e tests** to exercise the application
+3. **Takes screenshots** of key pages/states
+4. **Reads screenshots visually** to verify UI correctness
+5. **Checks server and browser console logs** for errors
+6. **Reports findings** and fixes issues
+
+This replaces the manual "let me check if it actually works" step.
+
+## Usage
+
+```
+/tlc:e2e-verify
+/tlc:e2e-verify dashboard       # verify specific area
+/tlc:e2e-verify --screenshots   # screenshot-heavy mode
+```
+
+## Process
+
+### Step 1: Ensure Dev Server is Running
+
+Check if the server is already up:
+
+```bash
+curl -s http://localhost:3148/health || curl -s http://localhost:3148/ 2>/dev/null
+curl -s http://localhost:4000/ 2>/dev/null
+```
+
+If not running:
+- Start the TLC server: `node server/index.js &` (port from `.tlc.json`)
+- Start the dashboard dev server if needed: `cd dashboard-web && npm run dev &`
+- Wait for both to be ready (poll health endpoints)
+
+### Step 2: Run Existing E2E Tests
+
+Check which Playwright config applies:
+- Root: `playwright.config.ts` (server e2e, baseURL `localhost:3147`)
+- Dashboard: `dashboard-web/playwright.config.ts` (dashboard e2e, baseURL `localhost:4000`)
+
+Run the relevant tests:
+
+```bash
+npx playwright test --reporter=list
+```
+
+- Capture stdout/stderr
+- Note any failures
+
+### Step 3: Take Screenshots
+
+Use Playwright to screenshot key pages. Create a temporary test script if no existing screenshots cover the area:
+
+```bash
+npx playwright test --project=chromium --reporter=list
+```
+
+For targeted screenshots, use Playwright's screenshot API via a quick script:
+
+```javascript
+// Save to /tmp/tlc-screenshots/
+const { chromium } = require('playwright');
+const browser = await chromium.launch();
+const page = await browser.newPage();
+
+// Screenshot key pages
+await page.goto('http://localhost:4000');
+await page.screenshot({ path: '/tmp/tlc-screenshots/dashboard-home.png', fullPage: true });
+
+// Login flow
+await page.goto('http://localhost:4000/login');
+await page.screenshot({ path: '/tmp/tlc-screenshots/login.png', fullPage: true });
+
+// After login
+await page.fill('[data-testid="email"]', 'user@local.com');
+await page.fill('[data-testid="password"]', '2026rocks');
+await page.click('[data-testid="login-btn"]');
+await page.waitForURL('**/dashboard**');
+await page.screenshot({ path: '/tmp/tlc-screenshots/after-login.png', fullPage: true });
+```
+
+Adapt the script based on what was changed — screenshot the areas affected by recent work.
+
+### Step 4: Visual Inspection
+
+**Read each screenshot using the Read tool** (Claude is multimodal and can see images).
+
+For each screenshot, check:
+- **Layout**: Is the page rendering correctly? No overlapping elements, broken grids?
+- **Content**: Is text readable? Are labels correct? No "undefined" or "[object Object]"?
+- **State**: Are loading states resolved? No spinners stuck? No empty states where data should be?
+- **Errors**: Any visible error messages, red banners, or console error overlays?
+- **Styling**: Does it look intentional? No broken CSS, missing icons, or unstyled elements?
+
+### Step 5: Check Logs
+
+**Server logs:**
+```bash
+# Check for errors in server output
+# If server was started with output capture, read the log file
+cat /tmp/tlc-server.log 2>/dev/null | grep -i "error\|warn\|fail" | tail -20
+```
+
+**Browser console:**
+- Playwright captures console messages — check test output for console errors
+- Look for: uncaught exceptions, failed network requests, React/Vue warnings
+
+**Network requests:**
+- Check for failed API calls (4xx, 5xx responses)
+- Check for CORS errors
+- Check for slow responses (>2s)
+
+### Step 6: Report and Fix
+
+**If everything looks good:**
+```
+✅ E2E Verification Complete
+
+Screenshots reviewed:
+- Dashboard home: ✅ Renders correctly
+- Login page: ✅ Form visible, styled correctly
+- After login: ✅ Dashboard loads with data
+
+Logs: No errors found
+Tests: 12/12 passing
+
+Code is verified.
+```
+
+**If issues found:**
+```
+⚠️ E2E Verification Found Issues
+
+1. Dashboard home: Table header misaligned on narrow viewport
+2. Server log: "Warning: deprecated API endpoint /api/v1/stats called"
+3. Console: "Failed to load resource: 404 /api/fonts/inter.woff2"
+
+Fixing...
+```
+
+Then fix each issue:
+- Read the relevant source files
+- Apply fixes
+- Re-run the verification for the fixed areas
+- Loop until clean
+
+### Step 7: Final Confirmation
+
+After all fixes:
+- Re-run full e2e suite
+- Take fresh screenshots of fixed areas
+- Confirm visually
+- Report final status
+
+## Screenshot Locations
+
+Screenshots are saved to `/tmp/tlc-screenshots/` for the session. Clean up after verification.
+
+## Guard Rails
+
+- **Don't skip failures.** Every visual anomaly and log error gets investigated.
+- **Don't change tests to match broken UI.** Fix the UI.
+- **Clean up temp files.** Remove screenshot scripts and temp screenshots when done.
+- **Respect server state.** Don't kill servers that were already running before verification.
+
+## Example
+
+```
+> /tlc:e2e-verify
+
+Checking servers...
+  Server (3148): ✅ running
+  Dashboard (4000): ✅ running
+
+Running e2e tests...
+  12/12 passing ✅
+
+Taking screenshots...
+  📸 /dashboard — captured
+  📸 /login — captured
+  📸 /settings — captured
+  📸 /phases — captured
+
+Reviewing screenshots...
+  /dashboard: ✅ Layout correct, data loading, no errors
+  /login: ✅ Form renders, labels correct
+  /settings: ⚠️ Theme toggle shows "undefined" label
+  /phases: ✅ Phase list renders correctly
+
+Checking logs...
+  Server: ✅ No errors
+  Console: ⚠️ "Cannot read property 'label' of undefined" on /settings
+
+Found 1 issue: Theme toggle label is undefined.
+Reading settings component...
+
+Fixed: Added fallback label for theme toggle.
+Re-verifying /settings... ✅ Label now shows "Dark Mode"
+
+✅ E2E Verification Complete — all clear.
+```
+
+## When to Use
+
+- After `/tlc:build` completes a phase
+- After `/tlc:watchci` reports green
+- Before marking a phase as verified (`/tlc:verify`)
+- Any time you want visual proof that the app works
+- Combine with `/tlc:watchci`: build → push → watchci → e2e-verify

package/.claude/commands/tlc/guard.md

@@ -0,0 +1,191 @@
+# /tlc:guard - TLC Process Guard
+
+Validates that TLC planning and building were done properly. Catches process shortcuts before they become problems.
+
+## What This Does
+
+1. **Checks planning quality** — phase files exist, tasks are properly broken down, acceptance criteria present
+2. **Checks build quality** — test-first was followed, coverage exists, no implementation without tests
+3. **Reports violations** with specific fixes
+4. **Optionally auto-fixes** structural issues
+
+Run this before marking anything as "done."
+
+## Usage
+
+```
+/tlc:guard
+/tlc:guard plan 42      # check planning for phase 42
+/tlc:guard build 42     # check build compliance for phase 42
+/tlc:guard --fix        # auto-fix what can be fixed
+```
+
+## Planning Guard
+
+### What Gets Checked
+
+Read `.planning/phases/{N}-PLAN.md` and validate:
+
+**Structure (required):**
+- [ ] Phase file exists at `.planning/phases/{N}-PLAN.md`
+- [ ] Has a clear title with phase number
+- [ ] Has a goal/objective section
+- [ ] Has task breakdown (not just a wall of text)
+
+**Task Quality (required):**
+- [ ] Each task has a checkbox marker (`[ ]`, `[>@user]`, or `[x@user]`)
+- [ ] Tasks are small enough to implement in one sitting (no mega-tasks)
+- [ ] Tasks have acceptance criteria or clear "done" definition
+- [ ] Tasks are ordered by dependency (prerequisites first)
+
+**Completeness (recommended):**
+- [ ] Technical approach is specified (not just "build X")
+- [ ] File paths are mentioned where relevant
+- [ ] Edge cases are considered
+- [ ] No vague tasks like "improve performance" or "fix bugs" (too broad)
+
+### Planning Violations
+
+```
+/tlc:guard plan 42
+
+Checking phase 42 plan...
+
+❌ VIOLATIONS:
+1. Task 3 has no acceptance criteria: "Implement auth module"
+   → Add: what endpoints, what auth method, what response format?
+
+2. Task 5 is too broad: "Handle all error cases"
+   → Break into specific error scenarios
+
+3. No dependency ordering — Task 4 depends on Task 2 but comes first
+
+⚠️ WARNINGS:
+1. No file paths mentioned — harder to review later
+2. Task 1 and Task 6 look like they could be one task
+
+Fix these before running /tlc:build.
+```
+
+## Build Guard
+
+### What Gets Checked
+
+For a phase that's been (partially) built, verify TLC compliance:
+
+**Test-First (critical):**
+- [ ] Test files exist for all implemented source files
+- [ ] Git log shows test commits BEFORE implementation commits (check timestamps and diffs)
+- [ ] No source file was added without a corresponding test file in the same or earlier commit
+
+**Coverage:**
+- [ ] Run tests and check they all pass
+- [ ] Coverage meets threshold from `.tlc.json` (default 80%)
+- [ ] New code specifically has coverage (not just overall project average)
+
+**Code Quality:**
+- [ ] No `console.log` debugging left in production code
+- [ ] No `TODO` or `FIXME` comments that should be tracked as tasks
+- [ ] No hardcoded secrets, URLs, or credentials (check for patterns)
+- [ ] No skipped tests (`.skip`, `xit`, `xdescribe`)
+
+**Process:**
+- [ ] Phase plan exists and tasks are checked off
+- [ ] Implementation matches what was planned (no scope creep)
+- [ ] Commits reference the phase/task they belong to
+
+### Build Violations
+
+```
+/tlc:guard build 42
+
+Checking phase 42 build compliance...
+
+❌ VIOLATIONS:
+1. TEST-FIRST BREACH: server/lib/auth/auth.service.js was committed
+   BEFORE server/lib/auth/auth.test.js
+   → Commits: abc123 (service) came before def456 (test)
+
+2. MISSING TEST: server/lib/auth/token-utils.js has no test file
+   → Expected: server/lib/auth/token-utils.test.js
+
+3. SKIPPED TEST: server/lib/auth/auth.test.js line 45 — test.skip()
+   → Either fix the test or remove it
+
+⚠️ WARNINGS:
+1. console.log found in server/lib/auth/auth.service.js:23
+2. TODO comment in server/lib/auth/auth.service.js:67
+3. Coverage for new files: 72% (below 80% threshold)
+
+Run /tlc:autofix to resolve skipped tests.
+```
+
+## Auto-Fix Mode
+
+With `--fix`, the guard can resolve some issues automatically:
+
+**Can auto-fix:**
+- Remove `console.log` statements (non-intentional ones)
+- Convert `TODO`/`FIXME` to tasks in the phase plan
+- Create skeleton test files for untested source files
+- Fix task checkbox formatting in plan files
+
+**Cannot auto-fix (reports only):**
+- Test-first order violations (that ship has sailed)
+- Missing acceptance criteria (needs human input)
+- Scope creep (needs human judgment)
+- Low coverage (needs more test cases written)
+
+## Combined Guard
+
+Running `/tlc:guard` without arguments checks everything for the current/latest phase:
+
+```
+/tlc:guard
+
+Detecting current phase... Phase 42: Auth Module
+
+=== PLANNING GUARD ===
+✅ Plan structure: OK
+✅ Task breakdown: 6 tasks, all with criteria
+⚠️ Task 5 seems broad — consider splitting
+
+=== BUILD GUARD ===
+✅ Test-first: All tests committed before implementation
+✅ Coverage: 87% (above 80% threshold)
+❌ 1 skipped test found
+⚠️ 2 console.log statements
+
+Overall: 1 violation, 3 warnings
+
+Run /tlc:guard --fix to auto-resolve what's possible.
+```
+
+## Integration with Other Commands
+
+This guard should be consulted:
+- **Before `/tlc:verify`** — don't verify code that wasn't built properly
+- **Before `/tlc:complete`** — don't complete a milestone with process violations
+- **After `/tlc:build`** — as a final check before moving on
+- **After `/tlc:plan`** — validate the plan before building
+
+## Example Full Flow
+
+```
+/tlc:plan 42          # Create the plan
+/tlc:guard plan 42    # Validate the plan ← catches bad plans early
+/tlc:build 42         # Build test-first
+/tlc:guard build 42   # Validate the build ← catches process shortcuts
+/tlc:e2e-verify       # Visual verification
+/tlc:watchci          # CI verification
+/tlc:verify 42        # Human acceptance
+/tlc:complete         # Mark done
+```
+
+## When to Use
+
+- After planning, before building
+- After building, before verification
+- When you suspect process was skipped
+- As a pre-push check
+- When onboarding — validates that TLC discipline is being followed

package/.claude/commands/tlc/help.md

@@ -57,6 +57,38 @@ Launches the visual dashboard. Detects where you are, shows what's next.
 | `/tlc:release` | Release a claimed task |
 | `/tlc:who` | Show who's working on what |
 
+### Plugins (auto-run via hooks)
+
+**After `/tlc:build`** (code written):
+guard → preflight → review (Claude + Codex) → if APPROVED → push + PR
+
+**After `git push`** (CI triggered):
+watchci (monitor GH Actions) → if green → e2e-verify (screenshots + logs)
+
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:guard` | Validates TLC process: plan quality, test-first compliance, coverage thresholds |
+| `/tlc:preflight` | Completeness check — all references, registries, configs, distribution paths |
+| `/tlc:review` | Multi-LLM review gate — Claude + Codex must both APPROVE before push |
+| `/tlc:watchci` | After push: monitors GH Actions, reads failure logs, fixes until green |
+| `/tlc:e2e-verify` | After CI green: Playwright screenshots, visual inspection, log checking |
+
+These fire automatically via PostToolUse hooks. You can also invoke them manually.
+
+### Code Quality
+
+| Command | What It Does |
+|---------|--------------|
+| `/tlc:review` | Review current branch |
+| `/tlc:review-pr` | Review a pull request |
+| `/tlc:refactor` | Step-by-step standards refactoring |
+| `/tlc:cleanup` | Automatic standards cleanup |
+| `/tlc:audit` | Check coding standards compliance |
+| `/tlc:security` | Security audit |
+| `/tlc:outdated` | Check outdated dependencies |
+| `/tlc:edge-cases` | Generate edge case tests |
+| `/tlc:quality` | Test quality scoring |
+
 ### Enterprise (v1.4+)
 
 | Command | What It Does |

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

@@ -262,9 +262,21 @@ All implementation follows **Red → Green → Refactor**:
 3. **Refactor**: Clean up while keeping tests green
 ```
 
-### 9b. Create Claude Settings for Bash Permissions (Automatic)
+### 9b. Create Claude Settings with Permissions AND Hooks (Automatic)
 
-**Always create `.claude/settings.json` during init.** This is not optional — TLC requires these permissions to run tests, commit, and build without interruption.
+**Always create `.claude/settings.json` during init.** This is not optional — TLC requires permissions for uninterrupted work AND hooks for the plugin system (enforcement, auto-verification, memory capture).
+
+**Also create `.claude/hooks/` directory** and copy all hook scripts from the TLC package. The hooks power the plugin system — without them, TLC is commands-only with no automation.
+
+Create `.claude/hooks/` with these scripts (copy from the installed TLC package at `~/.claude/hooks/` or from the npm package):
+- `tlc-block-tools.sh` — Blocks non-TLC planning tools (EnterPlanMode, TaskCreate, etc.)
+- `tlc-prompt-guard.sh` — Smart intent detection: parses user message for plan/build/fix/deploy intent and routes to the correct TLC command
+- `tlc-session-init.sh` — Initializes TLC state and ensures server is running
+- `tlc-post-push.sh` — Auto-triggers CI monitoring after `git push`
+- `tlc-post-build.sh` — Auto-triggers guard + e2e verification after build/plan
+- `tlc-capture-exchange.sh` — Captures conversations to team memory
+
+Make all hook scripts executable: `chmod +x .claude/hooks/*.sh`
 
 Create `.claude/settings.json`:
 
@@ -272,46 +284,70 @@ Create `.claude/settings.json`:
 {
   "permissions": {
     "allow": [
-      "Bash(npm *)",
-      "Bash(npx *)",
-      "Bash(node *)",
-      "Bash(git *)",
-      "Bash(gh *)",
-      "Bash(ssh *)",
-      "Bash(scp *)",
-      "Bash(rsync *)",
-      "Bash(curl *)",
-      "Bash(wget *)",
-      "Bash(docker *)",
-      "Bash(docker-compose *)",
-      "Bash(pytest*)",
-      "Bash(python *)",
-      "Bash(pip *)",
-      "Bash(go *)",
-      "Bash(cargo *)",
-      "Bash(make *)",
-      "Bash(cat *)",
-      "Bash(ls *)",
-      "Bash(pwd*)",
-      "Bash(cd *)",
-      "Bash(mkdir *)",
-      "Bash(cp *)",
-      "Bash(mv *)",
-      "Bash(which *)",
-      "Bash(echo *)",
-      "Bash(jq *)",
-      "Bash(wc *)",
-      "Bash(head *)",
-      "Bash(tail *)",
-      "Bash(sort *)",
-      "Bash(uniq *)",
-      "Bash(xargs *)"
+      "Bash(npm *)", "Bash(npx *)", "Bash(node *)", "Bash(git *)",
+      "Bash(gh *)", "Bash(ssh *)", "Bash(scp *)", "Bash(rsync *)",
+      "Bash(curl *)", "Bash(wget *)", "Bash(docker *)", "Bash(docker-compose *)",
+      "Bash(pytest*)", "Bash(python *)", "Bash(pip *)", "Bash(go *)",
+      "Bash(cargo *)", "Bash(make *)", "Bash(cat *)", "Bash(ls *)",
+      "Bash(pwd*)", "Bash(cd *)", "Bash(mkdir *)", "Bash(cp *)",
+      "Bash(mv *)", "Bash(which *)", "Bash(echo *)", "Bash(jq *)",
+      "Bash(wc *)", "Bash(head *)", "Bash(tail *)", "Bash(sort *)",
+      "Bash(uniq *)", "Bash(xargs *)"
     ]
+  },
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "EnterPlanMode|TaskCreate|TaskUpdate|TaskList|TaskGet|ExitPlanMode",
+      "hooks": [{
+        "type": "command",
+        "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/tlc-block-tools.sh",
+        "timeout": 5
+      }]
+    }],
+    "UserPromptSubmit": [{
+      "hooks": [{
+        "type": "command",
+        "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/tlc-prompt-guard.sh",
+        "timeout": 5
+      }]
+    }],
+    "SessionStart": [{
+      "hooks": [{
+        "type": "command",
+        "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/tlc-session-init.sh",
+        "timeout": 5
+      }]
+    }],
+    "PostToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [{
+          "type": "command",
+          "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/tlc-post-push.sh",
+          "timeout": 5
+        }]
+      },
+      {
+        "matcher": "Skill",
+        "hooks": [{
+          "type": "command",
+          "command": "bash $CLAUDE_PROJECT_DIR/.claude/hooks/tlc-post-build.sh",
+          "timeout": 5
+        }]
+      }
+    ],
+    "Stop": [{
+      "hooks": [{
+        "type": "command",
+        "command": "bash \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/tlc-capture-exchange.sh",
+        "timeout": 30
+      }]
+    }]
   }
 }
 ```
 
-If `.claude/settings.json` already exists, merge the permissions (don't overwrite user's existing config).
+If `.claude/settings.json` already exists, merge: preserve existing permissions (union), add hooks section if missing (don't overwrite existing hooks).
 
 ### 10. Create or Update PROJECT.md
 

package/.claude/commands/tlc/llm.md

@@ -28,20 +28,35 @@ Interactive setup to configure providers in `.tlc.json`:
 
 ### /tlc:llm status
 
-Show current configuration:
+Read from **`.tlc/.router-state.json`** (persistent state) and `.tlc.json` (config):
 
 ```
+LLM Router Status
+══════════════════════════════════════════════
+
+State: .tlc/.router-state.json
+  Probed: 2026-03-20T02:15:00Z (12 min ago)
+  TTL: 3600s (fresh)
+
 Providers:
   claude   ✓ /usr/local/bin/claude    [review, code-gen, refactor]
   codex    ✓ /usr/local/bin/codex     [review, code-gen]
   gemini   ✗ not found                [design, vision]
 
 Capabilities:
-  review    → claude, codex (fallback: claude)
-  code-gen  → claude
-  vision    → gemini (unavailable)
+  review    → claude, codex (fallback: claude)     2/2 available
+  code-gen  → claude                               1/1 available
+  vision    → gemini (unavailable)                  0/1 available
+
+Pipeline Integration:
+  Post-build review: claude + codex (consensus required)
+  Post-push e2e: claude (in-session)
 ```
 
+The state file is written by the `SessionStart` hook and re-probed every hour. All skills read from this file — no ad-hoc `which` calls.
+
+**Force re-probe:** `/tlc:llm probe` (deletes state file, next skill invocation re-probes)
+
 ### /tlc:llm models
 
 List models available from each provider.