tlc-claude-code 2.5.0 → 2.6.0

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

@@ -97,6 +97,40 @@ 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/.discuss-routing-active` with the active provider name from `models[0]` before doing any other discuss work. Remove `.tlc/.discuss-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 discussion instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Claude acts as the orchestrator for the routed implementation discussion instead of running the interview inline.
+2. Scan the roadmap, discussion history, relevant code, recent changes, and project conventions before dispatching discussion work.
+3. Package a prompt that asks the routed provider to propose a concrete implementation approach first, then surface only the highest-value confirm-or-correct questions.
+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 discussion output before accepting it:
+   - Confirm it reflects the actual repo context instead of asking the user to restate known facts.
+   - Confirm it leads with a recommendation, then asks only material decision questions.
+   - Reject vague brainstorming output or question lists that do not advance the phase.
+6. If the routed response misses key architectural context or asks low-value questions, issue a focused follow-up dispatch to tighten the discussion.
+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 weak discovery output, reject it and rerun with explicit context and decision targets.
+8. When finished, display the routed discussion result, persist any captured memory, remove `.tlc/.discuss-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing discussion instructions below are the Inline Mode instructions and should be followed unchanged.
+
+
 ## What This Does
 
 Runs a short implementation interview for the current phase using a silent expansion workflow:

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

@@ -95,7 +95,41 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
    - Execute inline (Claude) AND dispatch to CLI models simultaneously
    - Collect and merge results
 
-**Override:** Pass `--model <name>` to route this specific run to a different model.
+**Override:** Pass `--model <name>` to route this specific run to a different model.
+
+After `resolveRouting` returns, immediately write `.tlc/.docs-routing-active` with the active provider name from `models[0]` before doing any other docs work. Remove `.tlc/.docs-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 documentation instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Claude acts as the orchestrator for routed documentation work instead of maintaining docs inline.
+2. Gather the relevant repository context, documentation targets, configured docs settings, and any screenshot or API-doc generation expectations before dispatch.
+3. Break the docs work into focused slices when useful, such as README updates, API docs generation, screenshot capture guidance, or automation setup.
+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 the documentation changes match the current codebase and command intent.
+   - Confirm generated instructions or automation steps are specific enough to execute in this repo.
+   - Reject stale, generic, or obviously hallucinated documentation output.
+6. If the routed work comes back incomplete, dispatch follow-up tasks for the missing documentation slices rather than declaring success.
+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 low-confidence docs or broken setup steps, request a targeted correction before continuing.
+8. When finished, display the routed documentation result, persist any captured memory, remove `.tlc/.docs-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing documentation instructions below are the Inline Mode instructions and should be followed unchanged.
+
 
 ## Usage
 

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

@@ -0,0 +1,300 @@
+# /tlc:e2e - Generate Phase E2E Tests
+
+Parse acceptance criteria from a phase `PLAN.md`, generate matching E2E test files, scaffold an E2E framework if missing, run the generated tests to verify they execute, and commit the result.
+
+## 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: \"e2e\", 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`:
+   - Read `PROJECT.md`, the target phase `PLAN.md`, and `.tlc.json`
+   - Package the agent prompt below with project context
+   - Dispatch to the routed CLI
+   - Display the CLI output and stop
+
+3. If `models[0]` IS `claude`:
+   - Execute the agent prompt below as normal
+
+4. If `strategy` is `parallel`:
+   - Execute inline and dispatch to external providers simultaneously
+   - Collect and merge results
+
+**Override:** Pass `--model <name>` to route this specific run to a different model.
+
+After `resolveRouting` returns, immediately write `.tlc/.e2e-routing-active` with the active provider name from `models[0]` before doing any other e2e work. Remove `.tlc/.e2e-routing-active` on completion, cancellation, or failure cleanup.
+
+## What This Does
+
+1. Resolves the target phase
+2. Reads the phase `PLAN.md`
+3. Parses task acceptance criteria into automatable E2E scenarios
+4. Detects or scaffolds an E2E framework
+5. Generates E2E test files
+6. Runs only the generated tests to verify they execute
+7. Reports `N generated, M skipped (manual)`
+8. Commits the generated files and framework scaffolding
+
+## Usage
+
+```text
+/tlc:e2e
+/tlc:e2e 7
+```
+
+If no phase is provided, auto-detect the active phase from `ROADMAP.md` or fall back to the latest incomplete phase plan.
+
+## Process
+
+### Step 1: Resolve the Target Phase
+
+Determine the phase in this order:
+
+1. Explicit `[phase]` argument
+2. Active/current/in-progress phase in `ROADMAP.md`
+3. Highest-numbered `.planning/phases/*-PLAN.md` without a matching `*-VERIFIED.md`
+
+Target file:
+
+```text
+.planning/phases/{N}-PLAN.md
+```
+
+If the plan file does not exist, stop and report the missing path.
+
+### Step 2: Load Plan Context
+
+Read:
+- `.planning/phases/{N}-PLAN.md`
+- `.planning/phases/{N}-DISCUSSION.md` if present
+- `PROJECT.md` if present
+- `.tlc.json` if present
+
+Extract each task block and its acceptance criteria. Use the acceptance criteria as the source of truth for E2E generation.
+
+### Step 3: Parse Acceptance Criteria
+
+Use `server/lib/e2e/acceptance-parser.js` to normalize acceptance criteria for each task.
+
+Rules:
+- Parse task-by-task, not as one giant phase blob
+- Preserve the task title as the scenario name
+- Treat parser items with `type: 'manual'` as manual verification only
+- Do not generate automated tests for manual-only criteria
+- If a task has both automatable and manual criteria, generate tests for the automatable criteria and count the manual criteria as skipped
+
+Summary counters:
+- `generated`: number of generated E2E files written
+- `skipped (manual)`: number of acceptance criteria skipped because they require manual verification
+
+### Step 4: Detect or Scaffold the E2E Framework
+
+Use `server/lib/e2e/framework-detector.js`.
+
+Framework selection rules:
+- If Playwright is already configured, use Playwright
+- Else if the repo already uses `supertest` for API-level E2E coverage, use Supertest
+- Else scaffold Playwright by default
+
+When scaffolding Playwright:
+- Add `playwright.config.ts` if missing
+- Create `tests/e2e/` if no E2E directory exists
+- Add `@playwright/test` to `devDependencies` if missing
+- Add or update package scripts so generated tests can run cleanly
+
+When scaffolding Supertest:
+- Only choose this path for service-only repos with an existing Vitest/Jest-style API test setup
+- Reuse the project's current test runner instead of inventing a new one
+
+Do not replace an established framework just because another one is available.
+
+### Step 5: Generate Test Files
+
+Use `server/lib/e2e/test-generator.js` to generate the file bodies, then write the files into the detected E2E directory.
+
+Generation rules:
+- One generated file per task/scenario
+- Generated files must map directly to that task's acceptance criteria
+- Add a short generated header comment at the top of each file:
+  `Generated by /tlc:e2e from .planning/phases/{N}-PLAN.md`
+- Prefer stable filenames derived from the task title slug
+- Keep generated files idempotent: if the command is run again, update previously generated files in place
+- Never overwrite clearly hand-written E2E files that do not contain the generated header comment
+
+If a target file already exists and appears hand-written:
+- Skip it
+- Report it separately as a preserved manual file
+- Do not include it in `skipped (manual)` unless the acceptance criteria were also classified as manual
+
+### Step 6: Run the Generated Tests
+
+Run only the generated files.
+
+Playwright:
+```bash
+npx playwright test <generated-files> --reporter=list
+```
+
+Supertest with Vitest:
+```bash
+npx vitest run <generated-files>
+```
+
+Verification rules:
+- The generated tests must be discovered by the runner
+- They must execute without syntax errors, import errors, or framework bootstrapping failures
+- If the framework was scaffolded, verify the scaffolding in the same run
+- If execution fails because the repo is missing dependencies, install the minimum required dependencies and rerun
+- If execution still fails, stop and report the exact failure instead of committing broken scaffolding
+
+### Step 7: Commit
+
+Commit when done. This is mandatory if generation and execution verification succeed.
+
+Stage only the files created or updated for this command:
+- Generated E2E files
+- Framework config or package manifest changes required for E2E
+- Lockfile updates if dependencies were installed
+
+Commit message:
+
+```bash
+git commit -m "test(e2e): generate phase {N} coverage"
+```
+
+### Step 8: Report
+
+Return a compact summary:
+
+```text
+Phase {N} E2E generation complete
+Framework: playwright | supertest
+Generated: {N}
+Skipped (manual): {M}
+Preserved manual files: {K}
+Verification: passed
+Commit: {sha}
+```
+
+If verification failed, report:
+- framework used
+- generated file count
+- skipped manual count
+- exact command run
+- exact error
+- whether files were left uncommitted
+
+## Guard Rails
+
+- Do not invent scenarios not grounded in acceptance criteria
+- Do not overwrite hand-written E2E tests
+- Do not claim success if the generated tests were not actually executed
+- Do not commit if execution verification failed
+- Keep generation scoped to the requested phase
+- Prefer preserving existing repo conventions over TLC defaults
+
+## Example
+
+```text
+> /tlc:e2e 7
+
+Loading .planning/phases/7-PLAN.md...
+Parsing acceptance criteria...
+
+Detected framework: none
+Scaffolding Playwright...
+
+Generating E2E files...
+  Created tests/e2e/user-login.test.ts
+  Created tests/e2e/reset-password.test.ts
+  Created tests/e2e/session-timeout.test.ts
+
+Running generated tests...
+  3 files discovered
+  3 files executed successfully
+
+Committed: test(e2e): generate phase 7 coverage
+
+Phase 7 E2E generation complete
+Framework: playwright
+Generated: 3
+Skipped (manual): 2
+Preserved manual files: 0
+Verification: passed
+Commit: abc1234
+```

package/.claude/commands/tlc/edge-cases.md

@@ -95,7 +95,41 @@ process.stdout.write(JSON.stringify(result));" 2>/dev/null
    - Execute inline (Claude) AND dispatch to CLI models simultaneously
    - Collect and merge results
 
-**Override:** Pass `--model <name>` to route this specific run to a different model.
+**Override:** Pass `--model <name>` to route this specific run to a different model.
+
+After `resolveRouting` returns, immediately write `.tlc/.edge-cases-routing-active` with the active provider name from `models[0]` before doing any other edge-cases work. Remove `.tlc/.edge-cases-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 edge-case generation instructions inline in this path. Claude acts as the orchestrator for the routed provider run:
+
+1. Claude acts as the orchestrator for routed edge-case analysis and test generation instead of doing that analysis inline.
+2. Read the target file or function context, current test setup, and project conventions before dispatching the request.
+3. Package a prompt that asks the routed provider to identify meaningful edge cases, generate test coverage for them, and keep the output aligned with the project's existing test patterns.
+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 the generated edge cases are grounded in the actual target behavior and parameter surface.
+   - Confirm the tests are non-duplicative and materially improve coverage.
+   - Reject generic or mechanically generated cases that do not map to the real code.
+6. If the routed output misses important boundary conditions or produces weak tests, dispatch a focused follow-up for the missing scenarios.
+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 malformed or low-value test output, reject it and request a constrained retry.
+8. When finished, display the routed edge-case result, persist any captured memory, remove `.tlc/.edge-cases-routing-active`, and stop. Do **not** execute Inline Mode afterward.
+
+## INLINE MODE
+
+Use this mode only when `models[0]` **IS** `claude`.
+
+The existing edge-case generation instructions below are the Inline Mode instructions and should be followed unchanged.
+
 
 ## What This Does
 

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

@@ -136,7 +136,37 @@ Add test scripts to package.json:
 }
 ```
 
