tlc-claude-code 2.1.0 → 2.2.0

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

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

@@ -1,6 +1,6 @@
 # /tlc:review - Review Current Branch
 
-Review changes on current branch before pushing.
+Review changes on current branch before pushing. **Runs in a loop until clean.**
 
 ## What This Does
 
@@ -9,7 +9,10 @@ Review changes on current branch before pushing.
 3. Checks test coverage for all changed files
 4. Analyzes commit order for TDD compliance
 5. Scans for security issues
-6. Generates verdict: APPROVED or CHANGES_REQUESTED
+6. If issues found → **fix them automatically, then re-review**
+7. **Repeats until both Claude and Codex approve** — no arbitrary limit, runs until clean
+
+**This is an iterative review loop, not a single pass.** Think of it as RL-mode: keep fixing and re-checking until the code is foolproof.
 
 **This runs automatically at the end of `/tlc:build`.**
 
@@ -192,52 +195,38 @@ For each provider in `reviewProviders` (except `claude` which is the current ses
 
 **How to invoke:**
 
-1. **Save diff to temporary file with size limit** (max 500 lines per chunk):
+**Codex** — use its built-in `review` subcommand. It reads the git diff natively, no need to pipe files:
+
 ```bash
-# Get diff and check size
-git diff main...HEAD > /tmp/review-diff-full.patch
-line_count=$(wc -l < /tmp/review-diff-full.patch)
+# Review current branch against main (default)
+codex review --base main "Focus on: bugs, security issues, missing edge cases, test coverage gaps. End with APPROVED or CHANGES_REQUESTED."
 
-if [ "$line_count" -gt 500 ]; then
-  echo "⚠️ Large diff ($line_count lines) - chunking for review..."
-
-  # Split by file for targeted review
-  git diff --name-only main...HEAD | while read file; do
-    git diff main...HEAD -- "$file" > "/tmp/review-chunk-${file//\//_}.patch"
-  done
-
-  # Or truncate with warning
-  head -500 /tmp/review-diff-full.patch > /tmp/review-diff.patch
-  echo "... truncated (showing first 500 of $line_count lines)" >> /tmp/review-diff.patch
-else
-  cp /tmp/review-diff-full.patch /tmp/review-diff.patch
-fi
-```
+# Review uncommitted changes only
+codex review --uncommitted
 
-2. **Invoke each configured provider** (one chunk at a time if split):
+# Review a specific commit
+codex review --commit <sha>
 
-```bash
-# For Codex (GPT-5.2) - detailed review prompt
-codex --print "You are a senior code reviewer. Analyze this diff thoroughly:
+# Custom instructions via prompt
+codex review --base main "Check for TDD compliance: were tests written before implementation? Flag any implementation without corresponding test files."
+```
 
-1. **Line-by-line Analysis**: Comment on specific lines with issues
-2. **Bugs**: Identify potential bugs, edge cases, null checks
-3. **Security**: SQL injection, XSS, command injection, auth issues
-4. **Performance**: N+1 queries, unnecessary loops, memory leaks
-5. **Code Quality**: Naming, duplication, complexity, SOLID principles
-6. **Test Coverage**: Are the changes properly tested?
+`codex review` outputs a structured review to stdout. No `--print` flag needed — it's already non-interactive.
 
-For each issue found:
-- File and line number
-- Severity (critical/high/medium/low)
-- What's wrong
-- How to fix it
+**Gemini** — no built-in review command, so save diff and invoke:
 
-End with: APPROVED (no critical/high issues) or CHANGES_REQUESTED (has critical/high issues)
+```bash
+# Save diff for Gemini
+git diff main...HEAD > /tmp/review-diff.patch
+line_count=$(wc -l < /tmp/review-diff.patch)
 
-File: /tmp/review-diff.patch"
+# Truncate if too large
+if [ "$line_count" -gt 500 ]; then
+  head -500 /tmp/review-diff.patch > /tmp/review-diff-truncated.patch
+  echo "... truncated (showing first 500 of $line_count lines)" >> /tmp/review-diff-truncated.patch
+  mv /tmp/review-diff-truncated.patch /tmp/review-diff.patch
+fi
 
-# For Gemini - detailed review prompt
 gemini --print "Review this code diff as a senior engineer. Provide:
 - Specific line-by-line feedback
 - Security vulnerabilities with file:line references
@@ -245,14 +234,10 @@ gemini --print "Review this code diff as a senior engineer. Provide:
 - Code quality issues
 - Missing test coverage
 
-Be thorough and specific. File: /tmp/review-diff.patch"
-```
+Be thorough and specific. End with APPROVED or CHANGES_REQUESTED.
 
-**Large Diff Handling:**
-- Diffs over 500 lines are automatically chunked by file
-- Each file's changes reviewed separately
-- Results aggregated across all chunks
-- Alternative: truncate with warning (shows first 500 lines)
+$(cat /tmp/review-diff.patch)"
+```
 
 **Note:** Each CLI has its own syntax. Check `codex --help` and `gemini --help` for exact flags. The `--print` flag outputs the response without interactive mode.
 
@@ -277,7 +262,124 @@ Invoking Codex (GPT-5.2) for review...
 - Any CHANGES_REQUESTED = overall CHANGES_REQUESTED
 - Issues from all providers are combined in the report
 
-### Step 7: Generate Report
+### Step 7: Fix-and-Recheck Loop (RL Mode)
+
+**This is the core innovation. Reviews are not one-shot — they loop until clean.**
+
+After Steps 2-6 complete, if ANY issues were found:
+
+```
+┌─────────────────────────────────────────────┐
+│  REVIEW LOOP (runs until clean)             │
+│                                             │
+│  1. Collect all issues from Claude + Codex  │
+│  2. Fix each issue:                         │
+│     - Missing tests → write them            │
+│     - Security issues → patch the code      │
+│     - Coding standards → refactor           │
+│     - Codex feedback → apply fixes          │
+│  3. Run tests to verify fixes don't break   │
+│  4. Commit fixes                            │
+│  5. Re-run Steps 2-6 (full review again)    │
+│  6. If new issues → loop back to 1          │
+│  7. If clean → exit loop, generate report   │
+└─────────────────────────────────────────────┘
+```
+
+**Iteration rules:**
+
+1. **No arbitrary limit** — keep looping until BOTH providers return APPROVED. The code isn't done until it's clean.
+2. **Each iteration runs the FULL check** — don't skip steps. Fresh eyes each time.
+3. **Re-invoke Codex each iteration** — `codex review --base main` sees the latest fixes
+4. **Commit after each fix round** — `git commit -m "fix: address review feedback (round N)"`
+5. **Track what was fixed** — maintain a running list for the final report
+6. **Stuck detection** — if the SAME issue appears 3 times after being "fixed", stop and escalate to the user with context on what was tried. This is the only exit condition besides clean.
+
+**Fix priority order:**
+1. Security issues (HIGH severity) — fix these first, they block everything
+2. Missing tests — write them before touching implementation
+3. Implementation bugs flagged by Codex — apply fixes
+4. Coding standards (file size, `any` types, return types) — refactor
+5. Style/naming/docs — lowest priority, fix if time permits
+
+**What gets auto-fixed vs flagged for human:**
+
+| Issue Type | Auto-Fix | Human Review |
+|-----------|----------|--------------|
+| Missing test file | Write it | - |
+| Hardcoded secret | Replace with env var | If unclear what var to use |
+| `any` type | Replace with proper interface | If domain type unclear |
+| File >1000 lines | Split into sub-modules | If split strategy unclear |
+| Security vulnerability | Patch it | If fix might break behavior |
+| Codex-flagged bug | Apply suggestion | If suggestion conflicts with Claude |
+| Merge conflict | - | Always human |
+
+**Example iteration:**
+
+```
+───────────────────────────────────────
+Review Round 1/5
+───────────────────────────────────────
+Claude: CHANGES_REQUESTED
+  - Missing test for src/utils.js
+  - Hardcoded API key in src/config.js
+Codex:  CHANGES_REQUESTED
+  - Missing null check in src/parser.js:42
+  - No error handling in src/api.js:88
+
+Fixing 4 issues...
+  ✅ Created src/utils.test.js (3 tests)
+  ✅ Replaced hardcoded key with process.env.API_KEY
+  ✅ Added null check in parser.js:42
+  ✅ Added try/catch in api.js:88
+  ✅ All tests pass
+  ✅ Committed: fix: address review feedback (round 1)
+
+───────────────────────────────────────
+Review Round 2/5
+───────────────────────────────────────
+Claude: CHANGES_REQUESTED
+  - src/utils.test.js missing edge case for empty input
+Codex:  APPROVED
+
+Fixing 1 issue...
+  ✅ Added empty input edge case test
+  ✅ All tests pass
+  ✅ Committed: fix: address review feedback (round 2)
+
+───────────────────────────────────────
+Review Round 3/5
+───────────────────────────────────────
+Claude: APPROVED
+Codex:  APPROVED
+
+✅ All providers agree — exiting loop.
+───────────────────────────────────────
+```
+
+**Stuck detection (only exit besides clean):**
+
+```
+───────────────────────────────────────
+Review Round 7
+───────────────────────────────────────
+Claude: APPROVED
+Codex:  CHANGES_REQUESTED
+  - Complex refactor needed in src/legacy.js  ← appeared 3 times
+
+⚠️ STUCK: This issue has reappeared 3 times after being fixed.
+Escalating to human review.
+
+Attempts made:
+  Round 3: Extracted helper function → Codex still flagged
+  Round 5: Split into two modules → Codex still flagged
+  Round 7: Added interface layer → Codex still flagged
+
+This needs human judgment. Run /tlc:review again after manual fix.
+───────────────────────────────────────
+```
+
+### Step 8: Generate Report
 
 ```markdown
 # Code Review Report
@@ -305,14 +407,11 @@ Invoking Codex (GPT-5.2) for review...
 - TDD Score: 75%
 ```
 
-### Step 8: Return Verdict
+### Step 9: Return Verdict
 
-**APPROVED** - All checks pass. Ready to push/merge.
+**APPROVED** - All providers agree after N iterations. Ready to push/merge.
 
-**CHANGES_REQUESTED** - Issues found:
-- Missing tests → Add tests for flagged files
-- Low TDD score → Consider reordering commits or adding test commits
-- Security issues → Fix flagged patterns
+**CHANGES_REQUESTED** - Max iterations reached with remaining issues. Needs human review.
 
 ## Example Output
 
@@ -433,6 +532,9 @@ Action required:
 | `--providers <list>` | Override providers (e.g., `--providers codex,gemini`) |
 | `--codex-only` | Use only Codex for review |
 | `--no-external` | Skip external providers, use Claude only |
+| `--stuck-threshold <N>` | How many times the same issue reappears before escalating to human (default: 3) |
+| `--no-fix` | Single-pass review only — report issues but don't auto-fix |
+| `--fix-all` | Fix even low-priority style issues (default: skip style) |
 
 ## Integration
 

package/CLAUDE.md

@@ -19,6 +19,7 @@ When the user says X → invoke `Skill(skill="tlc:...")`:
 | "plan", "break this down" | `/tlc:plan` |
 | "build", "implement", "add feature" | `/tlc:build` |
 | "review", "check code" | `/tlc:review` |
+| "review plan", "check plan" | `/tlc:review-plan` |
 | "status", "what's next", "where are we" | `/tlc:progress` |
 | "discuss", "talk about approach" | `/tlc:discuss` |
 | "test", "run tests" | `/tlc:status` |