tlc-claude-code 1.5.2 → 1.5.4

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

@@ -0,0 +1,129 @@
+# /tlc:audit - Check Coding Standards Compliance
+
+Run a comprehensive audit of the codebase against TLC coding standards.
+
+## What This Does
+
+1. Checks that standards files exist (CLAUDE.md, CODING-STANDARDS.md)
+2. Detects architectural violations:
+   - Flat services/, interfaces/, controllers/ folders
+   - Inline interfaces in service files
+   - Hardcoded URLs and ports
+   - Magic strings without constants
+   - Flat seed folders
+3. Checks code quality:
+   - JSDoc coverage on exported functions
+   - Import style (no deep relative imports)
+4. Generates report to `.planning/AUDIT-REPORT.md`
+
+## Usage
+
+```
+/tlc:audit
+```
+
+## Process
+
+### Step 1: Load Audit Module
+
+```javascript
+const { auditProject, generateReport } = require('./lib/standards/audit-checker');
+```
+
+### Step 2: Run All Checks
+
+Run `auditProject(projectPath)` which executes:
+
+| Check | What It Finds |
+|-------|---------------|
+| Standards Files | Missing CLAUDE.md or CODING-STANDARDS.md |
+| Flat Folders | Files in src/services/, src/interfaces/, src/controllers/ |
+| Inline Interfaces | `interface X {` inside *.service.ts files |
+| Hardcoded URLs | http:// or https:// URLs in code |
+| Hardcoded Ports | `const port = 3000` patterns |
+| Magic Strings | `=== 'active'` comparisons without constants |
+| Flat Seeds | Seed files in src/seeds/ instead of src/{entity}/seeds/ |
+| Missing JSDoc | Exported functions without `/**` comments |
+| Deep Imports | `../../../` style imports (3+ levels) |
+
+### Step 3: Generate Report
+
+Create `.planning/AUDIT-REPORT.md` with:
+
+```markdown
+# Audit Report
+
+Generated: {timestamp}
+Status: {PASSED | FAILED}
+
+## Summary
+
+- Total Issues: {count}
+- Standards Files: {✓ | ✗}
+- Architecture: {✓ | ✗}
+- Code Quality: {✓ | ✗}
+
+## Issues Found
+
+### Flat Folders
+- src/services/user.service.ts → Move to src/user/user.service.ts
+
+### Hardcoded URLs
+- src/api.ts:15 - http://localhost:3000
+
+...
+```
+
+### Step 4: Display Results
+
+```
+TLC Audit Results
+═══════════════════════════════════════════════════════════════
+
+Status: ✗ FAILED (12 issues found)
+
+Standards Files:    ✓ PASSED
+Flat Folders:       ✗ 3 issues
+Inline Interfaces:  ✗ 2 issues
+Hardcoded URLs:     ✗ 4 issues
+Magic Strings:      ✗ 2 issues
+JSDoc Coverage:     ✗ 1 issue
+Import Style:       ✓ PASSED
+
+Report saved to: .planning/AUDIT-REPORT.md
+
+Fix automatically? Run /tlc:cleanup
+Fix step-by-step?  Run /tlc:refactor
+```
+
+## Example Output
+
+```
+> /tlc:audit
+
+Running TLC audit...
+
+Checking standards files... ✓
+Checking folder structure... ✗ Found 3 flat folders
+Checking inline interfaces... ✗ Found 2 violations
+Checking hardcoded config... ✗ Found 4 hardcoded URLs
+Checking magic strings... ✗ Found 2 magic strings
+Checking JSDoc coverage... ✓
+Checking import style... ✓
+
+═══════════════════════════════════════════════════════════════
+AUDIT FAILED - 11 issues found
+═══════════════════════════════════════════════════════════════
+
+Report: .planning/AUDIT-REPORT.md
+
+Next steps:
+  /tlc:cleanup  - Fix all issues automatically
+  /tlc:refactor - Fix step-by-step with previews
+```
+
+## Exit Codes
+
+- `0` - All checks passed
+- `1` - Issues found (report generated)
+- `2` - Error running audit

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

