tlc-claude-code 1.5.3 → 1.5.4

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

@@ -0,0 +1,279 @@
+# /tlc - Smart Entry Point
+
+One command. Context-aware. Visual dashboard.
+
+## What This Does
+
+Launches the TLC dashboard - a visual interface showing project state, phases, tests, and next actions.
+
+## Process
+
+### Step 1: Launch Dashboard
+
+Run the TLC dashboard:
+
+```bash
+# If in TLC repo (development)
+cd dashboard && npm run dev
+
+# If installed globally
+tlc-dashboard
+```
+
+The dashboard shows:
+- Project overview (from PROJECT.md)
+- Phase progress (from ROADMAP.md)
+- Test status (pass/fail counts)
+- Available actions
+
+### Step 2: Fallback to Text Mode
+
+If the dashboard cannot be launched (not installed, dependencies missing), fall back to text-based status:
+
+Check what exists:
+
+```
+□ PROJECT.md exists?
+□ .planning/ directory exists?
+□ .planning/ROADMAP.md exists?
+□ Test framework configured? (vitest.config.*, pytest.ini, etc.)
+□ Test files exist?
+□ Source files exist?
+```
+
+### Step 3: Route Based on State (Text Fallback)
+
+**No PROJECT.md → New or Init**
+```
+No project detected.
+
+1) Start new project (/tlc:new-project)
+2) Add TLC to existing code (/tlc:init)
+```
+
+**PROJECT.md exists, no roadmap → Need Planning**
+```
+Project exists but no roadmap.
+
+Let's break your project into phases.
+
+What's the first feature to build?
+```
+Then create ROADMAP.md with phases based on discussion.
+
+**Roadmap exists → Check Phase Status**
+
+Parse ROADMAP.md to find:
+- Completed phases: `[x]` or `[completed]`
+- Current phase: `[>]` or `[in progress]` or `[current]`
+- Next pending phase: first without marker
+
+### Step 4: Determine Current Phase Action
+
+For the current/next phase, check what exists:
+
+```
+Phase {N}: {Name}
+□ DISCUSSION.md exists? (.planning/phases/{N}-DISCUSSION.md)
+□ PLAN.md exists? (.planning/phases/{N}-*-PLAN.md)
+□ Tests written? (.planning/phases/{N}-TESTS.md or test files)
+□ Implementation done? (check if tests pass)
+□ Verified? (.planning/phases/{N}-VERIFIED.md)
+```
+
+### Step 5: Present Contextual Action
+
+Based on phase state, show ONE clear action:
+
+**Phase not discussed:**
+```
+Phase 2: User Dashboard
+
+Ready to discuss implementation approach.
+
+→ Continue? (Y/n)
+```
+Then run discuss flow.
+
+**Discussed but not planned:**
+```
+Phase 2: User Dashboard
+
+Discussion complete. Ready to create task plan.
+
+→ Continue? (Y/n)
+```
+Then run plan flow.
+
+**Planned but no tests:**
+```
+Phase 2: User Dashboard
+
+Plan ready. 4 tasks to implement.
+
+Next: Write tests, then build.
+
+→ Continue? (Y/n)
+```
+Then run build flow (tests first).
+
+**Tests written, not implemented:**
+```
+Phase 2: User Dashboard
+
+Tests ready (12 tests, all failing - expected).
+
+Next: Implement to make tests pass.
+
+→ Continue? (Y/n)
+```
+Then run implementation.
+
+**Implemented, not verified:**
+```
+Phase 2: User Dashboard
+
+Tests passing (12/12)
+
+Next: Human verification.
+
+→ Continue? (Y/n)
+```
+Then run verify flow.
+
+**Phase complete:**
+```
+Phase 2: User Dashboard - Complete
+
+Moving to Phase 3: Reports
+
+→ Continue? (Y/n)
+```
+
+### Step 6: Check Claude Permissions (One-Time)
+
+Check if `.claude/settings.json` exists with TLC permissions:
+
+```bash
+if [ ! -f ".claude/settings.json" ]; then
+  # First time - offer setup
+fi
+```
+
+**Skip if already configured.** Only ask once per project.
+
+If missing, offer to set up:
+
+```
+TLC works best with pre-approved bash commands.
+This avoids prompts for every test run and git commit.
+
+Allow TLC to run commands without prompts? (Y/n)
+```
+
+If yes, create `.claude/settings.json`:
+```json
+{
+  "permissions": {
+    "allow": [
+      "Bash(npm test*)",
+      "Bash(npm run test*)",
+      "Bash(npx vitest*)",
+      "Bash(npx mocha*)",
+      "Bash(pytest*)",
+      "Bash(go test*)",
+      "Bash(git status*)",
+      "Bash(git add *)",
+      "Bash(git commit *)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git pull*)",
+      "Bash(git checkout*)",
+      "Bash(git branch*)",
+      "Bash(npm install*)",
+      "Bash(npm run build*)"
+    ]
+  }
+}
+```
+
+**IMPORTANT:** `git push` is NOT included - always ask before pushing to remote.
+
+### Step 6b: Check Docs Setup (One-Time)
+
+Check if documentation automation is configured:
+
+```bash
+if [ ! -f ".github/workflows/docs-sync.yml" ] && [ -d ".git" ]; then
+  # First time - offer docs setup
+fi
+```
+
+**Skip if already configured or no git repo.** Only ask once per project.
+
+If missing, offer to set up:
+
+```
+Documentation Automation
+
+TLC can automatically maintain your docs:
+  • Update version references on push
+  • Sync to GitHub Wiki
+  • Generate API documentation
+  • Capture app screenshots
+
+Set up documentation automation? (Y/n)
+```
+
+If yes, run `/tlc:docs setup`:
+- Creates `docs/` directory
+- Adds `.github/workflows/docs-sync.yml`
+- Adds npm scripts for docs
+- Creates starter documentation
+
+### Step 7: Check for Untested Code
+
+If project has source files without tests:
+
+```
+Found 5 files without tests:
+  - src/utils/helpers.ts
+  - src/api/users.ts
+  - src/services/email.ts
+  ...
+
+Add tests for existing code? (Y/n)
+```
+
+If yes, run `/tlc:coverage` flow.
+
+### Step 8: All Phases Complete
+
+```
+All phases complete!
+
+Milestone ready for release.
+
+1) Tag release (/tlc:complete)
+2) Start next milestone (/tlc:new-milestone)
+3) Check test coverage (/tlc:coverage)
+4) Update documentation (/tlc:docs)
+```
+
+## Usage
+
+```
+/tlc
+```
+
+No arguments. Auto-detects everything. Launches dashboard when available.
+
+## Why This Exists
+
+Instead of remembering:
+- `/tlc:discuss 2`
+- `/tlc:plan 2`
+- `/tlc:build 2`
+- `/tlc:verify 2`
+
+Just run `/tlc`. It knows where you are.

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

