clavix 5.8.1 → 5.8.2

package/dist/cli/helpers/init/integrations.js

@@ -96,8 +96,9 @@ export function getDisplayNames(agentManager, integrations) {
  * Determine the command separator based on selected integrations
  */
 export function determineCommandSeparator(integrations) {
-    const usesColon = integrations.some((i) => COLON_SEPARATOR_INTEGRATIONS.includes(i));
-    const usesHyphen = integrations.some((i) => !COLON_SEPARATOR_INTEGRATIONS.includes(i));
+    const colonList = COLON_SEPARATOR_INTEGRATIONS;
+    const usesColon = integrations.some((i) => colonList.includes(i));
+    const usesHyphen = integrations.some((i) => !colonList.includes(i));
     if (usesColon && !usesHyphen) {
         return { primary: ':' };
     }

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

@@ -274,7 +274,7 @@ Result: Project permanently deleted
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -524,7 +524,7 @@ I'll explain what's wrong and what you might need to do:
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -125,6 +125,8 @@ Clavix provides a unified **improve** mode that intelligently selects the approp
 
 ## Instructions
 
+**Before beginning:** Use the Clarifying Questions Protocol (see Agent Transparency section) when you need critical information from the user (confidence < 95%). For prompt improvement, this means confirming intent, desired depth, or technical constraints when ambiguous.
+
 1. Take the user's prompt: `{{ARGS}}`
 
 2. **Intent Detection** - Analyze what the user is trying to achieve:
@@ -522,7 +524,7 @@ Wait for the user to decide what to do next.
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -79,6 +79,8 @@ Implementation: BLOCKED - I will create the plan, not the code
 
 ## Instructions
 
+**Before beginning:** Use the Clarifying Questions Protocol (see Agent Transparency section) when you need critical information from the user (confidence < 95%). For task planning, this means confirming which PRD to use, technical approach preferences, or task breakdown granularity.
+
 ### Part A: Agent Execution Protocol
 
 **As an AI agent, you must follow this strict sequence:**
@@ -219,7 +221,7 @@ Present the plan and ask:
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -87,6 +87,8 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
 
 ## Instructions
 
+**Before beginning:** Use the Clarifying Questions Protocol (see Agent Transparency section) when you need critical information from the user (confidence < 95%). For PRD development, this means confirming ambiguous project scope, technical requirements, or feature priorities.
+
 1. Guide the user through these strategic questions, **one at a time** with validation:
 
    **Question 1**: What are we building and why? (Problem + goal in 2-3 sentences)
@@ -344,7 +346,7 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -415,7 +415,7 @@ I'll update the PRD and add this to the refinement history. Confirm?
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -79,6 +79,8 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
 
 ## Instructions
 
+**Before beginning:** Use the Clarifying Questions Protocol (see Agent Transparency section) throughout the conversation when you need critical information from the user (confidence < 95%). In conversational mode, this means probing for unclear requirements, technical constraints, or user needs.
+
 1. Begin with a friendly introduction:
    ```
    I'm starting Clavix conversational mode for requirements gathering.
@@ -226,7 +228,7 @@ The goal is natural exploration of requirements, not a rigid questionnaire. Foll
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -80,6 +80,8 @@ Implementation: BLOCKED - I will extract requirements, not implement them
 
 ## Instructions
 
+**Before beginning:** Use the Clarifying Questions Protocol (see Agent Transparency section) when you need critical information from the user (confidence < 95%). For summarization, this means asking for missing context, unclear requirements, or ambiguous technical specifications before extraction.
+
 1. **Pre-Extraction Validation** - Check conversation completeness:
 
    **CHECKPOINT:** Pre-extraction validation started
@@ -401,7 +403,7 @@ The `/clavix:summarize` command extracts requirements from exploratory conversat
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -123,7 +123,7 @@ Implementation: BLOCKED - I'll analyze and report, not modify or fix
 
 ----
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.8.2)
 
 ### Agent Manual (Universal Protocols)
 {{INCLUDE:agent-protocols/AGENT_MANUAL.md}}

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

@@ -10,6 +10,7 @@ Core protocols that all AI agents must follow. Shared across most commands.
 | Component | Purpose | Used By |
 |-----------|---------|---------|
 | `AGENT_MANUAL.md` | Universal protocols (transparency, mode identification, communication patterns) | All 9 commands |
+| `clarifying-questions.md` | Systematic protocol for asking clarifying questions (95% confidence threshold) | improve, prd, plan, start, summarize |
 | `cli-reference.md` | CLI command reference including removed commands table | improve, prd, plan, implement, verify, archive |
 | `state-awareness.md` | Workflow state detection (mid-PRD, mid-implementation, etc.) | prd, plan, implement, summarize |
 | `state-assertion.md` | Required mode assertion output (MODE, Purpose, Implementation status) | Available for all commands |
@@ -46,12 +47,12 @@ Recovery patterns for common agent issues.
 
 | Command | Components Used |
 |---------|----------------|
-| `/clavix:improve` | AGENT_MANUAL, cli-reference, improvement-explanations, quality-dimensions, escalation-factors, pattern-impact |
-| `/clavix:prd` | AGENT_MANUAL, prd-examples, quality-dimensions, state-awareness, cli-reference |
-| `/clavix:plan` | AGENT_MANUAL, state-awareness, cli-reference, vibecoder-recovery |
+| `/clavix:improve` | AGENT_MANUAL (includes clarifying-questions), cli-reference, improvement-explanations, quality-dimensions, escalation-factors, pattern-impact |
+| `/clavix:prd` | AGENT_MANUAL (includes clarifying-questions), prd-examples, quality-dimensions, state-awareness, cli-reference |
+| `/clavix:plan` | AGENT_MANUAL (includes clarifying-questions), state-awareness, cli-reference, vibecoder-recovery |
 | `/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:start` | AGENT_MANUAL (includes clarifying-questions), supportive-companion, conversation-examples, vibecoder-recovery |
+| `/clavix:summarize` | AGENT_MANUAL (includes clarifying-questions), 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/AGENT_MANUAL.md

@@ -268,6 +268,12 @@ Each Clavix command has a specific mode. Stay within your mode:
 
 ---
 
+## Clarifying Questions Protocol
+
+{{INCLUDE:agent-protocols/clarifying-questions.md}}
+
+---
+
 ## Verification Block Template
 
 At the end of workflows that produce output, include verification:

package/dist/templates/slash-commands/_components/agent-protocols/clarifying-questions.md

@@ -0,0 +1,99 @@
+# Clarifying Questions Protocol
+
+When the user's request requires critical information to proceed correctly, use this protocol to gather necessary details systematically.
+
+## When to Ask Clarifying Questions
+
+Ask clarifying questions when:
+- **Critical ambiguity exists** - The request has multiple valid interpretations that lead to substantially different outcomes
+- **Missing essential context** - Information necessary to complete the task successfully is absent
+- **Technical specifications needed** - Specific versions, paths, identifiers, or constraints are required
+- **User choice required** - Multiple valid approaches exist and the user's preference is needed
+
+**Do NOT ask clarifying questions when:**
+- The information is trivial or easily inferred from context
+- You can make a reasonable default assumption and mention it
+- The question would slow down obviously simple tasks
+- You're seeking perfection rather than addressing genuine ambiguity
+
+## Question Format
+
+Use this structured format for maximum clarity and efficiency:
+
+### a. Multiple Choice Questions
+
+When presenting options, use clear labels and make selection easy:
+
+**Question:** [Your question here]
+
+**Options:**
+- **a.** First option - brief explanation
+- **b.** Second option - brief explanation  
+- **c.** Third option - brief explanation
+
+**Please respond with your choice (e.g., 'a' or 'option a').**
+
+### b. Custom Input Questions
+
+When you need specific information not in a predefined list:
+
+**Question:** [Your question here]
+
+**Please provide:** [Clear description of what format/content you need]
+
+**Example:** [Show an example of valid input]
+
+## Confidence Threshold
+
+**Ask clarifying questions when confidence < 95%**
+
+If you're 95%+ confident you understand the user's intent and have the necessary information, proceed without asking. If confidence is below 95%, stop and ask.
+
+## Best Practices
+
+1. **Ask questions sequentially** - Don't overwhelm with multiple questions at once unless they're tightly related
+2. **Explain why you're asking** - Briefly state what the answer will help you determine
+3. **Limit options** - Present 2-4 options maximum for choice questions
+4. **Make defaults clear** - If there's a sensible default, state it and ask for confirmation
+5. **Batch related questions** - If multiple questions are interdependent, present them together
+
+## Examples
+
+### Good: Clear Multiple Choice
+> I need to know where to save the configuration file to proceed correctly.
+>
+> **Options:**
+> - **a.** Project root (recommended for project-specific configs)
+> - **b.** Home directory (for user-wide settings)
+> - **c.** Custom path (you specify)
+>
+> **Please respond with your choice (e.g., 'a').**
+
+### Good: Custom Input with Context
+> To generate the migration script, I need the database schema version.
+>
+> **Please provide:** The current schema version number (e.g., "2.1.0" or "v3.4")
+>
+> If you're unsure, you can check with: `npm run db:version`
+
+### Bad: Unnecessary Question
+> ❌ "Do you want me to use good coding practices?"
+>
+> (This is always implied - just do it)
+
+### Bad: Analysis Paralysis
+> ❌ "Should I use const or let for this variable?"
+>
+> (This is implementation detail - decide yourself based on best practices)
+
+## Recovery Pattern
+
+If you realize you should have asked clarifying questions AFTER starting:
+
+1. **STOP** the current approach
+2. **EXPLAIN** what you discovered that requires clarification  
+3. **ASK** the necessary questions
+4. **RESUME** with the correct approach once answered
+
+**Example:**
+> I apologize - I started implementing the auth flow but realized I need to clarify which authentication method you want to use. Are we implementing: (a) JWT tokens, (b) Session-based auth, or (c) OAuth2?

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.8.1",
+  "version": "5.8.2",
   "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",