clavix 5.5.2 → 5.6.0

package/dist/cli/commands/init.d.ts

@@ -14,5 +14,6 @@ export default class Init extends Command {
     private handleLegacyCommands;
     private injectDocumentation;
     private extractClavixBlock;
+    private generateQuickstart;
 }
 //# sourceMappingURL=init.d.ts.map

package/dist/cli/commands/init.js

@@ -2,7 +2,10 @@ import { Command } from '@oclif/core';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import * as path from 'path';
+import { fileURLToPath } from 'url';
 import { AgentManager } from '../../core/agent-manager.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
 import { DocInjector } from '../../core/doc-injector.js';
 import { AgentsMdGenerator } from '../../core/adapters/agents-md-generator.js';
 import { OctoMdGenerator } from '../../core/adapters/octo-md-generator.js';
@@ -157,8 +160,9 @@ export default class Init extends Command {
             // Generate config
             console.log(chalk.cyan('⚙️  Generating configuration...'));
             await this.generateConfig(selectedIntegrations);
-            // Generate INSTRUCTIONS.md
+            // Generate INSTRUCTIONS.md and QUICKSTART.md
             await this.generateInstructions();
+            await this.generateQuickstart();
             // Generate commands for each selected integration
             console.log(chalk.cyan(`\n📝 Generating commands for ${selectedIntegrations.length} integration(s)...\n`));
             for (const integrationName of selectedIntegrations) {
@@ -561,5 +565,16 @@ To reconfigure integrations, run \`clavix init\` again.
         const match = content.match(regex);
         return match ? match[1].trim() : content;
     }
+    async generateQuickstart() {
+        const quickstartPath = path.join(__dirname, '..', '..', 'templates', 'instructions', 'QUICKSTART.md');
+        try {
+            const quickstartContent = await FileSystem.readFile(quickstartPath);
+            await FileSystem.writeFileAtomic('.clavix/QUICKSTART.md', quickstartContent);
+        }
+        catch {
+            // QUICKSTART.md template not found or write failed, skip silently
+            // This can happen in test environments or custom installations
+        }
+    }
 }
 //# sourceMappingURL=init.js.map

package/dist/core/doc-injector.js

@@ -169,6 +169,8 @@ For more information, run \`clavix --help\` in your terminal.
 
 This project uses Clavix for prompt improvement and PRD generation. The following slash commands are available:
 
+> **Command Format:** Commands shown with colon (\`:\`) format. Some tools use hyphen (\`-\`): Claude Code uses \`/clavix:improve\`, Cursor uses \`/clavix-improve\`. Your tool autocompletes the correct format.
+
 ### Prompt Optimization
 
 #### /clavix:improve [prompt]
@@ -185,7 +187,7 @@ Generate an optimized implementation task breakdown from your PRD. Creates a pha
 #### /clavix:implement
 Execute tasks or prompts with AI assistance. Auto-detects source: tasks.md (from PRD workflow) or prompts/ (from improve workflow). Supports automatic git commits and progress tracking.
 
-Use \`--latest\` to execute most recent prompt, \`--tasks\` to force task mode.
+Use \`--latest\` to implement most recent prompt, \`--tasks\` to force task mode.
 
 ### Session Management
 

package/dist/core/template-assembler.d.ts

@@ -51,6 +51,8 @@ export declare class TemplateAssembler {
     hasIncludes(content: string): boolean;
     /**
      * Process all include markers in content
+     * @param content - The template content to process
+     * @param depth - Current nesting depth (for circular include protection)
      */
     private processIncludes;
     /**

package/dist/core/template-assembler.js

@@ -1,5 +1,15 @@
 import { promises as fs } from 'fs';
 import * as path from 'path';
+import { DataError } from '../types/errors.js';
+/**
+ * Maximum depth for nested {{INCLUDE:}} directives
+ * Prevents infinite loops from circular includes
+ */
+const MAX_INCLUDE_DEPTH = 10;
+/**
+ * Depth at which to log a warning about deep nesting
+ */
+const DEPTH_WARNING_THRESHOLD = 5;
 /**
  * TemplateAssembler - v4.0 Template Modularity System
  *
@@ -30,13 +40,13 @@ export class TemplateAssembler {
     async assembleTemplate(templatePath) {
         const fullPath = path.join(this.templatesBasePath, 'slash-commands', '_canonical', templatePath);
         const content = await this.loadFile(fullPath);
-        return this.processIncludes(content);
+        return this.processIncludes(content, 0);
     }
     /**
      * Assemble template from raw content string
      */
     async assembleFromContent(content) {
-        return this.processIncludes(content);
+        return this.processIncludes(content, 0);
     }
     /**
      * Check if a template contains include markers
@@ -46,8 +56,19 @@ export class TemplateAssembler {
     }
     /**
      * Process all include markers in content
+     * @param content - The template content to process
+     * @param depth - Current nesting depth (for circular include protection)
      */
-    async processIncludes(content) {
+    async processIncludes(content, depth) {
+        // Circular include protection
+        if (depth > MAX_INCLUDE_DEPTH) {
+            throw new DataError(`Maximum include depth (${MAX_INCLUDE_DEPTH}) exceeded`, 'Check for circular {{INCLUDE:}} references in templates');
+        }
+        // Warn about deep nesting
+        if (depth === DEPTH_WARNING_THRESHOLD) {
+            console.warn(`[TemplateAssembler] Warning: Include depth ${depth} reached. ` +
+                'Consider flattening template structure.');
+        }
         const includedComponents = [];
         const missingComponents = [];
         const variablesUsed = new Set();
@@ -86,9 +107,9 @@ export class TemplateAssembler {
                 processedContent = processedContent.replace(fullMatch, `<!-- MISSING COMPONENT: ${componentPath} -->`);
             }
         }
-        // Process nested includes (recursive)
+        // Process nested includes (recursive with depth tracking)
         if (this.hasIncludes(processedContent)) {
-            const nestedResult = await this.processIncludes(processedContent);
+            const nestedResult = await this.processIncludes(processedContent, depth + 1);
             processedContent = nestedResult.content;
             includedComponents.push(...nestedResult.includedComponents);
             missingComponents.push(...nestedResult.missingComponents);

package/dist/templates/agents/agents.md

@@ -80,6 +80,8 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 ### Workflow Commands (Slash Commands)
 All workflows are executed via slash commands that AI agents read and follow:
 
+> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
+
 | Slash Command | Purpose |
 |---------------|---------|
 | `/clavix:improve` | Optimize prompts (auto-selects depth) |

package/dist/templates/instructions/QUICKSTART.md

@@ -0,0 +1,65 @@
+# Clavix Quick Reference
+
+## Commands at a Glance
+
+| Command | Purpose | Mode |
+|---------|---------|------|
+| `/clavix:improve` | Optimize a prompt with auto-depth | Planning |
+| `/clavix:prd` | Generate PRD via strategic questions | Planning |
+| `/clavix:plan` | Create task breakdown from PRD | Planning |
+| `/clavix:implement` | Execute tasks or prompts | Implementation |
+| `/clavix:start` | Begin conversational exploration | Planning |
+| `/clavix:summarize` | Extract requirements from conversation | Planning |
+| `/clavix:refine` | Update existing PRD or prompt | Planning |
+| `/clavix:verify` | Check implementation against requirements | Verification |
+| `/clavix:archive` | Move completed project to archive | Management |
+
+> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
+
+## Common Workflows
+
+**Quick optimization:**
+```
+/clavix:improve "your prompt here"
+  → /clavix:implement --latest
+```
+
+**Full planning cycle:**
+```
+/clavix:prd
+  → /clavix:plan
+  → /clavix:implement
+  → /clavix:verify
+  → /clavix:archive
+```
+
+**Exploratory approach:**
+```
+/clavix:start
+  → (conversation)
+  → /clavix:summarize
+  → /clavix:plan
+  → /clavix:implement
+```
+
+## Key Directories
+
+- `.clavix/outputs/` — Generated PRDs, tasks, prompts
+- `.clavix/outputs/prompts/` — Saved optimized prompts
+- `.clavix/outputs/archive/` — Archived completed projects
+- `.clavix/instructions/` — Detailed workflow documentation
+
+## Mode Boundaries
+
+- **Planning Mode** (improve, prd, plan, start, summarize, refine): NO code generation
+- **Implementation Mode** (implement): Code generation ALLOWED
+- **Verification Mode** (verify): Read-only checks
+- **Management Mode** (archive): File organization only
+
+## Getting Started
+
+1. Run `clavix init` to set up your project
+2. Use `/clavix:improve "your idea"` to optimize a prompt
+3. Use `/clavix:implement --latest` to implement it
+
+For detailed documentation, see `.clavix/instructions/` in your project.

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

@@ -326,9 +326,9 @@ Before considering this task complete, verify:
 
 ---
 
-## CHECKPOINT: Analysis Complete?
+**CHECKPOINT:** Analysis Complete
 
-**Before proceeding to save, verify you have output ALL of the following:**
+Before proceeding to save, verify you have output ALL of the following:
 
 **Standard Depth:**
 - [ ] **Intent Analysis** with type and confidence
@@ -349,9 +349,9 @@ Before considering this task complete, verify:
 
 ---
 
-## ⛔ SAVING CHECKPOINT (REQUIRED - DO NOT SKIP)
+**CHECKPOINT:** Saving Protocol (REQUIRED - DO NOT SKIP)
 
-**DO NOT output any "saved" message until you have COMPLETED and VERIFIED all save steps.**
+DO NOT output any "saved" message until you have COMPLETED and VERIFIED all save steps.
 
 This is a BLOCKING checkpoint. You cannot proceed to the final message until saving is verified.
 

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

@@ -252,11 +252,17 @@ mkdir -p .clavix/outputs/{sanitized-project-name}
 ```
 
 ### Step 5: Verify Files Were Created
-```bash
-ls .clavix/outputs/{project-name}/
-```
 
-**Expected output**:
+**Verification Protocol:**
+1. **Immediately after Write**, use Read tool to verify each file:
+   - Read `.clavix/outputs/{project-name}/full-prd.md`
+   - Confirm content matches what you wrote
+   - Read `.clavix/outputs/{project-name}/quick-prd.md`
+   - Confirm content matches what you wrote
+
+2. **If Read fails**: STOP and report error to user
+
+**Expected files**:
 - `full-prd.md`
 - `quick-prd.md`
 

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

@@ -9,9 +9,11 @@ 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 8 commands |
+| `AGENT_MANUAL.md` | Universal protocols (transparency, mode identification, communication patterns) | All 9 commands |
 | `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 |
+| `self-correction-protocol.md` | Mistake detection and correction patterns (supports variables) | Available for all commands |
 | `supportive-companion.md` | Conversational guidance for start mode | start |
 | `task-blocking.md` | Task execution protocols for implement mode | implement |
 
@@ -63,6 +65,18 @@ Components are included using the `{{INCLUDE:path}}` directive:
 {{INCLUDE:references/quality-dimensions.md}}
 ```
 
+### Variable Interpolation
+
+Components can accept variables for customization:
+
+```markdown
+{{INCLUDE:agent-protocols/state-assertion.md MODE_NAME="Improve" MODE_TYPE="planning" MODE_PURPOSE="Optimizing prompts" IMPL_STATUS="BLOCKED"}}
+```
+
+Variables use mustache-style syntax:
+- `{{VAR_NAME}}` - Simple replacement
+- `{{#VAR_NAME}}content{{/VAR_NAME}}` - Conditional block (shown if VAR_NAME is set)
+
 ## Guidelines for New Components
 
 1. **Single responsibility**: Each component should have one clear purpose

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

@@ -0,0 +1,21 @@
+## 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. {{MISTAKE_2}} | {{MISTAKE_2_DESC}} |
+| 3. {{MISTAKE_3}} | {{MISTAKE_3_DESC}} |
+| 4. {{MISTAKE_4}} | {{MISTAKE_4_DESC}} |
+| 5. {{MISTAKE_5}} | {{MISTAKE_5_DESC}} |
+| 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 {{MODE_NAME}}."
+
+**RESUME**: Return to the {{MODE_NAME}} workflow with correct approach.
+
+---

package/dist/templates/slash-commands/_components/agent-protocols/state-assertion.md

@@ -0,0 +1,12 @@
+## State Assertion (REQUIRED)
+
+**Before starting {{ACTION}}, output:**
+```
+**CLAVIX MODE: {{MODE_NAME}}**
+Mode: {{MODE_TYPE}}
+Purpose: {{MODE_PURPOSE}}
+{{#EXTRA_FIELD}}{{EXTRA_FIELD}}{{/EXTRA_FIELD}}
+Implementation: {{IMPL_STATUS}}
+```
+
+---

package/dist/templates/slash-commands/_components/sections/prd-examples.md

@@ -279,6 +279,28 @@ Copy and fill in:
 
 ---
 
+## Quick PRD Examples
+
+Quick PRDs condense the full PRD into 2-3 AI-optimized paragraphs for efficient agent consumption.
+
+### Quick PRD Example 1: Habit Tracker
+
+**Goal:** Build a mobile-first habit tracking app that helps users build consistent daily routines through streak tracking, reminders, and progress visualization. Target users are productivity-focused individuals who want simple habit management without complex features.
+
+**Core Features:** Daily habit check-in with streak counter, customizable reminder notifications, weekly/monthly progress charts, habit templates for common goals (exercise, reading, meditation). Tech stack: React Native, local storage with optional cloud sync.
+
+**Scope Boundaries:** No social features, no gamification beyond streaks, no premium tiers. Focus on core tracking reliability over feature breadth.
+
+### Quick PRD Example 2: API User Management
+
+**Goal:** Create a RESTful user management microservice for the existing e-commerce platform, handling authentication, authorization, and user profile CRUD operations. Must integrate with existing PostgreSQL database and support OAuth2.
+
+**Core Features:** JWT-based authentication, role-based access control (admin/user/guest), user registration with email verification, password reset flow, profile management endpoints. Built with Node.js/Express, PostgreSQL, Redis for session caching.
+
+**Scope Boundaries:** No frontend components, no payment integration, no analytics dashboard. Service-only implementation with OpenAPI documentation.
+
+---
+
 ### Key Elements of a Good Mini-PRD
 
 1. **Clear problem statement** - Why are we building this?

package/dist/utils/agent-error-messages.js

@@ -17,7 +17,7 @@ export class AgentErrorMessages {
             'Agent recovery options:\n' +
             '  1. Execute /clavix:prd to generate comprehensive PRD\n' +
             '  2. Execute /clavix:summarize if conversation exists\n\n' +
-            'Select option and execute, then retry this command.');
+            'Select option and run, then retry this command.');
     }
     /**
      * Error: No tasks.md found for specified project

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.5.2",
+  "version": "5.6.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\nWorks with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
   "type": "module",
   "main": "dist/index.js",