tlc-claude-code 2.4.10 → 2.6.0

package/.claude/commands/tlc/plan.md

@@ -97,6 +97,39 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 
 **Override:** Pass `--model <name>` to route this specific run to a different model.
 
+After `resolveRouting` returns, immediately write `.tlc/.plan-routing-active` with the active provider name from `models[0]` before doing any other plan work. Remove `.tlc/.plan-routing-active` on completion, cancellation, or failure cleanup.
+
+**Routing decision:**
+- If routing says external provider (`models[0] !== 'claude'`), follow **ONLY ORCHESTRATOR MODE** below.
+- If routing says Claude (`models[0] === 'claude'`), follow **INLINE MODE** below.
+
+## ORCHESTRATOR MODE
+
+Use this mode only when `models[0]` is **NOT** `claude`.
+
+Claude does not execute the planning instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Read the roadmap, current phase context, discussion artifacts, project constraints, and any existing research before dispatching planning work.
+2. Prepare a full planning prompt that asks the routed provider to research, decompose, and sequence the phase using the project's architectural and task-quality standards.
+3. Dispatch through the provider CLI path, using `codex exec` for Codex-style providers or `gemini -p` for Gemini-style providers, preferably via the shared dispatch layer when available.
+4. Verify the returned plan before accepting it:
+   - Confirm it addresses the correct phase and reflects the actual roadmap goal.
+   - Confirm tasks are actionable, testable, dependency-aware, and aligned with file/folder sizing constraints.
+   - Confirm the plan contains real implementation thinking rather than generic project-management filler.
+5. If the first routed result is incomplete, contradictory, or too vague to execute, send a focused follow-up planning dispatch that requests the missing structure instead of accepting it.
+6. Handle failures explicitly:
+   - If dispatch fails because of model mismatch, auth, or missing CLI, check `.tlc/.router-state.json` for the provider's actual available model and retry once with the corrected model.
+   - If retry still fails, stop and report the exact failure to the user. Do not silently fall back to Claude inline execution.
+   - If the provider produces a weak plan, reject it and re-dispatch with tighter scope and success criteria.
+7. When finished, display the routed planning result, persist any captured memory, remove `.tlc/.plan-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing planning instructions below are the Inline Mode instructions and should be followed unchanged.
+
+
 ## Architectural Standards
 
 **Plan like a principal engineer designing for scale:**
@@ -296,6 +329,49 @@ Create `.planning/phases/{N}-PLAN.md`:
 - File size warnings: {None / list any files projected to exceed 1000 lines and planned split}
 ```
 
+### Step 4b: GitHub Sync (automatic)
+
+After writing the plan file, check if GitHub sync is enabled and sync tasks to GitHub Issues:
+
+```bash
+node -e "
+const path = require('path');
+let gh;
+try { gh = require('tlc-claude-code/server/lib/github'); }
+catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+console.log(gh.isGitHubEnabled(process.cwd()));
+" 2>/dev/null
+```
+
+If the result is `true`:
+
+1. Run the sync:
+   ```bash
+   node -e "
+   const path = require('path');
+   const fs = require('fs');
+   const { execSync } = require('child_process');
+   let gh;
+   try { gh = require('tlc-claude-code/server/lib/github'); }
+   catch { gh = require(path.join(process.cwd(), 'server/lib/github')); }
+   const config = gh.loadGitHubConfig(process.cwd(), { fs }).config;
+   if (!config) { console.log('GitHub sync: no config'); process.exit(0); }
+   const planPath = process.argv[1];
+   const r = gh.syncPlan({
+     planPath,
+     config,
+     ghClient: { exec: (cmd) => execSync(cmd, { encoding: 'utf-8', stdio: ['pipe','pipe','pipe'] }) },
+     ghProjects: null,
+     fs
+   });
+   console.log(JSON.stringify(r));
+   " ".planning/phases/{N}-PLAN.md" 2>/dev/null
+   ```
+2. Report results: "GitHub: Created N issues, updated M, linked to project board"
+3. If sync fails, warn but do not block: "GitHub sync failed: [reason]. Plan saved locally. Run `/tlc:issues sync` to retry."
+
+If not enabled, skip silently (no message).
+
 ### Step 5: Review Plan
 
 Present plan summary:

package/.claude/commands/tlc/quick.md

@@ -97,6 +97,39 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 
 **Override:** Pass `--model <name>` to route this specific run to a different model.
 
+After `resolveRouting` returns, immediately write `.tlc/.quick-routing-active` with the active provider name from `models[0]` before doing any other quick work. Remove `.tlc/.quick-routing-active` on completion, cancellation, or failure cleanup.
+
+**Routing decision:**
+- If routing says external provider (`models[0] !== 'claude'`), follow **ONLY ORCHESTRATOR MODE** below.
+- If routing says Claude (`models[0] === 'claude'`), follow **INLINE MODE** below.
+
+## ORCHESTRATOR MODE
+
+Use this mode only when `models[0]` is **NOT** `claude`.
+
+Claude does not execute the quick-task instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Treat Claude as the orchestrator for a small, test-first routed task rather than executing the work inline.
+2. Gather the minimal project context needed for the quick task, then package a focused prompt with the task request, expected failing test, implementation scope, and verification target.
+3. Dispatch through the provider CLI path, using `codex exec` for Codex-style providers or `gemini -p` for Gemini-style providers, preferably via the shared dispatch layer when available.
+4. Verify the routed result before accepting it:
+   - Confirm a failing test or equivalent pre-change verification was part of the work when appropriate.
+   - Confirm the implementation actually addresses the user's quick task and stays scoped.
+   - Confirm post-change verification was run or the provider clearly explained why not.
+5. If the routed work is partial, off-scope, or skips verification, dispatch a narrow corrective follow-up instead of treating it as complete.
+6. Handle failures explicitly:
+   - If dispatch fails because of model mismatch, auth, or missing CLI, check `.tlc/.router-state.json` for the provider's actual available model and retry once with the corrected model.
+   - If retry still fails, stop and report the exact failure to the user. Do not silently fall back to Claude inline execution.
+   - If the provider returns incomplete code or missing tests, issue a targeted retry for the missing part.
+7. When finished, display the routed provider result, persist any captured memory, remove `.tlc/.quick-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing quick-task instructions below are the Inline Mode instructions and should be followed unchanged.
+
+
 ## Engineering Standards
 
 Even quick tasks follow senior engineer standards:

package/.claude/commands/tlc/release.md

@@ -1,135 +1,85 @@
-# /tlc:release - Release a Task
-
-Release a task you claimed so others can work on it.
-
-## Usage
-
-```
-/tlc:release [task-number]
-```
-
-## When to Use
-
-- Blocked and can't continue
-- Switching to a different task
-- End of day, won't finish
-- Decided task approach needs rethinking
-
-## Process
-
-### Step 1: Identify User
-
-Get current user identity (same as `/tlc:claim`):
-
-```bash
-if [ -n "$TLC_USER" ]; then
-  user=$TLC_USER
-else
-  user=$(git config user.name | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
-fi
-```
-
-### Step 2: Find Your Claims
-
-Parse current phase PLAN.md for tasks claimed by you:
-
-```
-Looking for tasks claimed by @alice...
-
-Your claimed tasks:
-  2. Add validation [>@alice]
-  5. Error handling [>@alice]
-```
-
-### Step 3: Select Task to Release
-
-If task-number provided:
-- Verify you own that task
-- If not yours, show error
-
-If not provided:
-- Show your claimed tasks
-- Prompt to select one
-
-### Step 4: Update Task Marker
-
-Change from claimed to available:
-
-```markdown
-### Task 2: Add validation [>@alice]
-```
-
-becomes:
-
-```markdown
-### Task 2: Add validation [ ]
-```
-
-### Step 5: Commit and Push
-
-```bash
-git add .planning/phases/{N}-PLAN.md
-git commit -m "release: task {N} - {title} (@{user})"
-git push
-```
-
-## Example Session
-
-```
-> /tlc:release
-
-Your claimed tasks in Phase 1:
-  2. Add validation [>@alice]
-  5. Error handling [>@alice]
-
-Release which task? [2/5]: 2
-
-Task 2: Add validation [>@alice] → [ ]
-
-✓ Committed: release: task 2 - Add validation (@alice)
-✓ Pushed
-
-Task 2 is now available for others.
-```
-
-## With Task Number
-
-```
-> /tlc:release 2
-
-Task 2: Add validation [>@alice] → [ ]
-
-✓ Committed: release: task 2 - Add validation (@alice)
-✓ Pushed
-
-Task 2 is now available for others.
-```
-
-## Error Handling
-
-**Not your task:**
-```
-Task 2 is claimed by @bob, not you.
-You can only release your own tasks.
-
-Your tasks: 5
-```
-
-**Task not claimed:**
-```
-Task 2 is not claimed (already available).
-Nothing to release.
-```
-
-**No tasks claimed:**
-```
-You have no claimed tasks in Phase 1.
-Use /tlc:claim to claim a task.
-```
-
-## Notes
-
-- Releasing doesn't undo any work you've done
-- Your commits remain in history
-- Another teammate can claim and continue where you left off
-- Consider adding a note to the task if you made partial progress
+# /tlc:release - Run the Release Pipeline
+
+Run the full TLC release pipeline for the current project.
+
+## Usage
+
+```bash
+/tlc:release
+/tlc:release --detached
+```
+
+## What This Does
+
+1. Watches CI for the release commit or branch state
+2. Bumps the version
+3. Updates the changelog
+4. Publishes the release
+5. Runs a mandatory post-release health check
+
+This is the "prepare, publish, and verify the release" command.
+
+## Process
+
+### Step 1: Watch CI
+
+- Confirm the branch is in a releasable state
+- Watch the relevant CI run and stop on failure
+- Do not continue to versioning or publish while CI is red
+
+### Step 2: Bump Version
+
+- Determine the next version according to the project's release rules
+- Update the version in the canonical project files
+- Keep the version bump in the release commit
+
+### Step 3: Update Changelog
+
+- Generate or update the changelog entry for the new version
+- Summarize the user-facing changes included in the release
+- Ensure the changelog and version stay in sync
+
+### Step 4: Publish
+
+- Publish the package, artifact, or release target configured for the project
+- Surface any publish failure immediately
+- Do not mark the release complete until publish succeeds
+
+### Step 5: Run Health Check
+
+- Read `deploy.healthUrl` from project configuration
+- Block the release if `deploy.healthUrl` is missing
+- Perform the health check after publish and fail the release if the deployed system is unhealthy
+
+The health check is mandatory. If there is no `deploy.healthUrl`, stop and report that release verification cannot proceed.
+
+## Detached Mode
+
+`/tlc:release --detached` dispatches the release pipeline to the local orchestrator instead of running inline.
+
+- Dispatch via `POST` to the orchestrator at `http://localhost:3100`
+- The orchestrator owns the long-running release session
+- Return the dispatched session details to the user so they can monitor progress separately
+
+Detached mode still requires the same release stages:
+
+1. CI watch
+2. Version bump
+3. Changelog update
+4. Publish
+5. Mandatory health check
+
+Detached mode does not relax the health-check requirement. If `deploy.healthUrl` is not configured, the orchestrated release must block rather than skipping verification.
+
+## Guard Rails
+
+- Do not publish while CI is failing or still running
+- Do not skip the changelog for a versioned release
+- Do not treat publish success as release success until the health check passes
+- Do not continue when `deploy.healthUrl` is missing; the release blocks until health-check configuration exists
+
+## When to Use
+
+- Shipping a new version after CI is green
+- Running the standard TLC release flow end-to-end
+- Handing a long-running release to the orchestrator with `--detached`

package/.claude/commands/tlc/restore.md

@@ -0,0 +1,14 @@
+# /tlc:restore - Restore DB Snapshot
+
+## What This Does
+
+Lists available snapshots and restores the selected one.
+
+## Process
+
+1. List snapshots from `.tlc/snapshots/` sorted newest first
+2. Show table: date, git ref, DB name, size
+3. Ask user to pick one
+4. Confirm: `Restore {snapshot}? This will overwrite the current database. (Y/n)`
+5. Run restore command based on DB type
+6. Report success or failure

package/.claude/commands/tlc/review.md

@@ -94,9 +94,46 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
 4. If `strategy` is `parallel`:
    - Execute inline (Claude) AND dispatch to CLI models simultaneously
    - Collect and merge results
+   - **CRITICAL: If a provider fails (wrong model, auth error, CLI missing), do NOT silently fall back to single-provider.** Instead:
+     1. Check `.tlc/.router-state.json` for the provider's actual available model and retry
+     2. If retry fails, ask the user: "[Provider] failed: [reason]. Run with [other provider] only, or fix and retry?"
+     3. Never say "proceeding with X-only" without user consent
 
 **Override:** Pass `--model <name>` to route this specific run to a different model.
 
+After `resolveRouting` returns, immediately write `.tlc/.review-routing-active` with the active provider name from `models[0]` before doing any other review work. Remove `.tlc/.review-routing-active` on completion, cancellation, or failure cleanup.
+
+**Routing decision:**
+- If routing says external provider (`models[0] !== 'claude'`), follow **ONLY ORCHESTRATOR MODE** below.
+- If routing says Claude (`models[0] === 'claude'`), follow **INLINE MODE** below.
+
+## ORCHESTRATOR MODE
+
+Use this mode only when `models[0]` is **NOT** `claude`.
+
+Claude does not execute the review instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Read the full review context, including project standards, changed files, base branch, router state, and any configured review providers.
+2. Package the exact review task for the routed provider and dispatch it through the provider CLI path, using `codex exec` for Codex-style providers or `gemini -p` for Gemini-style providers, preferably via the shared dispatch layer when available.
+3. Require the provider run to produce concrete review findings, approval state, coverage gaps, TDD observations, and security concerns aligned to the command intent.
+4. Verify the returned review before accepting it:
+   - Confirm the review actually inspected the current diff against the intended base.
+   - Confirm the findings are specific, actionable, and tied to the changed code rather than generic advice.
+   - Reject empty, shallow, or unverifiable review output and dispatch a focused retry.
+5. If the command is expected to fix issues in a review loop, orchestrate the fix dispatches as separate routed tasks, then re-run the external review until the result is clean or an explicit blocker remains.
+6. Handle failures explicitly:
+   - If dispatch fails because of model mismatch, auth, or missing CLI, check `.tlc/.router-state.json` for the provider's actual available model and retry once with the corrected model.
+   - If retry still fails, stop and report the exact failure to the user. Do not silently fall back to Claude inline execution.
+   - If the provider returns malformed or partial review output, issue a narrowed follow-up dispatch instead of continuing as if review succeeded.
+7. When finished, display the routed provider review result, persist any captured memory, remove `.tlc/.review-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing review instructions below are the Inline Mode instructions and should be followed unchanged.
+
+
 ## What This Does
 
 1. Compares current branch to main/master
@@ -236,7 +273,49 @@ Scan diff for common security issues:
 
 **Fail if:** Any HIGH severity issues found.
 
-### Step 5b: Coding Standards Check
+### Step 5b: Run E2E Tests
+
+Detect whether the project uses Playwright or a Supertest-based E2E setup, then execute the matching command:
+
+```bash
+# Framework detection
+if [ -f playwright.config.ts ] || [ -f playwright.config.js ] || [ -d tests/e2e ] || [ -d e2e ]; then
+  mkdir -p .tlc/screenshots
+  npx playwright test
+elif rg -l "supertest" package.json test tests src >/dev/null 2>&1; then
+  mkdir -p .tlc/screenshots
+  npx supertest
+else
+  echo "WARN: No E2E tests detected"
+fi
+```
+
+**Execution rules:**
+- Use `npx playwright test` when Playwright is detected.
+- Use `npx supertest` when a Supertest-based E2E framework is detected.
+- If E2E tests fail, include the failure in the report as **CHANGES_REQUESTED**.
+- If no E2E tests exist, add a warning to the report.
+- On failure, save screenshots to `.tlc/screenshots/`.
+
+**Report example:**
+```text
+E2E Tests:
+  ✅ Playwright suite passed
+```
+
+```text
+E2E Tests:
+  ❌ Playwright suite failed
+  Screenshots: .tlc/screenshots/
+  Verdict impact: CHANGES_REQUESTED
+```
+
+```text
+E2E Tests:
+  ⚠️ No E2E tests detected
+```
+
+### Step 5c: Coding Standards Check
 
 Scan all changed/added files for coding standards violations:
 

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

@@ -2,6 +2,140 @@
 
 Detect the current TLC state in one pass, print a minimal status, and run the next safe action automatically.
 
+## Routing
+
+This command supports multi-model routing via `~/.tlc/config.json`.
+
+**Before executing this command:**
+
+1. Read routing config:
+   ```bash
+   node -e "const fs = require('fs');
+const path = require('path');
+const os = require('os');
+function readJson(filePath, fileSystem) {
+  try {
+    return JSON.parse(fileSystem.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+function loadPersonalConfig(options) {
+  const configPath = path.join(options.homeDir, '.tlc', 'config.json');
+  return readJson(configPath, options.fs);
+}
+function loadProjectOverride(options) {
+  const configPath = path.join(options.projectDir, '.tlc.json');
+  const data = readJson(configPath, options.fs);
+  return data && data.task_routing_override ? data.task_routing_override : null;
+}
+function resolveRouting(options) {
+  let models = ['claude'];
+  let strategy = 'single';
+  let source = 'shipped-defaults';
+  let providers;
+  const personal = loadPersonalConfig({ homeDir: options.homeDir, fs: options.fs });
+  if (personal) {
+    if (personal.model_providers) {
+      providers = personal.model_providers;
+    }
+    const personalRouting = personal.task_routing && personal.task_routing[options.command];
+    if (personalRouting) {
+      if (Array.isArray(personalRouting.models)) {
+        models = personalRouting.models.slice();
+      } else if (typeof personalRouting.model === 'string') {
+        models = [personalRouting.model];
+      }
+      if (personalRouting.strategy) {
+        strategy = personalRouting.strategy;
+      }
+      source = 'personal-config';
+    }
+  }
+  const projectOverride = loadProjectOverride({ projectDir: options.projectDir, fs: options.fs });
+  if (projectOverride) {
+    const overrideEntry = projectOverride[options.command];
+    if (overrideEntry) {
+      if (Array.isArray(overrideEntry.models)) {
+        models = overrideEntry.models.slice();
+      } else if (typeof overrideEntry.model === 'string') {
+        models = [overrideEntry.model];
+      }
+      if (overrideEntry.strategy) {
+        strategy = overrideEntry.strategy;
+      }
+      source = 'project-override';
+    }
+  }
+  if (options.flagModel) {
+    models = [options.flagModel];
+    strategy = 'single';
+    source = 'flag-override';
+  }
+  const result = { models, strategy, source };
+  if (providers) {
+    result.providers = providers;
+  }
+  return result;
+}
+const result = resolveRouting({ command: "tlc", flagModel: process.argv[1], projectDir: process.cwd(), homeDir: process.env.HOME || os.homedir(), fs });
+process.stdout.write(JSON.stringify(result));" 2>/dev/null
+   ```
+
+2. If `models[0]` is NOT `claude` (i.e., routed to external model):
+   - Resolve orchestration modules with fallback: try `tlc-claude-code/server/lib/...` first, then `$PROJECT_DIR/server/lib/...`
+   - Build the full prompt with `buildFullPrompt` from `orchestration/prompt-builder`
+   - Dispatch to the target provider CLI through unified routing, using `codex exec` or `gemini -p` as appropriate
+   - Capture provider output for memory with `captureFromProvider` from `capture`, display the CLI output, and stop — do NOT execute the agent prompt below
+
+3. If `models[0]` IS `claude` (or no routing config exists):
+   - Execute the agent prompt below as normal (current behavior)
+
+4. If `strategy` is `parallel`:
+   - Resolve orchestration modules with fallback: try `tlc-claude-code/server/lib/...` first, then `$PROJECT_DIR/server/lib/...`
+   - Execute inline (Claude) AND dispatch each external provider through unified routing
+   - After each provider completes, capture its output with `captureFromProvider` from `capture`
+   - Collect and merge results
+   - **CRITICAL: If a provider fails (wrong model, auth error, CLI missing), do NOT silently fall back to single-provider.** Instead:
+     1. Check `.tlc/.router-state.json` for the provider's actual available model and retry
+     2. If retry fails, ask the user: "[Provider] failed: [reason]. Run with [other provider] only, or fix and retry?"
+     3. Never say "proceeding with X-only" without user consent
+
+**Override:** Pass `--model <name>` to route this specific run to a different model.
+
+After `resolveRouting` returns, immediately write `.tlc/.tlc-routing-active` with the active provider name from `models[0]` before doing any other tlc work. Remove `.tlc/.tlc-routing-active` on completion, cancellation, or failure cleanup.
+
+**Routing decision:**
+- If routing says external provider (`models[0] !== 'claude'`), follow **ONLY ORCHESTRATOR MODE** below.
+- If routing says Claude (`models[0] === 'claude'`), follow **INLINE MODE** below.
+
+## ORCHESTRATOR MODE
+
+Use this mode only when `models[0]` is **NOT** `claude`.
+
+Claude does not execute the auto-runner instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Claude acts as the orchestrator for the routed `/tlc` auto-runner flow instead of executing the detection logic inline.
+2. Read the roadmap, phase artifacts, version context, and any routing or state files needed to determine the next safe action before dispatching.
+3. Package a prompt that asks the routed provider to perform the one-pass TLC state detection, choose the next non-destructive command, and produce the compact status output required by this command.
+4. Dispatch through the provider CLI path, using `codex exec` for Codex-style providers or `gemini -p` for Gemini-style providers, preferably via the shared dispatch layer when available.
+5. Verify the routed result before accepting it:
+   - Confirm it chose the active phase and next action from the actual repository state.
+   - Confirm it preserved the command's safety rules and did not auto-run destructive actions.
+   - Reject verbose, menu-driven, or repo-disconnected output that does not match `/tlc` behavior.
+6. If the routed result mis-detects state or picks the wrong next action, dispatch a corrective follow-up using the exact missing or conflicting evidence.
+7. Handle failures explicitly:
+   - If dispatch fails because of model mismatch, auth, or missing CLI, check `.tlc/.router-state.json` for the provider's actual available model and retry once with the corrected model.
+   - If retry still fails, stop and report the exact failure to the user. Do not silently fall back to Claude inline execution.
+   - If the provider returns incomplete status or action selection, reject it and request a constrained retry.
+8. When finished, display the routed `/tlc` result, persist any captured memory, remove `.tlc/.tlc-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing auto-runner instructions below are the Inline Mode instructions and should be followed unchanged.
+
 ## What This Does
 
 `/tlc` is the default entry point. It should: