tlc-claude-code 2.0.1 → 2.2.0

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

@@ -0,0 +1,134 @@
+# /tlc:preflight - Completeness Check Before Done
+
+Never declare a task complete without running this. Catches gaps, loose ends, and half-solutions before they ship.
+
+## Philosophy
+
+**Assume nothing is complete.** Every task has edges you didn't think about. This skill forces you to actively look for what's missing rather than confirming what's present.
+
+## When This Runs
+
+This is a **plugin** — it fires automatically via PostToolUse hook whenever Claude is about to declare work "done." You don't invoke it manually.
+
+It also runs:
+- After `/tlc:build` (via guard + preflight chain)
+- After any multi-file change
+- Before recommending a commit or push
+
+## Process
+
+### Step 1: Inventory What Was Changed
+
+List every file that was created, modified, or deleted in this session. For each one:
+- What was the intent?
+- Was the change completed or left partial?
+
+### Step 2: Trace All References
+
+For every file changed, check:
+- **Is it registered/imported where needed?** (e.g., new module added to an index, new command added to a commands array, new route added to a router)
+- **Does anything else reference it?** (e.g., config files, package.json, install scripts, documentation)
+- **Are there parallel systems that need the same update?** (e.g., install.js AND postinstall.js, package.json `files` AND `bin`, CLAUDE.md AND help.md)
+
+This is the #1 source of half-solutions: changing the thing but not updating everything that points to the thing.
+
+### Step 3: Check Consistency Across Layers
+
+For each change, verify consistency across ALL layers:
+
+| Layer | Check |
+|-------|-------|
+| **Source files** | Does the code do what was intended? |
+| **Tests** | Do tests exist and pass? |
+| **Config** | Are config files updated (package.json, .tlc.json, settings.json)? |
+| **Distribution** | Will this ship to end users? (files array, install scripts, postinstall) |
+| **Documentation** | Is the change reflected in docs, help text, command tables? |
+| **Integration** | Do other systems that depend on this still work? |
+
+### Step 4: Ask the Hard Questions
+
+Before declaring done, explicitly answer each:
+
+1. **"If someone installs this fresh right now, will it work?"**
+   - Not "does it work on my machine" — does it work from a clean install?
+
+2. **"What did I assume exists that might not?"**
+   - Files, directories, env vars, running services, permissions
+
+3. **"What's the blast radius?"**
+   - What else touches the same files/systems I changed?
+   - Did I update ALL of those touchpoints?
+
+4. **"Is there a parallel path I forgot?"**
+   - Two install scripts? Two config files? Multiple places the same list appears?
+
+5. **"What would a user try that I didn't test?"**
+   - Edge cases in usage, not just happy path
+
+### Step 5: Report
+
+**If gaps found:**
+```
+PREFLIGHT CHECK — GAPS FOUND
+
+Changes made: 3 files created, 2 files modified
+
+Gaps:
+1. Created new-feature.md but not added to COMMANDS array in install.js
+2. Modified settings.json but init.md template not updated to match
+3. No test file for new utility function
+
+Fix these before declaring done.
+```
+
+**If clean:**
+```
+PREFLIGHT CHECK — CLEAR
+
+Changes made: 3 files created, 2 files modified
+All references updated: ✅
+Distribution verified: ✅
+Tests exist: ✅
+Config consistent: ✅
+
+Task is complete.
+```
+
+## Common Gap Patterns
+
+These are the most frequent gaps this skill catches:
+
+| Pattern | Example |
+|---------|---------|
+| **Registry miss** | New file created but not added to install array, export list, or index |
+| **Parallel system miss** | Updated install.js but not postinstall.js |
+| **Config drift** | Changed settings.json but init.md still generates the old version |
+| **Distribution miss** | File exists in repo but won't ship (not in package.json files) |
+| **Doc drift** | New command added but not in CLAUDE.md dispatch table or help.md |
+| **Test miss** | New code without corresponding test |
+| **Cross-reference miss** | Renamed something but didn't grep for all references |
+
+## Example
+
+```
+PREFLIGHT CHECK — GAPS FOUND
+
+Session changes:
+  + .claude/commands/tlc/watchci.md (new skill)
+  + .claude/commands/tlc/e2e-verify.md (new skill)
+  + .claude/commands/tlc/guard.md (new skill)
+  + .claude/hooks/tlc-post-push.sh (new hook)
+  + .claude/hooks/tlc-post-build.sh (new hook)
+  ~ .claude/settings.json (added PostToolUse hooks)
+  ~ CLAUDE.md (added dispatch entries)
+
+Gaps:
+  ❌ watchci.md, e2e-verify.md, guard.md not in COMMANDS array (bin/install.js)
+  ❌ .claude/hooks/ not in package.json files array — won't ship
+  ❌ postinstall.js doesn't copy hooks — fresh install broken
+  ❌ init.md settings template doesn't include new hooks
+  ❌ help.md doesn't list new commands
+  ❌ bootstrap.md was already missing from COMMANDS array (pre-existing gap)
+
+6 gaps found. Fix before declaring done.
+```

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

