tlc-claude-code 1.8.5 → 2.1.0

package/.claude/commands/tlc/bootstrap.md

@@ -0,0 +1,77 @@
+# /tlc:bootstrap - Workspace Bootstrap
+
+Clone all repos and set up a workspace on a new machine.
+
+## Usage
+
+```
+/tlc:bootstrap
+/tlc:bootstrap --dry-run
+/tlc:bootstrap --skip-install
+/tlc:bootstrap --parallel 5
+```
+
+## What This Does
+
+1. Reads `projects.json` from the workspace root
+2. Clones all repos that aren't already present
+3. Checks out the correct branch per repo
+4. Installs dependencies (npm install, pip install, etc.)
+5. Rebuilds vector indexes from memory text files
+6. Reports summary
+
+## Options
+
+| Flag | Default | Description |
+|------|---------|-------------|
+| `--dry-run` | false | Show what would be cloned without doing it |
+| `--skip-install` | false | Skip dependency installation |
+| `--parallel N` | 3 | Number of concurrent clones |
+
+## Process
+
+### Step 1: Read Registry
+
+Load `projects.json` from workspace root. If it doesn't exist:
+```
+No projects.json found.
+
+Run /tlc:init to initialize this workspace, or create projects.json manually.
+```
+
+### Step 2: Clone Repos
+
+For each project in the registry:
+- If directory already exists with `.git/` → skip
+- Otherwise → `git clone <url> <path>`
+- Checkout the `defaultBranch`
+
+### Step 3: Install Dependencies
+
+For each cloned repo (unless `--skip-install`):
+- Node.js (`package.json`) → `npm install`
+- Python (`requirements.txt`) → `pip install -r requirements.txt`
+- Go (`go.mod`) → `go mod download`
+
+### Step 4: Rebuild Vectors
+
+If Ollama is available:
+- Pull embedding model: `ollama pull mxbai-embed-large`
+- Rebuild vector indexes from memory text files
+
+### Step 5: Summary
+
+```
+Workspace bootstrap complete:
+  Cloned: 3 repos
+  Skipped: 1 (already present)
+  Failed: 0
+
+All repos ready. Run /tlc:progress to see project status.
+```
+
+## Related Commands
+
+- `/tlc:init` — Initialize TLC in an existing project
+- `/tlc:recall` — Search workspace memory
+- `/tlc:progress` — Check project status

package/.claude/commands/tlc/build.md

@@ -636,21 +636,35 @@ git add src/auth/login.ts tests/auth/login.test.ts
 git commit -m "feat: {task-title} - phase {N}"
 ```
 
-#### 7e. Mark Task Complete (Multi-User)
+#### 7e. Mark Task Complete in PLAN.md (MANDATORY)
 
-If using multi-user mode (task had `[>@user]` marker):
+**Always update the task marker in PLAN.md after tests pass.** This is not optional.
 
-1. Update marker: `[>@{user}]` → `[x@{user}]`
-2. Commit: `git commit -m "complete: task {N} - {title} (@{user})"`
-3. Push to share progress with team
+1. Open `.planning/phases/{phase}-PLAN.md`
+2. Find the task heading: `### Task {N}: {title} [ ]` (or `[>@{user}]`)
+3. Update the marker:
+   - Single-user: `[ ]` → `[x]`
+   - Multi-user: `[>@{user}]` → `[x@{user}]`
+4. Include the plan update in the same commit (step 7d) or commit separately
+
+**Example:**
+```
+### Task 3: Tabbed Project Detail Page [ ]     ← before
+### Task 3: Tabbed Project Detail Page [x]     ← after
+```
+
+This keeps the plan file as the single source of truth for task status. Do NOT wait until the end of the phase — mark each task done immediately after its tests pass.
+
+If in multi-user mode, also push to share progress with team.
 
 #### 7f. Move to next task
-Repeat 7a-7d for each task in the phase.
+Repeat 7a-7e for each task in the phase.
 
 **Critical Rules:**
 - Implement **one task at a time**
 - Run tests **after each task**
 - Commit **after each passing task**
+- **Mark task `[x]` in PLAN.md after each passing task** — never defer this
 - Do NOT batch — sequential execution catches issues early
 
 ### Step 8: Verify All Tests Pass (Green)

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