Skip to content
Shell

feat: Add Boris Cherny-inspired workflow patterns

Eddie Belaval293f08f83d64
diff --git a/ITERM-SETUP.md b/ITERM-SETUP.md
new file mode 100644
index 0000000..9bfcbe3
--- /dev/null
+++ b/ITERM-SETUP.md
@@ -0,0 +1,109 @@
+# iTerm2 Setup for Claude Code Parallel Sessions
+
+Follow this guide to set up iTerm2 for optimal parallel Claude sessions.
+
+## 1. Enable System Notifications
+
+### Step 1: iTerm2 Preferences
+1. Open iTerm2
+2. Press Cmd + , to open Preferences
+3. Go to: Profiles > Terminal
+4. Check: "Send Notification Center alerts"
+
+### Step 2: macOS Notification Settings
+1. Open System Settings > Notifications
+2. Find iTerm2
+3. Enable: Allow Notifications
+4. Set style to: Alerts (not Banners - you want them to stay)
+
+## 2. Set Up Numbered Tabs
+
+### Create a Profile for Claude Sessions
+1. iTerm2 Preferences > Profiles
+2. Click + to add new profile
+3. Name it: "Claude Session"
+4. Under General: Set Badge to show session number
+5. Under Colors: Choose a distinct color scheme
+6. Under Terminal: Check "Send Notification Center alerts"
+
+### Create 5 Default Tabs
+1. Open 5 tabs (Cmd + T four times)
+2. Right-click each tab > Edit Tab Title:
+ - Tab 1: "Claude 1"
+ - Tab 2: "Claude 2"
+ - Tab 3: "Claude 3"
+ - Tab 4: "Claude 4"
+ - Tab 5: "Claude 5"
+3. Window > Save Window Arrangement
+4. Name it: "Claude Workspace"
+
+### Auto-Launch Arrangement
+1. Preferences > General > Startup
+2. Set: "Open Default Window Arrangement"
+3. Preferences > Arrangements
+4. Set "Claude Workspace" as default
+
+## 3. Shell Aliases
+
+Add these to your ~/.zshrc for quick access:
+
+```zsh
+# Teleport shortcut
+alias ct='claude --teleport'
+
+# Quick numbered session launchers
+alias c1='echo "Starting Claude 1..."'
+alias c2='echo "Starting Claude 2..."'
+```
+
+## 4. Keyboard Shortcuts
+
+These are usually default in iTerm2:
+
+| Shortcut | Action |
+|----------|--------|
+| Cmd + 1 | Select Tab 1 |
+| Cmd + 2 | Select Tab 2 |
+| Cmd + 3 | Select Tab 3 |
+| Cmd + 4 | Select Tab 4 |
+| Cmd + 5 | Select Tab 5 |
+| Cmd + T | New Tab |
+
+## 5. Visual Differentiation
+
+### Tab Colors
+In each tab:
+1. Right-click tab
+2. "Edit Session"
+3. Under "Colors", set a unique tab color per session
+
+## 6. Daily Workflow
+
+### Morning Startup
+1. Open your Claude Workspace arrangement
+2. Tab 1: Main development work
+3. Tab 2: Tests/verification
+4. Tab 3-5: Ready for parallel tasks
+
+### During the Day
+1. Poll tabs every 10-15 minutes
+2. Watch for notifications - Claude waiting for input
+3. Farm out long tasks with ampersand suffix
+4. Check claude.ai/code for cloud session status
+
+## 7. Key Commands
+
+| Command | Purpose |
+|---------|---------|
+| claude "task" | Start interactive session |
+| claude "task" & | Send to cloud, free terminal |
+| claude --teleport | Pull cloud session back |
+| claude --resume | Resume last local session |
+
+## Verification
+
+Open System Settings > Notifications > iTerm2 and confirm:
+- Allow Notifications: ON
+- Alert style: Alerts
+
+You should now receive notifications when Claude needs your input across any tab.
diff --git a/PARALLEL-SESSIONS-GUIDE.md b/PARALLEL-SESSIONS-GUIDE.md
new file mode 100644
index 0000000..741b72c
--- /dev/null
+++ b/PARALLEL-SESSIONS-GUIDE.md
@@ -0,0 +1,194 @@
+# Parallel Sessions & Teleport Guide
+
+This guide documents the workflow patterns Boris Cherny (creator of Claude Code) uses to run 15+ Claude sessions simultaneously.
+
+## The Pattern: Breadth Over Depth
+
+Instead of using one Claude session sequentially, treat Claude like a **team of developers**:
+- Session 1: Working on feature A
+- Session 2: Writing tests for feature B
+- Session 3: Fixing bug C
+- Session 4: Updating docs
+- Session 5: Researching approach for feature D
+
+## Key Features You Need to Know
+
+### 1. The `&` Suffix (Background to Web)
+
+Add `&` at the end of your prompt to **hand off the session to claude.ai/code**:
+
+```bash
+claude "Refactor the authentication module to use JWTs" &
+```
+
+This:
+- Starts the task locally
+- Uploads the session to cloud
+- Frees up your terminal immediately
+- You can check progress at https://claude.ai/code
+
+**Use Case:** Long-running tasks you don't need to monitor actively.
+
+### 2. The `--teleport` Flag (Pull Session Back)
+
+Bring a web session back to your terminal:
+
+```bash
+claude --teleport
+```
+
+This:
+- Lists your active cloud sessions
+- Lets you select one to continue locally
+- Preserves full context from the web session
+
+**Use Case:**
+- Started a session on your phone, want to continue on desktop
+- Web session finished, want to continue locally with the results
+
+### 3. Session Continuation from iOS
+
+The Claude iOS app supports Claude Code sessions:
+1. Open Claude app on iPhone/iPad
+2. Start a coding session
+3. It runs with full tool access in the cloud
+4. Later, `--teleport` to bring it to your Mac
+
+**Use Case:** Start tasks during commute, continue at desk.
+
+### 4. Web Sessions at claude.ai/code
+
+Go to https://claude.ai/code to:
+- View all active sessions
+- Start new sessions without terminal
+- Monitor long-running tasks
+- Share session URLs with teammates
+
+## Terminal Setup for Parallel Work
+
+### Numbered Tabs (Boris's Pattern)
+
+Set up 5 terminal tabs numbered 1-5:
+
+**iTerm2:**
+- Right-click tab → Edit Tab Title
+- Name them: "Claude 1", "Claude 2", etc.
+- Or use badges: View → Show Tab Bar, then number them
+
+**Terminal.app:**
+- Shell → Edit Tab Title
+
+### iTerm2 Notifications (Essential)
+
+Get notified when Claude needs your input:
+
+1. Open iTerm2 Preferences (Cmd + ,)
+2. Go to: Profiles → Terminal
+3. Enable: "Post notifications for terminal bells"
+4. Add to your shell profile (~/.zshrc):
+```bash
+# Notify when command completes
+export PROMPT_COMMAND='echo -ne "\a"'
+```
+
+Or use the simpler approach - add to Claude config:
+```json
+{
+ "notifications": {
+ "onWaitingForInput": true
+ }
+}
+```
+
+## Workflow Examples
+
+### Example 1: Feature Development
+
+```bash
+# Terminal 1 - Main feature work
+claude "Implement user profile page"
+
+# Terminal 2 - Tests (in parallel)
+claude "Write tests for the user service"
+
+# Terminal 3 - Related refactor
+claude "Clean up the auth middleware" & # Send to cloud
+
+# Check Terminal 3 progress later at claude.ai/code
+```
+
+### Example 2: Morning Phone → Desktop
+
+**On iPhone (during commute):**
+1. Open Claude app
+2. "Review the open PRs and summarize what needs attention"
+3. Claude researches and writes summary
+
+**At Desktop:**
+```bash
+claude --teleport
+# Select the phone session
+# Continue: "Let's address the first PR..."
+```
+
+### Example 3: Long-Running Task
+
+```bash
+# Start big refactor
+claude "Refactor entire API layer to use new error handling" &
+
+# Continue other work in new terminal
+claude "Fix the login bug reported in issue #42"
+
+# Check refactor progress at claude.ai/code
+# When done, teleport back if needed
+```
+
+## Polling Pattern
+
+With 5 terminals running:
+
+1. **Kick off tasks** in each terminal
+2. **Poll regularly** - check each tab for prompts
+3. **Respond to notifications** - iTerm will alert you
+4. **Farm out long tasks** with `&`
+5. **Pull back** with `--teleport` when needed
+
+## Commands Quick Reference
+
+| Command | What It Does |
+|---------|-------------|
+| `claude "task"` | Start interactive session |
+| `claude "task" &` | Start and send to cloud |
+| `claude --teleport` | Pull cloud session to terminal |
+| `claude --resume` | Resume last local session |
+| `claude -p "task"` | Non-interactive (print and exit) |
+
+## Best Practices
+
+### DO:
+- Number your terminal tabs for quick switching
+- Enable notifications so you don't miss prompts
+- Use `&` for any task that might take >5 minutes
+- Start research tasks from phone during downtime
+- Keep one terminal free for quick tasks
+
+### DON'T:
+- Wait for one session to complete before starting another
+- Run all sessions locally (use cloud for long tasks)
+- Ignore notifications (Claude might be blocked waiting)
+- Forget about background sessions (check claude.ai/code regularly)
+
+## Mental Model
+
+Think of it as:
+```
+You (Manager)
+├── Claude 1 (Terminal) - Active conversation
+├── Claude 2 (Terminal) - Active conversation
+├── Claude 3 (Cloud via &) - Working independently
+├── Claude 4 (Cloud via &) - Working independently
+└── Claude 5 (Phone) - Mobile session, will teleport later
+```
+
+You're orchestrating a team, not having a single conversation.
diff --git a/QUICK-REFERENCE.md b/QUICK-REFERENCE.md
new file mode 100644
index 0000000..4b3538e
--- /dev/null
+++ b/QUICK-REFERENCE.md
@@ -0,0 +1,82 @@
+# Claude Code Quick Reference
+
+Your enhanced workflow based on Boris Cherny's patterns.
+
+## Slash Commands
+
+| Command | Purpose | Frequency |
+|---------|---------|-----------|
+| `/commit-push-pr` | Stage, commit, push, create PR | Daily - dozens of times |
+| `/sync-main` | Rebase current branch on main | Before PRs, after stale |
+| `/test-verify` | Run tests with coverage | Before commits |
+| `/verify` | Full 6-layer verification | Before PRs |
+| `/verify quick` | TypeScript + lint only | Quick checks |
+| `/verify visual` | Browser verification via Playwright | UI changes |
+| `/factory` | Marketing asset generation | Campaign work |
+
+## Session Management
+
+| Action | Command |
+|--------|---------|
+| Start session | `claude` |
+| Background to cloud | `claude "task" &` |
+| Pull from cloud | `claude --teleport` |
+| Resume last session | `claude --resume` |
+| Check cloud sessions | https://claude.ai/code |
+
+## Parallel Session Pattern
+
+```
+Tab 1: Main feature work
+Tab 2: Tests/verification
+Tab 3: Background task (sent to cloud)
+Tab 4: Ad-hoc debugging
+Tab 5: Research/exploration
+```
+
+## Verification Layers
+
+```
+Layer 1: Static Analysis (tsc, eslint)
+Layer 2: Unit Tests (jest/vitest)
+Layer 3: Integration Tests
+Layer 4: E2E Tests (playwright)
+Layer 5: Visual Verification (browser)
+Layer 6: Build Check
+```
+
+## Hooks Active
+
+| Hook | Trigger | Purpose |
+|------|---------|---------|
+| format-code.sh | Write/Edit | Auto-format with prettier/biome |
+| verify-after-write.sh | Write | Verify file saved correctly |
+| pev-verification.sh | Bash | Plan-Execute-Verify pattern |
+| reflection-gate.sh | Write/Edit | Self-critique on changes |
+
+## Git Workflow
+
+```
+/sync-main # Get latest from main
+ work work work
+/test-verify # Verify changes
+/commit-push-pr # Ship it
+```
+
+## When Stuck
+
+1. `/verify` to check current state
+2. Check console: `browser_console_messages`
+3. Check network: `browser_network_requests`
+4. Screenshot: `browser_take_screenshot`
+
+## Mental Model
+
+You are a **manager of Claude developers**:
+- Farm out tasks to parallel sessions
+- Poll for results
+- Context switch freely
+- Let cloud sessions cook
+
+---
+*Based on Boris Cherny's Claude Code workflow*
diff --git a/commands/commit-push-pr.md b/commands/commit-push-pr.md
new file mode 100644
index 0000000..86c676a
--- /dev/null
+++ b/commands/commit-push-pr.md
@@ -0,0 +1,92 @@
+# Commit, Push & Create PR
+
+You are executing the **commit-push-pr** workflow - the most frequently used inner-loop command.
+
+## Pre-computed Context (inline bash for speed)
+
+```bash
+# Current state
+BRANCH=$(git branch --show-current)
+STATUS=$(git status --porcelain)
+STAGED=$(git diff --cached --stat)
+UNSTAGED=$(git diff --stat)
+REMOTE_STATUS=$(git status -sb | head -1)
+RECENT_COMMITS=$(git log --oneline -5)
+PR_EXISTS=$(gh pr view --json number 2>/dev/null || echo "none")
+```
+
+**Branch:** $BRANCH
+**Remote Status:** $REMOTE_STATUS
+**Staged Changes:** $STAGED
+**Unstaged Changes:** $UNSTAGED
+**Recent Commits:** $RECENT_COMMITS
+**Existing PR:** $PR_EXISTS
+
+## User Intent
+
+$ARGUMENTS
+
+## Workflow
+
+### Step 1: Analyze Changes
+- Review STATUS to understand what's changed
+- Identify logical groupings if multiple changes exist
+- Check if changes are related or should be separate commits
+
+### Step 2: Stage Appropriately
+- If user specified files, stage those
+- If no specification, stage all related changes
+- NEVER stage unrelated changes together
+
+### Step 3: Craft Commit Message
+Follow semantic commit style:
+- `feat:` new feature
+- `fix:` bug fix
+- `refactor:` code restructuring
+- `docs:` documentation
+- `test:` adding tests
+- `chore:` maintenance
+
+Message format:
+```
+type: short description (imperative mood)
+
+- Bullet points for details if needed
+- Focus on WHY, not WHAT (the diff shows what)
+```
+
+### Step 4: Commit & Push
+```bash
+git add [files]
+git commit -m "message"
+git push -u origin $BRANCH
+```
+
+### Step 5: Create or Update PR
+If PR_EXISTS is "none":
+```bash
+gh pr create --title "PR Title" --body "## Summary
+- Key change 1
+- Key change 2
+
+## Test Plan
+- [ ] How to verify this works
+
+---
+Generated with [Claude Code](https://claude.com/claude-code)"
+```
+
+If PR already exists, just push (PR auto-updates).
+
+### Step 6: Report
+Output the PR URL and summary of what was done.
+
+## Error Handling
+- If push fails due to divergence: `git pull --rebase origin $BRANCH` first
+- If PR creation fails: check if branch is pushed, check gh auth status
+- If nothing to commit: report "No changes to commit"
+
+## Speed Optimizations
+- Pre-compute all git state via inline bash (no tool calls needed)
+- Single commit for related changes
+- Use `gh pr create` not manual GitHub navigation
diff --git a/commands/sync-main.md b/commands/sync-main.md
new file mode 100644
index 0000000..daeaeff
--- /dev/null
+++ b/commands/sync-main.md
@@ -0,0 +1,98 @@
+# Sync with Main Branch
+
+You are executing the **sync-main** workflow - keeps your feature branch up to date with main.
+
+## Pre-computed Context
+
+```bash
+CURRENT_BRANCH=$(git branch --show-current)
+MAIN_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@' || echo "main")
+LOCAL_CHANGES=$(git status --porcelain)
+COMMITS_BEHIND=$(git rev-list --count HEAD..origin/$MAIN_BRANCH 2>/dev/null || echo "unknown")
+COMMITS_AHEAD=$(git rev-list --count origin/$MAIN_BRANCH..HEAD 2>/dev/null || echo "unknown")
+```
+
+**Current Branch:** $CURRENT_BRANCH
+**Main Branch:** $MAIN_BRANCH
+**Uncommitted Changes:** $LOCAL_CHANGES
+**Commits Behind Main:** $COMMITS_BEHIND
+**Commits Ahead of Main:** $COMMITS_AHEAD
+
+## User Intent
+
+$ARGUMENTS
+
+## Workflow
+
+### Step 1: Stash if Needed
+If LOCAL_CHANGES is not empty:
+```bash
+git stash push -m "sync-main: auto-stash before rebase"
+```
+
+### Step 2: Fetch Latest
+```bash
+git fetch origin $MAIN_BRANCH
+```
+
+### Step 3: Rebase onto Main
+```bash
+git rebase origin/$MAIN_BRANCH
+```
+
+### Step 4: Handle Conflicts
+If rebase fails with conflicts:
+1. List conflicting files: `git diff --name-only --diff-filter=U`
+2. For each file, show the conflict markers
+3. Ask user how to resolve OR attempt auto-resolution if obvious
+4. After resolving: `git add <file>` then `git rebase --continue`
+
+If user wants to abort: `git rebase --abort`
+
+### Step 5: Pop Stash
+If we stashed earlier:
+```bash
+git stash pop
+```
+
+Handle stash conflicts if they occur.
+
+### Step 6: Force Push (if needed)
+After rebase, history has changed. Need force push:
+```bash
+git push --force-with-lease origin $CURRENT_BRANCH
+```
+
+Use `--force-with-lease` NOT `--force` for safety.
+
+### Step 7: Report
+```
+Sync complete:
+- Rebased $CURRENT_BRANCH onto $MAIN_BRANCH
+- Now up to date (was $COMMITS_BEHIND commits behind)
+- Pushed to remote
+```
+
+## Safety Checks
+- NEVER run on main/master branch directly
+- ALWAYS use --force-with-lease instead of --force
+- ALWAYS stash uncommitted work first
+- If conflicts are complex, ask user before auto-resolving
+
+## Common Scenarios
+
+**Clean sync (no conflicts):**
+```bash
+git fetch origin main
+git rebase origin/main
+git push --force-with-lease
+```
+
+**With local changes:**
+```bash
+git stash push -m "sync-main"
+git fetch origin main
+git rebase origin/main
+git push --force-with-lease
+git stash pop
+```
diff --git a/commands/test-verify.md b/commands/test-verify.md
new file mode 100644
index 0000000..f2512d5
--- /dev/null
+++ b/commands/test-verify.md
@@ -0,0 +1,128 @@
+# Test and Verify
+
+You are executing the **test-verify** workflow - runs tests and verifies the application works.
+
+## Pre-computed Context
+
+```bash
+# Detect project type and test framework
+HAS_PACKAGE_JSON=$(test -f package.json && echo "yes" || echo "no")
+TEST_SCRIPT=$(cat package.json 2>/dev/null | jq -r '.scripts.test // "none"')
+TYPECHECK_SCRIPT=$(cat package.json 2>/dev/null | jq -r '.scripts["type-check"] // .scripts.typecheck // "none"')
+LINT_SCRIPT=$(cat package.json 2>/dev/null | jq -r '.scripts.lint // "none"')
+BUILD_SCRIPT=$(cat package.json 2>/dev/null | jq -r '.scripts.build // "none"')
+HAS_PLAYWRIGHT=$(test -f playwright.config.ts && echo "yes" || echo "no")
+HAS_VITEST=$(grep -q "vitest" package.json 2>/dev/null && echo "yes" || echo "no")
+HAS_JEST=$(grep -q "jest" package.json 2>/dev/null && echo "yes" || echo "no")
+```
+
+**Package.json:** $HAS_PACKAGE_JSON
+**Test Script:** $TEST_SCRIPT
+**Type Check:** $TYPECHECK_SCRIPT
+**Lint Script:** $LINT_SCRIPT
+**Build Script:** $BUILD_SCRIPT
+**Has Playwright:** $HAS_PLAYWRIGHT
+**Has Vitest:** $HAS_VITEST
+**Has Jest:** $HAS_JEST
+
+## User Intent
+
+$ARGUMENTS
+
+## Full Verification Workflow
+
+### Phase 1: Static Analysis
+Run in parallel where possible:
+
+1. **Type Check** (if TypeScript project)
+```bash
+npm run type-check || npx tsc --noEmit
+```
+
+2. **Lint Check**
+```bash
+npm run lint
+```
+
+### Phase 2: Unit/Integration Tests
+```bash
+npm test
+```
+
+If specific test file requested in $ARGUMENTS:
+```bash
+npm test -- [file-pattern]
+```
+
+### Phase 3: E2E Tests (if Playwright exists)
+```bash
+npx playwright test
+```
+
+For specific test:
+```bash
+npx playwright test [test-name]
+```
+
+### Phase 4: Build Verification
+```bash
+npm run build
+```
+
+### Phase 5: Visual Verification (if requested or if UI changes)
+Use Playwright MCP to:
+1. Start dev server if not running
+2. Navigate to relevant pages
+3. Take screenshots
+4. Verify UI renders correctly
+
+## Reporting
+
+After each phase, report:
+```
+Phase 1 (Static Analysis): PASS/FAIL
+ - TypeScript: X errors
+ - ESLint: X warnings, X errors
+
+Phase 2 (Tests): PASS/FAIL
+ - X tests passed
+ - X tests failed
+ - X tests skipped
+
+Phase 3 (E2E): PASS/FAIL (if applicable)
+ - X specs passed
+
+Phase 4 (Build): PASS/FAIL
+ - Build time: Xs
+
+Overall: PASS/FAIL
+```
+
+## Quick Modes
+
+If $ARGUMENTS contains:
+- "quick" or "fast": Only run type-check + lint (skip tests)
+- "unit": Only run unit tests
+- "e2e": Only run Playwright tests
+- "build": Only verify build
+- "all" or empty: Full verification
+
+## Error Handling
+
+On failure:
+1. Capture full error output
+2. Identify the failing test/check
+3. Show relevant code context
+4. Suggest fix if obvious
+
+Do NOT proceed to later phases if earlier phases fail (unless user says "continue anyway").
+
+## Integration with Playwright MCP
+
+For visual verification:
+```
+1. browser_navigate to localhost:3000 (or dev server URL)
+2. browser_snapshot to capture page state
+3. browser_take_screenshot for visual record
+4. Compare with expected behavior
+```
diff --git a/commands/verify.md b/commands/verify.md
new file mode 100644
index 0000000..badcae7
--- /dev/null
+++ b/commands/verify.md
@@ -0,0 +1,45 @@
+# Verify Application
+
+You are invoking the **verify** skill - comprehensive verification following Boris Cherny's pattern.
+
+Load and follow the skill at: `.claude/skills/verify/SKILL.md`
+
+## Mode Selection
+
+Parse $ARGUMENTS to determine mode:
+- Empty or "all" → Full verification (all 6 layers)
+- "quick" → Static analysis only (Layer 1)
+- "visual" → Browser verification only (Layer 5)
+- "test" or "tests" → Unit + E2E tests (Layers 2-4)
+- "build" → Build verification only (Layer 6)
+- Anything else → Treat as component/feature name to focus on
+
+## Quick Reference
+
+### Full Verify
+```bash
+# Layer 1
+npm run type-check && npm run lint
+
+# Layer 2
+npm test
+
+# Layer 3 (if playwright exists)
+npx playwright test
+
+# Layer 4 (using Playwright MCP)
+# Navigate, snapshot, screenshot, check console
+
+# Layer 5
+npm run build
+```
+
+### Visual Verify Sequence
+1. `browser_navigate` to localhost:3000
+2. `browser_snapshot` to see page structure
+3. `browser_console_messages` to check for errors
+4. `browser_take_screenshot` for visual record
+5. Repeat for key pages
+
+## Arguments
+$ARGUMENTS
diff --git a/hooks.json b/hooks.json
index fff8218..64dac90 100644
--- a/hooks.json
+++ b/hooks.json
@@ -2,28 +2,46 @@
"hooks": {
"post-tool": {
"Write": [
+ "~/.claude/hooks/format-code.sh",
"~/.claude/hooks/verify-after-write.sh",
+ "~/.claude/hooks/agentic/reflection-gate.sh",
"~/.claude/hooks/auto-commit.sh",
"~/.claude/hooks/auto-documentation.sh",
"~/.claude/hooks/progress-report.sh",
"~/.claude/hooks/accessibility-check.sh",
- "~/.claude/hooks/performance-alert.sh"
+ "~/.claude/hooks/performance-alert.sh",
+ "~/.claude/hooks/pipeline/pipeline-activity-tracker.sh",
+ "~/.claude/hooks/track-tool-usage.sh Write"
],
"Edit": [
+ "~/.claude/hooks/format-code.sh",
"~/.claude/hooks/verify-after-edit.sh",
+ "~/.claude/hooks/agentic/reflection-gate.sh",
"~/.claude/hooks/progress-report.sh",
"~/.claude/hooks/accessibility-check.sh",
- "~/.claude/hooks/performance-alert.sh"
+ "~/.claude/hooks/performance-alert.sh",
+ "~/.claude/hooks/pipeline/pipeline-activity-tracker.sh",
+ "~/.claude/hooks/track-tool-usage.sh Edit"
],
"Bash": [
- "~/.claude/hooks/claude-corner-observer.sh"
+ "~/.claude/hooks/agentic/pev-verification.sh",
+ "~/.claude/hooks/track-tool-usage.sh Bash"
+ ],
+ "Read": [
+ "~/.claude/hooks/track-tool-usage.sh Read"
]
},
"user-prompt-submit": [
"~/.claude/hooks/pre-task-check.sh",
- "~/.claude/hooks/auto-git-workflow.sh"
+ "~/.claude/hooks/auto-git-workflow.sh",
+ "~/.claude/hooks/agentic/metacognitive-check.sh",
+ "~/.claude/hooks/pipeline/session-start-briefing.sh"
],
- "pre-pr-creation": "~/.claude/hooks/deployment-check.sh",
- "post-pr-creation": "~/.claude/hooks/claude-corner-observer.sh milestone"
+ "pre-tool": {
+ "Bash": [
+ "~/.claude/hooks/agentic/pev-verification.sh"
+ ]
+ },
+ "pre-pr-creation": "~/.claude/hooks/deployment-check.sh"
}
}
diff --git a/hooks/format-code.sh b/hooks/format-code.sh
new file mode 100755
index 0000000..a89e7e5
--- /dev/null
+++ b/hooks/format-code.sh
@@ -0,0 +1,77 @@
+#!/bin/bash
+# PostToolUse Formatter Hook
+# Automatically formats code after Write/Edit operations
+# Inspired by Boris Cherny's Claude Code workflow
+
+# Get the file path from the tool output
+# For Write/Edit tools, the file path is passed as first argument
+FILE_PATH="$1"
+
+# Exit if no file path or file doesn't exist
+[[ -z "$FILE_PATH" ]] && exit 0
+[[ ! -f "$FILE_PATH" ]] && exit 0
+
+# Get file extension
+EXT="${FILE_PATH##*.}"
+
+# Define formattable extensions
+FORMATTABLE_EXTS="ts tsx js jsx json css scss md html vue svelte"
+
+# Check if this extension should be formatted
+should_format() {
+ for ext in $FORMATTABLE_EXTS; do
+ [[ "$EXT" == "$ext" ]] && return 0
+ done
+ return 1
+}
+
+# Exit if not a formattable file
+should_format || exit 0
+
+# Find project root (look for package.json or .git)
+find_project_root() {
+ local dir="$(dirname "$FILE_PATH")"
+ while [[ "$dir" != "/" ]]; do
+ [[ -f "$dir/package.json" ]] && echo "$dir" && return
+ [[ -d "$dir/.git" ]] && echo "$dir" && return
+ dir="$(dirname "$dir")"
+ done
+ echo ""
+}
+
+PROJECT_ROOT=$(find_project_root)
+
+# If no project root found, skip formatting
+[[ -z "$PROJECT_ROOT" ]] && exit 0
+
+cd "$PROJECT_ROOT"
+
+# Try formatters in order of preference
+# 1. Biome (fastest)
+if [[ -f "biome.json" ]] || [[ -f "biome.jsonc" ]]; then
+ npx biome format --write "$FILE_PATH" 2>/dev/null
+ exit 0
+fi
+
+# 2. Prettier (most common)
+if [[ -f ".prettierrc" ]] || [[ -f ".prettierrc.json" ]] || [[ -f "prettier.config.js" ]] || [[ -f ".prettierrc.js" ]]; then
+ npx prettier --write "$FILE_PATH" 2>/dev/null
+ exit 0
+fi
+
+# 3. Check package.json for prettier
+if grep -q '"prettier"' package.json 2>/dev/null; then
+ npx prettier --write "$FILE_PATH" 2>/dev/null
+ exit 0
+fi
+
+# 4. ESLint with --fix for JS/TS files (if no prettier)
+if [[ "$EXT" =~ ^(ts|tsx|js|jsx)$ ]]; then
+ if [[ -f ".eslintrc" ]] || [[ -f ".eslintrc.json" ]] || [[ -f ".eslintrc.js" ]] || [[ -f "eslint.config.js" ]]; then
+ npx eslint --fix "$FILE_PATH" 2>/dev/null
+ exit 0
+ fi
+fi
+
+# No formatter found - that's okay, just exit cleanly
+exit 0
diff --git a/skills/verify/SKILL.md b/skills/verify/SKILL.md
new file mode 100644
index 0000000..c03fdb2
--- /dev/null
+++ b/skills/verify/SKILL.md
@@ -0,0 +1,183 @@
+# /verify - Unified Verification Skill
+
+A comprehensive verification skill that chains static analysis, tests, and visual verification. Inspired by Boris Cherny's "verify-app" subagent pattern.
+
+## Trigger
+- `/verify` - Run full verification suite
+- `/verify quick` - Static analysis only
+- `/verify visual` - Browser-based visual verification
+- `/verify [component]` - Verify specific component/feature
+
+## Philosophy
+
+> "The most important thing to get great results out of Claude Code -- give Claude a way to verify its work."
+> — Boris Cherny, Creator of Claude Code
+
+This skill provides that verification loop. It should be run:
+1. After completing a feature
+2. Before creating a PR
+3. After merging from main
+4. When debugging issues
+
+## Verification Layers
+
+```
+┌─────────────────────────────────────┐
+│ Layer 1: Static Analysis │
+│ - TypeScript compilation │
+│ - ESLint/Biome linting │
+│ - Prettier formatting check │
+├─────────────────────────────────────┤
+│ Layer 2: Unit Tests │
+│ - Jest/Vitest unit tests │
+│ - Component tests │
+│ - Utility function tests │
+├─────────────────────────────────────┤
+│ Layer 3: Integration Tests │
+│ - API route tests │
+│ - Database integration │
+│ - Service layer tests │
+├─────────────────────────────────────┤
+│ Layer 4: E2E Tests │
+│ - Playwright browser tests │
+│ - Critical user flows │
+│ - Cross-browser verification │
+├─────────────────────────────────────┤
+│ Layer 5: Visual Verification │
+│ - Live browser inspection │
+│ - Screenshot comparison │
+│ - Console error detection │
+│ - Network request validation │
+├─────────────────────────────────────┤
+│ Layer 6: Build Verification │
+│ - Production build succeeds │
+│ - Bundle size check │
+│ - No build warnings │
+└─────────────────────────────────────┘
+```
+
+## Execution Protocol
+
+### Full Verification (`/verify`)
+
+```
+1. STATIC ANALYSIS
+ ├── Run: npm run type-check || npx tsc --noEmit
+ ├── Run: npm run lint
+ └── GATE: Must pass before continuing
+
+2. UNIT TESTS
+ ├── Run: npm test
+ ├── Collect: Coverage report
+ └── GATE: Must pass before continuing
+
+3. E2E TESTS (if playwright.config exists)
+ ├── Run: npx playwright test
+ └── GATE: Must pass before continuing
+
+4. VISUAL VERIFICATION (using Playwright MCP)
+ ├── Start dev server if not running
+ ├── Navigate to key pages
+ ├── Take screenshots
+ ├── Check console for errors
+ ├── Verify no network failures
+ └── GATE: No critical issues
+
+5. BUILD
+ ├── Run: npm run build
+ └── GATE: Must succeed
+
+6. REPORT
+ └── Summary of all layers
+```
+
+### Quick Mode (`/verify quick`)
+Only runs Layer 1 (Static Analysis).
+
+### Visual Mode (`/verify visual`)
+Only runs Layer 5 (Visual Verification) using Playwright MCP.
+
+## Playwright MCP Integration
+
+For visual verification, use these MCP tools:
+
+```typescript
+// 1. Start by checking if dev server is running
+mcp__playwright-server__browser_navigate({ url: "http://localhost:3000" })
+
+// 2. Capture page state
+mcp__playwright-server__browser_snapshot()
+
+// 3. Check for console errors
+mcp__playwright-server__browser_console_messages({ level: "error" })
+
+// 4. Take screenshot for visual record
+mcp__playwright-server__browser_take_screenshot({ filename: "verify-{timestamp}.png" })
+
+// 5. Check network requests
+mcp__playwright-server__browser_network_requests()
+
+// 6. Navigate to key routes and repeat
+```
+
+## Key Pages to Verify
+
+For Next.js apps, automatically check:
+- `/` - Homepage
+- `/login` or `/auth` - Authentication (if exists)
+- Key feature pages based on recent changes
+
+## Error Classification
+
+| Severity | Action |
+|----------|--------|
+| CRITICAL | Stop verification, report immediately |
+| ERROR | Log and continue, fail at end |
+| WARNING | Log and continue, pass with warnings |
+| INFO | Log for reference |
+
+## Output Format
+
+```
+╔══════════════════════════════════════════════════════════╗
+║ VERIFICATION REPORT ║
+╠══════════════════════════════════════════════════════════╣
+║ Layer 1 - Static Analysis ✅ PASS ║
+║ TypeScript: 0 errors ║
+║ ESLint: 0 errors, 2 warnings ║
+╠══════════════════════════════════════════════════════════╣
+║ Layer 2 - Unit Tests ✅ PASS ║
+║ 42 tests passed ║
+║ Coverage: 78% ║
+╠══════════════════════════════════════════════════════════╣
+║ Layer 3 - E2E Tests ✅ PASS ║
+║ 12 specs passed ║
+╠══════════════════════════════════════════════════════════╣
+║ Layer 4 - Visual Verification ✅ PASS ║
+║ 3 pages checked ║
+║ 0 console errors ║
+║ Screenshots: verify-20240102-143022.png ║
+╠══════════════════════════════════════════════════════════╣
+║ Layer 5 - Build ✅ PASS ║
+║ Build time: 12.3s ║
+╠══════════════════════════════════════════════════════════╣
+║ ║
+║ OVERALL: ✅ VERIFICATION PASSED ║
+║ ║
+╚══════════════════════════════════════════════════════════╝
+```
+
+## Integration with Other Skills
+
+This skill works with:
+- `/commit-push-pr` - Run verify before creating PR
+- `/test-verify` - Subset focused on testing
+- `code-reviewer` subagent - Code quality checks
+
+## Automation Hook
+
+Can be triggered automatically via Stop hook for long-running tasks:
+```bash
+# ~/.claude/hooks/stop/verify-on-complete.sh
+# Runs /verify when Claude finishes a significant task
+```