-### 5. If Tests Already Exist
+### 5. Scaffold Observability
+
+1. Detect deploy target: run `server/lib/scaffolding/deploy-detector.js` `detectDeployTarget({ projectDir })`
+   - If result is `"unknown"`, ask user: `"Deploy target? 1) Docker Compose 2) Kubernetes/k3s 3) VPS 4) Not sure"`
+   - Store result in `.tlc.json` under `deploy.target`
+2. Scaffold logger: run `server/lib/scaffolding/logger-scaffold.js` `scaffoldLogger({ projectDir, language })`
+   - If skipped (existing logger found), report: `"Existing logger detected — skipping"`
+   - If generated, report files created and dependencies to install
+3. Scaffold health endpoint: run `server/lib/scaffolding/health-scaffold.js` `scaffoldHealth({ projectDir, deployTarget, framework })`
+   - Report endpoint(s) created
+4. Enable snapshots: add to `.tlc.json`: `{ snapshots: { enabled: true, maxRetention: 10 } }`
+
+### 6. Detect CI/CD
+
+After observability scaffolding, inspect the project's CI/CD posture:
+
+1. Detect CI: run `server/lib/scaffolding/ci-detector.js` `detectCI({ projectDir, fs })`
+   - Use the detector result fields: `platform`, `workflows`, and `gaps`
+   - Recognize `no-ci`, `missing-test-step`, `missing-deploy-step`, and `missing-coverage-upload`
+2. If no CI is found (`platform === "none"` or `gaps` includes `no-ci`):
+   - Scaffold GitHub Actions using `server/lib/scaffolding/ci-scaffolder.js`
+   - Report the workflow files created and any required secrets or environment variables
+3. If CI exists but has gaps:
+   - Report the existing CI platform and workflow files detected
+   - Report the missing capabilities from `gaps`
+   - Offer to fill the gaps instead of replacing the existing CI
+4. If CI is complete (`gaps.length === 0`):
+   - Report: `"CI/CD OK"`
+   - Include detected platform and workflow file paths in the summary
+
+### 7. If Tests Already Exist
 
 - Skip framework setup
 - Note existing test patterns for consistency