@@ -0,0 +1,159 @@
+# /tlc:verify - Human Acceptance Testing
+
+Verify the phase works as expected — with your own eyes.
+
+## What This Does
+
+1. Runs tests to confirm code works
+2. Walks you through each deliverable
+3. Captures issues for fixing
+4. Marks phase as verified when done
+
+## Usage
+
+```
+/tlc:verify [phase_number]
+```
+
+If no phase number, auto-detect current phase.
+
+## Process
+
+### Step 1: Run Tests
+
+```bash
+npm test   # or pytest, go test, etc.
+```
+
+- ✅ All pass → Continue to human verification
+- ❌ Some fail → Report failures, suggest fixing first
+
+### Step 2: Load Phase Deliverables
+
+Read from `.planning/phases/{N}-PLAN.md`:
+- Extract acceptance criteria from each task
+- Build verification checklist
+
+### Step 3: Walk Through Each Deliverable
+
+For each testable feature:
+
+```
+Phase 1: Authentication
+
+Verifying 3 deliverables:
+
+[1/3] User login with email/password
+
+Can you:
+1. Go to /login
+2. Enter valid credentials
+3. Get redirected to dashboard
+
+Works as expected? (Y/n/describe issue)
+>
+```
+
+### Step 4: Handle Issues
+
+If user reports issue:
+```
+> n - login works but no error message for wrong password
+
+Got it. Creating fix task:
+
+Issue: No error message for wrong password
+Location: Login form
+Expected: Show "Invalid credentials" message
+
+Add to current phase as fix task? (Y/n)
+```
+
+### Step 5: Mark Verified or Loop
+
+**All verified:**
+```
+✅ Phase 1 verified
+
+All 3 deliverables confirmed working.
+
+Creating .planning/phases/1-VERIFIED.md
+
+Ready for next phase? (Y/n)
+```
+
+**Issues found:**
+```
+Phase 1 verification incomplete
+
+Issues found:
+1. No error message for wrong password
+2. Session doesn't persist on refresh
+
+Fix tasks added to phase. Run /tlc:build 1 to implement fixes.
+```
+
+### Step 6: Create Verification Record
+
+Save to `.planning/phases/{N}-VERIFIED.md`:
+
+```markdown
+# Phase {N}: {Name} - Verification
+
+Verified: {date}
+
+## Deliverables
+
+- [x] User login with email/password
+- [x] Session persistence
+- [x] Logout functionality
+
+## Issues Found & Fixed
+
+- Login error message (fixed in commit abc123)
+- Session refresh (fixed in commit def456)
+
+## Notes
+
+{Any additional observations}
+```
+
+## Why Human Verification?
+
+**Tests verify code works.**
+**You verify it works the way you wanted.**
+
+Tests catch:
+- Logic errors
+- Regressions
+- Edge cases
+
+You catch:
+- "Technically correct but wrong layout"
+- "Works but confusing UX"
+- "Missing something I forgot to specify"
+
+Both matter.
+
+## Example
+
+```
+> /tlc:verify 1
+
+Running tests... ✅ 11 passing
+
+Phase 1: Authentication
+
+[1/3] Login with email/password
+Works? (Y/n) > y
+
+[2/3] Session persists across page refresh
+Works? (Y/n) > y
+
+[3/3] Logout clears session
+Works? (Y/n) > y
+
+✅ Phase 1 verified!
+
+Moving to Phase 2: Dashboard
+```

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

