tlc-claude-code 2.0.1 → 2.1.0

package/.claude/commands/tlc/deploy.md

@@ -648,9 +648,199 @@ Add to GitHub deploy keys (read-only):
   https://github.com/org/repo/settings/keys
 ```
 
-### Environment Variables
+### Secrets Management with HashiCorp Vault
 
-Secrets stored on dev server:
+**Never store secrets in `.env` files, code, or git.** All secrets go through HashiCorp Vault.
+
+#### Setup Vault
+
+```
+> /tlc:deploy vault setup
+
+HashiCorp Vault Setup
+════════════════════════════════════════════════
+
+Vault address: https://vault.example.com
+Auth method: [token/approle/github] approle
+
+Configuring AppRole auth for TLC...
+  ✓ Created policy: tlc-deploy-policy
+  ✓ Created AppRole: tlc-deploy
+  ✓ Role ID: 7c8a9b2d-...
+  ✓ Secret ID: (stored in CI secrets)
+
+Secrets engine: kv-v2 at secret/tlc/{project}
+
+Configuration saved to .tlc.json (no secrets stored)
+```
+
+#### Secret Paths
+
+Secrets are organized by environment in Vault:
+
+```
+secret/tlc/{project}/
+  ├── dev/
+  │   ├── database_url
+  │   ├── jwt_secret
+  │   ├── slack_webhook
+  │   └── github_webhook_secret
+  ├── staging/
+  │   ├── database_url
+  │   ├── jwt_secret
+  │   └── api_keys
+  └── production/
+      ├── database_url
+      ├── jwt_secret
+      ├── api_keys
+      └── ssl_certs
+```
+
+#### Vault Commands
+
+```
+> /tlc:deploy vault set dev/jwt_secret "new-secret-value"
+  ✓ Secret stored at secret/tlc/my-app/dev/jwt_secret
+
+> /tlc:deploy vault list dev
+  Secrets at secret/tlc/my-app/dev/:
+    database_url
+    jwt_secret
+    slack_webhook
+    github_webhook_secret
+
+> /tlc:deploy vault get dev/jwt_secret
+  ✓ Value copied to clipboard (not displayed)
+
+> /tlc:deploy vault rotate dev/jwt_secret
+  ✓ New secret generated and stored
+  ✓ Containers using this secret will be restarted
+```
+
+#### How Containers Get Secrets
+
+Secrets are injected at deploy time, never baked into images:
+
+```yaml
+# docker-compose.yml (generated per deployment)
+services:
+  app:
+    build: ./deployments/${BRANCH}
+    environment:
+      - VAULT_ADDR=${VAULT_ADDR}
+      - VAULT_ROLE_ID=${VAULT_ROLE_ID}
+    # Secrets fetched at startup via vault-agent sidecar
+    # OR injected via envconsul/consul-template
+```
+
+**Option A: Vault Agent Sidecar (recommended)**
+
+```yaml
+services:
+  vault-agent:
+    image: hashicorp/vault
+    command: vault agent -config=/etc/vault/agent.hcl
+    volumes:
+      - shared-secrets:/secrets
+
+  app:
+    depends_on: [vault-agent]
+    volumes:
+      - shared-secrets:/secrets:ro
+    environment:
+      - ENV_FILE=/secrets/.env
+```
+
+**Option B: envconsul (simpler)**
+
+```dockerfile
+# In app Dockerfile
+RUN curl -fsSL https://releases.hashicorp.com/envconsul/0.13.2/envconsul_0.13.2_linux_amd64.tgz | tar xz
+ENTRYPOINT ["envconsul", "-vault-addr", "$VAULT_ADDR", "-secret", "secret/tlc/${PROJECT}/${ENV}", "npm", "start"]
+```
+
+**Option C: CI-time injection (simplest, for non-production)**
+
+```yaml
+# GitHub Actions
+- name: Fetch secrets from Vault
+  uses: hashicorp/vault-action@v3
+  with:
+    url: ${{ secrets.VAULT_ADDR }}
+    method: approle
+    roleId: ${{ secrets.VAULT_ROLE_ID }}
+    secretId: ${{ secrets.VAULT_SECRET_ID }}
+    secrets: |
+      secret/data/tlc/${{ env.PROJECT }}/dev database_url | DATABASE_URL;
+      secret/data/tlc/${{ env.PROJECT }}/dev jwt_secret | JWT_SECRET;
+```
+
+#### Vault Configuration in .tlc.json
+
+```json
+{
+  "deploy": {
+    "domain": "project.example.com",
+    "vault": {
+      "enabled": true,
+      "addr": "https://vault.example.com",
+      "auth": "approle",
+      "secretPath": "secret/tlc/my-app",
+      "injection": "vault-agent",
+      "environments": ["dev", "staging", "production"]
+    }
+  }
+}
+```
+
+**No secrets in `.tlc.json`.** Only the Vault address and paths. Role IDs and Secret IDs live in CI secrets or the deploy server's own Vault agent.
+
+#### Secret Rotation
+
+```
+> /tlc:deploy vault rotate-all dev
+
+Rotating all secrets for dev environment...
+  ✓ database_url — rotated (new password generated)
+  ✓ jwt_secret — rotated (32-byte random)
+  ✓ slack_webhook — skipped (external, rotate manually)
+  ✓ github_webhook_secret — rotated
+
+Restarting affected containers...
+  ✓ dev containers restarted with new secrets
+
+Rotation complete. Old secrets invalidated.
+```
+
+#### Migration from .env Files
+
+If you have existing `.env` files:
+
+```
+> /tlc:deploy vault migrate
+
+Found .env files:
+  /opt/tlc-deploy/.env (4 secrets)
+  .env.local (2 secrets)
+
+Migrating to Vault...
+  ✓ JWT_SECRET → secret/tlc/my-app/dev/jwt_secret
+  ✓ DATABASE_URL → secret/tlc/my-app/dev/database_url
+  ✓ GITHUB_WEBHOOK_SECRET → secret/tlc/my-app/dev/github_webhook_secret
+  ✓ SLACK_WEBHOOK_URL → secret/tlc/my-app/dev/slack_webhook
+
+Securely deleting .env files...
+  ✓ /opt/tlc-deploy/.env shredded
+  ✓ .env.local shredded
+
+Check .gitignore includes: .env* ✓
+
+Migration complete. All secrets now in Vault.
+```
+
+### Environment Variables (Legacy / Non-Vault)
+
+If Vault is not configured, secrets fall back to `.env` files on the deploy server. **This is not recommended for production.**
 
 ```bash
 # /opt/tlc-deploy/.env
@@ -660,6 +850,8 @@ GITHUB_WEBHOOK_SECRET=webhook-secret
 SLACK_WEBHOOK_URL=https://hooks.slack.com/...
 ```
 
+**Warning:** TLC will flag `.env` files containing secrets during `/tlc:security` scans.
+
 ## Cleanup
 
 ### Remove old deployments

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 |