clavix 3.5.0 → 3.6.1

package/README.md

@@ -12,10 +12,10 @@
 
 | Version | Highlights | Details |
 | --- | --- | --- |
-| **v3.4.0** (Latest) | Provider categorization fixes | [Changelog](CHANGELOG.md#340---2025-11-24) |
-| **v3.3.1** | JSON5/JSON config bug fix | [Changelog](CHANGELOG.md#331---2025-11-23) |
-| **v3.3.0** | Provider management & interactive config | [Changelog](CHANGELOG.md#330---2025-11-23) |
-| **v3.1.0** | Clavix Intelligence™ brand evolution | [Changelog](CHANGELOG.md#310---2025-11-23) |
+| **v3.6.1** (Latest) | Documentation hierarchy & verbosity reduction | [Changelog](CHANGELOG.md#361---2025-11-24) |
+| **v3.6.0** | Enhanced generic connector instructions | [Changelog](CHANGELOG.md#360---2025-11-24) |
+| **v3.5.0** | "Providers" → "Integrations" terminology | [Changelog](CHANGELOG.md#350---2025-01-24) |
+| **v3.4.0** | Provider categorization fixes | [Changelog](CHANGELOG.md#340---2025-11-24) |
 
 **Requirements:** Node.js ≥ 16.0.0 (ESM support required)
 

package/dist/cli/commands/init.js

@@ -8,6 +8,7 @@ import { AgentsMdGenerator } from '../../core/adapters/agents-md-generator.js';
 import { OctoMdGenerator } from '../../core/adapters/octo-md-generator.js';
 import { WarpMdGenerator } from '../../core/adapters/warp-md-generator.js';
 import { CopilotInstructionsGenerator } from '../../core/adapters/copilot-instructions-generator.js';
+import { InstructionsGenerator } from '../../core/adapters/instructions-generator.js';
 import { FileSystem } from '../../utils/file-system.js';
 import { DEFAULT_CONFIG } from '../../types/config.js';
 import { GeminiAdapter } from '../../core/adapters/gemini-adapter.js';
@@ -216,6 +217,12 @@ export default class Init extends Command {
                     await this.injectDocumentation(adapter);
                 }
             }
+            // Generate .clavix/instructions/ folder for generic integrations
+            if (InstructionsGenerator.needsGeneration(selectedIntegrations)) {
+                console.log(chalk.gray('\n📁 Generating .clavix/instructions/ reference folder...'));
+                await InstructionsGenerator.generate();
+                console.log(chalk.gray('  ✓ Created detailed workflow guides for generic integrations'));
+            }
             // Success message
             console.log(chalk.bold.green('\n✅ Clavix initialized successfully!\n'));
             console.log(chalk.gray('Next steps:'));

package/dist/cli/commands/update.js

@@ -10,6 +10,7 @@ import { AgentManager } from '../../core/agent-manager.js';
 import { AgentsMdGenerator } from '../../core/adapters/agents-md-generator.js';
 import { OctoMdGenerator } from '../../core/adapters/octo-md-generator.js';
 import { WarpMdGenerator } from '../../core/adapters/warp-md-generator.js';
+import { InstructionsGenerator } from '../../core/adapters/instructions-generator.js';
 import { collectLegacyCommandFiles } from '../../utils/legacy-command-cleanup.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
@@ -91,6 +92,13 @@ export default class Update extends Command {
                 updatedCount += await this.updateCommands(adapter, flags.force);
             }
         }
+        // Update .clavix/instructions/ folder for generic integrations
+        if (updateDocs && InstructionsGenerator.needsGeneration(integrations)) {
+            this.log(chalk.gray('\n📁 Updating .clavix/instructions/ reference folder...'));
+            await InstructionsGenerator.generate();
+            this.log(chalk.gray('  ✓ Updated detailed workflow guides'));
+            updatedCount++;
+        }
         this.log('');
         if (updatedCount > 0) {
             this.log(chalk.green(`✅ Successfully updated ${updatedCount} file(s)`));

package/dist/core/adapters/instructions-generator.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Generator for .clavix/instructions/ reference folder
+ * Provides detailed workflow guides for generic integrations
+ */
+export declare class InstructionsGenerator {
+    static readonly TARGET_DIR = ".clavix/instructions";
+    /**
+     * Generic integrations that need the instructions folder
+     */
+    static readonly GENERIC_INTEGRATIONS: string[];
+    /**
+     * Generate .clavix/instructions/ folder with all reference files
+     */
+    static generate(): Promise<void>;
+    /**
+     * Copy static instruction files (core/, troubleshooting/, README.md)
+     * Excludes workflows/ directory - that comes from canonical templates
+     */
+    private static copyStaticInstructions;
+    /**
+     * Copy ALL canonical templates to .clavix/instructions/workflows/
+     * This ensures generic integrations have access to complete workflow set
+     */
+    private static copyCanonicalWorkflows;
+    /**
+     * Recursively copy directory contents
+     */
+    private static copyDirectory;
+    /**
+     * Check if instructions folder exists
+     */
+    static exists(): Promise<boolean>;
+    /**
+     * Check if any generic integration is selected
+     */
+    static needsGeneration(selectedIntegrations: string[]): boolean;
+    /**
+     * Remove instructions folder
+     */
+    static remove(): Promise<void>;
+}
+//# sourceMappingURL=instructions-generator.d.ts.map

package/dist/core/adapters/instructions-generator.js

@@ -0,0 +1,123 @@
+import { FileSystem } from '../../utils/file-system.js';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Generator for .clavix/instructions/ reference folder
+ * Provides detailed workflow guides for generic integrations
+ */
+export class InstructionsGenerator {
+    static TARGET_DIR = '.clavix/instructions';
+    /**
+     * Generic integrations that need the instructions folder
+     */
+    static GENERIC_INTEGRATIONS = [
+        'octo-md',
+        'warp-md',
+        'agents-md',
+        'copilot-instructions'
+    ];
+    /**
+     * Generate .clavix/instructions/ folder with all reference files
+     */
+    static async generate() {
+        const staticInstructionsPath = path.join(__dirname, '../../templates/instructions');
+        // Check if static template exists
+        if (!(await FileSystem.exists(staticInstructionsPath))) {
+            throw new Error(`.clavix/instructions static files not found at ${staticInstructionsPath}`);
+        }
+        // Create target directory
+        await FileSystem.ensureDir(this.TARGET_DIR);
+        // Step 1: Copy static instruction files (core/, troubleshooting/, README.md)
+        // Note: This skips workflows/ directory if it exists
+        await this.copyStaticInstructions(staticInstructionsPath, this.TARGET_DIR);
+        // Step 2: Copy ALL canonical workflows → .clavix/instructions/workflows/
+        await this.copyCanonicalWorkflows();
+    }
+    /**
+     * Copy static instruction files (core/, troubleshooting/, README.md)
+     * Excludes workflows/ directory - that comes from canonical templates
+     */
+    static async copyStaticInstructions(src, dest) {
+        const entries = await FileSystem.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            // Skip workflows/ directory - it will be populated from canonical
+            if (entry.isDirectory() && entry.name === 'workflows') {
+                continue;
+            }
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            if (entry.isDirectory()) {
+                await FileSystem.ensureDir(destPath);
+                await this.copyDirectory(srcPath, destPath);
+            }
+            else {
+                const content = await FileSystem.readFile(srcPath);
+                await FileSystem.writeFileAtomic(destPath, content);
+            }
+        }
+    }
+    /**
+     * Copy ALL canonical templates to .clavix/instructions/workflows/
+     * This ensures generic integrations have access to complete workflow set
+     */
+    static async copyCanonicalWorkflows() {
+        const canonicalPath = path.join(__dirname, '../../templates/slash-commands/_canonical');
+        const workflowsTarget = path.join(this.TARGET_DIR, 'workflows');
+        if (!(await FileSystem.exists(canonicalPath))) {
+            throw new Error(`Canonical templates not found at ${canonicalPath}`);
+        }
+        // Create workflows directory
+        await FileSystem.ensureDir(workflowsTarget);
+        // Copy all .md files from canonical
+        const entries = await FileSystem.readdir(canonicalPath, { withFileTypes: true });
+        const mdFiles = entries.filter(f => f.isFile() && f.name.endsWith('.md'));
+        for (const file of mdFiles) {
+            const srcPath = path.join(canonicalPath, file.name);
+            const destPath = path.join(workflowsTarget, file.name);
+            const content = await FileSystem.readFile(srcPath);
+            await FileSystem.writeFileAtomic(destPath, content);
+        }
+    }
+    /**
+     * Recursively copy directory contents
+     */
+    static async copyDirectory(src, dest) {
+        const entries = await FileSystem.readdir(src, { withFileTypes: true });
+        for (const entry of entries) {
+            const srcPath = path.join(src, entry.name);
+            const destPath = path.join(dest, entry.name);
+            if (entry.isDirectory()) {
+                await FileSystem.ensureDir(destPath);
+                await this.copyDirectory(srcPath, destPath);
+            }
+            else {
+                const content = await FileSystem.readFile(srcPath);
+                await FileSystem.writeFileAtomic(destPath, content);
+            }
+        }
+    }
+    /**
+     * Check if instructions folder exists
+     */
+    static async exists() {
+        return await FileSystem.exists(this.TARGET_DIR);
+    }
+    /**
+     * Check if any generic integration is selected
+     */
+    static needsGeneration(selectedIntegrations) {
+        return selectedIntegrations.some(integration => this.GENERIC_INTEGRATIONS.includes(integration));
+    }
+    /**
+     * Remove instructions folder
+     */
+    static async remove() {
+        if (await this.exists()) {
+            await FileSystem.remove(this.TARGET_DIR);
+        }
+    }
+}
+//# sourceMappingURL=instructions-generator.js.map

package/dist/templates/agents/agents.md

@@ -1,72 +1,167 @@
-# Clavix Workflows
+# Clavix Instructions for Generic Agents
 
-Use these instructions when your agent can only read documentation (no slash-command support).
+This guide is for agents that can only read documentation (no slash-command support). If your platform supports custom slash commands, use those instead.
 
-## Quick start
-- Install globally: `npm install -g clavix`
-- Or run ad hoc: `npx clavix@latest init`
-- Verify installation: `clavix version`
+---
 
-## Command reference
+## CLAVIX PLANNING MODE
+
+**You are in Clavix prompt/PRD development mode. You help create planning documents, NOT implement features.**
+
+**PLANNING workflows** (requirements & documentation):
+- Conversational mode, requirement extraction, fast/deep optimization, PRD generation
+- Your role: Ask questions, create PRDs/prompts, extract requirements
+- DO NOT implement features during these workflows
+
+**IMPLEMENTATION workflows** (code execution):
+- Only when user explicitly says: "Now implement this" or "Build the feature"
+- Your role: Write code, execute tasks, implement features
+
+**If unsure, ASK:** "Should I implement this now, or continue with planning?"
+
+See `.clavix/instructions/core/clavix-mode.md` for complete mode documentation.
+
+---
+
+## 📁 Detailed Workflow Instructions
+
+For complete step-by-step workflows, see `.clavix/instructions/`:
+
+| Workflow | Instruction File | Purpose |
+|----------|-----------------|---------|
+| **Conversational Mode** | `workflows/start.md` | Natural requirements gathering through discussion |
+| **Extract Requirements** | `workflows/summarize.md` | Analyze conversation → mini-PRD + optimized prompts |
+| **Quick Optimization** | `workflows/fast.md` | Intent detection + quality assessment + smart triage |
+| **Deep Analysis** | `workflows/deep.md` | Comprehensive with alternatives, validation, edge cases |
+| **PRD Generation** | `workflows/prd.md` | Socratic questions → full PRD + quick PRD |
+| **Mode Boundaries** | `core/clavix-mode.md` | Planning vs implementation distinction |
+| **File Operations** | `core/file-operations.md` | File creation patterns |
+
+**Troubleshooting:**
+- `troubleshooting/jumped-to-implementation.md` - If you started coding during planning
+- `troubleshooting/skipped-file-creation.md` - If files weren't created
+- `troubleshooting/mode-confusion.md` - When unclear about planning vs implementation
+
+---
+
+## 🔍 Workflow Detection Keywords
+
+| Keywords in User Request | Recommended Workflow | File Reference |
+|---------------------------|---------------------|----------------|
+| "improve this prompt", "make it better", "optimize" | Fast mode → Quick optimization | `workflows/fast.md` |
+| "analyze thoroughly", "edge cases", "alternatives" | Deep mode → Comprehensive analysis | `workflows/deep.md` |
+| "create a PRD", "product requirements" | PRD mode → Socratic questioning | `workflows/prd.md` |
+| "let's discuss", "not sure what I want" | Conversational mode → Start gathering | `workflows/start.md` |
+| "summarize our conversation" | Extract mode → Analyze thread | `workflows/summarize.md` |
+
+---
+
+## 📋 CLI Quick Reference
 
 | Command | Purpose |
-| --- | --- |
-| `clavix init` | Interactive setup. Select integrations and generate documentation/command files. |
-| `clavix fast "<prompt>"` | Quick prompt optimization with quality assessment (Clarity, Efficiency, Structure, Completeness, Actionability). CLI auto-saves to `.clavix/outputs/prompts/fast/`. When using slash commands, agent must save manually per template instructions. |
-| `clavix deep "<prompt>"` | Comprehensive analysis with alternatives, edge cases, and validation checklists. CLI auto-saves to `.clavix/outputs/prompts/deep/`. When using slash commands, agent must save manually per template instructions. |
-| `clavix execute [--latest]` | Execute saved prompts from fast/deep optimization. Interactive selection or `--latest` for most recent. |
-| `clavix prompts list` | View all saved prompts with status (NEW, EXECUTED, OLD, STALE) and storage statistics. |
-| `clavix prompts clear` | Manage prompt cleanup. Supports `--executed`, `--stale`, `--fast`, `--deep`, `--all` flags. |
-| `clavix prd` | Guided Socratic questions that generate `full-prd.md` and `quick-prd.md`. |
-| `clavix plan` | Transform PRDs or sessions into phase-based `tasks.md`. |
-| `clavix implement [--commit-strategy=<type>]` | Start task execution. Git strategies: per-task, per-5-tasks, per-phase, none (default: none). |
-| `clavix task-complete <taskId>` | Mark task as completed with validation and optional git commit. Auto-displays next task. |
-| `clavix start` | Begin conversational capture session for requirements gathering. |
-| `clavix summarize [session-id]` | Extract mini PRD and optimized prompts from saved sessions. |
-| `clavix list` | List sessions and/or output projects (`--sessions`, `--outputs`, filters). |
-| `clavix show [session-id]` | Inspect session details or use `--output <project>` to view outputs. |
-| `clavix archive [project]` | Archive completed projects or restore them (`--restore`). |
-| `clavix config [get|set|edit|reset]` | Manage `.clavix/config.json` preferences. |
-| `clavix update` | Refresh managed docs and slash commands (supports `--docs-only`, `--commands-only`). |
-| `clavix version` | Print installed version. |
-
-## Typical workflows
-- **Improve prompts quickly:** run `clavix fast` or `clavix deep` depending on complexity.
-- **Create strategy:** run `clavix prd` then `clavix plan` for an implementation checklist.
-- **Execute tasks:** use `clavix implement [--commit-strategy=<type>]`, commit work, repeat until tasks complete.
-- **Capture conversations:** record with `clavix start`, extract with `clavix summarize`.
-- **Stay organized:** inspect with `clavix list/show`, archive with `clavix archive`, refresh docs via `clavix update`.
-
-## Implementation with Git Strategy (Agent Workflow)
-
-When implementing tasks with `clavix implement`:
-
-1. **Check task count**: Read `tasks.md` and count phases
-2. **Ask user for git preferences** (optional, only if >3 phases):
-   ```
-   "I notice this implementation has [X] phases with [Y] tasks.
-
-   Git auto-commit preferences?
-   - per-task: Commit after each task (detailed history)
-   - per-5-tasks: Commit every 5 tasks (balanced)
-   - per-phase: Commit when phase completes (milestones)
-   - none: Manual git workflow (default)
-
-   I'll use 'none' if you don't specify."
-   ```
-
-3. **Run implement with strategy**:
-   ```bash
-   # With git strategy (if user specified):
-   clavix implement --commit-strategy=per-phase
-
-   # Or without (defaults to 'none' - manual commits):
-   clavix implement
-   ```
-
-4. **Default behavior**: If no `--commit-strategy` flag provided, defaults to `none` (manual commits)
-
-Artifacts are stored under `.clavix/`:
-- `.clavix/outputs/<project>/` for PRDs, tasks, prompts
-- `.clavix/sessions/` for captured conversations
-- `.clavix/templates/` for custom overrides
+|---------|---------|
+| `clavix init` | Interactive setup with integration selection |
+| `clavix fast "<prompt>"` | Quick optimization (CLI auto-saves; agent must save manually per template instructions) |
+| `clavix deep "<prompt>"` | Deep analysis (CLI auto-saves; agent must save manually per template instructions) |
+| `clavix execute [--latest]` | Execute saved prompts (interactive or --latest) |
+| `clavix prompts list` | View saved prompts with status (NEW, EXECUTED, OLD, STALE) |
+| `clavix prompts clear` | Manage cleanup (--executed, --stale, --fast, --deep, --all, --force) |
+| `clavix prd` | Guided PRD generation → `full-prd.md` + `quick-prd.md` |
+| `clavix plan` | Transform PRD → phase-based `tasks.md` |
+| `clavix implement [--commit-strategy=<type>]` | Execute tasks (git strategies: per-task, per-5-tasks, per-phase, none) |
+| `clavix start` | Begin conversational session |
+| `clavix summarize [session-id]` | Extract PRD from session |
+| `clavix list` | List sessions and outputs |
+| `clavix archive [project]` | Archive/restore completed projects |
+| `clavix update` | Refresh documentation |
+
+**Quick start:**
+```bash
+npm install -g clavix
+clavix init
+clavix version
+```
+
+---
+
+## 🔄 Standard Workflow
+
+**Clavix follows this progression:**
+
+```
+PRD Creation → Task Planning → Implementation → Archive
+```
+
+**Detailed steps:**
+
+1. **Planning Phase**
+   - Run: User uses conversational mode or direct PRD generation
+   - Output: `.clavix/outputs/{project}/full-prd.md` + `quick-prd.md`
+   - Mode: PLANNING
+
+2. **Task Preparation**
+   - Run: `clavix plan` transforms PRD into curated task list
+   - Output: `.clavix/outputs/{project}/tasks.md`
+   - Mode: PLANNING (Pre-Implementation)
+
+3. **Implementation Phase**
+   - Run: `clavix implement [--commit-strategy=<type>]`
+   - Agent executes tasks systematically
+   - Mode: IMPLEMENTATION
+   - Uses `clavix task-complete <taskId>` to mark progress
+
+4. **Completion**
+   - Run: `clavix archive [project]`
+   - Archives completed work
+   - Mode: Management
+
+**Key principle:** Planning workflows create documents. Implementation workflows write code.
+
+---
+
+## 💡 Best Practices for Generic Agents
+
+1. **Always reference instruction files** - Don't recreate workflow steps inline, point to `.clavix/instructions/workflows/`
+
+2. **Respect mode boundaries** - Planning mode = no code, Implementation mode = write code
+
+3. **Use checkpoints** - Follow the CHECKPOINT pattern from instruction files to track progress
+
+4. **Create files explicitly** - Use Write tool for every file, verify with ls, never skip file creation
+
+5. **Ask when unclear** - If mode is ambiguous, ask: "Should I implement or continue planning?"
+
+6. **Track complexity** - Use conversational mode for complex requirements (15+ exchanges, 5+ features, 3+ topics)
+
+7. **Label improvements** - When optimizing prompts, mark changes with [ADDED], [CLARIFIED], [STRUCTURED], [EXPANDED], [SCOPED]
+
+---
+
+## ⚠️ Common Mistakes
+
+### ❌ Jumping to implementation during planning
+**Wrong:** User discusses feature → agent generates code immediately
+
+**Right:** User discusses feature → agent asks questions → creates PRD/prompt → asks if ready to implement
+
+### ❌ Skipping file creation
+**Wrong:** Display content in chat, don't write files
+
+**Right:** Create directory → Write files → Verify existence → Display paths
+
+### ❌ Recreating workflow instructions inline
+**Wrong:** Copy entire fast mode workflow into response
+
+**Right:** Reference `.clavix/instructions/workflows/fast.md` and follow its steps
+
+### ❌ Not using instruction files
+**Wrong:** Make up workflow steps or guess at process
+
+**Right:** Read corresponding `.clavix/instructions/workflows/*.md` file and follow exactly
+
+---
+
+**Artifacts stored under `.clavix/`:**
+- `.clavix/outputs/<project>/` - PRDs, tasks, prompts
+- `.clavix/sessions/` - Captured conversations
+- `.clavix/templates/` - Custom overrides