@@ -0,0 +1,151 @@
+# /tlc:who - Team Status
+
+See who's working on what in the current phase.
+
+## Usage
+
+```
+/tlc:who
+```
+
+## Process
+
+### Step 1: Find Current Phase
+
+1. Read `.planning/ROADMAP.md`
+2. Find phase marked `[>]` or `[current]`
+3. Load `.planning/phases/{N}-*-PLAN.md`
+
+### Step 2: Parse Task Markers
+
+Extract status from task headings:
+
+| Marker | Status | Owner |
+|--------|--------|-------|
+| `[ ]` | available | - |
+| `[>@user]` | working | @user |
+| `[x@user]` | done | @user |
+
+### Step 3: Identify Current User
+
+```bash
+if [ -n "$TLC_USER" ]; then
+  user=$TLC_USER
+else
+  user=$(git config user.name | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
+fi
+```
+
+### Step 4: Display Team Status
+
+```
+Phase 2: User Dashboard
+
+| Task | Description | Status | Owner |
+|------|-------------|--------|-------|
+| 1 | Create layout | done | @alice |
+| 2 | Fetch data hook | available | - |
+| 3 | Add charts | working | @bob |
+| 4 | Loading states | available | - |
+
+Team Activity:
+  @alice: 1 done
+  @bob: 1 working
+
+You (@alice): No active tasks
+Available: 2, 4
+```
+
+## Output Format
+
+### Table View
+
+Shows all tasks with status:
+
+```
+Phase 1: Authentication
+
+| # | Task | Status | Owner |
+|---|------|--------|-------|
+| 1 | Create user schema | done | @alice |
+| 2 | Add validation | working | @bob |
+| 3 | Write migrations | done | @alice |
+| 4 | Integration tests | available | - |
+```
+
+### Summary
+
+After the table:
+
+```
+Summary:
+  Done: 2 tasks (@alice: 2)
+  Working: 1 task (@bob: 1)
+  Available: 1 task
+
+You (@charlie):
+  No tasks claimed
+  Available to claim: 4
+```
+
+### Your Status
+
+Highlights what you're working on:
+
+```
+You (@bob):
+  Working on: Task 2 - Add validation
+
+Next: Continue with /tlc:build or /tlc:release if blocked
+```
+
+## Example Output
+
+```
+> /tlc:who
+
+Phase 2: User Dashboard
+
+Tasks:
+  1. Create layout       [x@alice]  done
+  2. Fetch data hook     [ ]        available
+  3. Add charts          [>@bob]    working
+  4. Loading states      [ ]        available
+  5. Error boundaries    [x@alice]  done
+
+Team:
+  @alice  2 done
+  @bob    1 working
+
+You (@bob):
+  → Task 3: Add charts (in progress)
+
+Available tasks: 2, 4
+```
+
+## No Activity
+
+If no one has claimed anything:
+
+```
+> /tlc:who
+
+Phase 1: Authentication
+
+All 4 tasks available:
+  1. Create user schema [ ]
+  2. Add validation [ ]
+  3. Write migrations [ ]
+  4. Integration tests [ ]
+
+No team activity yet.
+Run /tlc:claim to get started.
+```
+
+## Notes
+
+- Shows current phase only
+- Pull latest first for accurate status: `git pull`
+- Task numbers match PLAN.md task numbers
+- Use `/tlc:claim N` to claim an available task
+- Use `/tlc:release N` to release your task

