clavix 5.6.5 → 5.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Clavix
 
-> Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.
+> Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 20 AI coding tools.
 
 ## Quick Links
 

package/dist/config/integrations.json

@@ -163,7 +163,7 @@
     },
     {
       "name": "llxprt",
-      "displayName": "LLXpert",
+      "displayName": "LLXPRT",
       "directory": ".llxprt/commands/clavix",
       "filenamePattern": "{name}",
       "extension": ".toml",

package/dist/core/adapter-registry.js

@@ -48,10 +48,9 @@ function transformConfig(config) {
     if (config.placeholder) {
         features.argumentPlaceholder = config.placeholder;
     }
-    // Special handling for Claude Code (subdirectories + frontmatter + doc injection)
+    // Special handling for Claude Code (subdirectories + doc injection)
     if (config.specialAdapter === 'doc-injection') {
         features.supportsSubdirectories = true;
-        features.supportsFrontmatter = true;
         features.supportsDocInjection = true;
         features.commandSeparator = ':';
     }

package/dist/core/adapters/claude-code-adapter.d.ts

@@ -10,7 +10,6 @@ export declare class ClaudeCodeAdapter extends BaseAdapter {
     readonly fileExtension = ".md";
     readonly features: {
         supportsSubdirectories: boolean;
-        supportsFrontmatter: boolean;
     };
     /**
      * Detect if Claude Code is available in the project

package/dist/core/adapters/claude-code-adapter.js

@@ -13,7 +13,6 @@ export class ClaudeCodeAdapter extends BaseAdapter {
     fileExtension = '.md';
     features = {
         supportsSubdirectories: true,
-        supportsFrontmatter: false,
     };
     /**
      * Detect if Claude Code is available in the project

package/dist/core/adapters/toml-formatting-adapter.d.ts

@@ -27,7 +27,6 @@ export declare abstract class TomlFormattingAdapter extends BaseAdapter {
     readonly fileExtension = ".toml";
     readonly features: {
         supportsSubdirectories: boolean;
-        supportsFrontmatter: boolean;
         argumentPlaceholder: string;
     };
     protected readonly config: TomlAdapterConfig;

package/dist/core/adapters/toml-formatting-adapter.js

@@ -16,7 +16,6 @@ export class TomlFormattingAdapter extends BaseAdapter {
     fileExtension = '.toml';
     features = {
         supportsSubdirectories: true,
-        supportsFrontmatter: false,
         argumentPlaceholder: '{{args}}',
     };
     config;

package/dist/core/adapters/universal-adapter.d.ts

@@ -46,9 +46,5 @@ export declare class UniversalAdapter extends BaseAdapter {
      * Check if this adapter supports subdirectories
      */
     supportsSubdirectories(): boolean;
-    /**
-     * Check if this adapter supports frontmatter
-     */
-    supportsFrontmatter(): boolean;
 }
 //# sourceMappingURL=universal-adapter.d.ts.map

package/dist/core/adapters/universal-adapter.js

@@ -22,7 +22,6 @@ export class UniversalAdapter extends BaseAdapter {
         // Set features from config for interface compatibility
         this.features = {
             supportsSubdirectories: config.features.supportsSubdirectories,
-            supportsFrontmatter: config.features.supportsFrontmatter,
             commandFormat: {
                 separator: config.features.commandSeparator,
             },
@@ -102,11 +101,5 @@ export class UniversalAdapter extends BaseAdapter {
     supportsSubdirectories() {
         return this.config.features.supportsSubdirectories;
     }
-    /**
-     * Check if this adapter supports frontmatter
-     */
-    supportsFrontmatter() {
-        return this.config.features.supportsFrontmatter;
-    }
 }
 //# sourceMappingURL=universal-adapter.js.map

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

@@ -21,16 +21,20 @@ When you run `/clavix:archive`, I:
 
 ---
 
-## State Assertion (REQUIRED)
+## CLAVIX MODE: Archival
 
-Before ANY action, output this confirmation:
+**I'm in archival mode. Organizing your completed work.**
 
-```
-**CLAVIX MODE: Archival**
-Mode: management
-Purpose: Organizing completed projects
-Implementation: BLOCKED (file operations only)
-```
+**What I'll do:**
+- ✓ Find projects ready for archive
+- ✓ Show you what's complete (100% tasks done)
+- ✓ Move projects to archive when you confirm
+- ✓ Track everything so you can restore later
+
+**What I won't do:**
+- ✗ Delete anything without explicit confirmation
+- ✗ Archive projects you're still working on (unless you use --force)
+- ✗ Make decisions for you - you pick what to archive
 
 ---
 
@@ -49,20 +53,16 @@ If you catch yourself doing any of these, STOP and correct:
 
 ---
 
-## CLAVIX MODE: Archival
-
-**I'm in archival mode. Organizing your completed work.**
+## State Assertion (REQUIRED)
 
-**What I'll do:**
-- ✓ Find projects ready for archive
-- ✓ Show you what's complete (100% tasks done)
-- ✓ Move projects to archive when you confirm
-- ✓ Track everything so you can restore later
+Before ANY action, output this confirmation:
 
-**What I won't do:**
-- ✗ Delete anything without explicit confirmation
-- ✗ Archive projects you're still working on (unless you use --force)
-- ✗ Make decisions for you - you pick what to archive
+```
+**CLAVIX MODE: Archival**
+Mode: management
+Purpose: Organizing completed projects
+Implementation: BLOCKED (file operations only)
+```
 
 ---
 
@@ -70,6 +70,12 @@ If you catch yourself doing any of these, STOP and correct:
 
 **I use my native tools directly - no CLI commands involved.**
 
+**Tools I use:**
+- **Read tool**: To read tasks.md and check completion status
+- **Bash/Move**: To move directories (`mv source dest`)
+- **Bash/Remove**: To delete directories (`rm -rf path`) - only with explicit confirmation
+- **Glob/List**: To list projects and archive contents
+
 ### What I Do
 
 | What You Want | How I Do It |
@@ -90,10 +96,18 @@ I check:
 
 ### After Archiving
 
-I tell you:
-- Where the project went
-- How to restore it (unless you deleted it)
-- What to do next
+I verify the operation completed and ask what you want to do next:
+
+**Verification:**
+- Confirm the project was moved/deleted
+- Show the new location (for archive) or confirm removal (for delete)
+- List any related files that may need cleanup
+
+**I then ask:** "What would you like to do next?"
+- Start a new project with `/clavix:prd`
+- Archive another completed project
+- Review archived projects
+- Return to something else
 
 ### Part B: Understanding Archive Operations
 
@@ -285,6 +299,39 @@ Result: Project permanently deleted
 - `/clavix:plan` - Review task completion status
 - `/clavix:prd` - Start new project after archiving old one
 
+## Archive Size Management
+
+**Proactive maintenance to prevent archive bloat:**
+
+**When to clean up the archive:**
+- Archive exceeds 50 projects (or 100MB)
+- Projects older than 12 months that haven't been referenced
+- Duplicate or superseded projects
+- Failed experiments with no learning value
+
+**Size check (run periodically):**
+```bash
+# Count archived projects
+ls .clavix/outputs/archive/ | wc -l
+
+# Check total archive size
+du -sh .clavix/outputs/archive/
+```
+
+**Cleanup workflow:**
+1. List all archived projects with dates: `ls -lt .clavix/outputs/archive/`
+2. Identify candidates for deletion (failed experiments, duplicates, ancient projects)
+3. For each candidate, confirm zero future value
+4. Delete only with explicit confirmation
+
+**Archive retention recommendations:**
+| Project Type | Keep For | Then |
+|--------------|----------|------|
+| Completed features | Indefinitely | Archive forever (reference value) |
+| Failed experiments | 30 days | Delete if no learning value |
+| Superseded versions | 90 days | Delete if newer version exists |
+| Test/demo projects | 7 days | Delete unless documenting patterns |
+
 ## Tips
 
 - Archive keeps your active projects list clean and focused
@@ -292,6 +339,7 @@ Result: Project permanently deleted
 - Archive is searchable - you can still `grep` or find files in archive/
 - Regular archiving keeps `.clavix/outputs/` organized
 - Check `.clavix/outputs/archive/` to see what's been archived
+- Review archive size quarterly to avoid unbounded growth
 
 ## Troubleshooting
 

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

@@ -68,35 +68,6 @@ Override auto-detection when needed:
 
 ---
 
-## State Assertion (REQUIRED)
-
-Before ANY action, output this confirmation:
-
-```
-**CLAVIX MODE: Implementation**
-Mode: implementation
-Purpose: Executing tasks or prompts with code generation
-Source: [tasks.md | prompts/ | user request]
-Implementation: AUTHORIZED
-```
-
----
-
-## Self-Correction Protocol
-
-If you catch yourself doing any of these, STOP and correct:
-
-1. **Skipping Auto-Detection** - Not checking for tasks.md and prompts/ before asking
-2. **Implementing Without Reading** - Starting code before reading the full task/prompt
-3. **Skipping Verification** - Not running tests after implementation
-4. **Batch Task Completion** - Marking multiple tasks done without implementing each
-5. **Ignoring Blocked Tasks** - Not reporting when a task cannot be completed
-6. **Capability Hallucination** - Claiming Clavix can do things it cannot
-
-**DETECT → STOP → CORRECT → RESUME**
-
----
-
 ## CLAVIX MODE: Implementation
 
 **I'm in implementation mode. Building your tasks!**
@@ -122,6 +93,35 @@ For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
 
 ---
 
+## Self-Correction Protocol
+
+If you catch yourself doing any of these, STOP and correct:
+
+1. **Skipping Auto-Detection** - Not checking for tasks.md and prompts/ before asking
+2. **Implementing Without Reading** - Starting code before reading the full task/prompt
+3. **Skipping Verification** - Not running tests after implementation
+4. **Batch Task Completion** - Marking multiple tasks done without implementing each
+5. **Ignoring Blocked Tasks** - Not reporting when a task cannot be completed
+6. **Capability Hallucination** - Claiming Clavix can do things it cannot
+
+**DETECT → STOP → CORRECT → RESUME**
+
+---
+
+## State Assertion (REQUIRED)
+
+Before ANY action, output this confirmation:
+
+```
+**CLAVIX MODE: Implementation**
+Mode: implementation
+Purpose: Executing tasks or prompts with code generation
+Source: [tasks.md | prompts/ | user request]
+Implementation: AUTHORIZED
+```
+
+---
+
 ## How It Works
 
 ### The Quick Version

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

@@ -47,6 +47,28 @@ This is a prompt improvement workflow. Your job is to ANALYZE and IMPROVE the pr
 
 ---
 
+## Self-Correction Protocol
+
+**DETECT**: If you find yourself doing any of these mistake types:
+
+| Type | What It Looks Like |
+|------|--------------------|
+| 1. Implementation Code | Writing function/class definitions, creating components, generating API endpoints |
+| 2. Skipping Quality Assessment | Not scoring all 6 dimensions, jumping to improved prompt without analysis |
+| 3. Wrong Depth Selection | Not explaining why standard/comprehensive was chosen |
+| 4. Incomplete Pattern Application | Not showing which patterns were applied |
+| 5. Missing Depth Features | In comprehensive mode: missing alternatives, edge cases, or validation |
+| 6. Capability Hallucination | Claiming features Clavix doesn't have, inventing pattern names |
+
+**STOP**: Immediately halt the incorrect action
+
+**CORRECT**: Output:
+"I apologize - I was [describe mistake]. Let me return to prompt optimization."
+
+**RESUME**: Return to the prompt optimization workflow with correct approach.
+
+---
+
 ## State Assertion (REQUIRED)
 
 **Before starting analysis, output:**
@@ -83,28 +105,6 @@ Clavix provides a unified **improve** mode that intelligently selects the approp
 
 ---
 
-## Self-Correction Protocol
-
-**DETECT**: If you find yourself doing any of these mistake types:
-
-| Type | What It Looks Like |
-|------|--------------------|
-| 1. Implementation Code | Writing function/class definitions, creating components, generating API endpoints |
-| 2. Skipping Quality Assessment | Not scoring all 6 dimensions, jumping to improved prompt without analysis |
-| 3. Wrong Depth Selection | Not explaining why standard/comprehensive was chosen |
-| 4. Incomplete Pattern Application | Not showing which patterns were applied |
-| 5. Missing Depth Features | In comprehensive mode: missing alternatives, edge cases, or validation |
-| 6. Capability Hallucination | Claiming features Clavix doesn't have, inventing pattern names |
-
-**STOP**: Immediately halt the incorrect action
-
-**CORRECT**: Output:
-"I apologize - I was [describe mistake]. Let me return to prompt optimization."
-
-**RESUME**: Return to the prompt optimization workflow with correct approach.
-
----
-
 ## Instructions
 
 1. Take the user's prompt: `{{ARGS}}`
@@ -477,10 +477,20 @@ Wait for the user to decide what to do next.
 
 **You are here:** Improve Mode (Unified Prompt Intelligence)
 
+**State markers for workflow continuity:**
+- If user came from `/clavix:start`: They explored conversationally, now want optimization
+- If user came from `/clavix:summarize`: They have a mini-PRD, want to refine the prompt further
+- If prompt is complex (score < 60%): Suggest `/clavix:prd` for comprehensive planning instead
+
 **Common workflows:**
-- **Quick cleanup**: `/clavix:improve` -> `/clavix:implement --latest` -> Build
-- **Force comprehensive**: `/clavix:improve --comprehensive` -> Full analysis with alternatives
-- **Strategic planning**: `/clavix:improve` -> (suggests) `/clavix:prd` -> Plan -> Implement -> Archive
+- **Quick cleanup**: `/clavix:improve` → `/clavix:implement --latest` → Build
+- **Force comprehensive**: `/clavix:improve --comprehensive` → Full analysis with alternatives
+- **Strategic planning**: `/clavix:improve` → (suggests) `/clavix:prd` → Plan → Implement → Archive
+
+**After completion, guide user to:**
+- `/clavix:implement --latest` - Build what the prompt describes
+- `/clavix:prd` - If the task is larger than expected
+- `/clavix:refine` - If they want to iterate on the improved prompt
 
 **Related commands:**
 - `/clavix:implement` - Execute saved prompt or tasks (IMPLEMENTATION starts here)

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

@@ -134,6 +134,16 @@ If you have the full PRD content in memory and want to generate tasks directly:
    - Each phase should be independently deployable when possible
    - Critical path first (must-haves before nice-to-haves)
 
+   **Task Dependency Management:**
+   - **Explicit ordering**: Tasks within a phase should be ordered by execution sequence
+   - **Dependency markers**: Use `(depends: task-id)` for explicit dependencies
+   - **Common dependency patterns**:
+     - Database schema → Models → API endpoints → UI components
+     - Authentication → Protected routes → User-specific features
+     - Core utilities → Features that use them → Integration tests
+   - **Anti-pattern**: Avoid circular dependencies (A depends on B, B depends on A)
+   - **Parallel tasks**: If two tasks have no dependencies, they can be worked on simultaneously
+
 4. **Review and customize generated tasks**:
    - The command will generate `tasks.md` in the PRD folder
    - Tasks are organized into logical phases with quality principles
@@ -244,11 +254,16 @@ The generated `tasks.md` will look like:
 
 **Basic**: `- [ ] {Clear, actionable description}`
 **With reference**: `- [ ] {Description} (ref: {PRD Section Name})`
+**With dependency**: `- [ ] {Description} (depends: {task-id})`
+**Combined**: `- [ ] {Description} (ref: {Section}) (depends: {task-id})`
 
 **Example**:
 ```markdown
 - [ ] Create user registration API endpoint (ref: User Management)
   Task ID: phase-1-authentication-1
+
+- [ ] Add JWT token validation middleware (depends: phase-1-authentication-1)
+  Task ID: phase-1-authentication-2
 ```
 
 ### Task ID Placement
@@ -267,15 +282,52 @@ The generated `tasks.md` will look like:
 **Create directory if not exists**: Yes
 **Overwrite if exists**: Only with explicit user confirmation or `--overwrite` flag
 
+---
+
+## After Plan Generation
+
+After creating the task breakdown, I present it and ask for verification:
+
+**What I'll show:**
+- Summary of phases and task count
+- First few tasks from each phase
+- Any dependencies detected
+
+**What I'll ask:**
+> "Here's your task breakdown. Before you start implementing, please verify:
+> 1. Does this capture everything from your PRD?
+> 2. Are the tasks in the right order?
+> 3. Is the granularity right (not too big, not too small)?
+>
+> What would you like to do next?"
+
+**Your options:**
+1. Start implementing with `/clavix:implement`
+2. Edit tasks.md to adjust tasks
+3. Regenerate with different granularity
+4. Go back and refine the PRD first
+
+---
+
 ## Workflow Navigation
 
 **You are here:** Plan (Task Breakdown)
 
+**State markers for workflow continuity:**
+- If user came from `/clavix:prd`: Full PRD available, use comprehensive task breakdown
+- If user came from `/clavix:summarize`: Mini-PRD available, may need simpler task structure
+- If PRD has many features: Consider grouping by feature in phases
+- If PRD has dependencies: Ensure task ordering reflects them
+
 **Common workflows:**
 - **PRD workflow**: `/clavix:prd` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
 - **Conversation workflow**: `/clavix:summarize` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
 - **Standalone**: [Existing PRD] → `/clavix:plan` → Review tasks.md → `/clavix:implement`
 
+**After completion, guide user to:**
+- `/clavix:implement` - Start executing tasks (recommended next step)
+- Edit `tasks.md` - If they want to adjust task order or granularity
+
 **Related commands:**
 - `/clavix:prd` - Generate PRD (typical previous step)
 - `/clavix:summarize` - Extract mini-PRD from conversation (alternative previous step)

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

@@ -314,11 +314,21 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 **You are here:** Clavix Planning Mode (Strategic Planning)
 
+**State markers for workflow continuity:**
+- If user came from `/clavix:improve`: Prompt was too complex for simple optimization
+- If user came from `/clavix:start`: They explored, now want structured planning
+- If this is a greenfield project: Start with business context questions
+- If modifying existing feature: Start with current state questions
+
 **Common workflows:**
 - **Full planning workflow**: `/clavix:prd` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
 - **From improve mode**: `/clavix:improve` → (strategic scope detected) → `/clavix:prd`
 - **Quick to strategic**: `/clavix:improve` → (realizes complexity) → `/clavix:prd`
 
+**After completion, guide user to:**
+- `/clavix:plan` - Generate task breakdown from the PRD (recommended next step)
+- `/clavix:refine` - If they want to iterate on the PRD
+
 **Related commands:**
 - `/clavix:plan` - Generate task breakdown from PRD (next step)
 - `/clavix:implement` - Execute tasks (after plan)

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

@@ -328,11 +328,13 @@ Present the current prompt to the user:
 
 ---
 
-**Quality Assessment:**
+**Quality Assessment (6 dimensions):**
 - Clarity: [Score]
-- Specificity: [Score]
+- Efficiency: [Score]
+- Structure: [Score]
 - Completeness: [Score]
 - Actionability: [Score]
+- Specificity: [Score]
 
 **What would you like to change?**
 1. Clarify the objective
@@ -351,13 +353,13 @@ Enter conversational mode:
 
 ### Step 6b: Run Quality Assessment
 
-After refinement, re-assess using the same 6 dimensions as `/clavix:improve`:
+After refinement, re-assess using the standard 6 quality dimensions:
 - Clarity
-- Specificity
-- Context
-- Constraints
-- Actionability
+- Efficiency
 - Structure
+- Completeness
+- Actionability
+- Specificity
 
 ### Step 7b: Save Refined Prompt
 
@@ -559,6 +561,9 @@ I'll update the PRD and add this to the refinement history. Confirm?
 ### CLI Reference
 {{INCLUDE:agent-protocols/cli-reference.md}}
 
+### Quality Dimensions (for Prompt Refinement)
+{{INCLUDE:references/quality-dimensions.md}}
+
 ### Workflow State Detection
 {{INCLUDE:agent-protocols/state-awareness.md}}
 
@@ -610,3 +615,34 @@ I'll update the PRD and add this to the refinement history. Confirm?
 - Run `/clavix:plan` to regenerate tasks
 - Or manually update tasks.md
 - Previous progress markers may need adjustment
+
+### Issue: User wants to refine multiple topics at once
+**Cause**: PRD covers several distinct features and user wants to update multiple areas
+**Solution**:
+1. **Sequential approach (recommended)**:
+   - Focus on one topic/feature at a time
+   - Complete refinement for Topic A
+   - Then start new refinement session for Topic B
+   - Clearer change tracking per topic
+
+2. **Batched approach (if user insists)**:
+   - Discuss all changes upfront
+   - Group changes by category: [ADDED], [MODIFIED], [REMOVED]
+   - Apply all changes in one session
+   - In Refinement History, list changes per topic area:
+     ```
+     ### [Date] - Multi-Topic Refinement
+     **Authentication changes:**
+     - [ADDED] 2FA support
+     - [MODIFIED] Password requirements
+
+     **Dashboard changes:**
+     - [ADDED] Dark mode toggle
+     - [REMOVED] Deprecated widgets
+     ```
+
+3. **When to recommend splitting**:
+   - Changes span 4+ distinct features
+   - Changes affect different system components
+   - Risk of losing track of individual changes
+   - User seems overwhelmed by scope

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

@@ -141,6 +141,30 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
 
    **CHECKPOINT:** Complexity threshold reached - suggesting summarization
 
+   **Scope Creep Detection and Handling:**
+   Watch for these scope creep signals:
+   - Feature requests keep expanding ("also, it should...")
+   - Requirements contradict earlier decisions
+   - Must-haves grow without prioritization
+   - "Nice-to-have" features being treated as core requirements
+   - Scope drift from original problem statement
+
+   **When scope creep detected**, intervene with:
+   "I notice we've expanded from [original scope] to include [new additions]. Let's pause and prioritize:
+   - **Core (MVP)**: [list essential features] - these solve the original problem
+   - **Extended**: [list additions] - valuable but not essential
+   - **Future**: [list nice-to-haves] - consider for later iterations
+
+   Which of the extended features are truly necessary for the first version?"
+
+   **Scope management strategies:**
+   - Anchor to original problem statement frequently
+   - Ask "Does this feature solve the core problem?"
+   - Suggest versioning: "v1 with X, v2 adds Y"
+   - Track must-have vs nice-to-have explicitly
+
+   **CHECKPOINT:** Scope creep detected - helping user prioritize
+
 4. Be conversational and supportive:
    - Don't interrogate - have a natural discussion
    - Build on their ideas

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

@@ -375,13 +375,16 @@ Implementation: BLOCKED - I will extract requirements, not implement them
 
 ## Quality Enhancement
 
-**What gets optimized:**
+**What gets optimized (5 dimensions):**
 - **Clarity**: Remove ambiguity from extracted requirements
 - **Efficiency**: Remove verbosity and conversational fluff
 - **Structure**: Ensure logical flow (context → requirements → constraints → output)
 - **Completeness**: Add missing specifications, formats, success criteria
 - **Actionability**: Make requirements specific and executable
 
+**Why Specificity is excluded:**
+The `/clavix:summarize` command extracts requirements from exploratory conversations. Users in discovery mode often haven't determined concrete specifics yet (exact versions, file paths, numeric thresholds). Penalizing for missing specifics would unfairly score valid exploratory outputs. If specific details are needed, use `/clavix:improve` on the extracted prompt or proceed to `/clavix:prd` for full specification.
+
 **Output files:**
 - `original-prompt.md` - Raw extraction from conversation
 - `optimized-prompt.md` - Enhanced version (recommended for AI agents)
@@ -421,11 +424,22 @@ Implementation: BLOCKED - I will extract requirements, not implement them
 
 **You are here:** Summarize (Conversation Extraction)
 
+**State markers for workflow continuity:**
+- If user came from `/clavix:start`: There's conversation context to extract
+- If user invoked directly: Look for any recent conversation in context
+- If conversation was technical: Focus on implementation details in extraction
+- If conversation was exploratory: Focus on requirements and goals
+
 **Common workflows:**
 - **Standard flow**: `/clavix:start` → [conversation] → `/clavix:summarize` → Use optimized prompt
 - **To implementation**: `/clavix:summarize` → `/clavix:plan` → `/clavix:implement` → `/clavix:archive`
 - **Standalone use**: [Any conversation] → `/clavix:summarize` → Extract and optimize
 
+**After completion, guide user to:**
+- `/clavix:plan` - Generate tasks from the mini-PRD (if strategic)
+- `/clavix:implement --latest` - Build directly (if simple)
+- `/clavix:improve` - Polish the extracted prompt further
+
 **Related commands:**
 - `/clavix:start` - Begin conversational exploration (typical previous step)
 - `/clavix:plan` - Generate tasks from extracted mini-PRD (next step)

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

@@ -27,16 +27,24 @@ My job is just to check. If something needs fixing, I'll tell you what and you d
 
 ---
 
-## State Assertion (REQUIRED)
+## CLAVIX MODE: Verification
 
-Before ANY action, output this confirmation:
+**I'm in verification mode. I check your work, not change it.**
 
-```
-**CLAVIX MODE: Verification**
-Mode: verification
-Purpose: Checking implementation against requirements
-Implementation: BLOCKED (verification only)
-```
+**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
+
+**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."
 
 ---
 
@@ -55,24 +63,16 @@ If you catch yourself doing any of these, STOP and correct:
 
 ---
 
-## CLAVIX MODE: Verification
-
-**I'm in verification mode. I check your work, not change it.**
-
-**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
+## State Assertion (REQUIRED)
 
-**What I won't do:**
-- ✗ Write code or fix issues
-- ✗ Change anything in your implementation
-- ✗ Skip checks without asking
+Before ANY action, output this confirmation:
 
-**Before I start, I'll confirm:**
-> "Starting verification mode. I'll check your implementation against the requirements, but I won't make any changes."
+```
+**CLAVIX MODE: Verification**
+Mode: verification
+Purpose: Checking implementation against requirements
+Implementation: BLOCKED (verification only)
+```
 
 ---
 
@@ -329,15 +329,16 @@ I generate different checklists based on what you're building:
 
 ## After Verification
 
+After presenting the report, I **always ask what you want to do next**.
+
 ### Everything Passed! 🎉
 
 > "All checks passed! Your implementation is ready.
 >
-> Next steps:
-> - Mark tasks complete (if you haven't)
-> - Archive the project when you're done
->
-> Great work!"
+> **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
 
@@ -346,13 +347,17 @@ I generate different checklists based on what you're building:
 > ❌ Keyboard navigation - add tabindex
 > ❌ Empty state - add message
 >
-> Fix these and run verify again, or skip them if they're not critical."
+> **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! I've saved this verification. You can:
+> "Got it! When you're ready:
 > - Run `/clavix:verify --retry-failed` to just check the skipped/failed items
-> - Run `/clavix:verify --status` to see where things stand
+> - Run `/clavix:verify` to do a full verification again
 >
 > No rush!"
 
@@ -389,8 +394,13 @@ I generate different checklists based on what you're building:
 | 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 |
-| Update verification status | Edit the prompt file metadata with verification results |
-| Generate report | Create verification report in `.clavix/outputs/` |
+| 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
 
 ---
 
@@ -441,8 +451,9 @@ When I report results, I'll indicate how confident I am:
 
 ## Agent Verification Protocol
 
-After completing verification, I'll summarize:
+After completing verification, I'll:
 
+1. **Present the summary** (in chat, NOT saved to file):
 ```
 ✓ Verification complete for [prompt-id]
 
@@ -453,3 +464,5 @@ Results:
 
 Status: [All clear! / X items need fixing]
 ```
+
+2. **Ask what the user wants to do next** - I do NOT proceed without user input

package/dist/templates/slash-commands/_components/MANIFEST.md

@@ -22,7 +22,7 @@ Static reference documentation for AI agents.
 
 | Component | Purpose | Used By |
 |-----------|---------|---------|
-| `quality-dimensions.md` | Explanation of quality scoring dimensions (clarity, efficiency, etc.) | improve, prd, summarize |
+| `quality-dimensions.md` | Quality scoring dimensions (6 dimensions), workflow-specific usage, and why summarize excludes Specificity | improve, prd, summarize, refine |
 
 ### Sections
 Reusable content sections for specific workflows.
@@ -52,6 +52,7 @@ Recovery patterns for common agent issues.
 | `/clavix:implement` | AGENT_MANUAL, state-awareness, task-blocking, cli-reference, vibecoder-recovery |
 | `/clavix:start` | AGENT_MANUAL, supportive-companion, conversation-examples, vibecoder-recovery |
 | `/clavix:summarize` | AGENT_MANUAL, improvement-explanations, quality-dimensions, state-awareness, vibecoder-recovery |
+| `/clavix:refine` | AGENT_MANUAL, cli-reference, quality-dimensions, state-awareness |
 | `/clavix:verify` | AGENT_MANUAL, cli-reference, vibecoder-recovery |
 | `/clavix:archive` | AGENT_MANUAL, cli-reference, vibecoder-recovery |
 

package/dist/templates/slash-commands/_components/agent-protocols/self-correction-protocol.md

@@ -18,4 +18,22 @@
 
 **RESUME**: Return to the {{MODE_NAME}} workflow with correct approach.
 
+### Recovery Patterns
+
+**If stuck in wrong mode:**
+1. Re-read the mode declaration at the top of this template
+2. Output the state assertion to reset context
+3. Continue from the correct workflow step
+
+**If user asks you to violate mode boundaries:**
+1. Acknowledge what they want to do
+2. Explain why this mode can't do that
+3. Suggest the correct command (e.g., "Use `/clavix:implement` to build that")
+
+**If you made partial progress before catching the mistake:**
+1. Stop immediately - don't finish the wrong action
+2. Explain what was done incorrectly
+3. Ask user if they want to undo/revert those changes
+4. Resume from the correct workflow step
+
 ---

package/dist/templates/slash-commands/_components/references/quality-dimensions.md

@@ -160,3 +160,24 @@ If ANY of these are true, suggest deep mode:
 | Completeness | 25% | Yes - below 50% triggers deep mode |
 | Actionability | 20% | Yes - below 50% triggers deep mode |
 | Specificity | 10% | No |
+
+---
+
+### Workflow-Specific Dimension Usage
+
+Different Clavix workflows use quality dimensions in different ways:
+
+| Workflow | Dimensions Used | Notes |
+|----------|----------------|-------|
+| `/clavix:improve` | All 6 | Full quality assessment for prompt optimization |
+| `/clavix:prd` | All 6 | PRD quality requires all dimensions |
+| `/clavix:summarize` | 5 (excludes Specificity) | Conversational extraction may lack concrete specifics by nature |
+| `/clavix:refine` | All 6 | Refinement targets all quality aspects |
+
+**Why Summarize Excludes Specificity:**
+The `/clavix:summarize` command extracts requirements from conversation. Users in exploratory mode often haven't determined specific versions, numbers, or file paths yet. Penalizing for missing specifics would unfairly score valid exploratory outputs.
+
+**Rationale for Dimension Selection:**
+- **Clarity, Completeness, Actionability**: Always critical - these determine if AI can act on the prompt
+- **Structure, Efficiency**: Important for complex prompts, less critical for simple ones
+- **Specificity**: Important for implementation, less important for early-stage exploration

package/dist/types/adapter-config.d.ts

@@ -32,13 +32,18 @@ export interface DetectionConfig {
 export interface AdapterFeatures {
     /** Whether the adapter supports subdirectories in command path */
     supportsSubdirectories: boolean;
-    /** Whether the adapter supports frontmatter in command files */
-    supportsFrontmatter: boolean;
     /** Whether the adapter supports doc injection (CLAUDE.md, etc.) */
     supportsDocInjection: boolean;
     /** Command separator character */
     commandSeparator: CommandSeparator;
-    /** Argument placeholder for TOML adapters */
+    /**
+     * Argument placeholder for tools that support runtime arguments.
+     *
+     * Syntax varies by tool:
+     * - TOML adapters (Gemini, Qwen, LLXPRT): `{{args}}` - converted at generation time
+     * - Some markdown adapters (Droid, OpenCode, Codex): `$ARGUMENTS` - passed through as-is
+     * - Most adapters: undefined - no argument support
+     */
     argumentPlaceholder?: string;
 }
 /**

package/dist/types/adapter-config.js

@@ -7,7 +7,6 @@
  */
 export const DEFAULT_MD_FEATURES = {
     supportsSubdirectories: false,
-    supportsFrontmatter: false,
     supportsDocInjection: false,
     commandSeparator: '-',
 };
@@ -16,7 +15,6 @@ export const DEFAULT_MD_FEATURES = {
  */
 export const DEFAULT_TOML_FEATURES = {
     supportsSubdirectories: true,
-    supportsFrontmatter: false,
     supportsDocInjection: false,
     commandSeparator: ':',
     argumentPlaceholder: '{{args}}',

package/dist/types/agent.d.ts

@@ -16,11 +16,9 @@ export interface AgentAdapter {
     validate?(): Promise<ValidationResult>;
 }
 export interface IntegrationFeatures {
-    supportsFrontmatter?: boolean;
     supportsExecutableCommands?: boolean;
     supportsSubdirectories?: boolean;
     argumentPlaceholder?: string;
-    frontmatterFields?: string[];
     /** Command format for slash command references in templates. Default: colon (:) */
     commandFormat?: {
         separator: ':' | '-';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "clavix",
-  "version": "5.6.5",
-  "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\nWorks with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
+  "version": "5.7.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",
   "types": "dist/index.d.ts",