clavix 6.1.2 → 6.2.0

package/dist/cli/commands/init.js

@@ -16,6 +16,8 @@ import { DEFAULT_CONFIG } from '../../types/config.js';
 import { GeminiAdapter } from '../../core/adapters/gemini-adapter.js';
 import { QwenAdapter } from '../../core/adapters/qwen-adapter.js';
 import { loadCommandTemplates } from '../../utils/template-loader.js';
+import { loadSkillTemplates } from '../../utils/skill-template-loader.js';
+import { isAgentSkillsIntegration } from '../../utils/integration-selector.js';
 import { CLAVIX_BLOCK_START, CLAVIX_BLOCK_END } from '../../constants.js';
 import { validateUserConfig } from '../../utils/schemas.js';
 export default class Init extends Command {
@@ -288,6 +290,33 @@ export default class Init extends Command {
                     await WarpMdGenerator.generate();
                     continue;
                 }
+                // Handle Agent Skills integrations
+                if (isAgentSkillsIntegration(integrationName)) {
+                    const adapter = agentManager.requireAdapter(integrationName);
+                    const scope = integrationName === 'agent-skills-global' ? 'global' : 'project';
+                    const location = scope === 'global' ? '~/.config/agents/skills/' : '.skills/';
+                    this.log(chalk.gray(`  ✓ Generating ${adapter.displayName}...`));
+                    // Validate before generating
+                    if (adapter.validate) {
+                        const validation = await adapter.validate();
+                        if (validation.warnings?.length) {
+                            for (const warning of validation.warnings) {
+                                this.log(chalk.yellow(`    ⚠ ${warning}`));
+                            }
+                        }
+                    }
+                    // Remove existing skills
+                    const removed = await adapter.removeAllCommands();
+                    if (removed > 0) {
+                        this.log(chalk.gray(`    Removed ${removed} existing skill(s)`));
+                    }
+                    // Generate skills using skill templates
+                    const skillTemplates = await loadSkillTemplates();
+                    await adapter.generateCommands(skillTemplates);
+                    this.log(chalk.gray(`    Created ${skillTemplates.length} skills in ${location}`));
+                    this.log(chalk.gray('    Skills: clavix-improve, clavix-prd, clavix-plan, clavix-implement, ...'));
+                    continue;
+                }
                 let adapter = agentManager.requireAdapter(integrationName);
                 this.log(chalk.gray(`  ✓ Generating ${adapter.displayName} commands...`));
                 if (adapter.name === 'codex') {
@@ -436,6 +465,25 @@ export default class Init extends Command {
                 await WarpMdGenerator.generate();
                 continue;
             }
+            // Handle Agent Skills integrations
+            if (isAgentSkillsIntegration(integrationName)) {
+                const adapter = agentManager.getAdapter(integrationName);
+                if (!adapter) {
+                    this.log(chalk.yellow(`  ⚠ Unknown integration: ${integrationName}`));
+                    continue;
+                }
+                this.log(chalk.gray(`  ✓ Regenerating ${adapter.displayName}...`));
+                // Remove existing skills
+                const removed = await adapter.removeAllCommands();
+                if (removed > 0) {
+                    this.log(chalk.gray(`    Removed ${removed} existing skill(s)`));
+                }
+                // Generate skills using skill templates
+                const skillTemplates = await loadSkillTemplates();
+                await adapter.generateCommands(skillTemplates);
+                this.log(chalk.gray(`    Regenerated ${skillTemplates.length} skills`));
+                continue;
+            }
             // Handle regular adapters
             const adapter = agentManager.getAdapter(integrationName);
             if (!adapter) {

package/dist/core/adapters/agent-skills-adapter.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Agent Skills Adapter
+ *
+ * Generates Agent Skills (per agentskills.io specification) from Clavix templates.
+ * Skills are directory-based with SKILL.md + optional references/scripts/assets.
+ *
+ * Supports both global (~/.config/agents/skills) and project-level (.skills) installation.
+ *
+ * @since v6.2.0
+ */
+import { BaseAdapter } from './base-adapter.js';
+import { CommandTemplate, IntegrationFeatures } from '../../types/agent.js';
+import { SkillScope } from '../../types/skill.js';
+import { ClavixConfig } from '../../types/config.js';
+export declare class AgentSkillsAdapter extends BaseAdapter {
+    readonly name: string;
+    readonly displayName: string;
+    readonly fileExtension = ".md";
+    readonly features: IntegrationFeatures;
+    private scope;
+    private customPath?;
+    protected readonly userConfig?: ClavixConfig;
+    constructor(scope?: SkillScope, userConfig?: ClavixConfig);
+    /**
+     * Get the skill installation scope
+     */
+    get installScope(): SkillScope;
+    /**
+     * Get the directory path based on scope
+     */
+    get directory(): string;
+    /**
+     * Expand tilde in path to home directory
+     */
+    private expandPath;
+    /**
+     * Get full path to skills directory
+     */
+    getCommandPath(): string;
+    /**
+     * Skills use directory names, not filenames
+     * Returns the skill directory name (e.g., 'clavix-improve')
+     */
+    getTargetFilename(name: string): string;
+    /**
+     * Detect if skills environment is available
+     * For global: check if ~/.config/agents/skills directory exists
+     * For project: check if .skills directory exists
+     */
+    detectProject(): Promise<boolean>;
+    /**
+     * Generate skills from command templates
+     * Creates directory structure per agentskills.io spec:
+     *   <skill-name>/
+     *   ├── SKILL.md
+     *   └── references/
+     *       └── <reference-files>.md
+     */
+    generateCommands(templates: CommandTemplate[]): Promise<void>;
+    /**
+     * Generate a single skill directory from a command template
+     */
+    private generateSkill;
+    /**
+     * Format template content as SKILL.md with proper frontmatter
+     */
+    private formatSkillContent;
+    /**
+     * Generate skill description optimized for agent discovery
+     * Descriptions should explain what the skill does AND when to use it
+     */
+    private generateSkillDescription;
+    /**
+     * Remove all Clavix-generated skills
+     * Skills are directories matching 'clavix-*' pattern
+     */
+    removeAllCommands(): Promise<number>;
+    /**
+     * Determine if an entry is a Clavix-generated skill
+     * Skills are directories starting with 'clavix-'
+     */
+    protected isClavixGeneratedCommand(name: string): boolean;
+    /**
+     * Validate skills directory
+     */
+    validate(): Promise<{
+        valid: boolean;
+        errors?: string[];
+        warnings?: string[];
+    }>;
+}
+/**
+ * Factory function to create adapter with scope
+ */
+export declare function createAgentSkillsAdapter(scope: SkillScope, userConfig?: ClavixConfig): AgentSkillsAdapter;
+//# sourceMappingURL=agent-skills-adapter.d.ts.map

package/dist/core/adapters/agent-skills-adapter.js

@@ -0,0 +1,235 @@
+/**
+ * Agent Skills Adapter
+ *
+ * Generates Agent Skills (per agentskills.io specification) from Clavix templates.
+ * Skills are directory-based with SKILL.md + optional references/scripts/assets.
+ *
+ * Supports both global (~/.config/agents/skills) and project-level (.skills) installation.
+ *
+ * @since v6.2.0
+ */
+import * as path from 'path';
+import * as os from 'os';
+import { BaseAdapter } from './base-adapter.js';
+import { SKILL_PATHS } from '../../types/skill.js';
+import { FileSystem } from '../../utils/file-system.js';
+import { IntegrationError } from '../../types/errors.js';
+import { logger } from '../../utils/logger.js';
+export class AgentSkillsAdapter extends BaseAdapter {
+    name;
+    displayName;
+    fileExtension = '.md';
+    features = {
+        supportsSubdirectories: true,
+        commandFormat: { separator: '-' },
+    };
+    scope;
+    customPath;
+    userConfig;
+    constructor(scope = 'global', userConfig) {
+        super();
+        this.scope = scope;
+        this.userConfig = userConfig;
+        // Set name and displayName based on scope
+        this.name = scope === 'global' ? 'agent-skills-global' : 'agent-skills-project';
+        this.displayName = scope === 'global' ? 'Agent Skills (Global)' : 'Agent Skills (Project)';
+        // Check for custom path in user config
+        const configKey = scope === 'global' ? 'agent-skills-global' : 'agent-skills-project';
+        if (userConfig?.experimental?.integrationPaths?.[configKey]) {
+            this.customPath = userConfig.experimental.integrationPaths[configKey];
+        }
+    }
+    /**
+     * Get the skill installation scope
+     */
+    get installScope() {
+        return this.scope;
+    }
+    /**
+     * Get the directory path based on scope
+     */
+    get directory() {
+        if (this.customPath) {
+            return this.customPath;
+        }
+        return this.scope === 'global' ? SKILL_PATHS.global : SKILL_PATHS.project;
+    }
+    /**
+     * Expand tilde in path to home directory
+     */
+    expandPath(p) {
+        if (p.startsWith('~/')) {
+            return path.join(os.homedir(), p.slice(2));
+        }
+        return p;
+    }
+    /**
+     * Get full path to skills directory
+     */
+    getCommandPath() {
+        const dir = this.directory;
+        if (dir.startsWith('~/') || this.scope === 'global') {
+            return this.expandPath(dir);
+        }
+        return path.join(process.cwd(), dir);
+    }
+    /**
+     * Skills use directory names, not filenames
+     * Returns the skill directory name (e.g., 'clavix-improve')
+     */
+    getTargetFilename(name) {
+        return `clavix-${name}`;
+    }
+    /**
+     * Detect if skills environment is available
+     * For global: check if ~/.config/agents/skills directory exists
+     * For project: check if .skills directory exists
+     */
+    async detectProject() {
+        const skillsPath = this.getCommandPath();
+        // Check if the skills directory itself exists (not parent)
+        return FileSystem.exists(skillsPath);
+    }
+    /**
+     * Generate skills from command templates
+     * Creates directory structure per agentskills.io spec:
+     *   <skill-name>/
+     *   ├── SKILL.md
+     *   └── references/
+     *       └── <reference-files>.md
+     */
+    async generateCommands(templates) {
+        const skillsPath = this.getCommandPath();
+        try {
+            // Ensure base directory exists
+            await FileSystem.ensureDir(skillsPath);
+            // Convert command templates to skill format and generate
+            for (const template of templates) {
+                await this.generateSkill(template, skillsPath);
+            }
+        }
+        catch (error) {
+            throw new IntegrationError(`Failed to generate Agent Skills: ${error}`, `Ensure ${skillsPath} is writable`);
+        }
+    }
+    /**
+     * Generate a single skill directory from a command template
+     */
+    async generateSkill(template, basePath) {
+        const skillName = `clavix-${template.name}`;
+        const skillDir = path.join(basePath, skillName);
+        // Ensure skill directory exists
+        await FileSystem.ensureDir(skillDir);
+        // Generate SKILL.md with proper frontmatter
+        const skillContent = this.formatSkillContent(template, skillName);
+        await FileSystem.writeFileAtomic(path.join(skillDir, 'SKILL.md'), skillContent);
+        // Note: References are embedded in the skill template itself
+        // The skill templates are pre-assembled with all content
+    }
+    /**
+     * Format template content as SKILL.md with proper frontmatter
+     */
+    formatSkillContent(template, skillName) {
+        // Create description optimized for skill discovery
+        const description = this.generateSkillDescription(template.name, template.description);
+        // Build frontmatter per agentskills.io spec
+        const frontmatter = [
+            '---',
+            `name: ${skillName}`,
+            `description: ${description}`,
+            'license: Apache-2.0',
+            '---',
+            '',
+        ].join('\n');
+        return frontmatter + template.content;
+    }
+    /**
+     * Generate skill description optimized for agent discovery
+     * Descriptions should explain what the skill does AND when to use it
+     */
+    generateSkillDescription(name, baseDescription) {
+        const descriptionMap = {
+            improve: 'Analyze and optimize prompts using 6-dimension quality assessment (Clarity, Efficiency, Structure, Completeness, Actionability, Specificity). Use when you need to improve a prompt before implementation.',
+            prd: 'Create comprehensive Product Requirements Documents through strategic questioning. Use when planning a new feature or project that needs clear requirements.',
+            plan: 'Transform PRD documents into actionable task breakdowns with dependencies. Use after creating a PRD to generate implementation tasks.',
+            implement: 'Execute implementation tasks or saved prompts with progress tracking. Use when ready to build what was planned in PRD or improved prompts.',
+            start: 'Begin conversational exploration to discover requirements through natural discussion. Use when ideas are vague and need refinement through dialogue.',
+            summarize: 'Extract structured requirements from conversations into mini-PRD format. Use after conversational exploration to capture what was discussed.',
+            refine: 'Iterate on existing PRDs or improved prompts to enhance quality. Use when you have a draft that needs further refinement.',
+            verify: 'Verify implementation against PRD requirements with systematic checking. Use after implementation to validate completeness.',
+            review: 'Review code changes with criteria-driven analysis (Security, Architecture, Standards, Performance). Use when reviewing PRs or code changes.',
+            archive: 'Archive completed projects by moving outputs to archive directory. Use when a project is complete and ready for archival.',
+        };
+        return descriptionMap[name] || baseDescription;
+    }
+    /**
+     * Remove all Clavix-generated skills
+     * Skills are directories matching 'clavix-*' pattern
+     */
+    async removeAllCommands() {
+        const skillsPath = this.getCommandPath();
+        // If directory doesn't exist, nothing to remove
+        if (!(await FileSystem.exists(skillsPath))) {
+            return 0;
+        }
+        const entries = await FileSystem.listFiles(skillsPath);
+        const clavixSkills = entries.filter((entry) => this.isClavixGeneratedCommand(entry));
+        let removed = 0;
+        for (const skillName of clavixSkills) {
+            const skillDir = path.join(skillsPath, skillName);
+            try {
+                // Remove entire skill directory
+                await FileSystem.remove(skillDir);
+                removed++;
+            }
+            catch (error) {
+                logger.warn(`Failed to remove skill ${skillDir}: ${error}`);
+            }
+        }
+        return removed;
+    }
+    /**
+     * Determine if an entry is a Clavix-generated skill
+     * Skills are directories starting with 'clavix-'
+     */
+    isClavixGeneratedCommand(name) {
+        return name.startsWith('clavix-');
+    }
+    /**
+     * Validate skills directory
+     */
+    async validate() {
+        const errors = [];
+        const warnings = [];
+        const skillsPath = this.getCommandPath();
+        const parentDir = path.dirname(skillsPath);
+        // Check if parent directory exists
+        if (!(await FileSystem.exists(parentDir))) {
+            if (this.scope === 'global') {
+                warnings.push(`Global skills directory ${parentDir} will be created`);
+            }
+            else {
+                warnings.push(`Project skills directory will be created`);
+            }
+        }
+        // Try to ensure directory exists
+        try {
+            await FileSystem.ensureDir(skillsPath);
+        }
+        catch (error) {
+            errors.push(`Cannot create skills directory: ${error}`);
+        }
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            warnings: warnings.length > 0 ? warnings : undefined,
+        };
+    }
+}
+/**
+ * Factory function to create adapter with scope
+ */
+export function createAgentSkillsAdapter(scope, userConfig) {
+    return new AgentSkillsAdapter(scope, userConfig);
+}
+//# sourceMappingURL=agent-skills-adapter.js.map

package/dist/core/adapters/universal-adapter.d.ts

@@ -48,5 +48,15 @@ export declare class UniversalAdapter extends BaseAdapter {
      * Check if this adapter supports subdirectories
      */
     supportsSubdirectories(): boolean;
+    /**
+     * Determine if a file is a Clavix-generated command
+     *
+     * Uses the filenamePattern from config to identify Clavix files.
+     * This prevents removal of user's existing command files.
+     *
+     * For pattern 'clavix-{name}' → matches 'clavix-*.md'
+     * For pattern '{name}' → matches '*.md' (all files with extension)
+     */
+    protected isClavixGeneratedCommand(filename: string): boolean;
 }
 //# sourceMappingURL=universal-adapter.d.ts.map

package/dist/core/adapters/universal-adapter.js

@@ -100,5 +100,31 @@ export class UniversalAdapter extends BaseAdapter {
     supportsSubdirectories() {
         return this.config.features.supportsSubdirectories;
     }
+    /**
+     * Determine if a file is a Clavix-generated command
+     *
+     * Uses the filenamePattern from config to identify Clavix files.
+     * This prevents removal of user's existing command files.
+     *
+     * For pattern 'clavix-{name}' → matches 'clavix-*.md'
+     * For pattern '{name}' → matches '*.md' (all files with extension)
+     */
+    isClavixGeneratedCommand(filename) {
+        // Must match our file extension
+        if (!filename.endsWith(this.config.fileExtension)) {
+            return false;
+        }
+        // Extract prefix from pattern (everything before {name})
+        const pattern = this.config.filenamePattern;
+        const prefixEnd = pattern.indexOf('{name}');
+        if (prefixEnd > 0) {
+            // Pattern has a prefix (e.g., 'clavix-{name}')
+            const prefix = pattern.substring(0, prefixEnd);
+            return filename.startsWith(prefix);
+        }
+        // Pattern is just '{name}' - this adapter owns all files in its directory
+        // This is safe for adapters like Claude Code that use dedicated subdirectories
+        return true;
+    }
 }
 //# sourceMappingURL=universal-adapter.js.map

package/dist/core/agent-manager.js

@@ -4,6 +4,7 @@ import { GeminiAdapter } from './adapters/gemini-adapter.js';
 import { QwenAdapter } from './adapters/qwen-adapter.js';
 import { LlxprtAdapter } from './adapters/llxprt-adapter.js';
 import { VibeAdapter } from './adapters/vibe-adapter.js';
+import { AgentSkillsAdapter } from './adapters/agent-skills-adapter.js';
 import { UniversalAdapter } from './adapters/universal-adapter.js';
 import { getSimpleAdapters } from './adapter-registry.js';
 import { IntegrationError } from '../types/errors.js';
@@ -27,6 +28,9 @@ export class AgentManager {
         this.registerAdapter(new QwenAdapter(userConfig)); // TOML format
         this.registerAdapter(new LlxprtAdapter(userConfig)); // TOML format
         this.registerAdapter(new VibeAdapter(userConfig)); // Vibe CLI skills
+        // Register Agent Skills adapters (both global and project scope)
+        this.registerAdapter(new AgentSkillsAdapter('global', userConfig));
+        this.registerAdapter(new AgentSkillsAdapter('project', userConfig));
         // Register simple adapters from config (using UniversalAdapter factory)
         for (const config of getSimpleAdapters()) {
             // Skip adapters that have special handlers registered above

package/dist/templates/agents/agents 5.md

@@ -0,0 +1,200 @@
+# Clavix Instructions for Generic Agents
+
+This guide is for agents that can only read documentation (no slash-command support). If your platform supports custom slash commands, use those instead.
+
+---
+
+## ⛔ CLAVIX MODE ENFORCEMENT
+
+**CRITICAL: Know which mode you're in and STOP at the right point.**
+
+**OPTIMIZATION workflows** (NO CODE ALLOWED):
+- Improve mode - Prompt optimization only (auto-selects depth)
+- Your role: Analyze, optimize, show improved prompt, **STOP**
+- ❌ DO NOT implement the prompt's requirements
+- ✅ After showing optimized prompt, tell user: "Run `/clavix:implement --latest` to implement"
+
+**PLANNING workflows** (NO CODE ALLOWED):
+- Conversational mode, requirement extraction, PRD generation
+- Your role: Ask questions, create PRDs/prompts, extract requirements
+- ❌ DO NOT implement features during these workflows
+
+**IMPLEMENTATION workflows** (CODE ALLOWED):
+- Only after user runs execute/implement commands
+- Your role: Write code, execute tasks, implement features
+- ✅ DO implement code during these workflows
+
+**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 |
+| **Prompt Optimization** | `workflows/improve.md` | Intent detection + quality assessment + auto-depth selection |
+| **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 |
+| **Verification** | `core/verification.md` | Post-implementation verification |
+
+**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" | Improve mode → Auto-depth optimization | `workflows/improve.md` |
+| "analyze thoroughly", "edge cases", "alternatives" | Improve mode (--comprehensive) | `workflows/improve.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` |
+| "refine", "update PRD", "change requirements", "modify prompt" | Refine mode → Update existing content | `workflows/refine.md` |
+| "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
+
+**When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
+
+---
+
+## 📋 Clavix Commands (v5)
+
+### Setup Commands (CLI)
+| Command | Purpose |
+|---------|---------|
+| `clavix init` | Initialize Clavix in a project |
+| `clavix update` | Update templates after package update |
+| `clavix diagnose` | Check installation health |
+| `clavix version` | Show version |
+
+### 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) |
+| `/clavix:prd` | Generate PRD through guided questions |
+| `/clavix:plan` | Create task breakdown from PRD |
+| `/clavix:implement` | Execute tasks or prompts (auto-detects source) |
+| `/clavix:start` | Begin conversational session |
+| `/clavix:summarize` | Extract requirements from conversation |
+| `/clavix:refine` | Refine existing PRD or saved prompt |
+
+### Agentic Utilities (Project Management)
+These utilities provide structured workflows for project completion:
+
+| Utility | Purpose |
+|---------|---------|
+| `/clavix:verify` | Check implementation against PRD requirements, run validation |
+| `/clavix:archive` | Archive completed work to `.clavix/archive/` for reference |
+
+**Quick start:**
+```bash
+npm install -g clavix
+clavix init
+```
+
+**How it works:** Slash commands are markdown templates. When invoked, the agent reads the template and follows its instructions using native tools (Read, Write, Edit, Bash).
+
+---
+
+## 🔄 Standard Workflow
+
+**Clavix follows this progression:**
+
+```
+PRD Creation → Task Planning → Implementation → Archive
+```
+
+**Detailed steps:**
+
+1. **Planning Phase**
+   - Run: `/clavix:prd` or `/clavix:start` → `/clavix:summarize`
+   - 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`
+   - Agent executes tasks systematically
+   - Mode: IMPLEMENTATION
+   - Agent edits tasks.md directly to mark progress (`- [ ]` → `- [x]`)
+
+4. **Completion**
+   - Run: `/clavix:archive`
+   - 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/improve.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/templates/` - Custom overrides
+
+---
+
+**For complete workflows:** Always reference `.clavix/instructions/workflows/{workflow}.md`
+
+**For troubleshooting:** Check `.clavix/instructions/troubleshooting/`
+
+**For mode clarification:** See `.clavix/instructions/core/clavix-mode.md`