vibe-validate 0.17.1-rc.3 → 0.17.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vibe-validate",
-  "version": "0.17.1-rc.3",
+  "version": "0.17.1",
   "description": "Git-aware validation orchestration for vibe coding (LLM-assisted development) - umbrella package",
   "type": "module",
   "bin": {
@@ -50,7 +50,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@vibe-validate/cli": "0.17.1-rc.3"
+    "@vibe-validate/cli": "0.17.1"
   },
   "devDependencies": {
     "@types/node": "^20.14.8",
@@ -60,7 +60,6 @@
   "scripts": {
     "test": "vitest run",
     "lint": "echo 'No linting needed for delegation wrappers'",
-    "postinstall": "node scripts/install-skill.js",
-    "preuninstall": "node scripts/uninstall-skill.js"
+    "postinstall": "node scripts/install-skill.js"
   }
 }

package/skill/SKILL.md

@@ -22,7 +22,7 @@ permissions:
 
 # vibe-validate Expert Agent
 
-You are an expert in **vibe-validate**, a git-aware validation orchestration tool designed for LLM-assisted development (vibe coding). You help developers leverage vibe-validate's 312x faster cached validation and 90-95% context window reduction.
+You are an expert in **vibe-validate**, a git-aware validation orchestration tool designed for LLM-assisted development (vibe coding). You help developers leverage vibe-validate's dramatically faster cached validation and 90-95% context window reduction.
 
 ## Core Principles
 
@@ -54,7 +54,7 @@ npx vibe-validate pre-commit
 
 ```bash
 # Step 2: Query cached state (DO NOT re-run tests!)
-npx vibe-validate state --yaml
+npx vibe-validate state
 ```
 
 **Step 3: Analyze the state output**:
@@ -85,6 +85,9 @@ git merge origin/main  # or git rebase origin/main
 npx vibe-validate pre-commit
 ```
 
+**For complete workflow patterns and decision trees**:
+- **Load**: [Workflows & Decision Trees](resources/workflows.md)
+
 ### 2. Context-Optimized Test Running
 
 **When**: Running tests, linting, type checking during development
@@ -121,15 +124,13 @@ guidance: "Fix assertion in tests/foo.test.ts:42"
 - ❌ Already-wrapped: `pnpm validate`
 - ❌ Interactive: `git log`
 
-**NEW in v0.15.0 - Smart Caching**:
-
-The `run` command automatically caches results by git tree hash:
+**Smart Caching** (automatic):
 
 ```bash
 # First run - executes and caches (~30s)
 npx vibe-validate run "pnpm test"
 
-# Repeat run - instant (<200ms) ✨
+# Repeat run - instant (<1s) ✨
 npx vibe-validate run "pnpm test"
 ```
 
@@ -137,31 +138,20 @@ npx vibe-validate run "pnpm test"
 ```bash
 # Check cache without executing
 npx vibe-validate run --check "pnpm test"
-# Exit 0 if cached, exit 1 if not
 
 # Force fresh execution
 npx vibe-validate run --force "pnpm test"
-# Always executes, updates cache
 ```
 
-**View/manage run cache**:
-```bash
-# List cached runs
-npx vibe-validate history list --run
-
-# Filter by command
-npx vibe-validate history list --run "vitest"
-
-# Clear run cache
-npx vibe-validate history prune --run --all
-```
+**For complete run capability details**:
+- **Load**: [Run Capability Guide](resources/run-capability.md)
 
 ### 3. Full Validation Pipeline
 
 **When**: Validating before push, checking all validation steps
 
 ```bash
-# Run full validation with caching
+# Run all validation phases
 npx vibe-validate validate
 
 # Force re-validation (bypass cache)
@@ -200,11 +190,11 @@ npx vibe-validate doctor
 **When**: Checking current validation status, debugging failures
 
 ```bash
-# Human-readable summary
+# Query current state (instant, no re-run)
 npx vibe-validate state
 
-# Full error output (YAML)
-npx vibe-validate state --yaml
+# Full error output
+npx vibe-validate state --verbose
 ```
 
 **State includes**:
@@ -214,7 +204,31 @@ npx vibe-validate state --yaml
 - Failed step details
 - Complete error output
 
-### 6. PR Monitoring
+### 6. Work Recovery & Protection
+
+**When**: User accidentally loses work, wants to recover from previous state
+
+**Quick recovery**:
+```bash
+# List recent validation snapshots
+vv history list --limit 5
+
+# Recover deleted file
+git cat-file -p <tree-hash>:path/to/file.ts > path/to/file.ts
+
+# Recover entire directory
+git checkout <tree-hash> -- src/
+```
+
+**Automatic snapshots created during**:
+- `vv validate` - Full validation pipeline
+- `vv pre-commit` - Pre-commit workflow
+- `vv run <command>` - Individual command execution
+
+**For comprehensive recovery patterns**:
+- **Load**: [Work Recovery Guide](resources/work-recovery.md)
+
+### 7. PR Monitoring
 
 **When**: Waiting for CI validation, debugging CI failures
 
@@ -224,9 +238,6 @@ npx vibe-validate watch-pr
 
 # Specific PR number
 npx vibe-validate watch-pr 123
-
-# YAML output
-npx vibe-validate watch-pr --yaml
 ```
 
 **Features**:
@@ -234,7 +245,7 @@ npx vibe-validate watch-pr --yaml
 - Extracts vibe-validate state from failed runs
 - Provides recovery commands
 
-### 7. Project Initialization
+### 8. Project Initialization
 
 **When**: Setting up vibe-validate in a new project
 
@@ -252,127 +263,16 @@ npx vibe-validate init --template typescript-react
 
 **After init**: Always run `npx vibe-validate doctor`
 
-### 8. Work Recovery & Protection
-
-**When**: User accidentally loses work, wants to recover from previous state, or wants to compare code states
+**For comprehensive setup guidance**:
+- **Load**: [Configure Project Guide](resources/configure-project.md)
 
-#### View Validation Snapshots
+### 9. Improving Poor Extraction Results
 
-```bash
-# List all validation points (timestamped tree hashes)
-vv history list
-
-# Show details of specific validation
-vv history show <tree-hash>
-
-# YAML output for programmatic access
-vv history list --yaml
-```
-
-#### Recover Lost Work
-
-**Scenario**: User accidentally ran `git restore .` or deleted files
-
-```bash
-# Step 1: Find recent validation point
-vv history list --limit 5
-
-# Step 2: View file content from that validation
-git cat-file -p <tree-hash>:path/to/file.ts
-
-# Step 3: Recover the file
-git cat-file -p <tree-hash>:path/to/file.ts > path/to/file.ts
-
-# Or recover entire directory
-git checkout <tree-hash> -- src/
-```
-
-#### Compare Code States
-
-**Scenario**: User wants to see what changed between two validation points
-
-```bash
-# Compare two tree hashes
-git diff <old-tree-hash> <new-tree-hash>
-
-# Compare specific file between validations
-git diff <old-tree-hash>:<file> <new-tree-hash>:<file>
-
-# Show what files changed
-git diff --name-status <old-tree-hash> <new-tree-hash>
-```
-
-#### View Files in Snapshot
-
-```bash
-# List all files in a tree hash
-git ls-tree -r <tree-hash>
-
-# List specific directory
-git ls-tree -r <tree-hash> src/
-
-# View specific file
-git cat-file -p <tree-hash>:src/feature.ts
-```
-
-#### When Work is Protected
-
-Automatic snapshots are created during:
-- `vv validate` - Full validation pipeline
-- `vv pre-commit` - Pre-commit workflow
-- `vv run <command>` - Individual command execution (v0.15.0+)
-
-Each creates a tree hash in git objects that captures complete working directory state.
-
-#### What Gets Protected
-
-- ✅ Staged changes (in git index)
-- ✅ Unstaged modifications (tracked files)
-- ✅ Untracked files (new files, not in .gitignore)
-
-Not protected (by design):
-- ❌ Files in .gitignore (secrets, build artifacts)
-
-#### Recovery Patterns
-
-**Pattern 1: Undo Recent Changes**
-```bash
-# List recent validations
-vv history list --limit 10
-
-# Pick validation from before bad changes
-# Recover all affected files
-git checkout <good-tree-hash> -- src/
-```
-
-**Pattern 2: Cherry-pick Deleted File**
-```bash
-# Find validation when file existed
-vv history list
-
-# Recover just that file
-git cat-file -p <tree-hash>:path/to/deleted.ts > path/to/deleted.ts
-```
-
-**Pattern 3: Compare Before/After Refactoring**
-```bash
-# Before refactoring validation: abc123
-# After refactoring validation: def456
-
-# See all changes
-git diff abc123 def456
-
-# If refactoring went wrong, revert specific files
-git checkout abc123 -- src/refactored-file.ts
-```
-
-### 5. Improving Poor Extraction Results
-
-**When**: Validation fails (exitCode !== 0) but no errors extracted (totalErrors === 0), or generic extractor is being used
+**When**: Validation fails (exitCode !== 0) but no errors extracted (totalErrors === 0)
 
 **Step 1: Identify the problem**
 ```bash
