clavix 4.12.0 → 5.0.1

package/README.md

@@ -1,10 +1,10 @@
 # Clavix
-> Prompt optimization for AI coding. Transform rough ideas into structured, actionable prompts using pattern-based analysis—no framework to learn.
+> 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)
-- [Providers](#providers)
+- [Supported AI Tools](#supported-ai-tools)
 - [Quickstart](#quickstart)
 - [Full documentation](#full-documentation)
 
@@ -12,109 +12,117 @@
 
 | Version | Highlights | Details |
 | --- | --- | --- |
-| **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) |
+| **v5.0.0** (Latest) | Agentic-first architecture - lean template delivery | [Changelog](CHANGELOG.md#500---2025-01-27) |
+| **v4.12.0** | Final v4 release with full CLI commands | [Changelog](docs/archive/v4-changelog.md) |
 
-**Requirements:** Node.js ≥ 16.0.0 (ESM support required)
+**Requirements:** Node.js >= 18.0.0
 
 ## Why Clavix?
-Better prompts lead to better code. Clavix analyzes what you're trying to do and applies structured optimization patterns—no framework to learn, no methodology to master. Just describe what you want, and Clavix structures it for AI consumption.
 
-**What Clavix provides:**
-- **Pattern-based intent detection** - Weighted keyword scoring across 11 intent categories
-- **20 optimization patterns** - Automatically applied based on intent and quality assessment
-- **Workflow management** - PRD generation, task breakdown, and implementation tracking
-- **Universal integration** - Supports 20+ AI coding assistants with native slash commands
+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
-Clavix uses pattern-based analysis to:
-- **Detect intent** - Keyword scoring and phrase detection across 11 intent categories
-- **Assess quality** - Heuristic scoring across 6 dimensions: Clarity, Efficiency, Structure, Completeness, Actionability, Specificity
-- **Apply patterns** - 20 optimization patterns automatically selected based on intent and quality
-- **Generate output** - Structured prompts optimized for AI coding assistants
 
-Optimization applies automatically—no frameworks to learn, no manual analysis required. Just describe what you want in plain language, and Clavix structures it into an AI-ready prompt.
+Clavix v5 follows an **agentic-first architecture**:
+
+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
 
-See [docs/philosophy.md](docs/philosophy.md) for an honest look at what Clavix is and isn't.
+**No TypeScript code executes during slash command usage.** The templates are the product - they instruct AI agents on what to do.
 
-## Providers
+## Supported AI Tools
 
-| Category | Providers |
+| Category | Tools |
 | --- | --- |
-| IDE & editor 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 |
+| 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 |
 
-Provider paths and argument placeholders are listed in [docs/integrations.md](docs/integrations.md).
+Full list and configuration: [docs/integrations.md](docs/integrations.md)
 
 ## Quickstart
 
-### For AI Agents (Recommended)
-
-Most Clavix users work through AI coding assistants:
-
-> **💡 Choosing Your Workflow:**
-> - **Improve** – Optimize a single prompt (auto-selects depth)
-> - **PRD** – Plan something new with guided questions
-> - **Start** – Explore ideas conversationally
->
-> See [Choosing the Right Workflow](docs/guides/choosing-workflow.md) for detailed guidance.
+### 1. Install and Initialize
 
 ```bash
-# 1. Initialize in your project
 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 agent
-/clavix:improve "Create a login page"     # Optimize a prompt
-/clavix:prd                                # Full PRD workflow
-/clavix:start                              # Conversational exploration
+### 2. Use Slash Commands
 
-# 3. Manage saved prompts
-/clavix:execute  # Execute saved prompts
-/clavix:verify   # Verify implementation against checklist
+In your AI coding assistant (Claude Code, Cursor, etc.):
 
-# 4. Implement with task tracking
-/clavix:plan              # Generate tasks from PRD
-/clavix:implement         # Start implementation workflow
-clavix task-complete <taskId>  # Mark tasks done with auto-commit
+```
+/clavix:improve "Create a secure login page with JWT"
 ```
 
-**Supported agents**: Claude Code, Cursor, Windsurf, and [17+ more providers](docs/integrations.md)
+The AI agent reads the improve template and:
+- Analyzes your prompt for quality
+- Applies optimization patterns
+- Saves the improved version to `.clavix/outputs/prompts/`
 
-Learn more: [Workflow guide](docs/guides/choosing-workflow.md)
+### 3. Choose Your Workflow
 
-### Direct CLI Usage (Alternative)
+| Command | When to Use |
+|---------|-------------|
+| `/clavix:improve` | Optimize a single prompt (auto-selects depth) |
+| `/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:archive` | Archive completed projects |
 
-You can also use Clavix directly from the terminal:
+See [Choosing the Right Workflow](docs/guides/choosing-workflow.md) for detailed guidance.
+
+### 4. Keep Templates Updated
 
 ```bash
-clavix init
-clavix improve "Create a login page"           # Auto-selects depth
-clavix improve --comprehensive "Complex API"   # Force comprehensive
-clavix prd
+clavix update   # After npm update clavix
 ```
 
+## CLI Commands
+
+Clavix v5 has only 4 CLI commands (for setup, not workflows):
+
+| Command | Purpose |
+|---------|---------|
+| `clavix init` | Initialize Clavix in a project |
+| `clavix update` | Update templates after package update |
+| `clavix config` | Manage configuration |
+| `clavix version` | Show version |
+
+**All workflows** (`/clavix:improve`, `/clavix:prd`, etc.) are **slash commands** that AI agents execute by reading markdown templates.
+
 ## Full documentation
 - Overview & navigation: [docs/README.md](docs/README.md)
-- Command reference: [docs/commands/](docs/commands/README.md)
-- Providers: [docs/integrations.md](docs/integrations.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)
-- Guides: [docs/guides/](docs/guides/workflows.md)
+- v4 Architecture (archived): [docs/archive/v4-architecture.md](docs/archive/v4-architecture.md)
 
 ## Requirements
 
 ### For End Users
-- **Node.js ≥ 16.0.0** (ESM support required)
+- **Node.js >= 18.0.0**
 - npm or yarn package manager
+- An AI coding assistant (Claude Code, Cursor, Windsurf, etc.)
 
 ### For Contributors
-- **Node.js ≥ 16.0.0**
+- **Node.js >= 18.0.0**
 - Run tests: `npm test`
 - Lint: `npm run lint`
 - Build: `npm run build`

package/dist/cli/commands/init.js

@@ -273,51 +273,44 @@ Welcome to Clavix! This directory contains your local Clavix configuration and d
 .clavix/
 ├── config.json           # Your Clavix configuration
 ├── INSTRUCTIONS.md       # This file
+├── instructions/         # Workflow instruction files for AI agents
 ├── sessions/             # Conversational mode session files
 ├── outputs/
 │   ├── <project-name>/  # Per-project outputs
 │   │   ├── full-prd.md
 │   │   ├── quick-prd.md
-│   │   ├── tasks.md
-│   │   └── .clavix-implement-config.json
-│   ├── prompts/         # Saved prompts for re-execution (v4.11 unified)
+│   │   └── tasks.md
+│   ├── prompts/         # Saved prompts for re-execution
 │   └── archive/         # Archived completed projects
 └── templates/           # Custom template overrides (optional)
 \`\`\`
 
-## CLI Commands Reference
+## Clavix Commands (v5)
 
-### Prompt Improvement (v4.11)
-- \`clavix improve "<prompt>"\` - Smart prompt optimization with auto depth selection
-- \`clavix improve "<prompt>" --comprehensive\` - Force comprehensive depth analysis
-- \`clavix execute [--latest]\` - Execute saved prompts
-- \`clavix prompts list\` - View all saved prompts with status (NEW/EXECUTED/OLD/STALE)
-- \`clavix prompts clear\` - Cleanup prompts (\`--executed\`, \`--stale\`, \`--standard\`, \`--comprehensive\`, \`--all\`)
+### Setup Commands (CLI)
 
-### PRD & Planning
-- \`clavix prd\` - Generate PRD through guided Socratic questions
-- \`clavix plan\` - Transform PRD or session into phase-based \`tasks.md\`
-- \`clavix start\` - Start conversational mode for requirements gathering
-- \`clavix summarize [session-id]\` - Extract mini-PRD and prompts from conversation
+| Command | Purpose |
+|---------|---------|
+| \`clavix init\` | Initialize Clavix in a project |
+| \`clavix update\` | Update templates after package update |
+| \`clavix config\` | Manage configuration |
+| \`clavix version\` | Show version |
 
-### Implementation
-- \`clavix implement [--commit-strategy=<type>]\` - Execute tasks with optional git auto-commits
-- \`clavix task-complete <taskId>\` - Mark task complete with validation, auto-show next task
+### Workflow Commands (Slash Commands)
 
-### Project Management
-- \`clavix list [--sessions|--outputs]\` - List sessions and/or output projects
-- \`clavix show [session-id|--output <project>]\` - Inspect session or project details
-- \`clavix archive [project] [--restore]\` - Archive completed projects or restore them
+All workflows are executed via slash commands that AI agents read and follow:
 
-### Configuration
-- \`clavix init\` - Initialize Clavix (you just ran this!)
-- \`clavix config [get|set|edit|reset]\` - Manage configuration preferences
-- \`clavix update [--docs-only|--commands-only]\` - Refresh managed docs and slash commands
-- \`clavix version\` - Print installed version
-
-## Slash Commands (AI Agents)
-
-If using Claude Code, Cursor, or Windsurf, the following slash commands are available:
+| 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 with progress tracking |
+| \`/clavix:start\` | Begin conversational session |
+| \`/clavix:summarize\` | Extract requirements from conversation |
+| \`/clavix:execute\` | Run saved prompts |
+| \`/clavix:verify\` | Verify implementation |
+| \`/clavix:archive\` | Archive completed projects |
 
 **Note:** Running \`clavix init\` or \`clavix update\` will regenerate all slash commands from templates. Any manual edits to generated commands will be lost. If you need custom commands, create new command files instead of modifying generated ones.
 
@@ -325,143 +318,51 @@ If using Claude Code, Cursor, or Windsurf, the following slash commands are avai
 - Claude Code, Gemini, Qwen: \`/clavix:improve\` (colon format)
 - Cursor, Droid, Windsurf, etc.: \`/clavix-improve\` (hyphen format)
 
-### Prompt Improvement (v4.11)
-- \`improve [prompt]\` - Smart optimization with auto depth selection
-- \`execute\` - Execute saved prompts
-
-### PRD & Planning
-- \`/clavix:prd\` - Generate PRD through guided questions
-- \`/clavix:plan\` - Generate task breakdown from PRD
-- \`/clavix:start\` - Start conversational mode
-- \`/clavix:summarize\` - Summarize conversation
-
-### Implementation
-- \`/clavix:implement\` - Execute task workflow with git integration
-
-### Project Management
-- \`/clavix:archive\` - Archive completed projects
-
-## Workflows
-
-### Prompt Lifecycle (v4.11)
-
-1. **Create improved prompt**:
-   \`\`\`bash
-   clavix improve "your prompt here"
-   # Clavix auto-selects depth based on quality analysis:
-   # - <60% quality: standard depth (basic fixes)
-   # - 60-74%: asks user to choose
-   # - >=75%: comprehensive depth (polish)
-   \`\`\`
-   - CLI auto-saves to \`.clavix/outputs/prompts/\`
-   - Slash commands require manual save per template instructions
-
-2. **Execute saved prompt**:
-   \`\`\`bash
-   clavix execute --latest  # Most recent prompt
-   clavix execute           # Interactive selection
-   \`\`\`
-
-3. **Manage prompts**:
-   \`\`\`bash
-   clavix prompts list              # View all with status
-   clavix prompts clear --executed  # Remove executed prompts
-   clavix prompts clear --stale     # Remove stale (30+ days)
-   \`\`\`
-
-**Prompt Status**:
-- \`NEW\` - Just created, never executed
-- \`EXECUTED\` - Successfully executed at least once
-- \`OLD\` - 7+ days old, not executed
-- \`STALE\` - 30+ days old, not executed
-
-### Implementation Workflow (v1.3+)
-
-1. **Generate PRD**:
-   \`\`\`bash
-   clavix prd
-   # Creates: .clavix/outputs/<project>/full-prd.md + quick-prd.md
-   \`\`\`
-
-2. **Create task breakdown**:
-   \`\`\`bash
-   clavix plan
-   # Creates: .clavix/outputs/<project>/tasks.md
-   \`\`\`
+## Standard Workflow
 
-3. **Execute tasks with git integration**:
-   \`\`\`bash
-   # Manual commits (default):
-   clavix implement
+**Clavix follows this progression:**
 
-   # Or with auto-commit strategy:
-   clavix implement --commit-strategy=per-phase
-   \`\`\`
+\`\`\`
+PRD Creation → Task Planning → Implementation → Archive
+\`\`\`
 
-4. **Mark tasks complete**:
-   \`\`\`bash
-   clavix task-complete <taskId>
-   # Validates completion, optionally commits, shows next task
-   \`\`\`
+**Detailed steps:**
 
-5. **Archive when done**:
-   \`\`\`bash
-   clavix archive my-project
-   \`\`\`
+1. **Planning Phase**
+   - Run: \`/clavix:prd\` or \`/clavix:start\` → \`/clavix:summarize\`
+   - Output: \`.clavix/outputs/{project}/full-prd.md\` + \`quick-prd.md\`
 
-### Git Auto-Commit Strategies (v2.8.1)
+2. **Task Preparation**
+   - Run: \`/clavix:plan\` transforms PRD into curated task list
+   - Output: \`.clavix/outputs/{project}/tasks.md\`
 
-When using \`clavix implement --commit-strategy=<type>\`:
+3. **Implementation Phase**
+   - Run: \`/clavix:implement\`
+   - Agent executes tasks systematically
+   - Agent edits tasks.md directly to mark progress (\`- [ ]\` → \`- [x]\`)
 
-- \`none\` (default) - Manual git workflow, full control
-- \`per-task\` - Commit after each completed task (detailed history)
-- \`per-5-tasks\` - Commit every 5 tasks (balanced)
-- \`per-phase\` - Commit when phase completes (milestone-based)
+4. **Completion**
+   - Run: \`/clavix:archive\`
+   - Archives completed work
 
-**Recommendation**: Use \`none\` for most projects. Only enable auto-commits for large implementations with clear phases.
+**Key principle:** Planning workflows create documents. Implementation workflows write code.
 
-## When to Use Which Mode (v4.11)
+## Prompt Lifecycle
 
-- **Improve mode**: Smart prompt optimization with auto depth selection
-  - Standard depth: Quick cleanup for simpler prompts
-  - Comprehensive depth: Thorough analysis for complex requirements
-- **PRD mode**: Strategic planning with architecture, risks, and business impact
-- **Conversational mode** (\`start\`/\`summarize\`): Natural discussion → extract structured requirements
+1. **Optimize prompt**: \`/clavix:improve\` - Analyzes and improves your prompt
+2. **Review**: Agent lists saved prompts from \`.clavix/outputs/prompts/\`
+3. **Execute**: \`/clavix:execute\` - Implement when ready
+4. **Cleanup**: Agent deletes old prompt files from \`.clavix/outputs/prompts/\`
 
-## Typical Workflows
+## When to Use Which Mode
 
-**Improve a prompt** (v4.11 unified):
-\`\`\`bash
-clavix improve "Add user authentication"
-clavix execute --latest
-\`\`\`
-
-**Create and execute strategy**:
-\`\`\`bash
-clavix prd              # Generate PRD
-clavix plan             # Create tasks.md
-clavix implement        # Execute with manual commits
-\`\`\`
-
-**Capture conversation**:
-\`\`\`bash
-clavix start            # Record conversation
-# ... discuss requirements ...
-clavix summarize        # Extract mini-PRD + prompt
-\`\`\`
-
-**Stay organized**:
-\`\`\`bash
-clavix list             # See all projects
-clavix show --output my-project
-clavix archive my-project
-\`\`\`
+- **Improve mode** (\`/clavix:improve\`): Smart prompt optimization with auto-depth selection
+- **PRD mode** (\`/clavix:prd\`): Strategic planning with architecture and business impact
+- **Conversational mode** (\`/clavix:start\` → \`/clavix:summarize\`): Natural discussion → extract structured requirements
 
 ## Customization
 
-Create custom templates in \`.clavix/templates/\` to override defaults:
-- \`improve.txt\` - Custom improve mode template
-- \`prd-questions.txt\` - Custom PRD questions
+Create custom templates in \`.clavix/templates/\` to override defaults.
 
 Edit configuration:
 \`\`\`bash

package/dist/cli/commands/update.js

@@ -215,28 +215,26 @@ export default class Update extends Command {
 
 This project uses Clavix for prompt improvement and PRD generation.
 
-### Available Commands
-- \`clavix improve [prompt]\` - Unified prompt optimization with auto-depth selection
-- \`clavix improve --comprehensive [prompt]\` - Force comprehensive analysis
-- \`clavix improve --standard [prompt]\` - Force standard optimization
-- \`clavix analyze [prompt]\` - JSON analysis output for programmatic use
-- \`clavix prd\` - Generate a comprehensive PRD through guided questions
-- \`clavix start\` - Start a conversational session for iterative development
-- \`clavix summarize\` - Extract requirements from conversation history
-- \`clavix execute [--latest]\` - Execute saved prompts
-- \`clavix verify [--latest]\` - Verify implementation against checklist
+### Setup Commands (CLI)
+| Command | Purpose |
+|---------|---------|
+| \`clavix init\` | Initialize Clavix in a project |
+| \`clavix update\` | Update templates after package update |
+| \`clavix config\` | Manage configuration |
+| \`clavix version\` | Show version |
 
-### Quick Start
-\`\`\`bash
-# Prompt optimization (auto-selects depth)
-clavix improve "Build a user auth system"
-
-# Generate a PRD
-clavix prd
-
-# Start conversational mode
-clavix start
-\`\`\`
+### Workflow Commands (Slash Commands)
+| 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 with progress tracking |
+| \`/clavix:start\` | Begin conversational session |
+| \`/clavix:summarize\` | Extract requirements from conversation |
+| \`/clavix:execute\` | Run saved prompts |
+| \`/clavix:verify\` | Verify implementation |
+| \`/clavix:archive\` | Archive completed projects |
 
 Learn more: https://github.com/clavixdev/clavix`;
     }

package/dist/templates/agents/agents.md

@@ -66,36 +66,38 @@ For complete step-by-step workflows, see `.clavix/instructions/`:
 
 ---
 
-## 📋 CLI Quick Reference
+## 📋 Clavix Commands (v5)
 
+### Setup Commands (CLI)
 | Command | Purpose |
 |---------|---------|
-| `clavix init` | Interactive setup with integration selection |
-| `clavix improve "<prompt>"` | Unified optimization with auto-depth selection |
-| `clavix improve --comprehensive "<prompt>"` | Force comprehensive analysis |
-| `clavix improve --standard "<prompt>"` | Force standard optimization |
-| `clavix analyze "<prompt>"` | JSON analysis output for programmatic use |
-| `clavix execute [--latest]` | Execute saved prompts (interactive or --latest) |
-| `clavix verify [--latest]` | Verify implementation against checklist |
-| `clavix prompts list` | View saved prompts with status (NEW, EXECUTED, OLD, STALE) |
-| `clavix prompts clear` | Manage cleanup (--executed, --stale, --standard, --comprehensive, --all) |
-| `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 |
+| `clavix init` | Initialize Clavix in a project |
+| `clavix update` | Update templates after package update |
+| `clavix config` | Manage configuration |
+| `clavix version` | Show version |
+
+### Workflow Commands (Slash Commands)
+All workflows are executed via slash commands that AI agents read and follow:
+
+| 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 with progress tracking |
+| `/clavix:start` | Begin conversational session |
+| `/clavix:summarize` | Extract requirements from conversation |
+| `/clavix:execute` | Run saved prompts |
+| `/clavix:verify` | Verify implementation |
+| `/clavix:archive` | Archive completed projects |
 
 **Quick start:**
 ```bash
 npm install -g clavix
 clavix init
-clavix version
 ```
 
-**Save behavior:** CLI auto-saves prompts to `.clavix/outputs/`. When using slash commands, the agent must save manually per template instructions (no automatic persistence).
+**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).
 
 ---
 
@@ -110,23 +112,23 @@ PRD Creation → Task Planning → Implementation → Archive
 **Detailed steps:**
 
 1. **Planning Phase**
-   - Run: User uses conversational mode or direct PRD generation
+   - 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
+   - 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>]`
+   - Run: `/clavix:implement`
    - Agent executes tasks systematically
    - Mode: IMPLEMENTATION
-   - Uses `clavix task-complete <taskId>` to mark progress
+   - Agent edits tasks.md directly to mark progress (`- [ ]` → `- [x]`)
 
 4. **Completion**
-   - Run: `clavix archive [project]`
+   - Run: `/clavix:archive`
    - Archives completed work
    - Mode: Management
 
@@ -167,7 +169,7 @@ PRD Creation → Task Planning → Implementation → Archive
 ### ❌ Recreating workflow instructions inline
 **Wrong:** Copy entire fast mode workflow into response
 
-**Right:** Reference `.clavix/instructions/workflows/fast.md` and follow its steps
+**Right:** Reference `.clavix/instructions/workflows/improve.md` and follow its steps
 
 ### ❌ Not using instruction files
 **Wrong:** Make up workflow steps or guess at process