@@ -0,0 +1,217 @@
+# /tlc:autofix - Automatic Test Failure Recovery
+
+Run tests, analyze failures, and automatically apply fixes for common error patterns.
+
+## What This Does
+
+1. Runs test suite and captures failures
+2. Matches errors against known patterns
+3. Generates fix proposals
+4. Applies fixes (with user confirmation)
+5. Re-runs tests to verify
+6. Offers to commit fixes
+
+## Usage
+
+```
+/tlc:autofix
+```
+
+## Process
+
+### Step 1: Run Tests
+
+Execute test suite to capture current state:
+
+```bash
+npm test 2>&1
+```
+
+### Step 2: Parse Failures
+
+For each failing test, extract:
+- Test name
+- Error message
+- File and line number
+
+### Step 3: Match Patterns
+
+Known error patterns:
+
+| Pattern | Example | Fix |
+|---------|---------|-----|
+| null-property-access | `Cannot read properties of null` | Add null check |
+| undefined-property-access | `Cannot read properties of undefined` | Add undefined check |
+| module-not-found | `Cannot find module './utils'` | Add/fix import |
+| function-not-defined | `validateEmail is not defined` | Add import/export |
+| expected-value-mismatch | `expected undefined to equal` | Check return value |
+| timeout | `Timeout of 5000ms exceeded` | Add await/increase timeout |
+
+### Step 4: Display Analysis
+
+```
+Test Failures: 4
+
+1) src/auth.test.ts > login > rejects invalid password
+   Error: Cannot read properties of null (reading 'email')
+   Fix: Add null check before accessing 'email'
+   Confidence: HIGH
+
+2) src/user.test.ts > getUser > returns user object
+   Error: Cannot find module '../utils/helper'
+   Fix: Add missing import
+   Confidence: HIGH
+
+3) src/api.test.ts > paginate > handles page 0
+   Error: expected undefined to equal []
+   Fix: Check function return value
+   Confidence: LOW
+
+4) src/complex.test.ts > integration > complex flow
+   Error: Some unusual error
+   Fix: Unable to auto-fix
+   Confidence: NONE
+
+Fixable: 3 (2 high, 1 low)
+Unfixable: 1
+
+Apply fixes? (Y/n)
+```
+
+### Step 5: Apply Fixes
+
+For each fixable failure:
+
+1. Read source file
+2. Apply suggested fix
+3. Show progress:
+   ```
+   [████████░░░░░░░░░░░░] 2/4 (50%)
+     Fixing null check in auth.ts
+   ```
+
+### Step 6: Verify Fixes
+
+Re-run tests after fixes:
+
+```bash
+npm test 2>&1
+```
+
+Check results:
+- ✅ Test passes → Mark as fixed
+- ❌ Still fails → Rollback change, mark as unfixable
+
+### Step 7: Display Summary
+
+```
+AutoFix Summary
+═══════════════
+
+Total:  4
+fixed:  3 ✓
+failed: 1 ✗
+
+Successfully fixed:
+  ✓ src/auth.test.ts > login > rejects invalid password
+    Added null check
+  ✓ src/user.test.ts > getUser > returns user object
+    Added missing import
+  ✓ src/api.test.ts > paginate > handles page 0
+    Fixed return value
+
+Could not fix:
+  ✗ src/complex.test.ts > integration > complex flow
+    Reason: Unknown error pattern
+
+Commit fixes?
+  1) Yes - commit all fixes
+  2) No - review changes first
+```
+
+### Step 8: Commit (Optional)
+
+If user chooses to commit:
+
+```bash
+git add -A
+git commit -m "fix: auto-fix test failures (3 fixed)"
+```
+
+## Configuration
+
+In `.tlc.json`:
+
+```json
+{
+  "autofix": {
+    "maxAttempts": 5,
+    "strategies": ["null-check", "import", "return-value"],
+    "confirmBeforeApply": true
+  }
+}
+```
+
+## Confidence Levels
+
+| Level | Meaning | Behavior |
+|-------|---------|----------|
+| HIGH | Known pattern, reliable fix | Apply automatically |
+| MEDIUM | Likely fix, may need review | Apply with confirmation |
+| LOW | Suggested fix, uncertain | Show suggestion only |
+| NONE | Unknown pattern | Skip, suggest manual fix |
+
+## Error Patterns
+
+Supported patterns for auto-fixing:
+
+1. **null-property-access**: Accessing property on null
+2. **undefined-property-access**: Accessing property on undefined
+3. **module-not-found**: Missing import statement
+4. **function-not-defined**: Function not exported/imported
+5. **function-not-a-function**: Wrong export type
+6. **timeout**: Missing async/await or slow test
+
+## Example Session
+
+```
+User: /tlc:autofix
+
+Claude: Running tests...
+  ❌ 4 tests failing
+
+Analyzing failures...
+
+1) login > rejects invalid password
+   → null-property-access: 'email'
+   → Fix: Add null check (HIGH confidence)
+
+2) getUser > returns user object
+   → module-not-found: '../utils/helper'
+   → Fix: Add import (HIGH confidence)
+
+3) paginate > handles page 0
+   → expected-value-mismatch
+   → Fix: Check return (LOW confidence)
+
+4) complex flow
+   → Unknown pattern
+   → Cannot auto-fix
+
+Apply fixes? (Y/n)
+
+User: y
+
+Claude: [████████████████████] 3/3 (100%)
+
+Re-running tests...
+  ✅ 3 tests now passing
+  ❌ 1 still failing (requires manual fix)
+
+AutoFix Summary
+═══════════════
+fixed:  3 ✓
+failed: 1 ✗
+
+Commit fixes? (Y/n)
+```

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