-npx vibe-validate state --yaml
+npx vibe-validate state
 ```
 
 Look for:
@@ -385,216 +285,61 @@ extraction:
       extractor: generic  # ❌ Fell back to generic
 ```
 
-**Step 2: Understand what happened**
-- If `totalErrors: 0` but command failed → extractor didn't recognize error format
-- If `extractor: generic` → no specific extractor found for this tool
-- If errors seem truncated → extractor may need tuning
-
-**Step 3: Create custom extractor**
-→ **Load**: [Extending Extraction Guide](resources/extending-extraction.md)
-
-This guide will:
-1. Help you use `vv create-extractor` scaffolding command
-2. Show you how to identify error patterns in your tool's output
-3. Guide implementation of the extraction logic
-4. Show testing and verification steps
-
-**Progressive detail**: If you need to understand how extractors work internally first, the Extending Extraction Guide links to the complete [Error Extractors Guide](resources/error-extractors-guide.md).
-
-## Decision Trees
-
-### When User Requests a Commit
-
-```
-User: "Commit these changes"
-  ↓
-Run: npx vibe-validate pre-commit
-  ↓
-  ├─ Pass → Proceed with commit
-  │
-  └─ Fail → Query: npx vibe-validate state --yaml
-           ↓
-           Analyze failedStepOutput
-           ↓
-           Fix errors
-           ↓
-           Re-run: npx vibe-validate pre-commit (fast with cache!)
-           ↓
-           Repeat until pass
-```
-
-### When User Requests Running Tests
-
-```
-User: "Run the tests in path/to/test.ts"
-  ↓
-Run: npx vibe-validate run "npx vitest path/to/test.ts"
-  ↓
-Parse YAML output
-  ↓
-  ├─ exitCode: 0 → Report success
-  │
-  └─ exitCode: 1 → Show errors[] from YAML
-           ↓
-           User fixes or asks for help
-           ↓
-           Re-run (wrapped)
-```
-
-### When Validation Behaves Unexpectedly
-
-```
-Issue: Validation slow/flaky/failing unexpectedly
-  ↓
-Run: npx vibe-validate doctor
-  ↓
-  ├─ Issues found → Follow guidance to fix
-  │
-  └─ No issues → Check configuration validity
-           ↓
-           Run: npx vibe-validate config --validate
-```
-
-## Performance & Caching
-
-### How Caching Works
-
-**Cache key**: Git tree hash (deterministic content hash)
-- Same code = same hash
-- Includes untracked files
-- No timestamps (purely content-based)
-
-**Cache hit**: ~288ms (312x faster than full validation)
-**Cache miss**: ~60-90s (runs all validation steps)
-
-**When cache invalidates**:
-- Any file content changes
-- New files added
-- Files deleted
-- Working tree modifications
-
-**When cache persists**:
-- Switching branches (if same code)
-- Git operations (commits, merges) that result in same tree
-- Time passing (content-based, not time-based)
-
-### Leveraging Caching for Speed
-
-**Pattern**: Fix incrementally
-```bash
-# First run: Full validation (~90s)
-npx vibe-validate validate
-
-# Fix 1-2 errors
-# Second run: Mostly cached, only changed files re-validated
-npx vibe-validate validate
+**Step 2: Create custom extractor**
+- **Load**: [Extending Extraction Guide](resources/extending-extraction.md)
 
-# Repeat: Fast iteration with caching
-```
+This guide shows how to use `vv create-extractor` and implement custom error extraction logic.
 
 ## Configuration
 