@@ -170,7 +200,7 @@ If option 2 selected, create multi-framework config:
 }
 ```
 
-### 6. Analyze Existing Code Structure
+### 8. Analyze Existing Code Structure
 
 Scan the codebase and generate summary:
 - Main directories and their purpose
@@ -178,7 +208,7 @@ Scan the codebase and generate summary:
 - Entry points (main files, API routes, etc.)
 - Dependencies and their roles
 
-### 7. Identify Untested Code
+### 9. Identify Untested Code
 
 Compare source files against test files to identify:
 - Modules/components with no corresponding tests
@@ -201,7 +231,7 @@ Untested:
 Critical paths without tests: 2 (auth, payments)
 ```
 
-### 8. Offer Retrospective Test Writing
+### 10. Offer Retrospective Test Writing
 
 Ask the user:
 
@@ -406,7 +436,7 @@ Create `.claude/settings.json`:
 
 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
+### 11. Create or Update PROJECT.md
 
 If PROJECT.md doesn't exist, create it with:
 
@@ -441,7 +471,7 @@ Tests are written BEFORE implementation, not after.
 
 If PROJECT.md exists, append the TLC section only.
 
-### 11. Set Up Documentation (Optional)
+### 12. Set Up Documentation (Optional)
 
 If the project doesn't have docs automation:
 
@@ -459,7 +489,7 @@ Set up documentation automation? (Y/n)
 
 If yes, run `/tlc:docs setup`.
 
-### 12. Enterprise Features (Optional)
+### 13. Enterprise Features (Optional)
 
 After basic setup, offer enterprise features:
 
@@ -505,7 +535,7 @@ Commands available:
   /tlc:compliance  - SOC 2 compliance dashboard
 ```
 
-### 13. Report Summary
+### 14. Report Summary
 
 ```
 TLC initialized for [project name]

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

