clavix 5.5.0 → 5.5.1

package/README.md

@@ -1,64 +1,27 @@
 # 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 19+ other AI coding tools.
-
-## Table of contents
-- [Why Clavix?](#why-clavix)
-- [How It Works](#how-it-works)
-- [Supported AI Tools](#supported-ai-tools)
-- [Quickstart](#quickstart)
-- [Full documentation](#full-documentation)
-
-## Release Notes
-
-| Version | Highlights | Details |
-| --- | --- | --- |
-| **v5.5.0** (Latest) | Architecture cleanup, consolidated adapters, documentation overhaul | [Changelog](CHANGELOG.md) |
-| **v5.0.0** | Agentic-first architecture - lean template delivery | [Changelog](CHANGELOG.md#500---2025-01-27) |
-
-**Requirements:** Node.js >= 18.0.0
-
-## Why Clavix?
-
-Better prompts lead to better code. Clavix provides **markdown templates** that teach AI agents how to:
-- **Optimize prompts** - Transform rough ideas into structured, AI-ready prompts
-- **Create PRDs** - Generate comprehensive requirements documents through guided questions
-- **Plan implementations** - Break down PRDs into phased task lists
-- **Track progress** - Manage task completion with optional git commits
-
-**No framework to learn.** Just describe what you want, and your AI agent follows the Clavix templates to structure it properly.
-
-Learn more in [docs/why-clavix.md](docs/why-clavix.md).
 
-## How It Works
+> 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 19+ other AI coding tools.
 
-Clavix v5 follows an **agentic-first architecture**:
+## Quick Links
 
-1. **You run `clavix init`** - Sets up `.clavix/` directory with slash command templates
-2. **You invoke a slash command** - Like `/clavix:improve` in Claude Code or Cursor
-3. **Your AI agent reads the template** - The markdown file contains all instructions
-4. **The agent follows the instructions** - Using its native tools (Write, Read, Edit, etc.)
-5. **Output is saved** - To `.clavix/outputs/` for future reference
+| I want to... | Go to |
+|--------------|-------|
+| Get started | [Quickstart](#quickstart) |
+| See all commands | [docs/commands.md](docs/commands.md) |
+| Understand the architecture | [docs/architecture.md](docs/architecture.md) |
+| Check integrations | [docs/integrations.md](docs/integrations.md) |
+| Contribute | [CONTRIBUTING.md](CONTRIBUTING.md) |
 
-**No TypeScript code executes during slash command usage.** The templates are the product - they instruct AI agents on what to do.
+## Command Format
 
-## Supported AI Tools
+**Your command format depends on your AI tool:**
 
-| Category | Tools |
-| --- | --- |
-| IDE extensions | Cursor, Windsurf, Kilocode, Roocode, Cline |
-| CLI agents | Claude Code, Droid CLI, CodeBuddy CLI, OpenCode, Gemini CLI, Qwen Code, LLXPRT, Amp, Crush CLI, Codex CLI, Augment CLI |
-| Universal adapters | AGENTS.md, GitHub Copilot, OCTO.md, WARP.md |
+| Tool Type | Format | Example |
+|-----------|--------|---------|
+| **CLI tools** (Claude Code, Gemini, Qwen) | Colon (`:`) | `/clavix:improve` |
+| **IDE extensions** (Cursor, Windsurf, Cline) | Hyphen (`-`) | `/clavix-improve` |
 
-### Feature Matrix
-
-| Feature | Claude Code | Cursor/Windsurf | Gemini/Qwen | Generic Agents |
-|---------|-------------|-----------------|-------------|----------------|
-| Slash commands | ✅ Native | ✅ Native | ✅ TOML | ❌ Read-only |
-| Doc injection | ✅ CLAUDE.md | ✅ .cursor/rules | ✅ N/A | ✅ AGENTS.md |
-| Namespace dirs | ✅ clavix/ | ✅ clavix/ | ✅ clavix/ | N/A |
-| Auto-detection | ✅ Yes | ✅ Yes | ✅ Yes | N/A |
-
-Full list and configuration: [docs/integrations.md](docs/integrations.md)
+**Rule of thumb:** CLI tools use colon, IDE extensions use hyphen.
 
 ## Quickstart
 
@@ -69,80 +32,76 @@ npm install -g clavix
 clavix init
 ```
 
-This creates `.clavix/` with slash command templates and injects documentation into your CLAUDE.md (or equivalent).
-
 ### 2. Use Slash Commands
 
-In your AI coding assistant (Claude Code, Cursor, etc.):
-
 ```
 /clavix:improve "Create a secure login page with JWT"
 ```
 
-The AI agent reads the improve template and:
-- Analyzes your prompt for quality
-- Applies optimization patterns
-- Saves the improved version to `.clavix/outputs/prompts/`
+The AI agent reads the template and optimizes your prompt.
 
 ### 3. Choose Your Workflow
 
-**Core Workflows:**
 | Command | When to Use |
 |---------|-------------|
-| `/clavix:improve` | Optimize a single prompt (auto-selects depth) |
+| `/clavix:improve` | Optimize a single prompt |
 | `/clavix:prd` | Plan something new with guided questions |
-| `/clavix:start` | Explore ideas conversationally first |
 | `/clavix:plan` | Generate tasks from a PRD |
 | `/clavix:implement` | Execute tasks with progress tracking |
-| `/clavix:summarize` | Extract requirements from conversation |
 
-**Project Management:**
-| Utility | Purpose |
-|---------|---------|
-| `/clavix:verify` | Check implementation against PRD requirements |
-| `/clavix:archive` | Archive completed projects to `.clavix/archive/` |
+See [Getting Started](docs/getting-started.md) for the full guide.
 
-See [Choosing the Right Workflow](docs/guides/choosing-workflow.md) for detailed guidance.
+## How It Works
 
-### 4. Keep Templates Updated
+Clavix is **agentic-first**:
 
-```bash
-clavix update   # After npm update clavix
-```
+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/`
 
-## CLI Commands
+**No TypeScript executes during slash commands.** The markdown templates ARE the product.
 
-Clavix v5 has 4 CLI commands (for setup and diagnostics, not workflows):
+See [Architecture](docs/architecture.md) for details.
+
+## Supported AI Tools
+
+| Category | Tools |
+|----------|-------|
+| IDE extensions | Cursor, Windsurf, Kilocode, Roocode, Cline |
+| CLI agents | Claude Code, Gemini CLI, Qwen Code, Droid CLI, CodeBuddy, OpenCode, LLXPRT, Amp, Crush CLI, Codex CLI, Augment CLI |
+| Universal | AGENTS.md, GitHub Copilot, OCTO.md, WARP.md |
+
+Full list: [docs/integrations.md](docs/integrations.md)
+
+## CLI Commands
 
 | Command | Purpose |
 |---------|---------|
-| `clavix init` | Initialize or reconfigure Clavix in a project |
-| `clavix update` | Update templates after package update |
-| `clavix diagnose` | Check installation and report issues |
+| `clavix init` | Initialize Clavix in a project |
+| `clavix update` | Regenerate templates |
+| `clavix diagnose` | Check installation |
 | `clavix version` | Show version |
 
-**All workflows** (`/clavix:improve`, `/clavix:prd`, etc.) are **slash commands** that AI agents execute by reading markdown templates.
+All workflows (`/clavix:improve`, etc.) are **slash commands** that AI agents execute.
 
-## Full documentation
-- Overview & navigation: [docs/README.md](docs/README.md)
-- Integrations: [docs/integrations.md](docs/integrations.md)
-- How it works: [docs/how-it-works.md](docs/how-it-works.md)
-- Philosophy: [docs/philosophy.md](docs/philosophy.md)
+## Documentation
 
-## Requirements
+- [Getting Started](docs/getting-started.md) - Installation and first workflow
+- [Commands Reference](docs/commands.md) - All commands in one place
+- [Architecture](docs/architecture.md) - How Clavix works
+- [Integrations](docs/integrations.md) - Full tool matrix
+- [CONTRIBUTING.md](CONTRIBUTING.md) - Contribute to Clavix
 
-### For End Users
-- **Node.js >= 18.0.0**
-- npm or yarn package manager
-- An AI coding assistant (Claude Code, Cursor, Windsurf, etc.)
+## Requirements
 
-### For Contributors
 - **Node.js >= 18.0.0**
-- Run tests: `npm test`
-- Lint: `npm run lint`
-- Build: `npm run build`
+- npm or yarn
+- An AI coding tool (Claude Code, Cursor, etc.)
 
 ## License
+
 Apache-2.0
 
 ## Star History

package/dist/cli/commands/init.js

@@ -272,18 +272,30 @@ export default class Init extends Command {
                 await InstructionsGenerator.generate();
                 console.log(chalk.gray('  ✓ Created detailed workflow guides for generic integrations'));
             }
-            // Success message
-            // v4.11: Use generic command names - format varies by integration
-            // (claude-code uses colon like /clavix:improve, droid uses hyphen like /clavix-improve)
+            // Success message with prominent command format display
             console.log(chalk.bold.green('\n✅ Clavix initialized successfully!\n'));
-            console.log(chalk.gray('Next steps:'));
+            // Determine the primary command format based on selected integrations
+            const colonTools = ['claude-code', 'gemini', 'qwen', 'crush', 'llxprt', 'augment'];
+            const usesColon = selectedIntegrations.some((i) => colonTools.includes(i));
+            const usesHyphen = selectedIntegrations.some((i) => !colonTools.includes(i));
+            const separator = usesColon && !usesHyphen ? ':' : usesHyphen && !usesColon ? '-' : ':';
+            const altSeparator = separator === ':' ? '-' : ':';
+            // Show command format prominently at the TOP
+            console.log(chalk.bold('📋 Your command format:'), chalk.bold.cyan(`/clavix${separator}improve`));
+            if (usesColon && usesHyphen) {
+                console.log(chalk.gray('   (Some integrations use'), chalk.cyan(`/clavix${altSeparator}improve`), chalk.gray('instead)'));
+            }
+            console.log();
+            // Available commands
+            console.log(chalk.gray('Available slash commands:'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}improve`), chalk.gray('- Smart prompt optimization'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}prd`), chalk.gray('- Generate PRD through guided questions'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}plan`), chalk.gray('- Create task breakdown from PRD'));
+            console.log(chalk.gray('  •'), chalk.cyan(`/clavix${separator}implement`), chalk.gray('- Execute tasks or prompts'));
+            console.log(chalk.gray('\nNext steps:'));
             console.log(chalk.gray('  • Slash commands are now available in your AI agent'));
-            console.log(chalk.gray('  • Run'), chalk.cyan('clavix --help'), chalk.gray('to see all CLI commands'));
-            console.log(chalk.gray('  • Available slash commands:'));
-            console.log(chalk.gray('    ◦'), chalk.cyan('improve'), chalk.gray('- Smart prompt optimization with auto depth selection'));
-            console.log(chalk.gray('    ◦'), chalk.cyan('prd'), chalk.gray('- Generate PRD through guided questions'));
-            console.log(chalk.gray('    ◦'), chalk.cyan('execute'), chalk.gray('- Run saved prompts'));
-            console.log(chalk.gray('\n  Command format varies by integration (colon vs hyphen)\n'));
+            console.log(chalk.gray('  • Run'), chalk.cyan('clavix diagnose'), chalk.gray('to verify installation'));
+            console.log();
         }
         catch (error) {
             const { getErrorMessage, toError } = await import('../../utils/error-utils.js');
@@ -378,6 +390,17 @@ export default class Init extends Command {
 
 Welcome to Clavix! This directory contains your local Clavix configuration and data.
 
+## Command Format
+
+**Your command format depends on your AI tool:**
+
+| Tool Type | Format | Example |
+|-----------|--------|---------|
+| **CLI tools** (Claude Code, Gemini, Qwen) | Colon (\`:\`) | \`/clavix:improve\` |
+| **IDE extensions** (Cursor, Windsurf, Cline) | Hyphen (\`-\`) | \`/clavix-improve\` |
+
+**Rule of thumb:** CLI tools use colon, IDE extensions use hyphen.
+
 ## Directory Structure
 
 \`\`\`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clavix",
-  "version": "5.5.0",
+  "version": "5.5.1",
   "description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation.\n\nSLASH COMMANDS (in your AI assistant):\n  /clavix:improve    Optimize prompts with auto-depth\n  /clavix:prd        Generate PRD through questions\n  /clavix:plan       Create task breakdown from PRD\n  /clavix:implement  Execute tasks with progress tracking\n  /clavix:start      Begin conversational session\n  /clavix:summarize  Extract requirements from conversation\n\nWorks with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
   "type": "module",
   "main": "dist/index.js",