-### Config File Location
-
-`vibe-validate.config.yaml` (project root)
+**Config file**: `vibe-validate.config.yaml` (project root)
 
 **Schema URL** (for IDE autocomplete):
 ```yaml
 $schema: https://unpkg.com/@vibe-validate/config/config.schema.json
 ```
 
-### Key Configuration Sections
-
-```yaml
-git:
-  mainBranch: main          # Default branch for sync checks
-  remoteOrigin: origin      # Remote name
-  autoSync: false           # Never auto-merge (safety)
-
-validation:
-  failFast: true            # Stop on first phase failure
-  phases:
-    - name: Pre-Qualification
-      parallel: true        # Run steps in parallel
-      steps:
-        - name: TypeScript
-          command: pnpm typecheck
-        - name: ESLint
-          command: pnpm lint
-
-    - name: Testing
-      parallel: false       # Sequential
-      steps:
-        - name: Unit Tests
-          command: pnpm test
-```
-
-**For detailed configuration**: Load [Configuration Reference](resources/configuration-reference.md)
-
-## Error Extractors
+**For complete configuration reference**:
+- **Load**: [Configuration Reference](resources/configuration-reference.md)
 
-vibe-validate extracts errors from tool output for LLM consumption.
+## Performance & Caching
 
-**Supported tools**:
-- TypeScript (`tsc`)
-- ESLint
-- Vitest / Jest
-- OpenAPI validators
-- Generic (fallback)
+**How it works**:
+- Git tree hash (content-based) = cache key
+- Same code = same hash = instant cache hit
+- Changed code = new hash = re-validation
 
-**Extraction**: Removes ANSI codes, progress bars, passing tests → extracts only errors with file:line context.
+**Cache persists across**:
+- Branch switches (if same code)
+- Time passing (content-based, not time-based)
+- Git operations (commits, merges)
 
-**If errors aren't being captured**: See workflow below for improving extraction.
+**For complete caching internals and optimization strategies**:
+- **Load**: [Caching Internals Guide](resources/caching-internals.md)
 
 ## Troubleshooting
 
-### "vibe-validate not found"
+### Quick Fixes
 
-**Solution**: Install in project:
+**"vibe-validate not found"**
 ```bash
 npm install -D vibe-validate
 ```
 
-### "Validation slow every time"
-
-**Check**:
-1. In a git repository? `git rev-parse --git-dir`
-2. Run: `npx vibe-validate doctor`
-
-### "Validation passes locally but fails in CI"
-
-**Check**:
-1. Force re-run locally: `npx vibe-validate validate --force`
-2. Verify no hardcoded paths or environment-specific code
-3. Check test isolation (no shared state)
-
-### "Branch sync check fails incorrectly"
-
-**Check**:
-1. Fetch latest: `git fetch origin`
-2. Verify tracking: `git branch -vv`
-3. Confirm remote exists: `git ls-remote origin main`
-
-### "I accidentally deleted my work"
-
-**Check recent validations**:
+**"Validation slow every time"**
 ```bash
-vv history list --limit 5
+git rev-parse --git-dir  # Check if in git repo
+npx vibe-validate doctor  # Run diagnostics
 ```
 
