clavix 6.0.0 → 6.1.1

package/README.md

@@ -1,6 +1,6 @@
 # Clavix
 
-> Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 21 AI coding tools.
+> Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, GitHub Copilot, and many AI coding tools.
 
 ## Quick Links
 
@@ -19,7 +19,7 @@
 | Tool Type | Format | Example |
 |-----------|--------|---------|
 | **CLI tools** (Claude Code, Gemini, Qwen) | Colon (`:`) | `/clavix:improve` |
-| **IDE extensions** (Cursor, Windsurf, Cline) | Hyphen (`-`) | `/clavix-improve` |
+| **IDEs & extensions** (Cursor, Windsurf, Cline, GitHub Copilot) | Hyphen (`-`) | `/clavix-improve` |
 
 **Rule of thumb:** CLI tools use colon, IDE extensions use hyphen.
 
@@ -32,13 +32,19 @@ npm install -g clavix
 clavix init
 ```
 
+During `clavix init`, pick your AI tools (Cursor, Claude Code, GitHub Copilot, etc.). Clavix installs slash command templates into those integrations.
+
 ### 2. Use Slash Commands
 
-```
+```text
+# CLI-style tools (Claude Code, Gemini, Qwen)
 /clavix:improve "Create a secure login page with JWT"
+
+# IDE-style tools (Cursor, Windsurf, GitHub Copilot, etc.)
+/clavix-improve "Create a secure login page with JWT"
 ```
 
-The AI agent reads the template and optimizes your prompt.
+The AI agent reads the Clavix template and optimizes your prompt.
 
 ### 3. Choose Your Workflow
 