@@ -0,0 +1,255 @@
+# /tlc:bug - Log a Bug or Feedback
+
+Report issues discovered during development or QA verification.
+
+## Usage
+
+```
+/tlc:bug [description]
+```
+
+Or interactive:
+```
+/tlc:bug
+```
+
+## Process
+
+### Step 1: Gather Bug Information
+
+If description provided as argument, use it. Otherwise prompt:
+
+```
+What's the issue?
+> Login fails when email contains a + symbol
+
+Where did you find this?
+1) During development
+2) During /tlc:verify (QA)
+3) From automated tests
+4) User reported
+> 2
+
+Severity?
+1) Critical - blocks release
+2) High - major feature broken
+3) Medium - workaround exists
+4) Low - cosmetic/minor
+> 2
+```
+
+### Step 2: Identify Context
+
+Automatically detect:
+- Current user: `git config user.name` or `$TLC_USER`
+- Current phase: from `.planning/ROADMAP.md`
+- Current task: from any `[>@user]` marker in PLAN.md
+- Git branch: `git branch --show-current`
+- Last commit: `git log -1 --oneline`
+
+### Step 3: Generate Bug ID
+
+Format: `BUG-{NNN}` where NNN is sequential.
+
+Read `.planning/BUGS.md` to find highest existing ID, increment.
+
+### Step 4: Create Bug Entry
+
+Append to `.planning/BUGS.md`:
+
+```markdown
+---
+
+### BUG-007: Login fails with + symbol in email
+
+**Status:** Open
+**Severity:** High
+**Reporter:** @alice
+**Date:** 2024-01-26
+**Phase:** 2 - Authentication
+**Task:** Task 3 - Email validation
+**Branch:** feature/auth
+**Commit:** a1b2c3d
+
+**Description:**
+Login fails when email contains a + symbol (e.g., user+test@example.com)
+
+**Steps to Reproduce:**
+1. Go to login page
+2. Enter email: user+test@example.com
+3. Enter valid password
+4. Click Login
+
+**Expected:** Should accept valid email and log in
+**Actual:** Shows "Invalid email format" error
+
+**Notes:**
+Plus addressing is valid per RFC 5321. Regex validation is too strict.
+```
+
+### Step 5: Commit Bug Report
+
+```bash
+git add .planning/BUGS.md
+git commit -m "bug: BUG-007 - Login fails with + symbol (@alice)"
+```
+
+### Step 6: Link to Task (Optional)
+
+If bug relates to a specific task, offer to add reference:
+
+```
+Link this bug to Task 3 in the current phase? (Y/n)
+```
+
+If yes, add to task in PLAN.md:
+```markdown
+### Task 3: Email validation [>@bob]
+
+**Bugs:** BUG-007
+```
+
+### Step 7: Notify
+
+```
+Bug logged: BUG-007
+File: .planning/BUGS.md
+Committed: bug: BUG-007 - Login fails with + symbol (@alice)
+
+Push to share with team? (Y/n)
+```
+
+## Bug Status Workflow
+
+| Status | Meaning |
+|--------|---------|
+| Open | New, not yet addressed |
+| In Progress | Someone is fixing |
+| Fixed | Code fixed, needs verification |
+| Verified | Fix confirmed working |
+| Closed | Resolved |
+| Won't Fix | Declined with reason |
+
+## Updating Bug Status
+
+To update an existing bug:
+
+```
+/tlc:bug --update BUG-007 --status "Fixed"
+```
+
+Or interactive:
+```
+/tlc:bug --update
+
+Which bug?
+  BUG-005: Session timeout too short (Open)
+  BUG-006: Missing loading spinner (Open)
+  BUG-007: Login fails with + symbol (Open)
+> BUG-007
+
+New status?
+1) In Progress
+2) Fixed
+3) Verified
+4) Closed
+5) Won't Fix
+> 2
+
+Add resolution notes?
+> Fixed regex in src/auth/validate.ts to allow + in local part
+
+Updated BUG-007: Open → Fixed
+```
+
+## Viewing Bugs
+
+To see all open bugs:
+
+```
+/tlc:bug --list
+
+Open Bugs (3):
+
+| ID | Severity | Description | Reporter | Phase |
+|----|----------|-------------|----------|-------|
+| BUG-005 | Medium | Session timeout too short | @alice | 2 |
+| BUG-006 | Low | Missing loading spinner | @bob | 2 |
+| BUG-007 | High | Login fails with + symbol | @alice | 2 |
+
+Critical: 0 | High: 1 | Medium: 1 | Low: 1
+```
+
+## Integration with /tlc:verify
+
+During `/tlc:verify`, QA is prompted to log bugs:
+
+```
+Testing Task 3: Email validation
+
+Did you find any issues? (Y/n) y
+
+/tlc:bug (interactive mode)
+...
+```
+
+## Example Session
+
+```
+> /tlc:bug "Button color doesn't match design spec"
+
+Gathering context...
+  User: @alice
+  Phase: 3 - Dashboard
+  Branch: feature/dashboard
+
+Severity?
+1) Critical
+2) High
+3) Medium
+4) Low
+> 4
+
+BUG-008 created:
+  "Button color doesn't match design spec"
+  Severity: Low
+  Phase: 3 - Dashboard
+
+Committed: bug: BUG-008 - Button color doesn't match design spec (@alice)
+
+Push? (Y/n) y
+Pushed to origin/feature/dashboard
+```
+
+## BUGS.md Format
+
+The bugs file has a header and entries:
+
+```markdown
+# Bug Tracker
+
+## Summary
+
+| Status | Count |
+|--------|-------|
+| Open | 3 |
+| In Progress | 1 |
+| Fixed | 2 |
+| Closed | 5 |
+
+## Open Bugs
+
+### BUG-007: Login fails with + symbol in email
+...
+
+### BUG-006: Missing loading spinner
+...
+
+## Closed Bugs
+
+### BUG-001: App crashes on startup
+**Status:** Closed
+**Resolution:** Fixed null check in main.ts
+**Closed:** 2024-01-25 by @bob
+...
+```