package/bin/postinstall.js

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Get source and destination directories
+const srcDir = path.join(__dirname, '..', '.claude', 'commands', 'tlc');
+const destDir = path.join(os.homedir(), '.claude', 'commands', 'tlc');
+
+// Create destination directory if it doesn't exist
+function ensureDir(dir) {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+// Copy all .md files from source to destination
+function copyCommands() {
+  try {
+    // Ensure destination exists
+    ensureDir(destDir);
+
+    // Check if source exists
+    if (!fs.existsSync(srcDir)) {
+      // Silent exit if source doesn't exist (might be dev install)
+      return;
+    }
+
+    // Get all .md files
+    const files = fs.readdirSync(srcDir).filter(f => f.endsWith('.md'));
+
+    let copied = 0;
+    for (const file of files) {
+      const src = path.join(srcDir, file);
+      const dest = path.join(destDir, file);
+
+      // Copy file (overwrite if exists)
+      fs.copyFileSync(src, dest);
+      copied++;
+    }
+
+    if (copied > 0) {
+      console.log(`\x1b[32m✓\x1b[0m TLC: Installed ${copied} commands to ~/.claude/commands/tlc/`);
+    }
+  } catch (err) {
+    // Silent fail - don't break npm install
+    if (process.env.DEBUG) {
+      console.error('TLC postinstall error:', err.message);
+    }
+  }
+}
+
+copyCommands();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tlc-claude-code",
-  "version": "1.5.3",
+  "version": "1.5.4",
   "description": "TLC - Test Led Coding for Claude Code",
   "bin": {
     "tlc": "./bin/tlc.js",
@@ -9,6 +9,7 @@
   },
   "files": [
     "bin/",
+    ".claude/commands/",
     "dashboard/dist/",
     "dashboard/package.json",
     "server/index.js",
@@ -28,6 +29,7 @@
     ".gitattributes"
   ],
   "scripts": {
+    "postinstall": "node bin/postinstall.js",
     "build": "cd dashboard && npm run build",
     "prepublishOnly": "npm run build",
     "docs": "node scripts/docs-update.js",