clavix 5.6.5 → 5.6.6

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/templates/slash-commands/_canonical/archive.md

@@ -285,6 +285,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 +325,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/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

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)

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/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/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.6.6",
+  "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",