clavix 5.10.3 → 6.1.0

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`