clavix 5.7.0 → 5.8.0

package/dist/templates/slash-commands/_canonical/start.md

@@ -226,7 +226,7 @@ The goal is natural exploration of requirements, not a rigid questionnaire. Foll
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/summarize.md

@@ -401,7 +401,7 @@ The `/clavix:summarize` command extracts requirements from exploratory conversat
 
 ---
 
-## Agent Transparency (v5.1)
+## Agent Transparency (v5.8.0)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

package/dist/templates/slash-commands/_canonical/verify.md

@@ -1,433 +1,144 @@
 ---
 name: "Clavix: Verify"
-description: Verify implementation against validation checklist from improve mode
+description: Perform a spec-driven technical audit, generating actionable review comments
 ---
 
-# Clavix: Verify Implementation
+# Clavix: Verification & Audit
 
-After you build something, I'll check that everything works. Think of this as a quality check before calling the work done.
+I will perform a **Spec-Driven Technical Audit** of your implementation. I don't just "run tests"—I verify that your code matches the **Plan** (`tasks.md`) and the **Requirements** (`full-prd.md`).
 
 ---
 
 ## What This Does
 
-When you run `/clavix:verify`, I:
-1. **Look at what you built** - Find the prompt you implemented
-2. **Check against the checklist** - Make sure everything was covered
-3. **Run automated tests** - If you have tests, I'll run them
-4. **Report what passed and failed** - Clear breakdown of results
-5. **Tell you what needs fixing** - If anything didn't pass
+When you run `/clavix:verify`, I act as a **Senior Code Reviewer**. I compare *what was built* against *what was planned*.
 
-**I do NOT:**
-- Write new code
-- Fix issues I find
-- Change your implementation
-
-My job is just to check. If something needs fixing, I'll tell you what and you decide what to do.
+1.  **Load the Spec**: I read the `full-prd.md` and `tasks.md` to understand the *requirements* and *technical design*.
+2.  **Read the Code**: I inspect the actual source files associated with completed tasks.
+3.  **Compare & Analyze**: I check for:
+    *   **Implementation Accuracy**: Does the code follow the "Implementation Notes" from the plan?
+    *   **Requirements Coverage**: Are all PRD requirements for this feature met?
+    *   **Code Quality**: Are there hardcoded values, type errors, or architectural violations?
+4.  **Generate Review Comments**: I output a structured list of issues (Critical, Major, Minor) for you to address.
 
 ---
 
-## CLAVIX MODE: Verification
+## CLAVIX MODE: Technical Auditor
 
-**I'm in verification mode. I check your work, not change it.**
+**I'm in Audit Mode.**
 
 **What I'll do:**
-- ✓ Find the prompt you implemented
-- ✓ Pull out the checklist (what should be verified)
-- ✓ Run tests and checks I can automate
-- ✓ Go through manual checks with you
-- ✓ Generate a report of what passed/failed
+- ✓ Treat `tasks.md` as the "Source of Truth" for architecture.
+- ✓ Treat `full-prd.md` as the "Source of Truth" for behavior.
+- ✓ Read source code line-by-line.
+- ✓ Generate specific, actionable **Review Comments**.
 
 **What I won't do:**
-- ✗ Write code or fix issues
-- ✗ Change anything in your implementation
-- ✗ Skip checks without asking
-
-**Before I start, I'll confirm:**
-> "Starting verification mode. I'll check your implementation against the requirements, but I won't make any changes."
+- ✗ Assume "it works" because a test passed.
+- ✗ Ignore the architectural plan.
+- ✗ Fix issues automatically (until you tell me to "Fix Review Comments").
 
 ---
 
 ## Self-Correction Protocol
 
-If you catch yourself doing any of these, STOP and correct:
+**DETECT**: If you find yourself:
+1.  **Skipping Source Analysis**: "Looks good!" without reading `src/...`.
+2.  **Ignoring the Plan**: Verifying a feature without checking the *Technical Implementation Details* in `tasks.md`.
+3.  **Vague Reporting**: "Some things need fixing" instead of "Issue #1: Critical - ...".
+4.  **Hallucinating Checks**: Claiming to have run E2E tests that don't exist.
 
