clavix 5.8.1 → 5.9.0

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.9.0)
 
 ### 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.9.0)
 
 ### 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.9.0)
 
 ### 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:**
@@ -105,30 +107,37 @@ Implementation: BLOCKED - I will create the plan, not the code
    - Check `.clavix/outputs/<project-name>/` for `full-prd.md`, `quick-prd.md`, etc.
    - If missing, check legacy `.clavix/outputs/summarize/`.
 2. **Read PRD**: Ingest the requirements.
+3. **Extract Architecture**: Look for the "Architecture & Design" section. Note any specific patterns (e.g., Clean Architecture, Feature-Sliced Design) or structural decisions.
 
 #### **Phase 3: Task Generation**
-1. **Synthesize**: Combine [PRD Requirements] + [Codebase Patterns].
-2. **Draft Tasks**: Create tasks that specify *exactly* what to change in the code.
-3. **Create `tasks.md`**: Use the format in "Task Format Reference".
-4. **Save to**: `.clavix/outputs/[project-name]/tasks.md`.
+1. **Synthesize**: Combine [PRD Requirements] + [Codebase Patterns] + [Architecture Decisions].
+2. **Prioritize Structure**: Ensure initial tasks cover any necessary architectural setup (e.g., creating folders for new layers, setting up base classes).
+3. **Draft Tasks**: Create tasks that specify *exactly* what to change in the code.
+4. **Create `tasks.md`**: Use the format in "Task Format Reference".
+5. **Save to**: `.clavix/outputs/[project-name]/tasks.md`.
 
 ### Part B: Behavioral Guidance (Technical Specificity)
 
 **Your goal is "Low-Level Engineering Plans", not "High-Level Management Plans".**
 
-1. **Specific File Paths**:
+1. **Architecture First**:
+   - If the PRD specifies a pattern (e.g., Repository), the first tasks MUST set up that structure.
+   - **Bad**: "Implement user feature."
+   - **Good**: "Create `src/repositories/UserRepository.ts` interface first, then implementation."
+
+2. **Specific File Paths**:
    - **Bad**: "Create a user profile component."
    - **Good**: "Create `src/components/user/UserProfile.tsx`. Export as default."
 
-2. **Technical Constraints**:
+3. **Technical Constraints**:
    - **Bad**: "Add validation."
    - **Good**: "Use `zod` schema in `src/schemas/user.ts`. Integrate with `react-hook-form`."
 
-3. **Respect Existing Architecture**:
+4. **Respect Existing Architecture**:
    - If the project uses a `services/` folder for API calls, do **not** put `fetch` calls directly in components.
    - If the project uses `shadcn/ui`, instruct to use those primitives, not raw HTML.
 
-4. **Granularity**:
+5. **Granularity**:
    - Each task should be a single logical unit of work (approx. 20-40 mins).
    - Separate "Backend API" from "Frontend UI" tasks.
    - Separate "Type Definition" from "Implementation" if complex.
@@ -148,6 +157,7 @@ Implementation: BLOCKED - I will create the plan, not the code
 
 ## Technical Context & Standards
 *Detected Stack & Patterns*
+- **Architecture**: {e.g., Feature-Sliced Design, Monolith}
 - **Framework**: {e.g., Next.js 14 App Router}
 - **Styling**: {e.g., Tailwind CSS + shadcn/ui}
 - **State**: {e.g., Zustand (stores in /src/store)}
@@ -219,7 +229,7 @@ Present the plan and ask:
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.9.0)
 
 ### 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)
@@ -123,6 +125,11 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
      - "Are there performance requirements (load time, concurrent users)?"
    - **If "I don't know"**: Suggest common stacks based on project type or skip
 
+   **Question 3.5**: Any specific architectural patterns or design choices?
+
+   - **Optional**
+   - **Prompt**: "Do you have preferences for folder structure, design patterns (e.g., Repository, Adapter), or architectural style (Monolith vs Microservices)?"
+
    **Question 4**: What is explicitly OUT of scope? (What are we NOT building?)
 
    - **Validation**: At least 1 explicit exclusion
@@ -134,7 +141,7 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
 
    **Question 5**: Any additional context or requirements?
 
-   - **Optional**: Press Enter to skip
+   - **Optional**
    - **Helpful areas**: Compliance needs, accessibility, localization, deadlines, team constraints
 
 2. **Before proceeding to document generation**, verify minimum viable answers:
@@ -159,6 +166,9 @@ Both documents are automatically validated for quality (Clarity, Structure, Comp
    ### Technical Requirements
    [User's answer to Q3, detailed]
 
+   ### Architecture & Design
+   [User's answer to Q3.5 if provided]
+
    ## Out of Scope
    [User's answer to Q4]
 
@@ -344,7 +354,7 @@ The validation ensures generated PRDs are immediately usable for AI consumption
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.9.0)
 
 ### 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.9.0)
 
 ### 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.
@@ -96,6 +98,7 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
 2. As the user describes their needs:
    - Ask clarifying questions about unclear points
    - Probe for technical constraints
+   - Probe for architectural preferences (e.g., 'Do you need a specific structure like Clean Architecture, Microservices, or Feature-Sliced Design?')
    - Explore edge cases and requirements
    - Help them think through user needs
    - Identify potential challenges
@@ -115,6 +118,7 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
    - Target users
    - Core features
    - Technical requirements
+   - Architecture & Design
    - Success criteria
    - Constraints and scope
 
@@ -226,7 +230,7 @@ The goal is natural exploration of requirements, not a rigid questionnaire. Foll
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.9.0)
 
 ### 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
@@ -113,6 +115,7 @@ Implementation: BLOCKED - I will extract requirements, not implement them
    - **Problem/Goal** [confidence]: What is the user trying to build or solve?
    - **Key Requirements** [confidence per requirement]: What features and functionality were discussed?
    - **Technical Constraints** [confidence]: Any technologies, integrations, or performance needs?
+   - **Architecture & Design** [confidence]: Any specific patterns, structures, or design choices?
    - **User Needs** [confidence]: Who are the end users and what do they need?
    - **Success Criteria** [confidence]: How will success be measured?
    - **Context** [confidence]: Any important background or constraints?
@@ -195,6 +198,11 @@ Implementation: BLOCKED - I will extract requirements, not implement them
    - **Integrations:** [External systems]
    - **Other:** [Any other technical constraints]
 
+   ## Architecture & Design
+   - **Pattern:** [e.g. Monolith, Microservices, Serverless]
+   - **Structure:** [e.g. Feature-based, Layered, Clean Architecture]
+   - **Key Decisions:** [Specific design choices made]
+
    ## User Context
    **Target Users:** [Who will use this?]
    **Primary Use Case:** [Main problem being solved]
@@ -401,7 +409,7 @@ The `/clavix:summarize` command extracts requirements from exploratory conversat
 
 ---
 
-## Agent Transparency (v5.8.1)
+## Agent Transparency (v5.9.0)
 
 ### 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.9.0)
 
 ### 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.9.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",