clavix 7.2.0 → 7.2.2

package/README.md

@@ -81,3 +81,13 @@ Run `clavix init` and select your tools. Command format varies by tool:
 ## License
 
 Apache-2.0
+
+## Star History
+
+<a href="https://www.star-history.com/#ClavixDev/Clavix&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&legend=top-left" />
+ </picture>
+</a>

package/dist/core/adapters/agent-skills-adapter.d.ts

@@ -45,6 +45,7 @@ export declare class AgentSkillsAdapter extends BaseAdapter {
     /**
      * Skills use directory names, not filenames
      * Returns the skill directory name (e.g., 'clavix-improve')
+     * Special case: 'using-clavix' keeps its name (no prefix) to match superpowers pattern
      */
     getTargetFilename(name: string): string;
     /**
@@ -82,7 +83,7 @@ export declare class AgentSkillsAdapter extends BaseAdapter {
     removeAllCommands(): Promise<number>;
     /**
      * Determine if an entry is a Clavix-generated skill
-     * Skills are directories starting with 'clavix-'
+     * Skills are directories starting with 'clavix-' or the special 'using-clavix' meta-skill
      */
     protected isClavixGeneratedCommand(name: string): boolean;
     /**

package/dist/core/adapters/agent-skills-adapter.js

@@ -104,8 +104,13 @@ export class AgentSkillsAdapter extends BaseAdapter {
     /**
      * Skills use directory names, not filenames
      * Returns the skill directory name (e.g., 'clavix-improve')
+     * Special case: 'using-clavix' keeps its name (no prefix) to match superpowers pattern
      */
     getTargetFilename(name) {
+        // using-clavix is special - it's the meta-skill that tells agents how to use other skills
+        if (name === 'using-clavix') {
+            return 'using-clavix';
+        }
         return `clavix-${name}`;
     }
     /**
@@ -147,7 +152,8 @@ export class AgentSkillsAdapter extends BaseAdapter {
      * Generate a single skill directory from a command template
      */
     async generateSkill(template, basePath) {
-        const skillName = `clavix-${template.name}`;
+        // using-clavix keeps its name (no prefix) - it's the meta-skill
+        const skillName = template.name === 'using-clavix' ? 'using-clavix' : `clavix-${template.name}`;
         const skillDir = path.join(basePath, skillName);
         // Ensure skill directory exists
         await FileSystem.ensureDir(skillDir);
@@ -190,6 +196,7 @@ export class AgentSkillsAdapter extends BaseAdapter {
             verify: 'Verify implementation against PRD requirements with systematic checking. Use after implementation to validate completeness.',
             review: 'Review code changes with criteria-driven analysis (Security, Architecture, Standards, Performance). Use when reviewing PRs or code changes.',
             archive: 'Archive completed projects by moving outputs to archive directory. Use when a project is complete and ready for archival.',
+            'using-clavix': 'Use when starting any conversation involving Clavix workflows - establishes skill invocation rules, verification requirements, and workflow orchestration',
         };
         return descriptionMap[name] || baseDescription;
     }
@@ -221,10 +228,10 @@ export class AgentSkillsAdapter extends BaseAdapter {
     }
     /**
      * Determine if an entry is a Clavix-generated skill
-     * Skills are directories starting with 'clavix-'
+     * Skills are directories starting with 'clavix-' or the special 'using-clavix' meta-skill
      */
     isClavixGeneratedCommand(name) {
-        return name.startsWith('clavix-');
+        return name.startsWith('clavix-') || name === 'using-clavix';
     }
     /**
      * Validate skills directory

package/dist/templates/agents/agents.md

@@ -4,6 +4,23 @@ This guide is for agents that can only read documentation (no slash-command supp
 
 ---
 
+## 🚨 FIRST: Load using-clavix Skill
+
+**Before ANY Clavix workflow, invoke the `using-clavix` skill.**
+
+This meta-skill establishes:
+- Skill invocation rules (check skills BEFORE any response)
+- Required skill chains (prd → plan → implement → verify)
+- Iron Laws for verification (no completion claims without evidence)
+- Workflow orchestration and fix loops
+
+If you have even a 1% chance a Clavix skill applies, you MUST check it first.
+
+**In environments with Skill tool:** Invoke `using-clavix` before any Clavix action.
+**In environments without Skill tool:** Read `.config/agents/skills/using-clavix/SKILL.md` or the bundled template.
+
+---
+
 ## ⛔ CLAVIX MODE ENFORCEMENT
 
 **CRITICAL: Know which mode you're in and STOP at the right point.**

package/dist/templates/skills/implement-templates/implementer-prompt.md

@@ -0,0 +1,117 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent for a specific task.
+
+```
+Task tool:
+
+description: "Implement Task N: [task name]"
+
+prompt: |
+  You are implementing Task N: [task name]
+
+  ## Task Description
+
+  [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+
+  ## Context
+
+  [Scene-setting: where this fits in the project, dependencies, architectural context]
+  [Reference any relevant PRD sections or prior tasks]
+
+  ## Before You Begin
+
+  If you have questions about:
+  - The requirements or acceptance criteria
+  - The approach or implementation strategy
+  - Dependencies or assumptions
+  - Anything unclear in the task description
+
+  **Ask them now.** Raise any concerns before starting work.
+
+  ## Your Job
+
+  Once you're clear on requirements:
+
+  1. Implement exactly what the task specifies
+  2. Write tests (following TDD if task says to)
+  3. Verify implementation works (run tests, check build)
+  4. Commit your work
+  5. Self-review (see below)
+  6. Report back
+
+  Work from: [directory/workspace]
+
+  **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+  It's always OK to pause and clarify. Don't guess or make assumptions.
+
+  ## Before Reporting Back: Self-Review
+
+  Review your work with fresh eyes. Ask yourself:
+
+  **Completeness:**
+  - Did I fully implement everything in the spec?
+  - Did I miss any requirements?
+  - Are there edge cases I didn't handle?
+
+  **Quality:**
+  - Is this my best work?
+  - Are names clear and accurate (match what things do, not how they work)?
+  - Is the code clean and maintainable?
+
+  **Discipline:**
+  - Did I avoid overbuilding (YAGNI)?
+  - Did I only build what was requested?
+  - Did I follow existing patterns in the codebase?
+
+  **Testing:**
+  - Do tests actually verify behavior (not just mock behavior)?
+  - Did I follow TDD if required?
+  - Are tests comprehensive?
+
+  **If you find issues during self-review, fix them now before reporting.**
+
+  ## Report Format
+
+  When done, report:
+
+  ```
+  ## Implementation Complete
+
+  **Task:** [task name]
+  **Status:** Complete / Partial / Blocked
+
+  ### What I Implemented
+  - [List of changes made]
+
+  ### Files Changed
+  - `path/to/file.ts` - [what changed]
+
+  ### Test Results
+  [Paste test output or summary]
+
+  ### Self-Review Findings
+  - [Any issues found and fixed during self-review]
+  - [Or "No issues found"]
+
+  ### Issues or Concerns
+  - [Any remaining concerns or questions]
+  - [Or "None"]
+  ```
+```
+
+---
+
+## When to Use This Template
+
+- Dispatching a subagent to implement a single task from the plan
+- Each task gets its own fresh subagent (no context pollution)
+- Subagent implements, tests, commits, and self-reviews before reporting
+
+## Key Points
+
+1. **Provide full task text** - Don't make subagent read the plan file
+2. **Include context** - Where this fits, what came before
+3. **Encourage questions** - Subagent should ask before guessing
+4. **Require self-review** - Catches issues before handoff
+5. **Structured report** - Clear summary of what was done

package/dist/templates/skills/implement-templates/quality-reviewer-prompt.md

@@ -0,0 +1,121 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Task tool:
+
+description: "Review code quality for Task N"
+
+prompt: |
+  You are reviewing the code quality of an implementation that has already
+  passed spec compliance review.
+
+  ## What Was Implemented
+
+  [From implementer's report - what they built]
+
+  ## Files to Review
+
+  [List of files changed with paths]
+
+  ## Review Dimensions
+
+  Evaluate the implementation across these dimensions:
+
+  ### 🔒 Security
+  - No hardcoded secrets, keys, or tokens
+  - Proper input validation
+  - Safe handling of user data
+  - No injection vulnerabilities
+
+  ### 🏗️ Architecture
+  - Follows existing project patterns
+  - Appropriate separation of concerns
+  - Consistent with codebase conventions
+  - No layer violations
+
+  ### 📏 Standards
+  - Clear, descriptive naming
+  - Reasonable function/method length
+  - DRY principle followed
+  - No console.logs in production code
+  - Proper TypeScript types (no `any` without reason)
+
+  ### ⚡ Performance
+  - No obvious N+1 patterns
+  - Appropriate async handling
+  - No unnecessary operations in loops
+  - Resources properly cleaned up
+
+  ### 🧪 Testing
+  - Tests actually test behavior (not mocks)
+  - Edge cases covered
+  - Error scenarios handled
+  - Tests are readable and maintainable
+
+  ## Report Format
+
+  ```
+  ## Code Quality Review
+
+  **Task:** [task name]
+  **Status:** ✅ Approved | ⚠️ Minor Issues | ❌ Needs Fixes
+
+  ### Strengths
+  - [What's done well]
+
+  ### Issues
+
+  **🔴 Critical** (must fix)
+  - [file:line] [issue description]
+
+  **🟠 Important** (should fix)
+  - [file:line] [issue description]
+
+  **🟡 Minor** (nice to fix)
+  - [file:line] [issue description]
+
+  ### Assessment
+  ✅ Approved - code is production ready
+  OR
+  ⚠️ Approved with notes - minor issues, can proceed
+  OR
+  ❌ Needs fixes - address critical/important issues before proceeding
+  ```
+```
+
+---
+
+## When to Use This Template
+
+- AFTER spec compliance review passes (never before)
+- Evaluates HOW code is written, not WHAT it does
+- Final gate before marking task complete
+
+## Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| 🔴 Critical | Security risk, broken functionality | Must fix |
+| 🟠 Important | Significant quality issue | Should fix |
+| 🟡 Minor | Style, optimization | Nice to fix |
+
+## Key Points
+
+1. **Only after spec passes** - Wrong order wastes time
+2. **Focus on quality** - Spec compliance already verified
+3. **Specific references** - file:line for every issue
+4. **Clear severity** - Helps prioritize fixes
+5. **Actionable feedback** - Say what to fix, not just what's wrong
+
+## If Issues Found
+
+1. Implementer fixes critical/important issues
+2. Quality reviewer reviews again
+3. Repeat until approved
+4. Only then mark task complete

package/dist/templates/skills/implement-templates/spec-reviewer-prompt.md

@@ -0,0 +1,108 @@
+# Spec Compliance Reviewer Prompt Template
+
+Use this template when dispatching a spec compliance reviewer subagent.
+
+**Purpose:** Verify implementer built what was requested (nothing more, nothing less)
+
+```
+Task tool:
+
+description: "Review spec compliance for Task N"
+
+prompt: |
+  You are reviewing whether an implementation matches its specification.
+
+  ## What Was Requested
+
+  [FULL TEXT of task requirements from the plan]
+
+  ## What Implementer Claims They Built
+
+  [From implementer's report - paste their summary]
+
+  ## CRITICAL: Do Not Trust the Report
+
+  The implementer may have finished quickly or missed details. Their report may be
+  incomplete, inaccurate, or optimistic. You MUST verify everything independently.
+
+  **DO NOT:**
+  - Take their word for what they implemented
+  - Trust their claims about completeness
+  - Accept their interpretation of requirements
+
+  **DO:**
+  - Read the actual code they wrote
+  - Compare actual implementation to requirements line by line
+  - Check for missing pieces they claimed to implement
+  - Look for extra features they didn't mention
+
+  ## Your Job
+
+  Read the implementation code and verify:
+
+  ### Missing Requirements
+  - Did they implement everything that was requested?
+  - Are there requirements they skipped or missed?
+  - Did they claim something works but didn't actually implement it?
+
+  ### Extra/Unneeded Work
+  - Did they build things that weren't requested?
+  - Did they over-engineer or add unnecessary features?
+  - Did they add "nice to haves" that weren't in spec?
+
+  ### Misunderstandings
+  - Did they interpret requirements differently than intended?
+  - Did they solve the wrong problem?
+  - Did they implement the right feature but wrong way?
+
+  **Verify by reading code, not by trusting report.**
+
+  ## Report Format
+
+  ```
+  ## Spec Compliance Review
+
+  **Task:** [task name]
+  **Status:** ✅ Spec Compliant | ❌ Issues Found
+
+  ### Missing Requirements
+  - [List what's missing with file:line references]
+  - [Or "None - all requirements implemented"]
+
+  ### Extra/Unneeded Work
+  - [List extras that weren't requested]
+  - [Or "None - nothing extra added"]
+
+  ### Misunderstandings
+  - [List any misinterpretations]
+  - [Or "None - requirements correctly understood"]
+
+  ### Verdict
+  ✅ Spec compliant - proceed to code quality review
+  OR
+  ❌ Issues found - implementer must fix before proceeding
+  ```
+```
+
+---
+
+## When to Use This Template
+
+- After implementer reports task complete
+- BEFORE code quality review (order matters)
+- Verify what was built matches what was requested
+
+## Key Points
+
+1. **Don't trust the implementer's report** - Verify independently
+2. **Read actual code** - Not just claims about code
+3. **Check both directions** - Missing AND extra work
+4. **Spec compliance first** - Quality review only after spec passes
+5. **Clear verdict** - Either passes or needs fixes
+
+## If Issues Found
+
+1. Implementer fixes the specific issues
+2. Spec reviewer reviews again
+3. Repeat until spec compliant
+4. Only then proceed to code quality review

package/dist/templates/skills/implement.md

@@ -1,15 +1,26 @@
 ---
 name: clavix-implement
-description: Execute implementation tasks or saved prompts with progress tracking
+description: Execute implementation tasks or saved prompts with progress tracking. Use when ready to build what was planned in PRD or improved prompts.
 license: Apache-2.0
 ---
-
 # Clavix Implement Skill
 
 Execute tasks from tasks.md or saved prompts with systematic progress tracking.
 
 ---
 
+## The Iron Law
+
+```
+NO TASK MARKED COMPLETE WITHOUT VERIFICATION EVIDENCE
+```
+
+If you haven't run the verification command in this message, you cannot claim it passes.
+
+**Violating the letter of this rule is violating the spirit of this rule.**
+
+---
+
 ## State Assertion (REQUIRED)
 
 **Before ANY action, output this confirmation:**
@@ -142,16 +153,60 @@ For each task, follow this cycle:
 - Follow existing codebase patterns
 - Create/modify files as specified in task
 
-### 4. Mark Complete
+### 4. Verification Gate (REQUIRED)
+
+**BEFORE marking task complete:**
+
+1. **IDENTIFY**: What command proves this task works?
+   - Tests: `npm test`, `pytest`, etc.
+   - Build: `npm run build`, `tsc`, etc.
+   - Lint: `npm run lint`, `eslint`, etc.
+
+2. **RUN**: Execute the verification command (fresh, complete)
+   - Run the full command, not partial checks
+   - Don't rely on previous runs
+
+3. **READ**: Check full output
+   - Exit code (0 = success)
+   - Count failures/errors
+   - Read warnings
+
+4. **VERIFY**: Does output confirm success?
+   - If NO → Go to Fix Loop
+   - If YES → Mark complete WITH evidence
+
+**Skip any step = lying, not verifying**
+
+### 5. Fix Loop (When Verification Fails)
+
+```
+Verification failed
+       │
+       ▼
+Analyze the failure
+       │
+       ▼
+Implement fix
+       │
+       ▼
+Re-run verification ◄───┐
+       │                │
+       ├── Still fails ─┘
+       │
+       ▼ (passes)
+Continue to Mark Complete
+```
+
+**NEVER skip the re-verification after fixes.**
+
+If 3+ fix attempts fail: STOP and ask for help. Don't keep guessing.
+
+### 6. Mark Complete
 - Edit tasks.md directly
 - Change `- [ ]` to `- [x]`
+- Include verification evidence in progress report
 
-### 5. Verify
-- Run tests if available
-- Check acceptance criteria
-- If fails: present fix options
-
-### 6. Next Task
+### 7. Next Task
 - Find next incomplete task (`- [ ]`)
 - Report progress
 - Continue cycle
@@ -198,16 +253,16 @@ After implementing each task:
    - Verify file paths match specification
 
 3. **If verification fails**:
-   > "Tests are failing for this task. Let me see what's wrong...
-   >
-   > [Analyze and fix issues]
+   > "Tests are failing for this task. Analyzing the failure...
    >
-   > Options:
-   > 1. I'll try to fix this
-   > 2. Skip verification for now
-   > 3. Show you what needs attention
+   > **Failure**: [describe what failed]
+   > **Root cause**: [analysis of why]
    >
-   > What would you prefer?"
+   > Implementing fix..."
+
+   Then fix and re-run verification. Repeat until passing.
+
+   **Do NOT offer to skip verification.** The Iron Law applies.
 
 ---
 
@@ -313,9 +368,41 @@ executed: false  →  executed: true
 - A tasks.md (from `/clavix-plan`) OR
 - A saved prompt (from `/clavix-improve`)
 
-**Next Steps**:
-- `/clavix-verify` - Verify implementation against PRD
-- `/clavix-archive` - Archive completed project
+**After ALL tasks complete:**
+
+**REQUIRED SUB-SKILL**: Use `clavix-verify` to audit implementation against PRD
+
+Do NOT skip this step. Do NOT consider implementation complete without verification.
+
+```
+All tasks marked complete
+         │
+         ▼
+   clavix-verify  ◄────────────┐
+         │                      │
+         ├── Issues found? ────►│
+         │        Fix them      │
+         │        Re-verify ────┘
+         │
+         ▼ (all pass)
+   clavix-archive (optional)
+```
+
+---
+
+## Subagent Templates
+
+For delegating implementation work to subagents, use these templates:
+
+- `./implementer-prompt.md` - Dispatch implementer subagent
+- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer
+- `./quality-reviewer-prompt.md` - Dispatch code quality reviewer
+
+**Subagent workflow:**
+1. Implementer does work + self-review
+2. Spec reviewer verifies compliance (loop until passes)
+3. Quality reviewer verifies quality (loop until passes)
+4. Only then mark task complete
 
 ---
 
@@ -394,4 +481,4 @@ Progress: 1/8 tasks (12.5%)
 Task ID: phase-1-setup-02
 
 Continue? (y/n)
-```
+```

package/dist/templates/skills/plan.md

@@ -1,9 +1,8 @@
 ---
 name: clavix-plan
-description: Transform PRDs into actionable task breakdowns with dependencies
+description: Transform PRD documents into actionable task breakdowns with dependencies. Use after creating a PRD to generate implementation tasks.
 license: Apache-2.0
 ---
-
 # Clavix Plan Skill
 
 Transform PRD documents into structured, actionable task lists with proper sequencing.
@@ -161,7 +160,7 @@ Implementation: BLOCKED - I will create the plan, not the code
 
 ---
 
-*Generated by Clavix /clavix:plan*
+*Generated by Clavix /clavix-plan*
 ```
 
 ### Task ID Format
@@ -231,6 +230,15 @@ Present the plan and ask:
 >
 > Type `/clavix-implement` to start coding, or tell me what to adjust."
 
+**REQUIRED SUB-SKILL**: The generated plan should include this header:
+
+```markdown
+> **For Claude:** REQUIRED SUB-SKILL: Use clavix-implement to execute this plan task-by-task.
+> After all tasks complete, use clavix-verify to audit implementation against PRD.
+```
+
+This ensures the implementation chain is followed completely.
+
 ---
 
 ## Save Location
@@ -284,6 +292,21 @@ Tasks file: `.clavix/outputs/{project}/tasks.md`
 ## Next Steps
 
 After task generation, guide user to:
+
+**REQUIRED SUB-SKILL**: Use `clavix-implement` to execute tasks
+
+Do not skip directly to coding. Follow the skill chain:
+
+```
+clavix-plan (you are here)
+      │
+      ▼ REQUIRED
+clavix-implement
+      │
+      ▼ REQUIRED (after all tasks)
+clavix-verify
+```
+
 - `/clavix-implement` - Start executing tasks
 - Review and adjust task priorities as needed
-- Manual edit of `.clavix/outputs/{project}/tasks.md` if needed
+- Manual edit of `.clavix/outputs/{project}/tasks.md` if needed