clavix 7.1.1 → 7.2.1

package/README.md

@@ -81,3 +81,13 @@ Run `clavix init` and select your tools. Command format varies by tool:
 ## License
 
 Apache-2.0
+
+## Star History
+
+<a href="https://www.star-history.com/#ClavixDev/Clavix&type=date&legend=top-left">
+ <picture>
+   <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&theme=dark&legend=top-left" />
+   <source media="(prefers-color-scheme: light)" srcset="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&legend=top-left" />
+   <img alt="Star History Chart" src="https://api.star-history.com/svg?repos=ClavixDev/Clavix&type=date&legend=top-left" />
+ </picture>
+</a>

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`

package/dist/templates/agents/octo 2.md

@@ -0,0 +1,237 @@
+# Clavix Instructions for Octofriend
+
+Clavix workflows optimized for Octofriend's capabilities: model switching, multi-turn thinking, and zero telemetry.
+
+---
+
+## ⛔ CLAVIX MODE ENFORCEMENT
+
+**CRITICAL: Know which mode you're in and STOP at the right point.**
+
+**OPTIMIZATION workflows** (NO CODE ALLOWED):
+- `/clavix:improve` - Prompt optimization with smart depth auto-selection
+- 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):
+- `/clavix:start`, `/clavix:summarize`, `/clavix:prd`, `/clavix:plan`
+- Your role: Ask questions, create PRDs/prompts, extract requirements
+- ❌ DO NOT implement features during these workflows
+
+**IMPLEMENTATION workflows** (CODE ALLOWED):
+- `/clavix:implement`
+- Your role: Write code, execute tasks, implement features
+- ✅ DO implement code during these workflows
+- Mark task completion by editing tasks.md directly (`- [ ]` → `- [x]`)
+
+See `.clavix/instructions/core/clavix-mode.md` for complete mode documentation.
+
+---
+
+## 📁 Detailed Workflow Instructions
+
+**Complete step-by-step workflows** in `.clavix/instructions/workflows/`:
+
+| Workflow | File | Purpose |
+|----------|------|---------|
+| Conversational mode | `start.md` | Natural requirements gathering |
+| Extract requirements | `summarize.md` | Convert conversation → PRD + prompts |
+| Smart optimization | `improve.md` | Prompt optimization with auto-depth |
+| PRD generation | `prd.md` | Strategic planning through questions |
+
+**Core references:**
+- `core/clavix-mode.md` - Mode boundaries (planning vs implementation)
+- `core/file-operations.md` - Proven file creation patterns
+- `core/verification.md` - Checkpoint patterns
+
+**Troubleshooting:**
+- `troubleshooting/jumped-to-implementation.md` - If you start implementing
+- `troubleshooting/skipped-file-creation.md` - If files aren't created
+- `troubleshooting/mode-confusion.md` - Planning vs implementation confusion
+
+**For Octo/Kimi users:** These instruction files have explicit step-by-step guidance that works well with structured processing. Always reference them when executing workflows.
+
+---
+
+## 🔍 Workflow Detection Keywords
+
+| Keywords | Workflow | Mode |
+|----------|----------|------|
+| prd, product requirements, specification | `prd` | Planning |
+| improve, optimize, enhance prompt | `improve` | Planning |
+| start, conversational, discuss | `start` | Planning |
+| summarize, extract, requirements | `summarize` | Planning |
+| implement, build, execute | `implement` | Implementation |
+
+**When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
+
+---
+
+## 🎯 Octofriend-Specific Guidance
+
+### Model Switching Strategy
+
+**Fast models** (Qwen-Max, etc.):
+- Standard depth optimization (`improve` workflow)
+- Formatting and structure
+- Straightforward questions
+
+**Thinking models** (DeepSeek-R1, etc.):
+- Comprehensive depth optimization (`improve` workflow)
+- Architectural decisions
+- Complex problem-solving
+- PRD generation (`prd` workflow)
+
+**Switch models based on task complexity** - Octofriend makes this seamless.
+
+### Multi-Turn Thinking
+
+Enable multi-turn for:
+- Architectural decisions
+- Comprehensive analysis
+- Strategic planning
+- Complex problem decomposition
+
+Multi-turn helps thinking models explore solution space thoroughly.
+
+### Zero Telemetry Advantage
+
+Users can share sensitive requirements safely:
+- Proprietary business logic
+- Confidential features
+- Internal system details
+- Competitive information
+
+Octofriend's zero telemetry makes it ideal for planning confidential projects.
+
+### Custom Autofix
+
+Trust Octofriend's autofix for:
+- Tool call failures
+- Parameter corrections
+- Retry logic
+
+Autofix handles edge cases gracefully - let it work.
+
+---
+
+## 📋 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)
+| Slash Command | Purpose |
+|---------------|---------|
+| `/clavix:improve` | Optimize prompts (auto-selects depth) |
+| `/clavix:prd` | Generate PRD through 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)
+| Utility | Purpose |
+|---------|---------|
+| `/clavix:verify` | Check implementation against PRD requirements |
+| `/clavix:archive` | Archive completed work to `.clavix/archive/` |
+
+---
+
+## 🔄 Prompt Execution Workflow
+
+**When you have a saved prompt to execute:**
+
+1. **List available prompts**: List files in `.clavix/outputs/prompts/*.md`
+2. **Execute prompt**: `/clavix:implement --latest` - implement saved prompt
+3. **Implement**: Agent reads the optimized prompt and implements the feature
+
+**Note:** Slash commands save prompts as `.md` files with frontmatter metadata.
+
+---
+
+## 🔄 Standard Workflow
+
+**Complete project flow:**
+
+1. **Planning** (`/clavix:prd`)
+   - Creates PRD (full + quick versions)
+   - Saves to `.clavix/outputs/{project}/`
+
+2. **Task Preparation** (`/clavix:plan`)
+   - Transforms PRD → curated tasks.md
+   - Phase-based organization
+
+3. **Implementation** (`/clavix:implement`)
+   - Agent executes tasks systematically
+   - Marks progress by editing tasks.md (`- [ ]` → `- [x]`)
+   - Optional git commit strategies
+
+4. **Completion** (`/clavix:archive`)
+   - Archives completed project
+
+**Alternative quick paths:**
+- **Quick improvement**: `/clavix:improve` → `/clavix:implement --latest` → Done
+- **Conversational**: `/clavix:start` → `/clavix:summarize` → `/clavix:implement` → Done
+
+---
+
+## 💡 Best Practices for Octofriend
+
+1. **Use thinking models for planning** - DeepSeek-R1 excels at strategic thinking
+2. **Switch to fast models for execution** - Qwen-Max handles implementation well
+3. **Enable multi-turn for complex decisions** - Let the model think thoroughly
+4. **Reference instruction files explicitly** - "See `.clavix/instructions/workflows/prd.md`"
+5. **Trust file operations** - Octofriend's Write tool is reliable
+6. **Leverage zero telemetry** - Share proprietary details safely
+7. **Follow the standard workflow** - PRD → Plan → Implement → Archive
+
+---
+
+## ⚠️ Common Mistakes
+
+### ❌ Implementing during planning workflows
+**Wrong:** User runs `/clavix:prd`, you generate PRD then start building features
+
+**Right:** User runs `/clavix:prd`, you generate PRD, save files, suggest `/clavix:plan` as next step
+
+### ❌ Skipping file creation
+**Wrong:** Display optimized prompt, stop there
+
+**Right:** Display prompt, save to `.clavix/outputs/`, verify, show path
+
+### ❌ Not referencing instruction files
+**Wrong:** Trying to remember workflow details from this file
+
+**Right:** "See `.clavix/instructions/workflows/improve.md` for complete workflow"
+
+### ❌ Using wrong model for task
+**Wrong:** Using fast model for complex architectural planning
+
+**Right:** Switch to thinking model (DeepSeek-R1) for strategic decisions
+
+---
+
+## 🆘 When in Doubt
+
+1. **Check which slash command was run** - Determines your mode (planning vs implementation)
+2. **Reference instruction files** - They have complete step-by-step guidance
+3. **Ask the user** - "Should I implement this (run `/clavix:implement`), or continue planning?"
+4. **Switch models** - Use thinking models for complex planning tasks
+
+---
+
+**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`
+
+Octofriend + Clavix = Strategic planning with zero telemetry, perfect for confidential projects.

package/dist/templates/skills/implement-templates/implementer-prompt.md

@@ -0,0 +1,117 @@
+# Implementer Subagent Prompt Template
+
+Use this template when dispatching an implementer subagent for a specific task.
+
+```
+Task tool:
+
+description: "Implement Task N: [task name]"
+
+prompt: |
+  You are implementing Task N: [task name]
+
+  ## Task Description
+
+  [FULL TEXT of task from plan - paste it here, don't make subagent read file]
+
+  ## Context
+
+  [Scene-setting: where this fits in the project, dependencies, architectural context]
+  [Reference any relevant PRD sections or prior tasks]
+
+  ## Before You Begin
+
+  If you have questions about:
+  - The requirements or acceptance criteria
+  - The approach or implementation strategy
+  - Dependencies or assumptions
+  - Anything unclear in the task description
+
+  **Ask them now.** Raise any concerns before starting work.
+
+  ## Your Job
+
+  Once you're clear on requirements:
+
+  1. Implement exactly what the task specifies
+  2. Write tests (following TDD if task says to)
+  3. Verify implementation works (run tests, check build)
+  4. Commit your work
+  5. Self-review (see below)
+  6. Report back
+
+  Work from: [directory/workspace]
+
+  **While you work:** If you encounter something unexpected or unclear, **ask questions**.
+  It's always OK to pause and clarify. Don't guess or make assumptions.
+
+  ## Before Reporting Back: Self-Review
+
+  Review your work with fresh eyes. Ask yourself:
+
+  **Completeness:**
+  - Did I fully implement everything in the spec?
+  - Did I miss any requirements?
+  - Are there edge cases I didn't handle?
+
+  **Quality:**
+  - Is this my best work?
+  - Are names clear and accurate (match what things do, not how they work)?
+  - Is the code clean and maintainable?
+
+  **Discipline:**
+  - Did I avoid overbuilding (YAGNI)?
+  - Did I only build what was requested?
+  - Did I follow existing patterns in the codebase?
+
+  **Testing:**
+  - Do tests actually verify behavior (not just mock behavior)?
+  - Did I follow TDD if required?
+  - Are tests comprehensive?
+
+  **If you find issues during self-review, fix them now before reporting.**
+
+  ## Report Format
+
+  When done, report:
+
+  ```
+  ## Implementation Complete
+
+  **Task:** [task name]
+  **Status:** Complete / Partial / Blocked
+
+  ### What I Implemented
+  - [List of changes made]
+
+  ### Files Changed
+  - `path/to/file.ts` - [what changed]
+
+  ### Test Results
+  [Paste test output or summary]
+
+  ### Self-Review Findings
+  - [Any issues found and fixed during self-review]
+  - [Or "No issues found"]
+
+  ### Issues or Concerns
+  - [Any remaining concerns or questions]
+  - [Or "None"]
+  ```
+```
+
+---
+
+## When to Use This Template
+
+- Dispatching a subagent to implement a single task from the plan
+- Each task gets its own fresh subagent (no context pollution)
+- Subagent implements, tests, commits, and self-reviews before reporting
+
+## Key Points
+
+1. **Provide full task text** - Don't make subagent read the plan file
+2. **Include context** - Where this fits, what came before
+3. **Encourage questions** - Subagent should ask before guessing
+4. **Require self-review** - Catches issues before handoff
+5. **Structured report** - Clear summary of what was done

package/dist/templates/skills/implement-templates/quality-reviewer-prompt.md

@@ -0,0 +1,121 @@
+# Code Quality Reviewer Prompt Template
+
+Use this template when dispatching a code quality reviewer subagent.
+
+**Purpose:** Verify implementation is well-built (clean, tested, maintainable)
+
+**Only dispatch after spec compliance review passes.**
+
+```
+Task tool:
+
+description: "Review code quality for Task N"
+
+prompt: |
+  You are reviewing the code quality of an implementation that has already
+  passed spec compliance review.
+
+  ## What Was Implemented
+
+  [From implementer's report - what they built]
+
+  ## Files to Review
+
+  [List of files changed with paths]
+
+  ## Review Dimensions
+
+  Evaluate the implementation across these dimensions:
+
+  ### 🔒 Security
+  - No hardcoded secrets, keys, or tokens
+  - Proper input validation
+  - Safe handling of user data
+  - No injection vulnerabilities
+
+  ### 🏗️ Architecture
+  - Follows existing project patterns
+  - Appropriate separation of concerns
+  - Consistent with codebase conventions
+  - No layer violations
+
+  ### 📏 Standards
+  - Clear, descriptive naming
+  - Reasonable function/method length
+  - DRY principle followed
+  - No console.logs in production code
+  - Proper TypeScript types (no `any` without reason)
+
+  ### ⚡ Performance
+  - No obvious N+1 patterns
+  - Appropriate async handling
+  - No unnecessary operations in loops
+  - Resources properly cleaned up
+
+  ### 🧪 Testing
+  - Tests actually test behavior (not mocks)
+  - Edge cases covered
+  - Error scenarios handled
+  - Tests are readable and maintainable
+
+  ## Report Format
+
+  ```
+  ## Code Quality Review
+
+  **Task:** [task name]
+  **Status:** ✅ Approved | ⚠️ Minor Issues | ❌ Needs Fixes
+
+  ### Strengths
+  - [What's done well]
+
+  ### Issues
+
+  **🔴 Critical** (must fix)
+  - [file:line] [issue description]
+
+  **🟠 Important** (should fix)
+  - [file:line] [issue description]
+
+  **🟡 Minor** (nice to fix)
+  - [file:line] [issue description]
+
+  ### Assessment
+  ✅ Approved - code is production ready
+  OR
+  ⚠️ Approved with notes - minor issues, can proceed
+  OR
+  ❌ Needs fixes - address critical/important issues before proceeding
+  ```
+```
+
+---
+
+## When to Use This Template
+
+- AFTER spec compliance review passes (never before)
+- Evaluates HOW code is written, not WHAT it does
+- Final gate before marking task complete
+
+## Severity Levels
+
+| Level | Meaning | Action |
+|-------|---------|--------|
+| 🔴 Critical | Security risk, broken functionality | Must fix |
+| 🟠 Important | Significant quality issue | Should fix |
+| 🟡 Minor | Style, optimization | Nice to fix |
+
+## Key Points
+
+1. **Only after spec passes** - Wrong order wastes time
+2. **Focus on quality** - Spec compliance already verified
+3. **Specific references** - file:line for every issue
+4. **Clear severity** - Helps prioritize fixes
+5. **Actionable feedback** - Say what to fix, not just what's wrong
+
+## If Issues Found
+
+1. Implementer fixes critical/important issues
+2. Quality reviewer reviews again
+3. Repeat until approved
+4. Only then mark task complete