@@ -0,0 +1,363 @@
+# /tlc:review-plan - Review a TLC Phase Plan
+
+Review a `.planning/phases/{N}-PLAN.md` file for structure, scope, architecture, and completeness. Uses Claude in-session plus Codex (if available) for consensus.
+
+## What This Does
+
+1. Auto-detects the target plan file (or uses the phase number you provide)
+2. **Runs Claude in-session analysis** against all quality dimensions
+3. **Invokes Codex** (if available in router state) for a second opinion
+4. Combines verdicts — both must APPROVE for overall APPROVED
+5. Generates a structured report with per-provider attribution
+
+## Usage
+
+```
+/tlc:review-plan        # Auto-detect latest PLAN.md
+/tlc:review-plan 7      # Review .planning/phases/7-PLAN.md
+/tlc:review-plan 12     # Review .planning/phases/12-PLAN.md
+```
+
+## Process
+
+### Step 1: Load Context
+
+**Read router state first**, then load the plan file.
+
+```javascript
+// 1. Read persistent router state (written by session-init hook)
+const routerState = JSON.parse(fs.readFileSync('.tlc/.router-state.json', 'utf-8'));
+
+// 2. Read config for capability mappings
+const config = JSON.parse(fs.readFileSync('.tlc.json', 'utf-8'));
+const reviewProviders = config.router?.capabilities?.['review-plan']?.providers
+  || config.router?.capabilities?.review?.providers
+  || ['claude'];
+
+// 3. Filter to only AVAILABLE providers (from state file)
+const availableReviewers = reviewProviders.filter(p =>
+  routerState.providers[p]?.available === true
+);
+```
+
+**The state file (`.tlc/.router-state.json`) is authoritative for availability.** Never run `which codex` yourself — read the state file. If the state file is missing or stale (>1 hour), probe manually and write a fresh one.
+
+**Locate the plan file:**
+
+```bash
+# If phase number provided (e.g., "7"):
+PLAN_FILE=".planning/phases/7-PLAN.md"
+
+# If no argument — find the highest-numbered PLAN.md:
+ls .planning/phases/*-PLAN.md | sort -t- -k1 -n | tail -1
+```
+
+Also optionally read for context (if they exist):
+- `.planning/phases/{N}-DISCUSSION.md` — design decisions
+- `PROJECT.md` — project name, tech stack
+- `.planning/ROADMAP.md` — phase dependencies
+
+### Step 2: Claude In-Session Review
+
+Analyze the plan across four dimensions. For each, produce a list of issues (empty = passing).
+
+#### Dimension 1: Structure
+
+Check every `### Task N:` block for:
+
+| Field | Check | Fail Condition |
+|-------|-------|----------------|
+| `**Goal:**` | Present and non-empty | Missing or blank |
+| `**Files:**` | At least one file listed | No files listed |
+| `**Acceptance Criteria:**` | At least one `- [ ]` checkbox | Missing or empty section |
+| `**Test Cases:**` | At least one bullet | Missing or empty section |
+
+#### Dimension 2: Scope
+
+| Check | Fail Condition |
+|-------|----------------|
+| Task title specificity | Title contains vague words: `system`, `entire`, `all`, `everything`, `complete`, `whole`, `full` |
+| Vertical slice | Task mixes unrelated concerns (e.g., "Add auth AND refactor DB") |
+| No files listed | Task has empty `**Files:**` section |
+
+#### Dimension 3: Architecture
+
+| Check | Fail Condition |
+|-------|----------------|
+| File line estimates | Any file has `estimated: NNN lines` where NNN > 1000 |
+| Folder density | Any folder listed that already has > 15 files (check disk if accessible) |
+| Module structure | Files dumped into flat `src/services/` or `src/controllers/` with > 5 items |
+
+#### Dimension 4: Completeness
+
+| Check | Fail Condition |
+|-------|----------------|
+| Prerequisites section | No `## Prerequisites` block in the plan |
+| Dependencies section | No `## Dependencies` block (warn, not fail) |
+| Phase ordering | Prerequisites reference phases that don't exist in ROADMAP (if readable) |
+
+#### Dimension 5: TDD Readiness
+
+Every task must have testable acceptance criteria:
+
+| Check | Fail Condition |
+|-------|----------------|
+| Criteria are checkboxes | Criteria written as prose instead of `- [ ] ...` checkboxes |
+| Criteria are specific | Criterion is too vague to write a test for (e.g., "works correctly") |
+| Test cases listed | `**Test Cases:**` section is absent or has zero items |
+| Test cases cover happy + sad paths | Only happy-path tests listed (warn) |
+
+**Scoring:**
+- 0 structure issues + 0 scope issues + 0 completeness issues + all tasks TDD-ready = **APPROVED**
+- Any issues in structure, completeness, or TDD = **CHANGES_REQUESTED**
+- Scope/architecture issues alone = **CHANGES_REQUESTED**
+
+### Step 3: Invoke Codex (if available)
+
+**CRITICAL: This step runs automatically when Codex is available in router state.**
+
+Check availability:
+```javascript
+const codexAvailable = routerState.providers?.codex?.available === true
+  && availableReviewers.includes('codex');
+```
+
+If Codex is available, invoke it with `exec` in read-only sandbox mode:
+
+```bash
+# Write the plan-review JSON schema to a temp file
+cat > /tmp/plan-review-schema.json << 'EOF'
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "required": ["verdict", "structureIssues", "scopeIssues", "suggestions"],
+  "properties": {
+    "verdict": { "type": "string", "enum": ["APPROVED", "CHANGES_REQUESTED"] },
+    "structureIssues": { "type": "array", "items": { "type": "string" } },
+    "scopeIssues":     { "type": "array", "items": { "type": "string" } },
+    "suggestions":     { "type": "array", "items": { "type": "string" } }
+  }
+}
+EOF
+
+# Invoke Codex with the plan content
+codex exec -s read-only --output-schema /tmp/plan-review-schema.json \
+  "Review this TLC phase plan for quality. Check:
+1. Structure: every task has Goal, Files, Acceptance Criteria (checkboxes), and Test Cases.
+2. Scope: no vague titles, each task is a vertical slice with specific deliverables.
+3. Architecture: no files planned >1000 lines, no folders >15 files.
+4. Completeness: Prerequisites section present, dependencies are explicit.
+5. TDD: every acceptance criterion is a testable, specific checkbox; test cases cover happy and sad paths.
+
+Respond with JSON matching the output schema.
+
+PLAN CONTENT:
+$(cat .planning/phases/${PHASE_NUMBER}-PLAN.md)"
+```
+
+If `codex exec` is not available (older Codex without `exec` subcommand), fall back to:
+
+```bash
+codex --print \
+  "Review this TLC phase plan. For each issue found, format as:
+  - [structure|scope|architecture|completeness|tdd] <description>
+End your response with either: Verdict: APPROVED or Verdict: CHANGES_REQUESTED
+
+$(cat .planning/phases/${PHASE_NUMBER}-PLAN.md)"
+```
+
+Parse the fallback output using the `Verdict: APPROVED|CHANGES_REQUESTED` pattern.
+
+**If Codex is unavailable:** Skip this step. Claude-only review proceeds. Note in the report: `Codex: unavailable (skipped)`.
+
+### Step 4: Combine Verdicts
+
+```
+Overall verdict rules:
+- ALL available providers approve  → APPROVED
+- ANY provider requests changes    → CHANGES_REQUESTED
+- Only 1 provider available        → that provider's verdict is final
+```
+
+Combine issues from all providers. Tag each issue with its source: `[Claude]` or `[Codex]`.
+
+### Step 5: Generate Report
+
+```markdown
+# Plan Review Report
+
+**Plan:** .planning/phases/{N}-PLAN.md
+**Phase:** {N}
+**Tasks:** {count}
+**Date:** {ISO timestamp}
+
+## Verdict: APPROVED | CHANGES_REQUESTED
+
+## Dimension Results
+
+### Structure
+  ✅ All tasks have Goal, Files, Acceptance Criteria, and Test Cases
+  — or —
+  ❌ 2 tasks missing acceptance criteria
+  ├── Task 3: "Add OAuth flow" — missing **Acceptance Criteria:** section
+  └── Task 5: "Write migration" — missing **Test Cases:** section
+
+### Scope
+  ✅ All task titles are specific and scoped
+  — or —
+  ⚠️  Task 2: "Complete user system" — title too vague (contains "complete", "system")
+
+### Architecture
+  ✅ No files planned over 1000 lines
+  ✅ No folders over 15 files
+
+### Completeness
+  ✅ Prerequisites section present
+  ⚠️  No ## Dependencies section (recommended)
+
+### TDD Readiness
+  ✅ All tasks have testable criteria as checkboxes
+  — or —
+  ❌ Task 4 criteria written as prose, not checkboxes
+
+## Provider Results
+
+  ✅ Claude:  APPROVED
+  ✅ Codex:   APPROVED (GPT-5.2)
+  — or —
+  ❌ Codex:   unavailable (skipped)
+
+## Combined Issues
+
+  [Claude] Task 3 missing acceptance criteria
+  [Codex]  Task 2 scope too broad — split into separate tasks
+
+## Action Required
+
+1. Add **Acceptance Criteria:** checkboxes to Task 3
+2. Narrow Task 2 title and split "auth" from "profile" concerns
+3. Add test cases covering auth failure paths in Task 1
+```
+
+## Example Output
+
+### Plan Passes Review
+
+```
+/tlc:review-plan 7
+
+Loading router state from .tlc/.router-state.json...
+  Plan review providers: claude, codex
+
+Target plan: .planning/phases/7-PLAN.md (5 tasks)
+
+─────────────────────────────────────────
+Claude in-session review...
+─────────────────────────────────────────
+
+Structure:    ✅ All 5 tasks complete
+Scope:        ✅ All titles specific
+Architecture: ✅ No oversized files planned
+Completeness: ✅ Prerequisites present
+TDD:          ✅ All criteria as checkboxes
+
+Claude verdict: ✅ APPROVED
+
+─────────────────────────────────────────
+Invoking Codex (GPT-5.2) for plan review...
+─────────────────────────────────────────
+
+Codex verdict: ✅ APPROVED
+  - Clear task decomposition
+  - Good test coverage planning
+  - Prerequisites are explicit
+
+Provider Results:
+  ✅ Claude: APPROVED
+  ✅ Codex:  APPROVED
+
+─────────────────────────────────────────
+✅ APPROVED — Plan is ready for /tlc:build (2/2 agree)
+─────────────────────────────────────────
+```
+
+### Plan Needs Changes
+
+```
+/tlc:review-plan 12
+
+Loading router state from .tlc/.router-state.json...
+  Plan review providers: claude, codex
+
+Target plan: .planning/phases/12-PLAN.md (4 tasks)
+
+─────────────────────────────────────────
+Claude in-session review...
+─────────────────────────────────────────
+
+Structure:    ❌ 2 issues
+  ├── Task 2: missing **Acceptance Criteria:**
+  └── Task 4: missing **Test Cases:**
+Scope:        ⚠️  1 issue
+  └── Task 1: "Complete full system" — title too vague
+Architecture: ✅ No oversized files planned
+Completeness: ❌ 1 issue
+  └── No ## Prerequisites section
+TDD:          ❌ 1 issue
+  └── Task 3: criteria written as prose, not checkboxes
+
+Claude verdict: ❌ CHANGES_REQUESTED
+
+─────────────────────────────────────────
+Invoking Codex (GPT-5.2) for plan review...
+─────────────────────────────────────────
+
+Codex verdict: ❌ CHANGES_REQUESTED
+  - Task 2 has no way to verify completion
+  - Task 1 scope covers too many concerns
+  - Missing error-path test cases throughout
+
+Provider Results:
+  ❌ Claude: CHANGES_REQUESTED
+  ❌ Codex:  CHANGES_REQUESTED
+
+Combined Issues:
+  [Claude] Task 2 missing acceptance criteria
+  [Claude] Task 4 missing test cases
+  [Claude] Task 1 title too vague ("complete", "system")
+  [Claude] No ## Prerequisites section
+  [Claude] Task 3 criteria are prose, not checkboxes
+  [Codex]  Task 2 has no verifiable completion criteria
+  [Codex]  Task 1 mixes auth, profile, and settings concerns
+  [Codex]  Missing error/failure path test cases in Tasks 1–3
+
+─────────────────────────────────────────────────────
+❌ CHANGES_REQUESTED (0/2 approved)
+
+Action required:
+1. Add **Acceptance Criteria:** checkboxes to Task 2
+2. Add **Test Cases:** to Task 4
+3. Rename Task 1 — split auth/profile/settings into separate tasks
+4. Add ## Prerequisites section listing prior phases
+5. Rewrite Task 3 criteria as - [ ] checkboxes
+6. Add sad-path test cases to Tasks 1–3 (Codex)
+─────────────────────────────────────────────────────
+```
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `--no-external` | Skip Codex, use Claude only |
+| `--codex-only` | Use only Codex (skip Claude in-session deep checks) |
+| `--strict` | Treat warnings (vague titles, missing deps) as failures |
+
+## Integration
+
+This review runs automatically:
+- At the end of `/tlc:plan` (informational — does not block)
+- Can be run manually before `/tlc:build` to validate a plan
+
+## ARGUMENTS
+
+$ARGUMENTS