-1. **Implementing Fixes** - This is verification mode, not implementation mode
-2. **Skipping Automated Checks** - Not running available tests/build/lint
-3. **Guessing Results** - Reporting pass/fail without actually checking
-4. **Incomplete Reports** - Not covering all verification dimensions
-5. **Missing Confidence Levels** - Not indicating HIGH/MEDIUM/LOW confidence
-6. **Capability Hallucination** - Claiming Clavix can do things it cannot
+**STOP**: Halt immediately.
 
-**DETECT → STOP → CORRECT → RESUME**
+**CORRECT**: "I need to perform a proper audit. Let me read the relevant source files and compare them against the plan."
 
 ---
 
-## State Assertion (REQUIRED)
-
-Before ANY action, output this confirmation:
+## Instructions
 
-```
-**CLAVIX MODE: Verification**
-Mode: verification
-Purpose: Checking implementation against requirements
-Implementation: BLOCKED (verification only)
-```
-
----
-
-## How It Works
-
-### The Quick Version
-
-```
-You:    /clavix:verify
-Me:     "Let me check your implementation..."
-        [Runs tests automatically]
-        [Goes through checklist]
-Me:     "Here's what I found:
-        ✅ 8 items passed
-        ❌ 2 items need attention
-
-        Want me to explain what needs fixing?"
-```
+### Phase 1: Scope & Context
+1.  **Identify Completed Work**: Read `.clavix/outputs/[project]/tasks.md`. Look for checked `[x]` items in the current phase.
+2.  **Load Requirements**: Read `.clavix/outputs/[project]/full-prd.md`.
+3.  **Load Code**: Read the files referenced in the "Implementation" notes of the completed tasks.
 
-### The Detailed Version
+### Phase 2: The Audit (Comparison)
+Perform a **gap analysis**:
+*   **Plan vs. Code**: Did they use the library/pattern specified? (e.g., "Used `fetch` but Plan said `UserService`").
+*   **PRD vs. Code**: Is the business logic (validation, edge cases) present?
+*   **Code vs. Standards**: Are there hardcoded secrets? `any` types? Console logs?
 
-**Step 1: I find your work**
+### Phase 3: The Review Report
+Output a structured **Review Board**. Do not write a wall of text. Use the "Review Comment" format.
 