@@ -79,7 +85,7 @@ Have a conversation to explore requirements, then extract and plan.
 ```
 Refine existing PRDs or prompts based on feedback.
 
-### All 9 Slash Commands
+### All 10 Slash Commands
 
 | Command | Purpose |
 |---------|---------|
@@ -91,21 +97,24 @@ Refine existing PRDs or prompts based on feedback.
 | `/clavix:summarize` | Extract requirements from conversation |
 | `/clavix:refine` | Refine existing PRD or prompt |
 | `/clavix:verify` | Verify implementation against requirements |
+| `/clavix:review` | Review teammate PRs using criteria presets |
 | `/clavix:archive` | Archive completed projects |
 
-See [Getting Started](docs/getting-started.md) for the full guide.
+`/clavix:review` is for reviewing teammates' PRs (criteria-driven, severity levels, saved reports), while `/clavix:verify` checks your implementation against your own PRD.
+
+For a full walkthrough, see [Getting Started](docs/getting-started.md).
 
 ## How It Works
 
 Clavix is **agentic-first**:
 
-1. **You run `clavix init`** - Sets up slash command templates
-2. **You invoke a slash command** - Like `/clavix:improve`
-3. **AI agent reads the template** - Markdown instructions
-4. **Agent follows instructions** - Using its native tools
-5. **Output is saved** - To `.clavix/outputs/`
+1. **You run `clavix init`** – Select integrations (Cursor, Claude Code, GitHub Copilot, etc.). Clavix installs markdown templates into each tool (e.g. `.cursor/commands/`, `.github/prompts/clavix-*.prompt.md`).
+2. **You invoke a slash command** – Like `/clavix:improve`, `/clavix:plan`, or `/clavix:review` in your AI tool.
+3. **The AI agent reads the template** – Structured markdown instructions with frontmatter.
+4. **The agent follows the instructions** – Using its native tools (edit files, run tests, summarize, review PRs, etc.).
+5. **Outputs are saved locally** – Under `.clavix/outputs/` (including `.clavix/outputs/reviews/` for PR review reports).
 
-**No TypeScript executes during slash commands.** The markdown templates ARE the product.
+**No TypeScript executes during slash commands.** The markdown templates ARE the product; Clavix only installs and updates them.
 
 See [Architecture](docs/architecture.md) for details.
 
@@ -113,9 +122,11 @@ See [Architecture](docs/architecture.md) for details.
 
 | Category | Tools |
 |----------|-------|
-| IDE extensions | Cursor, Windsurf, Kilocode, Roocode, Cline |
+| IDEs & extensions | Cursor, Windsurf, Kilocode, Roocode, Cline, GitHub Copilot (VS Code) |
 | CLI agents | Claude Code, Gemini CLI, Qwen Code, Droid CLI, CodeBuddy, OpenCode, LLXPRT, Amp, Crush CLI, Codex CLI, Augment CLI, Vibe CLI |
-| Universal | AGENTS.md, GitHub Copilot, OCTO.md, WARP.md |
+| Universal formats | AGENTS.md, OCTO.md, WARP.md |
+
+In GitHub Copilot Chat, Clavix commands appear as `/clavix-improve`, `/clavix-prd`, `/clavix-review`, etc.
 
 Full list: [docs/integrations.md](docs/integrations.md)
 
@@ -123,12 +134,12 @@ Full list: [docs/integrations.md](docs/integrations.md)
 
 | Command | Purpose |
 |---------|---------|
-| `clavix init` | Initialize Clavix in a project |
-| `clavix update` | Regenerate templates |
-| `clavix diagnose` | Check installation |
+| `clavix init` | Initialize or reconfigure Clavix integrations in a project |
+| `clavix update` | Regenerate templates for selected integrations |
+| `clavix diagnose` | Check installation and integration health |
 | `clavix version` | Show version |
 
-All workflows (`/clavix:improve`, etc.) are **slash commands** that AI agents execute.
+All workflows (`/clavix:improve`, `/clavix:plan`, `/clavix:review`, etc.) are **slash commands** that your AI tools execute using Clavix templates.
 
 ## Documentation
 
@@ -142,7 +153,7 @@ All workflows (`/clavix:improve`, etc.) are **slash commands** that AI agents ex
 
 - **Node.js >= 18.0.0**
 - npm or yarn
-- An AI coding tool (Claude Code, Cursor, etc.)
+- An AI coding tool (Claude Code, Cursor, GitHub Copilot, etc.)
 
 ## License
 

package/dist/cli/commands/init.js

@@ -10,7 +10,6 @@ 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';
 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';
@@ -278,12 +277,6 @@ export default class Init extends Command {
                     await AgentsMdGenerator.generate();
                     continue;
                 }
-                // Handle copilot-instructions separately (it's not an adapter)
-                if (integrationName === 'copilot-instructions') {
-                    this.log(chalk.gray('  ✓ Generating .github/copilot-instructions.md...'));
-                    await CopilotInstructionsGenerator.generate();
-                    continue;
-                }
                 // Handle octo-md separately (it's not an adapter)
                 if (integrationName === 'octo-md') {
                     this.log(chalk.gray('  ✓ Generating OCTO.md...'));
@@ -433,11 +426,6 @@ export default class Init extends Command {
                 await AgentsMdGenerator.generate();
                 continue;
             }
-            if (integrationName === 'copilot-instructions') {
-                this.log(chalk.gray('  ✓ Regenerating .github/copilot-instructions.md...'));
-                await CopilotInstructionsGenerator.generate();
-                continue;
-            }
             if (integrationName === 'octo-md') {
                 this.log(chalk.gray('  ✓ Regenerating OCTO.md...'));
                 await OctoMdGenerator.generate();

package/dist/cli/helpers/init/integrations.d.ts

@@ -5,7 +5,7 @@ import type { AgentManager } from '../../../core/agent-manager.js';
 /**
  * Doc generator integrations (not regular adapters)
  */
-export declare const DOC_GENERATOR_INTEGRATIONS: readonly ["agents-md", "octo-md", "warp-md", "copilot-instructions"];
+export declare const DOC_GENERATOR_INTEGRATIONS: readonly ["agents-md", "octo-md", "warp-md"];
 /**
  * Integrations that use colon separator (CLI tools)
  */

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

@@ -5,17 +5,11 @@ 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';
 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';
 /**
  * Doc generator integrations (not regular adapters)
  */
-export const DOC_GENERATOR_INTEGRATIONS = [
-    'agents-md',
-    'octo-md',
-    'warp-md',
-    'copilot-instructions',
-];
+export const DOC_GENERATOR_INTEGRATIONS = ['agents-md', 'octo-md', 'warp-md'];
 /**
  * Integrations that use colon separator (CLI tools)
  */
@@ -47,9 +41,6 @@ export async function generateDocGeneratorContent(integrationName) {
         case 'warp-md':
             await WarpMdGenerator.generate();
             break;
-        case 'copilot-instructions':
-            await CopilotInstructionsGenerator.generate();
-            break;
     }
 }
 /**
@@ -66,9 +57,6 @@ export async function cleanupDocGeneratorIntegration(integrationName) {
         case 'warp-md':
             await DocInjector.removeBlock('WARP.md');
             break;
-        case 'copilot-instructions':
-            await DocInjector.removeBlock('.github/copilot-instructions.md');
-            break;
     }
 }
 /**

package/dist/config/integrations.json

@@ -194,14 +194,15 @@
       "type": "universal"
     },
     {
-      "name": "copilot-instructions",
+      "name": "copilot",
       "displayName": "GitHub Copilot",
-      "directory": ".github",
-      "filenamePattern": "copilot-instructions",
-      "extension": ".md",
+      "directory": ".github/prompts",
+      "filenamePattern": "clavix-{name}",
+      "extension": ".prompt.md",
       "separator": "-",
       "detection": ".github",
-      "type": "universal"
+      "specialAdapter": "prompt-files",
+      "type": "standard"
     },
     {
       "name": "octo-md",

package/dist/core/adapters/copilot-prompts-adapter.d.ts

@@ -0,0 +1,64 @@
+import { BaseAdapter } from './base-adapter.js';
+import { CommandTemplate } from '../../types/agent.js';
+import { ClavixConfig } from '../../types/config.js';
+/**
+ * GitHub Copilot Prompts Adapter
+ *
+ * Generates custom slash commands as .prompt.md files in .github/prompts/
+ * These appear as /clavix-improve, /clavix-prd, etc. in VS Code with GitHub Copilot
+ *
+ * Format reference: https://code.visualstudio.com/docs/copilot/copilot-customization
+ *
+ * @since v6.1.0
+ */
+export declare class CopilotPromptsAdapter extends BaseAdapter {
+    readonly name = "copilot";
+    readonly displayName = "GitHub Copilot";
+    readonly directory = ".github/prompts";
+    readonly fileExtension = ".prompt.md";
+    readonly features: {
+        supportsSubdirectories: boolean;
+        commandFormat: {
+            separator: "-";
+        };
+    };
+    protected readonly userConfig?: ClavixConfig;
+    constructor(userConfig?: ClavixConfig);
+    /**
+     * Detect if GitHub Copilot is likely in use
+     * Check for .github directory (common for GitHub projects)
+     */
+    detectProject(): Promise<boolean>;
+    /**
+     * Get command path for Copilot prompts
+     */
+    getCommandPath(): string;
+    /**
+     * Get target filename for a command
+     * Format: clavix-{name}.prompt.md
+     */
+    getTargetFilename(name: string): string;
+    /**
+     * Determine if a file is a Clavix-generated prompt
+     */
+    protected isClavixGeneratedCommand(filename: string): boolean;
+    /**
+     * Format command content with Copilot prompt file frontmatter
+     *
+     * Copilot prompt files support YAML frontmatter with:
+     * - name: The slash command name (shown after /)
+     * - description: Short description shown in command picker
+     * - agent: Which agent to use (ask, edit, agent)
+     * - tools: List of available tools
+     */
+    protected formatCommand(template: CommandTemplate): string;
+    /**
+     * Generate YAML frontmatter for Copilot prompt file
+     */
+    private generateFrontmatter;
+    /**
+     * Generate commands with Copilot-specific formatting
+     */
+    generateCommands(templates: CommandTemplate[]): Promise<void>;
+}
+//# sourceMappingURL=copilot-prompts-adapter.d.ts.map

package/dist/core/adapters/copilot-prompts-adapter.js

@@ -0,0 +1,118 @@
+import * as path from 'path';
+import { BaseAdapter } from './base-adapter.js';
+import { FileSystem } from '../../utils/file-system.js';
+import { IntegrationError } from '../../types/errors.js';
+/**
+ * GitHub Copilot Prompts Adapter
+ *
+ * Generates custom slash commands as .prompt.md files in .github/prompts/
+ * These appear as /clavix-improve, /clavix-prd, etc. in VS Code with GitHub Copilot
+ *
+ * Format reference: https://code.visualstudio.com/docs/copilot/copilot-customization
+ *
+ * @since v6.1.0
+ */
+export class CopilotPromptsAdapter extends BaseAdapter {
+    name = 'copilot';
+    displayName = 'GitHub Copilot';
+    directory = '.github/prompts';
+    fileExtension = '.prompt.md';
+    features = {
+        supportsSubdirectories: false,
+        commandFormat: { separator: '-' },
+    };
+    userConfig;
+    constructor(userConfig) {
+        super();
+        this.userConfig = userConfig;
+    }
+    /**
+     * Detect if GitHub Copilot is likely in use
+     * Check for .github directory (common for GitHub projects)
+     */
+    async detectProject() {
+        return await FileSystem.exists('.github');
+    }
+    /**
+     * Get command path for Copilot prompts
+     */
+    getCommandPath() {
+        return this.directory;
+    }
+    /**
+     * Get target filename for a command
+     * Format: clavix-{name}.prompt.md
+     */
+    getTargetFilename(name) {
+        return `clavix-${name}${this.fileExtension}`;
+    }
+    /**
+     * Determine if a file is a Clavix-generated prompt
+     */
+    isClavixGeneratedCommand(filename) {
+        return filename.startsWith('clavix-') && filename.endsWith('.prompt.md');
+    }
+    /**
+     * Format command content with Copilot prompt file frontmatter
+     *
+     * Copilot prompt files support YAML frontmatter with:
+     * - name: The slash command name (shown after /)
+     * - description: Short description shown in command picker
+     * - agent: Which agent to use (ask, edit, agent)
+     * - tools: List of available tools
+     */
+    formatCommand(template) {
+        const frontmatter = this.generateFrontmatter(template);
+        return `${frontmatter}\n${template.content}`;
+    }
+    /**
+     * Generate YAML frontmatter for Copilot prompt file
+     */
+    generateFrontmatter(template) {
+        // Extract description from template frontmatter if present
+        const descMatch = template.content.match(/^---\s*\n[\s\S]*?description:\s*(.+)\n[\s\S]*?---/);
+        const description = descMatch ? descMatch[1].trim() : template.description;
+        // Map Clavix commands to appropriate Copilot agents
+        const agentMapping = {
+            improve: 'ask',
+            prd: 'ask',
+            start: 'ask',
+            summarize: 'ask',
+            refine: 'ask',
+            plan: 'ask',
+            review: 'ask',
+            verify: 'ask',
+            implement: 'agent',
+            archive: 'agent',
+        };
+        const agent = agentMapping[template.name] || 'ask';
+        // For implementation commands, include tools
+        const toolsLine = agent === 'agent' ? '\ntools:\n  - editFiles\n  - runCommands\n  - codebase' : '';
+        return `---
+name: clavix-${template.name}
+description: "${description.replace(/"/g, '\\"')}"
+agent: ${agent}${toolsLine}
+---`;
+    }
+    /**
+     * Generate commands with Copilot-specific formatting
+     */
+    async generateCommands(templates) {
+        const commandPath = this.getCommandPath();
+        try {
+            // Ensure directory exists
+            await FileSystem.ensureDir(commandPath);
+            // Generate each command file
+            for (const template of templates) {
+                const content = this.formatCommand(template);
+                const filename = this.getTargetFilename(template.name);
+                const filePath = path.join(commandPath, filename);
+                await FileSystem.writeFileAtomic(filePath, content);
+            }
+        }
+        catch (error) {
+            throw new IntegrationError(`Failed to generate ${this.displayName} commands: ${error}`, `Ensure ${commandPath} is writable`);
+        }
+    }
+}
+//# sourceMappingURL=copilot-prompts-adapter.js.map

package/dist/core/agent-manager.js

@@ -1,4 +1,5 @@
 import { ClaudeCodeAdapter } from './adapters/claude-code-adapter.js';
+import { CopilotPromptsAdapter } from './adapters/copilot-prompts-adapter.js';
 import { GeminiAdapter } from './adapters/gemini-adapter.js';
 import { QwenAdapter } from './adapters/qwen-adapter.js';
 import { LlxprtAdapter } from './adapters/llxprt-adapter.js';
@@ -21,6 +22,7 @@ export class AgentManager {
         this.userConfig = userConfig;
         // Register special adapters (require custom logic)
         this.registerAdapter(new ClaudeCodeAdapter(userConfig)); // Doc injection
+        this.registerAdapter(new CopilotPromptsAdapter(userConfig)); // Prompt files
         this.registerAdapter(new GeminiAdapter(userConfig)); // TOML format
         this.registerAdapter(new QwenAdapter(userConfig)); // TOML format
         this.registerAdapter(new LlxprtAdapter(userConfig)); // TOML format

package/dist/templates/agents/agents 2.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`