-**Recover from most recent**:
+**"I accidentally deleted my work"**
 ```bash
-# View what was in that validation
-git ls-tree -r <tree-hash>
-
-# Recover specific file
-git cat-file -p <tree-hash>:path/to/file.ts > path/to/file.ts
-
-# Recover directory
-git checkout <tree-hash> -- src/
+vv history list --limit 5  # Find recent validation
+git checkout <tree-hash> -- path/to/file.ts  # Recover
 ```
 
-**If validation wasn't run recently**: Work might not be recoverable via vibe-validate. Try `git reflog` or file recovery tools.
+**For comprehensive troubleshooting**:
+- **Load**: [Troubleshooting Guide](resources/troubleshooting.md)
 
 ## Reference Documentation
 
@@ -614,52 +359,22 @@ For creating custom extractors:
 - **Load**: [Extending Extraction](resources/extending-extraction.md)
 
 ### Agent Integration
-For integration with other AI assistants (Cursor, Aider, Continue):
-- **Load**: [Agent Integration Guide](../../docs/agent-integration-guide.md)
-
-### Development Context
-For vibe-validate development workflows (if working on vibe-validate itself):
-- **Load**: [CLAUDE.md](../../CLAUDE.md)
-
-## Dogfooding (Meta)
-
-**If you're working on the vibe-validate codebase itself**:
-
-You ARE using vibe-validate while helping develop it. This is intentional dogfooding!
-
-**Always use vibe-validate tools during development**:
-```bash
-# Instead of raw commands:
-npx vitest packages/cli/test/run.test.ts
-
-# Use the tool you're building:
-npx vibe-validate run "npx vitest packages/cli/test/run.test.ts"
-```
-
-**Why this matters**:
-- Validates the tool works (proof)
-- Saves YOUR context window (90-95% reduction)
-- Demonstrates natural UX (if you use it instinctively, users will trust it)
+For integration with other AI assistants (Cursor, Aider, Continue) or when user asks for help configuring those tools:
+- **Load**: [Agent Integration Guide](resources/agent-integration-guide.md)
 
-**Key principle**: If you find yourself typing raw test commands, STOP and use vibe-validate instead.
+**Note**: This guide is NOT for Claude Code (you already have vibe-validate via this skill). Only load if user specifically asks about configuring Cursor, Aider, Continue, or similar tools.
 
 ## Best Practices
 
-1. **Always validate before commits** - Use `pre-commit` workflow
-2. **Query state before re-running** - Use `state` command (instant)
-3. **Fix incrementally** - Don't try to fix everything at once
-4. **Trust the extractors** - Error formats are well-tested
-5. **Leverage caching** - Most re-runs are <1s when you fix incrementally
-6. **Use YAML output** - Structured data for your parsing
-7. **Run doctor after upgrades** - Catch deprecated files and config issues
-8. **Validate frequently for safety** - Creates automatic snapshots of your work
-9. **Check history before panic** - Your work is probably saved in a tree hash
+1. **Always validate before commits** - Use `pre-commit` workflow to prevent broken code
+2. **Query state before re-running** - Use `state` command instead of re-running tests
+3. **Wrap commands with `run`** - Get 90-95% context reduction automatically
 
-## Remember
+## Key Reminders
 
 - **Pre-commit validation prevents broken commits** (most important workflow)
 - **State queries are instant** (don't re-run tests to see errors)
-- **Caching provides 312x speedup** (when code unchanged)
+- **Caching provides dramatic speedup** (when code unchanged)
 - **Context reduction saves 90-95%** (wrap commands with `run`)
 - **Git tree hashing is deterministic** (same code = same cache key)