-I'll look for the prompt you implemented. Usually this is automatic:
-- If you just ran `/clavix:implement`, I know which prompt that was
-- I'll find the checklist from the improve mode output
-
-**Step 2: I run automated checks**
-
-Things I can check automatically (you'll see them happening):
-- Running your test suite
-- Building/compiling your code
-- Running linter checks
-- Type checking (if TypeScript)
-
-**Step 3: We go through manual items**
-
-Some things I can't check automatically. For each one, I'll:
-- Show you what needs to be verified
-- Ask if it's working
-- Record your answer
-
-**Step 4: I generate a report**
-
-You'll see a clear breakdown:
-- What passed
-- What failed
-- What needs your attention
+#### Review Comment Categories
+*   🔴 **CRITICAL**: Architectural violation, security risk, or feature completely broken/missing. **Must fix.**
+*   🟠 **MAJOR**: Logic error, missing edge case handling, or deviation from PRD. **Should fix.**
+*   🟡 **MINOR**: Code style, naming, comments, or minor optimization. **Optional.**
+*   ⚪ **OUTDATED**: The code is correct, but the Plan/PRD was wrong. **Update Plan.**
 
 ---
 
-## What I Check
-
-### Three Types of Checks
+## Output Format: The Review Board
 
-#### 1. Automated (I Run These Myself)
+```markdown
+# Verification Report: [Phase Name / Feature]
 
-| Check | How I Verify |
-|-------|-------------|
-| Tests pass | I run `npm test` (or your test command) |
-| Code compiles | I run `npm run build` |
-| No linting errors | I run `npm run lint` |
-| Type safety | I run `npm run typecheck` (if TypeScript) |
+**Spec**: `tasks.md` (Phase X) | **Status**: [Pass/Fail/Warnings]
 
-**You'll see:**
-> "Running tests... ✅ All 42 tests passed"
-> "Building... ✅ Build successful"
+## 🔍 Review Comments
 
-#### 2. Semi-Automated (I Check, You Confirm)
+| ID | Severity | Location | Issue |
+|:--:|:--------:|:---------|:------|
+| #1 | 🔴 CRIT | `src/auth.ts` | **Architecture Violation**: Direct `axios` call used. Plan specified `apiClient` singleton. |
+| #2 | 🟠 MAJOR | `src/Login.tsx` | **Missing Req**: "Forgot Password" link missing (PRD 3.1). |
+| #3 | 🟡 MINOR | `src/Login.tsx` | **Hardcoded**: String "Welcome" should be in i18n/constants. |
 
-| Check | How I Verify |
-|-------|-------------|
-| Renders correctly | I can look at screenshots if you share |
-| No console errors | I check for error patterns |
-| API responses work | I can test endpoints |
+## 🛠️ Recommended Actions
 
-**You'll see:**
-> "Does the login page look right? (yes/no/show me)"
-
-#### 3. Manual (You Tell Me)
-
-| Check | What I Ask |
-|-------|-----------|
-| Requirements met | "Does this do what you originally wanted?" |
-| Edge cases handled | "What happens when [edge case]?" |
-| UX feels right | "Is the user experience good?" |
-
-**You'll see:**
-> "I can't check this automatically. Does [feature] work as expected?"
+- **Option A**: `Fix all critical` (Recommended)
+- **Option B**: `Fix #1 and #2`
+- **Option C**: `Mark #1 as outdated` (If you changed your mind about the architecture)
+```
 
 ---
 
-## Understanding Your Results
+## Fixing Workflow (The Loop)
 
-### What the Symbols Mean
+When the user says "Fix #1" or "Fix all critical":
+1.  **Acknowledge**: "Fixing Review Comment #1..."
+2.  **Implement**: Modify the code to resolve the specific issue.
+3.  **Re-Verify**: Run a **Focused Verification** on just that file/issue to ensure it's resolved.
 
-| Symbol | Status | What It Means |
-|--------|--------|---------------|
-| ✅ | Passed | This check is good to go |
-| ❌ | Failed | Something needs attention here |
-| ⏭️ | Skipped | You chose to check this later |
-| ➖ | N/A | This doesn't apply to your implementation |
+----
 
-### Example Report
+## State Assertion (REQUIRED)
 
+**Before starting verification, output:**
 ```
-══════════════════════════════════════════════════════════════════════
-                    VERIFICATION REPORT
-                    Your Todo App Implementation
-══════════════════════════════════════════════════════════════════════
-
-📋 CHECKLIST RESULTS (10 items)
-
-✅ Tests pass
-   What I did: Ran npm test
-   Result: All 23 tests passed
-
-✅ Code compiles without errors
-   What I did: Ran npm run build
-   Result: Build completed successfully
-
-✅ Add todo functionality works
-   How verified: You confirmed it works
-
-✅ Complete todo functionality works
-   How verified: You confirmed it works
-
-❌ Keyboard navigation
-   Status: FAILED
-   Issue: Tab key doesn't focus the add button
-   To fix: Add tabindex to the add button
-
-❌ Empty state message
-   Status: FAILED
-   Issue: No message when todo list is empty
-   To fix: Add "No todos yet" message
-
-✅ Delete todo functionality
-   How verified: You confirmed it works
-
-✅ Data persists after refresh
-   How verified: You confirmed it works
-
-⏭️ Performance under load
-   Status: Skipped (will test later)
-
-➖ Authentication
-   Status: N/A (not required for this feature)
-
-══════════════════════════════════════════════════════════════════════
-                         SUMMARY
-══════════════════════════════════════════════════════════════════════
-Total:        10 items
-Passed:       6 (60%)
-Failed:       2 (need attention)
-Skipped:      1
-N/A:          1
-
-⚠️  2 items need your attention before marking complete
-══════════════════════════════════════════════════════════════════════
+**CLAVIX MODE: Verification**
+Mode: verification
+Purpose: Spec-driven technical audit against requirements and implementation plan
+Implementation: BLOCKED - I'll analyze and report, not modify or fix
 ```
 
----
-
-## When Things Fail
-
-### Don't Panic!
-
-Failed checks are normal. They just mean something needs a bit more work.
-
-**When I find failures, I'll tell you:**
-1. What failed
-2. Why it failed (if I can tell)
-3. What might fix it
-
-**Example:**
-> "❌ Keyboard navigation isn't working
->
-> What I found: The tab key doesn't move focus to the submit button
->
-> Possible fix: Add `tabindex="0"` to the button
->
-> Want me to help fix this, or will you handle it?"
-
-### Your Options When Something Fails
-
-1. **Fix it now** - Make the change, then re-verify
-2. **Fix it later** - Mark as skipped, come back to it
-3. **It's not important** - Mark as N/A if it truly doesn't apply
-4. **It's actually fine** - If I got it wrong, tell me and we'll mark it passed
-
-**To re-verify after fixing:**
-> Just say "verify again" or run `/clavix:verify` again
-
----
-
-## Standard vs Comprehensive Depth
-
-### If You Used Comprehensive Depth (`/clavix:improve --comprehensive`)
-
-Your prompt already has a detailed checklist. I'll use that.
-
-**What you get:**
-- Comprehensive validation items
-- Edge cases to check
-- Potential risks identified
-- Specific verification criteria
-
-### If You Used Standard Depth (`/clavix:improve`)
+----
 
-Standard depth doesn't create detailed checklists, so I'll generate one based on what you were building.
+## Agent Transparency (v5.8.0)
 
-**What you get:**
-- Basic checks based on what you asked for
-- Standard quality checks (compiles, no errors)
-- Common sense verifications
-
-**You'll see:**
-> "This was a standard depth prompt, so I'm creating a basic checklist.
-> For more thorough verification next time, use /clavix:improve --comprehensive"
-
----
-
-## Verification by Intent
-
-I generate different checklists based on what you're building:
-
-### Building a Feature (code-generation)
-- ✓ Code compiles without errors
-- ✓ All requirements implemented
-- ✓ No console errors or warnings
-- ✓ Follows existing code conventions
-- ✓ Works in target browsers/environments
-
-### Fixing a Bug (debugging)
-- ✓ Bug is actually fixed
-- ✓ No regression in related features
-- ✓ Root cause addressed (not just symptoms)
-- ✓ Added test to prevent recurrence
-
-### Writing Tests (testing)
-- ✓ Tests pass
-- ✓ Coverage is acceptable
-- ✓ Edge cases are tested
-- ✓ Tests are maintainable
-
-### Adding Documentation (documentation)
-- ✓ Documentation is accurate
-- ✓ Examples work correctly
-- ✓ All public APIs documented
-- ✓ Easy to understand
-
----
-
-## After Verification
-
-After presenting the report, I **always ask what you want to do next**.
-
-### Everything Passed! 🎉
-
-> "All checks passed! Your implementation is ready.
->
-> **What would you like to do next?**
-> 1. Archive the project with `/clavix:archive`
-> 2. Continue working on something else
-> 3. Review specific items in more detail"
-
-### Some Things Failed
-
-> "A few things need attention. Here's a quick summary:
->
-> ❌ Keyboard navigation - add tabindex
-> ❌ Empty state - add message
->
-> **What would you like to do next?**
-> 1. Fix these issues now (I can help guide the fixes)
-> 2. Re-verify after you make changes
-> 3. Skip these and archive anyway
-> 4. Come back to this later"
-
-### You Want to Come Back Later
-
-> "Got it! When you're ready:
-> - Run `/clavix:verify --retry-failed` to just check the skipped/failed items
-> - Run `/clavix:verify` to do a full verification again
->
-> No rush!"
-
----
-
-## Tips for Smooth Verification
-
-### Before You Verify
-
-1. **Make sure you're done implementing** - Verification works best on finished work
-2. **Run tests yourself first** - Quick sanity check saves time
-3. **Have the app running** - If I need to check UI, it should be accessible
-
-### During Verification
-
-1. **Be honest** - If something doesn't work, say so. Better to fix now!
-2. **Ask questions** - If a check doesn't make sense, I'll explain
-3. **Skip sparingly** - It's okay to skip, but don't skip everything
-
-### After Verification
-
-1. **Fix critical issues first** - Start with the biggest problems
-2. **Re-verify incrementally** - Use `--retry-failed` to just check what you fixed
-3. **Don't stress perfection** - 80% is often good enough to ship
-
----
-
-## Reference: Verification Operations
-
-**I perform these operations using my native tools:**
-
-| Operation | How I Do It |
-|-----------|-------------|
-| Check most recent implementation | Read `.clavix/outputs/prompts/` directory, find newest file |
-| Check specific prompt | Read the specific `.clavix/outputs/prompts/<id>.md` file |
-| Run automated checks | Execute `npm test`, `npm run build`, `npm run lint` via Bash tool |
-| Present report | Display verification results in chat (I do NOT save reports to files) |
-
-**After presenting the report, I ask:** "What would you like to do next?"
-- Fix the failed items
-- Re-verify after making changes
-- Archive the project if all passed
-- Continue working on something else
-
----
-
-## Workflow Navigation
-
-**Where you are:** Verification (checking your work)
-
-**How you got here:**
-1. `/clavix:improve` → Optimized your prompt
-2. `/clavix:implement` → Implemented the requirements
-3. **`/clavix:verify`** → Now checking it works (you are here)
-
-**What's next:**
-- Fix any failed items → Run verify again
-- All passed → `/clavix:archive` to wrap up
+### Agent Manual (Universal Protocols)
+{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
 
-**Related commands:**
-- `/clavix:implement` - Execute tasks or prompts (previous step)
-- `/clavix:improve --comprehensive` - Get comprehensive checklist next time
-- `/clavix:archive` - Archive when done (next step)
+### Self-Correction Protocol
+{{INCLUDE:agent-protocols/self-correction-protocol.md}}
 
----
+### State Awareness
+{{INCLUDE:agent-protocols/state-awareness.md}}
 
-## Agent Transparency (v5.1)
+### Supportive Companion
+{{INCLUDE:agent-protocols/supportive-companion.md}}
 
-### Agent Manual (Universal Protocols)
-{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
+### Task Blocking
+{{INCLUDE:agent-protocols/task-blocking.md}}
 
 ### CLI Reference
 {{INCLUDE:agent-protocols/cli-reference.md}}
@@ -437,32 +148,7 @@ After presenting the report, I **always ask what you want to do next**.
 
 ---
 
-## Verification Confidence Levels
-
-When I report results, I'll indicate how confident I am:
-
-| Level | What It Means | Example |
-|-------|---------------|---------|
-| **HIGH** | Automated test passed | `npm test` returned success |
-| **MEDIUM** | I checked and it looks right | Code review confirmed the change |
-| **LOW** | Best guess, you should double-check | General assessment without proof |
-
----
-
-## Agent Verification Protocol
-
-After completing verification, I'll:
-
-1. **Present the summary** (in chat, NOT saved to file):
-```
-✓ Verification complete for [prompt-id]
-
-Results:
-- Total: [X] items checked
-- Passed: [Y] ([Z]%)
-- Failed: [N] items need attention
-
-Status: [All clear! / X items need fixing]
-```
-
-2. **Ask what the user wants to do next** - I do NOT proceed without user input
+## Tips for the Agent
+*   **Be Strict**: You are the gatekeeper of quality. It's better to be annoying about an architectural violation now than to let technical debt slide.
+*   **Be Specific**: Never say "fix the code". Say "Import `apiClient` from `@/utils/api` and replace line 42."
+*   **Trust the Code**: If the code says `console.log`, and the plan says "No logs", that is a defect.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.7.0",
+  "version": "5.8.0",
   "description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation.\n\nSLASH COMMANDS (in your AI assistant):\n  /clavix:improve    Optimize prompts with auto-depth\n  /clavix:prd        Generate PRD through questions\n  /clavix:plan       Create task breakdown from PRD\n  /clavix:implement  Execute tasks with progress tracking\n  /clavix:start      Begin conversational session\n  /clavix:summarize  Extract requirements from conversation\n  /clavix:refine     Refine existing PRD or prompt\n  /clavix:verify     Verify implementation against requirements\n  /clavix:archive    Archive completed projects\n\nWorks with Claude Code, Cursor, Windsurf, and 20 AI coding tools.",
   "type": "module",
   "main": "dist/index.js",
@@ -14,7 +14,7 @@
   },
   "scripts": {
     "clean": "rm -rf dist",
-    "validate:consistency": "node --loader ts-node/esm scripts/validate-consistency.ts",
+    "validate:consistency": "tsx scripts/validate-consistency.ts",
     "prebuild": "npm run clean && npm run validate:consistency",
     "build": "tsc && npm run copy-templates",
     "build:prod": "npm run build && npm run remove-sourcemaps",
@@ -91,6 +91,7 @@
     "prettier": "^3.6.2",
     "ts-jest": "^29.4.5",
     "ts-node": "^10.9.2",
+    "tsx": "^4.21.0",
     "typescript": "^5.9.3",
     "typescript-eslint": "^8.46.4"
   },