@@ -8,6 +8,7 @@ Initialize a new project with test-led development.
 2. Suggest tech stack based on your needs
 3. Create roadmap
 4. Set up test infrastructure
+5. Set up baseline CI workflow
 
 ## Process
 
@@ -146,6 +147,7 @@ Create PROJECT.md with tech decisions:
 | Database | PostgreSQL | Relational data needs |
 | Architecture | Modular monolith | Start simple |
 | Hosting | Docker + Railway | Easy CI/CD |
+| CI/CD | GitHub Actions | Baseline test and deploy workflow |
 
 ## Constraints
 - Timeline: MVP in 4 weeks
@@ -272,6 +274,9 @@ Scaffold based on chosen stack:
 project/
 ├── src/
 ├── test/
+├── .github/
+│   └── workflows/
+│       └── ci.yml
 ├── .env.example
 ├── .tlc.json
 ├── .mocharc.json
@@ -309,7 +314,43 @@ Add to `package.json`:
 }
 ```
 
-### Step 9: Set Up Documentation (Optional)
+### Step 9: Scaffold Observability
+
+During project template generation, scaffold observability alongside the rest of the project setup:
+
+1. Detect deploy target: run `server/lib/scaffolding/deploy-detector.js` `detectDeployTarget({ projectDir })`
+   - If result is `"unknown"`, ask user: `"Deploy target? 1) Docker Compose 2) Kubernetes/k3s 3) VPS 4) Not sure"`
+   - Store result in `.tlc.json` under `deploy.target`
+2. Scaffold logger: run `server/lib/scaffolding/logger-scaffold.js` `scaffoldLogger({ projectDir, language })`
+   - If skipped (existing logger found), report: `"Existing logger detected — skipping"`
+   - If generated, report files created and dependencies to install
+3. Scaffold health endpoint: run `server/lib/scaffolding/health-scaffold.js` `scaffoldHealth({ projectDir, deployTarget, framework })`
+   - Report endpoint(s) created
+4. Enable snapshots: add to `.tlc.json`: `{ snapshots: { enabled: true, maxRetention: 10 } }`
+
+### Step 10: Detect and Scaffold CI Workflow
+
+During project template generation, add CI/CD setup after observability:
+
+1. Detect CI: run `server/lib/scaffolding/ci-detector.js` `detectCI({ projectDir, fs })`
+   - Inspect `platform`, `workflows`, and `gaps`
+2. If no CI is found (`platform === "none"` or `gaps` includes `no-ci`):
+   - Scaffold GitHub Actions using `server/lib/scaffolding/ci-scaffolder.js`
+   - Include at least one workflow in `.github/workflows/` for tests, coverage, and deploy handoff where appropriate
+   - Report files created plus any secrets or variables still required
+3. If CI already exists but has gaps:
+   - Report the existing platform and workflow files
+   - Report the gaps found by the detector
+   - Offer to fill the gaps without replacing the current CI setup
+4. If CI is complete (`gaps.length === 0`):
+   - Report: `"CI/CD OK"`
+
+Add CI metadata to the generated project template where applicable:
+- CI platform: `[github-actions|jenkins|gitlab|circleci|none]`
+- CI workflows: `[paths created or detected]`
+- CI gaps: `[none|gap list]`
+
+### Step 11: Set Up Documentation (Optional)
 
 Offer to set up documentation automation:
 
@@ -330,7 +371,7 @@ If yes, run the docs setup:
 - Add `.github/workflows/docs-sync.yml`
 - Add npm scripts for docs maintenance
 
-### Step 10: Enterprise Features (Optional)
+### Step 12: Enterprise Features (Optional)
 
 If compliance requirements were mentioned in Step 1, or for enterprise projects:
 
@@ -395,5 +436,6 @@ Interactive flow that:
 3. Lets you adjust
 4. Creates roadmap
 5. Sets up tests
-6. Sets up documentation automation
-7. Optionally enables enterprise features
+6. Scaffolds observability
+7. Sets up documentation automation
+8. Optionally enables enterprise features

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:**