clavix 4.11.2 → 5.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (162) hide show
  1. package/README.md +72 -60
  2. package/dist/cli/commands/update.js +9 -10
  3. package/dist/templates/agents/agents.md +14 -8
  4. package/dist/templates/agents/copilot-instructions.md +1 -1
  5. package/dist/templates/instructions/core/verification.md +2 -2
  6. package/dist/templates/slash-commands/_canonical/archive.md +83 -121
  7. package/dist/templates/slash-commands/_canonical/execute.md +32 -42
  8. package/dist/templates/slash-commands/_canonical/implement.md +32 -44
  9. package/dist/templates/slash-commands/_canonical/improve.md +14 -53
  10. package/dist/templates/slash-commands/_canonical/start.md +1 -1
  11. package/dist/templates/slash-commands/_canonical/summarize.md +8 -8
  12. package/dist/templates/slash-commands/_components/agent-protocols/cli-reference.md +84 -180
  13. package/dist/templates/slash-commands/_components/agent-protocols/error-handling.md +2 -2
  14. package/dist/templates/slash-commands/_components/agent-protocols/file-formats.md +41 -59
  15. package/dist/templates/slash-commands/_components/agent-protocols/state-assertion.md +1 -1
  16. package/dist/templates/slash-commands/_components/references/intent-types.md +1 -1
  17. package/dist/templates/slash-commands/_components/sections/file-saving-protocol.md +20 -27
  18. package/dist/templates/slash-commands/_components/sections/pattern-visibility.md +29 -46
  19. package/dist/templates/slash-commands/_components/troubleshooting/file-not-saved.md +4 -5
  20. package/dist/types/config.d.ts +57 -0
  21. package/dist/utils/legacy-command-cleanup.js +31 -4
  22. package/package.json +5 -4
  23. package/dist/cli/commands/analyze.d.ts +0 -17
  24. package/dist/cli/commands/analyze.js +0 -133
  25. package/dist/cli/commands/archive.d.ts +0 -36
  26. package/dist/cli/commands/archive.js +0 -266
  27. package/dist/cli/commands/deep.d.ts +0 -17
  28. package/dist/cli/commands/deep.js +0 -170
  29. package/dist/cli/commands/execute.d.ts +0 -15
  30. package/dist/cli/commands/execute.js +0 -168
  31. package/dist/cli/commands/fast.d.ts +0 -18
  32. package/dist/cli/commands/fast.js +0 -219
  33. package/dist/cli/commands/implement.d.ts +0 -24
  34. package/dist/cli/commands/implement.js +0 -289
  35. package/dist/cli/commands/improve.d.ts +0 -32
  36. package/dist/cli/commands/improve.js +0 -250
  37. package/dist/cli/commands/list.d.ts +0 -17
  38. package/dist/cli/commands/list.js +0 -217
  39. package/dist/cli/commands/plan.d.ts +0 -21
  40. package/dist/cli/commands/plan.js +0 -297
  41. package/dist/cli/commands/prd.d.ts +0 -24
  42. package/dist/cli/commands/prd.js +0 -321
  43. package/dist/cli/commands/prompts/clear.d.ts +0 -16
  44. package/dist/cli/commands/prompts/clear.js +0 -222
  45. package/dist/cli/commands/prompts/list.d.ts +0 -8
  46. package/dist/cli/commands/prompts/list.js +0 -88
  47. package/dist/cli/commands/show.d.ts +0 -21
  48. package/dist/cli/commands/show.js +0 -191
  49. package/dist/cli/commands/start.d.ts +0 -40
  50. package/dist/cli/commands/start.js +0 -210
  51. package/dist/cli/commands/summarize.d.ts +0 -17
  52. package/dist/cli/commands/summarize.js +0 -196
  53. package/dist/cli/commands/task-complete.d.ts +0 -27
  54. package/dist/cli/commands/task-complete.js +0 -269
  55. package/dist/cli/commands/verify.d.ts +0 -28
  56. package/dist/cli/commands/verify.js +0 -349
  57. package/dist/core/archive-manager.d.ts +0 -100
  58. package/dist/core/archive-manager.js +0 -302
  59. package/dist/core/basic-checklist-generator.d.ts +0 -35
  60. package/dist/core/basic-checklist-generator.js +0 -344
  61. package/dist/core/checklist-parser.d.ts +0 -48
  62. package/dist/core/checklist-parser.js +0 -238
  63. package/dist/core/config-manager.d.ts +0 -149
  64. package/dist/core/config-manager.js +0 -230
  65. package/dist/core/conversation-analyzer.d.ts +0 -86
  66. package/dist/core/conversation-analyzer.js +0 -387
  67. package/dist/core/conversation-quality-tracker.d.ts +0 -81
  68. package/dist/core/conversation-quality-tracker.js +0 -195
  69. package/dist/core/git-manager.d.ts +0 -126
  70. package/dist/core/git-manager.js +0 -282
  71. package/dist/core/intelligence/confidence-calculator.d.ts +0 -93
  72. package/dist/core/intelligence/confidence-calculator.js +0 -124
  73. package/dist/core/intelligence/index.d.ts +0 -11
  74. package/dist/core/intelligence/index.js +0 -15
  75. package/dist/core/intelligence/intent-detector.d.ts +0 -54
  76. package/dist/core/intelligence/intent-detector.js +0 -723
  77. package/dist/core/intelligence/pattern-library.d.ts +0 -104
  78. package/dist/core/intelligence/pattern-library.js +0 -339
  79. package/dist/core/intelligence/patterns/actionability-enhancer.d.ts +0 -27
  80. package/dist/core/intelligence/patterns/actionability-enhancer.js +0 -192
  81. package/dist/core/intelligence/patterns/alternative-phrasing-generator.d.ts +0 -29
  82. package/dist/core/intelligence/patterns/alternative-phrasing-generator.js +0 -239
  83. package/dist/core/intelligence/patterns/ambiguity-detector.d.ts +0 -22
  84. package/dist/core/intelligence/patterns/ambiguity-detector.js +0 -196
  85. package/dist/core/intelligence/patterns/assumption-explicitizer.d.ts +0 -30
  86. package/dist/core/intelligence/patterns/assumption-explicitizer.js +0 -296
  87. package/dist/core/intelligence/patterns/base-pattern.d.ts +0 -192
  88. package/dist/core/intelligence/patterns/base-pattern.js +0 -103
  89. package/dist/core/intelligence/patterns/completeness-validator.d.ts +0 -27
  90. package/dist/core/intelligence/patterns/completeness-validator.js +0 -221
  91. package/dist/core/intelligence/patterns/conciseness-filter.d.ts +0 -20
  92. package/dist/core/intelligence/patterns/conciseness-filter.js +0 -92
  93. package/dist/core/intelligence/patterns/context-precision.d.ts +0 -32
  94. package/dist/core/intelligence/patterns/context-precision.js +0 -389
  95. package/dist/core/intelligence/patterns/conversation-summarizer.d.ts +0 -30
  96. package/dist/core/intelligence/patterns/conversation-summarizer.js +0 -277
  97. package/dist/core/intelligence/patterns/dependency-identifier.d.ts +0 -23
  98. package/dist/core/intelligence/patterns/dependency-identifier.js +0 -166
  99. package/dist/core/intelligence/patterns/domain-context-enricher.d.ts +0 -21
  100. package/dist/core/intelligence/patterns/domain-context-enricher.js +0 -198
  101. package/dist/core/intelligence/patterns/edge-case-identifier.d.ts +0 -30
  102. package/dist/core/intelligence/patterns/edge-case-identifier.js +0 -269
  103. package/dist/core/intelligence/patterns/error-tolerance-enhancer.d.ts +0 -22
  104. package/dist/core/intelligence/patterns/error-tolerance-enhancer.js +0 -179
  105. package/dist/core/intelligence/patterns/implicit-requirement-extractor.d.ts +0 -24
  106. package/dist/core/intelligence/patterns/implicit-requirement-extractor.js +0 -259
  107. package/dist/core/intelligence/patterns/objective-clarifier.d.ts +0 -22
  108. package/dist/core/intelligence/patterns/objective-clarifier.js +0 -126
  109. package/dist/core/intelligence/patterns/output-format-enforcer.d.ts +0 -22
  110. package/dist/core/intelligence/patterns/output-format-enforcer.js +0 -151
  111. package/dist/core/intelligence/patterns/prd-structure-enforcer.d.ts +0 -23
  112. package/dist/core/intelligence/patterns/prd-structure-enforcer.js +0 -183
  113. package/dist/core/intelligence/patterns/prerequisite-identifier.d.ts +0 -23
  114. package/dist/core/intelligence/patterns/prerequisite-identifier.js +0 -221
  115. package/dist/core/intelligence/patterns/requirement-prioritizer.d.ts +0 -24
  116. package/dist/core/intelligence/patterns/requirement-prioritizer.js +0 -134
  117. package/dist/core/intelligence/patterns/scope-definer.d.ts +0 -26
  118. package/dist/core/intelligence/patterns/scope-definer.js +0 -236
  119. package/dist/core/intelligence/patterns/step-decomposer.d.ts +0 -31
  120. package/dist/core/intelligence/patterns/step-decomposer.js +0 -242
  121. package/dist/core/intelligence/patterns/structure-organizer.d.ts +0 -31
  122. package/dist/core/intelligence/patterns/structure-organizer.js +0 -218
  123. package/dist/core/intelligence/patterns/success-criteria-enforcer.d.ts +0 -22
  124. package/dist/core/intelligence/patterns/success-criteria-enforcer.js +0 -165
  125. package/dist/core/intelligence/patterns/success-metrics-enforcer.d.ts +0 -24
  126. package/dist/core/intelligence/patterns/success-metrics-enforcer.js +0 -165
  127. package/dist/core/intelligence/patterns/technical-context-enricher.d.ts +0 -25
  128. package/dist/core/intelligence/patterns/technical-context-enricher.js +0 -165
  129. package/dist/core/intelligence/patterns/topic-coherence-analyzer.d.ts +0 -26
  130. package/dist/core/intelligence/patterns/topic-coherence-analyzer.js +0 -300
  131. package/dist/core/intelligence/patterns/user-persona-enricher.d.ts +0 -24
  132. package/dist/core/intelligence/patterns/user-persona-enricher.js +0 -141
  133. package/dist/core/intelligence/patterns/validation-checklist-creator.d.ts +0 -31
  134. package/dist/core/intelligence/patterns/validation-checklist-creator.js +0 -242
  135. package/dist/core/intelligence/quality-assessor.d.ts +0 -51
  136. package/dist/core/intelligence/quality-assessor.js +0 -505
  137. package/dist/core/intelligence/types.d.ts +0 -111
  138. package/dist/core/intelligence/types.js +0 -3
  139. package/dist/core/intelligence/universal-optimizer.d.ts +0 -84
  140. package/dist/core/intelligence/universal-optimizer.js +0 -371
  141. package/dist/core/prd-generator.d.ts +0 -76
  142. package/dist/core/prd-generator.js +0 -173
  143. package/dist/core/prompt-manager.d.ts +0 -110
  144. package/dist/core/prompt-manager.js +0 -274
  145. package/dist/core/prompt-optimizer.d.ts +0 -268
  146. package/dist/core/prompt-optimizer.js +0 -959
  147. package/dist/core/question-engine.d.ts +0 -167
  148. package/dist/core/question-engine.js +0 -356
  149. package/dist/core/session-manager.d.ts +0 -139
  150. package/dist/core/session-manager.js +0 -365
  151. package/dist/core/task-manager.d.ts +0 -211
  152. package/dist/core/task-manager.js +0 -981
  153. package/dist/core/verification-hooks.d.ts +0 -67
  154. package/dist/core/verification-hooks.js +0 -309
  155. package/dist/core/verification-manager.d.ts +0 -107
  156. package/dist/core/verification-manager.js +0 -415
  157. package/dist/index 2.js +0 -13
  158. package/dist/index.d 2.ts +0 -4
  159. package/dist/types/session.d.ts +0 -78
  160. package/dist/types/session.js +0 -8
  161. package/dist/types/verification.d.ts +0 -205
  162. package/dist/types/verification.js +0 -9
@@ -65,7 +65,7 @@ Tell them: **"Run `/clavix:execute --latest` to implement this prompt."**
65
65
  ```
66
66
  **CLAVIX MODE: Improve**
67
67
  Mode: planning
68
- Purpose: Optimizing user prompt with Clavix Intelligence
68
+ Purpose: Optimizing user prompt with pattern-based analysis
69
69
  Depth: [standard|comprehensive] (auto-detected based on quality score)
70
70
  Implementation: BLOCKED - I will analyze and improve the prompt, not implement it
71
71
  ```
@@ -373,9 +373,8 @@ This is a BLOCKING checkpoint. You cannot proceed to the final message until sav
373
373
  |------|--------|-------------|--------------|
374
374
  | 1 | Create directory | Write tool (create parent dirs) | Directory exists |
375
375
  | 2 | Generate prompt ID | Format: `{std\|comp}-YYYYMMDD-HHMMSS-<random>` | ID is unique |
376
- | 3 | Write prompt file | **Write tool** | File created |
377
- | 4 | Update .index.json | **Write tool** | Entry added |
378
- | 5 | **VERIFY: Read back files** | **Read tool** | Both files readable |
376
+ | 3 | Write prompt file with frontmatter | **Write tool** | File created |
377
+ | 4 | **VERIFY: Read back file** | **Read tool** | File readable |
379
378
 
380
379
  **⚠️ WARNING:** If you output "saved" without completing verification, you are LYING to the user.
381
380
 
@@ -436,63 +435,26 @@ originalPrompt: <user's original prompt text>
436
435
  <Insert edge cases>
437
436
  ```
438
437
 
439
- ### Step 4: Update Index File (Write Tool)
440
-
441
- **Use the Write tool** to update the index at `.clavix/outputs/prompts/.index.json`:
442
-
443
- **If index file doesn't exist**, create it with:
444
- ```json
445
- {
446
- "version": "2.0",
447
- "prompts": []
448
- }
449
- ```
450
-
451
- **Then add a new metadata entry** to the `prompts` array:
452
- ```json
453
- {
454
- "id": "<prompt-id>",
455
- "filename": "<prompt-id>.md",
456
- "depthUsed": "standard|comprehensive",
457
- "timestamp": "<ISO-8601 timestamp>",
458
- "createdAt": "<ISO-8601 timestamp>",
459
- "path": ".clavix/outputs/prompts/<prompt-id>.md",
460
- "originalPrompt": "<user's original prompt text>",
461
- "executed": false,
462
- "executedAt": null
463
- }
464
- ```
465
-
466
438
  ---
467
439
 
468
440
  ## ✅ VERIFICATION (REQUIRED - Must Pass Before Final Output)
469
441
 
470
- **After completing Steps 1-4, you MUST verify the save succeeded.**
442
+ **After completing Steps 1-3, you MUST verify the save succeeded.**
471
443
 
472
- ### Verification Step A: Read the Prompt File
444
+ ### Verification: Read the Prompt File
473
445
 
474
446
  Use the **Read tool** to read the file you just created:
475
447
  - Path: `.clavix/outputs/prompts/<your-prompt-id>.md`
476
448
 
477
- **If Read fails:** ⛔ STOP - Saving failed. Retry Steps 3-4.
478
-
479
- ### Verification Step B: Read the Index File
480
-
481
- Use the **Read tool** to read the index:
482
- - Path: `.clavix/outputs/prompts/.index.json`
483
-
484
- **Confirm:** Your prompt ID appears in the `prompts` array.
485
-
486
- **If not found:** ⛔ STOP - Index update failed. Retry Step 4.
449
+ **If Read fails:** ⛔ STOP - Saving failed. Retry Step 3.
487
450
 
488
451
  ### Verification Checklist
489
452
 
490
453
  Before outputting final message, confirm ALL of these:
491
454
 
492
455
  - [ ] I used the **Write tool** to create `.clavix/outputs/prompts/<id>.md`
493
- - [ ] I used the **Write tool** to update `.clavix/outputs/prompts/.index.json`
494
456
  - [ ] I used the **Read tool** to verify the prompt file exists and has content
495
- - [ ] I used the **Read tool** to verify my prompt ID is in .index.json
457
+ - [ ] The file has valid frontmatter with id, timestamp, and executed: false
496
458
  - [ ] I know the **exact file path** I created (not a placeholder)
497
459
 
498
460
  **If ANY checkbox is unchecked: ⛔ STOP and complete the missing step.**
@@ -538,13 +500,13 @@ Wait for the user to decide what to do next.
538
500
  - `/clavix:start` - Conversational exploration before prompting
539
501
  - `/clavix:verify` - Verify implementation against checklist
540
502
 
541
- **CLI commands:**
542
- - `clavix prompts list` - View saved prompts
543
- - `clavix prompts clear --executed` - Clean up executed prompts
503
+ **Managing saved prompts:**
504
+ - List prompts: `ls .clavix/outputs/prompts/*.md`
505
+ - Prompt files: `.clavix/outputs/prompts/<id>.md` (metadata in frontmatter)
544
506
 
545
507
  ---
546
508
 
547
- ## Agent Transparency (v4.11)
509
+ ## Agent Transparency (v5.0)
548
510
 
549
511
  ### CLI Reference (Commands I Execute)
550
512
  {{INCLUDE:agent-protocols/cli-reference.md}}
@@ -586,10 +548,9 @@ Wait for the user to decide what to do next.
586
548
  mkdir -p .clavix/outputs/prompts
587
549
  ```
588
550
 
589
- **Error: Index file corrupted or invalid JSON**
590
- ```bash
591
- echo '{"version":"2.0","prompts":[]}' > .clavix/outputs/prompts/.index.json
592
- ```
551
+ **Error: Prompt file has invalid frontmatter**
552
+ - Re-save the prompt file with valid YAML frontmatter
553
+ - Ensure id, timestamp, and executed fields are present
593
554
 
594
555
  ### Issue: Wrong depth auto-selected
595
556
  **Cause**: Borderline quality score
@@ -164,7 +164,7 @@ Implementation: BLOCKED - I will ask questions and explore needs, not implement
164
164
 
165
165
  After the conversational session, `/clavix:summarize` will:
166
166
  - Extract requirements from the conversation
167
- - Apply Clavix Intelligence™ optimization
167
+ - Apply pattern-based optimization
168
168
  - Analyze intent and assess quality (Clarity, Efficiency, Structure, Completeness, Actionability)
169
169
  - Generate both original extraction and optimized version
170
170
  - Display quality scores and improvements
@@ -54,7 +54,7 @@ For complete mode documentation, see: `.clavix/instructions/core/clavix-mode.md`
54
54
  | 2. Skipping Pre-Validation | Not checking conversation completeness before extracting requirements |
55
55
  | 3. Missing Confidence Indicators | Not annotating requirements with [HIGH], [MEDIUM], [LOW] confidence |
56
56
  | 4. Not Creating Output Files | Not creating mini-prd.md, optimized-prompt.md, and quick-prd.md files |
57
- | 5. No Clavix Intelligence™ Applied | Not applying quality patterns to extracted requirements |
57
+ | 5. No Optimization Applied | Not applying quality patterns to extracted requirements |
58
58
  | 6. Capability Hallucination | Claiming features Clavix doesn't have, inventing workflows |
59
59
 
60
60
  **STOP**: Immediately halt the incorrect action
@@ -229,7 +229,7 @@ Implementation: BLOCKED - I will extract requirements, not implement them
229
229
 
230
230
  Use the Write tool to create `.clavix/outputs/[project-name]/optimized-prompt.md`
231
231
 
232
- **Content:** Enhanced version with Clavix Intelligence™ improvements (see step 4 below for optimization)
232
+ **Content:** Enhanced version with pattern-based optimization (see step 4 below for optimization)
233
233
 
234
234
  **Format:**
235
235
  ```markdown
@@ -243,7 +243,7 @@ Implementation: BLOCKED - I will extract requirements, not implement them
243
243
 
244
244
  ---
245
245
 
246
- ## Clavix Intelligence™ Improvements Applied
246
+ ## Optimization Improvements Applied
247
247
 
248
248
  1. **[ADDED]** - [Description of what was added and why]
249
249
  2. **[CLARIFIED]** - [What was ambiguous and how it was clarified]
@@ -273,8 +273,8 @@ Implementation: BLOCKED - I will extract requirements, not implement them
273
273
  - Something went wrong with file creation
274
274
  - Retry the Write tool for the missing file
275
275
 
276
- 4. **Clavix Intelligence™ Optimization** (automatic with labeled improvements):
277
- - After extracting the prompt, analyze using Clavix Intelligence™
276
+ 4. **Pattern-Based Optimization** (automatic with labeled improvements):
277
+ - After extracting the prompt, analyze using pattern-based optimization
278
278
  - Apply optimizations for Clarity, Efficiency, Structure, Completeness, and Actionability
279
279
  - **Label all improvements** with quality dimension tags:
280
280
  - **[Efficiency]**: "Removed 12 conversational words, reduced from 45 to 28 words"
@@ -286,7 +286,7 @@ Implementation: BLOCKED - I will extract requirements, not implement them
286
286
  - Show quality scores (before/after) and labeled improvements
287
287
  - These improvements were already applied when creating optimized-prompt.md in step 3.4
288
288
 
289
- **CHECKPOINT:** Applied Clavix Intelligence™ optimization - [N] improvements added
289
+ **CHECKPOINT:** Applied pattern-based optimization - [N] improvements added
290
290
 
291
291
  5. **Highlight Key Insights** discovered during the conversation:
292
292
  ```markdown
@@ -324,8 +324,8 @@ Implementation: BLOCKED - I will extract requirements, not implement them
324
324
 
325
325
  **📁 Location:** `.clavix/outputs/[project-name]/`
326
326
 
327
- **🎯 Clavix Intelligence™:**
328
- Applied [N] optimizations:
327
+ **🎯 Optimizations Applied:**
328
+ Applied [N] improvements:
329
329
  - [Brief summary of improvements]
330
330
 
331
331
  **🔍 Key Insights:**
@@ -1,214 +1,118 @@
1
- ## CLI Commands Reference (For Agent Execution)
1
+ ## CLI Commands Reference (v5.0 - Agentic-First)
2
2
 
3
- These are commands YOU (the agent) run automatically. Never ask the user to run these - you execute them and report results.
3
+ Clavix v5 follows an **agentic-first architecture**. Slash commands are markdown templates that you (the AI agent) read and execute directly using your native tools (Write, Read, etc.).
4
+
5
+ **CLI commands are ONLY for project setup**, not for workflow execution.
4
6
 
5
7
  ---
6
8
 
7
- ### Prompt Management Commands
9
+ ### Setup Commands (User runs these)
8
10
 
9
- #### `clavix fast "prompt"`
10
- **What it does:** Quickly improves a prompt and saves it
11
- **When to run:** After user provides a prompt for optimization
12
- **You say:** "Let me improve this prompt for you..."
13
- **Example:**
14
- ```bash
15
- clavix fast "build a todo app"
16
- ```
11
+ These are commands the **user** runs in their terminal to set up Clavix:
17
12
 
18
- #### `clavix deep "prompt"`
19
- **What it does:** Comprehensive prompt analysis with alternatives and edge cases
20
- **When to run:** When prompt needs thorough analysis (complex requirements, low quality score)
21
- **You say:** "This needs a deeper look - let me analyze it thoroughly..."
22
- **Example:**
23
- ```bash
24
- clavix deep "create authentication system with OAuth"
25
- ```
13
+ #### `clavix init`
14
+ **What it does:** Sets up Clavix in current project
15
+ **When user runs it:** First time using Clavix in a project
16
+ **Features:**
17
+ - Auto-detects AI coding tools (Claude Code, Cursor, etc.)
18
+ - Configures integrations
19
+ - Creates .clavix/ directory with slash commands
20
+ - Injects documentation into CLAUDE.md
26
21
 
27
- #### `clavix analyze "prompt"`
28
- **What it does:** Returns structured JSON with intent, quality scores, and escalation recommendation
29
- **When to run:** When you need data-driven decision on which mode to use
30
- **You say:** Nothing - this is for internal decision-making
31
- **Example:**
32
- ```bash
33
- clavix analyze "build a login page"
34
- ```
35
- **Output:** JSON with `intent`, `confidence`, `quality` (6 dimensions), `escalation` (score + recommendation)
22
+ #### `clavix update`
23
+ **What it does:** Updates slash commands and documentation
24
+ **When user runs it:** After Clavix package update
36
25
  **Flags:**
37
- - `--pretty` - Pretty-print the JSON output
26
+ - `--docs-only` - Update only documentation
27
+ - `--commands-only` - Update only slash commands
38
28
 
39
- #### `clavix prompts list`
40
- **What it does:** Shows all saved prompts with their status
41
- **When to run:** To verify a prompt was saved, or find prompt IDs
42
- **You say:** "Let me check your saved prompts..."
43
- **Example output:**
44
- ```
45
- 📋 Saved Prompts (3 total)
46
- fast-20250126-143022-a3f2 [not executed] "build a todo app..."
47
- deep-20250126-150000-b4c3 [executed] "authentication system..."
48
- ```
29
+ #### `clavix config get <key>`
30
+ **What it does:** Gets a configuration value
31
+ **Example:** `clavix config get integrations`
49
32
 
50
- #### `clavix prompts clear --executed`
51
- **What it does:** Removes prompts that have already been implemented
52
- **When to run:** During cleanup or when user wants to tidy up
53
- **You say:** "Cleaning up executed prompts..."
33
+ #### `clavix config set <key> <value>`
34
+ **What it does:** Updates a configuration value
35
+ **Example:** `clavix config set preferences.verboseLogging true`
54
36
 
55
- #### `clavix prompts clear --stale`
56
- **What it does:** Removes prompts older than 30 days
57
- **When to run:** When storage is cluttered with old prompts
58
- **You say:** "Removing old prompts to keep things tidy..."
37
+ #### `clavix version`
38
+ **What it does:** Shows current Clavix version
39
+ **Example output:** `Clavix v5.0.0`
59
40
 
60
41
  ---
61
42
 
62
- ### Implementation Commands
43
+ ### How Workflows Execute (Agentic-First)
63
44
 
64
- #### `clavix execute --latest`
65
- **What it does:** Retrieves the most recent saved prompt for implementation
66
- **When to run:** When starting implementation workflow
67
- **You say:** "Getting your latest prompt ready for implementation..."
68
- **Flags:**
69
- - `--latest` - Get most recent prompt
70
- - `--fast` - Filter to fast prompts only
71
- - `--deep` - Filter to deep prompts only
72
- - `--id <prompt-id>` - Get specific prompt
73
-
74
- #### `clavix implement`
75
- **What it does:** Starts implementation session from task plan
76
- **When to run:** After PRD and tasks exist, ready to build
77
- **You say:** "Starting implementation - let me check your tasks..."
78
- **Flags:**
79
- - `--commit-strategy=per-task` - Commit after each task
80
- - `--commit-strategy=per-phase` - Commit after each phase
81
- - `--list` - Show available tasks
82
-
83
- #### `clavix task-complete <task-id>`
84
- **What it does:** Marks a task as done, updates tracking, optionally commits
85
- **When to run:** IMMEDIATELY after finishing each task implementation
86
- **You say:** "Marking that task as complete..."
87
- **CRITICAL:** Never manually edit tasks.md checkboxes - always use this command
88
- **Example:**
89
- ```bash
90
- clavix task-complete phase-1-setup-project-1
91
- ```
92
- **Flags:**
93
- - `--no-git` - Skip git commit
94
- - `--force` - Complete even if already done
45
+ **In v5, you (the agent) execute workflows directly using your native tools:**
95
46
 
96
- #### `clavix verify --latest`
97
- **What it does:** Runs verification checks against implementation
98
- **When to run:** After implementation, before considering work done
99
- **You say:** "Running verification checks..."
100
- **Flags:**
101
- - `--latest` - Verify most recent executed prompt
102
- - `--id <prompt-id>` - Verify specific prompt
103
- - `--status` - Show verification status only
104
- - `--retry-failed` - Re-run only failed checks
105
- - `--export markdown` - Generate verification report
106
- - `--run-hooks` - Run automated tests (default: true)
47
+ | Workflow | How You Execute It |
48
+ |----------|-------------------|
49
+ | **Save prompt** | Use **Write tool** to create `.clavix/outputs/prompts/<id>.md` (with frontmatter metadata) |
50
+ | **Save PRD** | Use **Write tool** to create `.clavix/outputs/<project>/full-prd.md` |
51
+ | **Save tasks** | Use **Write tool** to create `.clavix/outputs/<project>/tasks.md` |
52
+ | **Mark task complete** | Use **Edit tool** to change `- [ ]` to `- [x]` in tasks.md |
53
+ | **Archive project** | Use **Bash tool** to `mv .clavix/outputs/<project> .clavix/outputs/archive/` |
54
+ | **List prompts** | Use **Glob/Bash** to list `.clavix/outputs/prompts/*.md` files |
55
+ | **Read project** | Use **Read tool** on `.clavix/outputs/<project>/` files |
107
56
 
108
57
  ---
109
58
 
110
- ### Planning Commands
59
+ ### Agent Execution Protocol (v5)
111
60
 
112
- #### `clavix prd`
113
- **What it does:** Launches PRD generation workflow
114
- **When to run:** When user wants to plan a feature/project
115
- **You say:** "Let's plan this out properly..."
61
+ **DO:**
62
+ 1. Use your native tools (Write, Read, Edit, Bash) to perform operations
63
+ 2. Save outputs to `.clavix/outputs/` directory structure
64
+ 3. Follow the workflow instructions in each slash command template
65
+ 4. Report results in friendly language to the user
116
66
 
117
- #### `clavix plan`
118
- **What it does:** Generates task breakdown from PRD
119
- **When to run:** After PRD exists, ready to create tasks
120
- **You say:** "Creating your implementation tasks..."
121
- **Flags:**
122
- - `--project <name>` - Specify which project
123
- - `--overwrite` - Regenerate existing tasks
67
+ **DON'T:**
68
+ 1. Try to run `clavix` CLI commands during workflows (they don't exist anymore)
69
+ 2. Ask user to run terminal commands for workflow operations
70
+ 3. Skip verification after completing work
71
+ 4. Assume CLI commands exist - use your tools directly
124
72
 
125
73
  ---
126
74
 
127
- ### Project Management Commands
128
-
129
- #### `clavix archive <project-name>`
130
- **What it does:** Archives completed project
131
- **When to run:** When all tasks are done and verified
132
- **You say:** "Archiving this project for your records..."
133
- **Flags:**
134
- - `--force` - Archive even if incomplete
135
- - `--delete` - Permanently delete instead
136
- - `--list` - Show archived projects
137
- - `--restore <name>` - Restore from archive
138
-
139
- #### `clavix list`
140
- **What it does:** Shows sessions and outputs
141
- **When to run:** To find projects, check progress
142
- **You say:** "Let me show you what we have..."
143
- **Flags:**
144
- - `--sessions` - List only sessions
145
- - `--outputs` - List only outputs
146
- - `--archived` - Include archived
147
- - `--project <name>` - Filter by project
75
+ ### File System Structure
148
76
 
149
- #### `clavix show --output <project>`
150
- **What it does:** Shows detailed project information
151
- **When to run:** When user asks about a specific project
152
- **You say:** "Here's what's in that project..."
77
+ ```
78
+ .clavix/
79
+ ├── config.json # Project configuration
80
+ ├── outputs/
81
+ │ ├── prompts/ # Saved prompts from /clavix:improve
82
+ │ │ └── *.md # Individual prompts (metadata in frontmatter)
83
+ │ ├── <project-name>/ # PRD projects
84
+ │ │ ├── full-prd.md # Comprehensive PRD
85
+ │ │ ├── quick-prd.md # AI-optimized summary
86
+ │ │ └── tasks.md # Implementation tasks
87
+ │ └── archive/ # Archived projects
88
+ └── commands/ # Slash command templates (managed by clavix update)
89
+ ```
153
90
 
91
+ **Prompt File Format:**
92
+ ```markdown
93
+ ---
94
+ id: std-20250127-143022-a3f2
95
+ timestamp: 2025-01-27T14:30:22Z
96
+ executed: false
97
+ originalPrompt: "the user's original prompt"
154
98
  ---
155
99
 
156
- ### Setup & Configuration Commands
157
-
158
- #### `clavix init`
159
- **What it does:** Sets up Clavix in current project
160
- **When to run:** First time using Clavix in a project
161
- **You say:** "Setting up Clavix for this project..."
162
- **Features:**
163
- - Auto-detects tech stack
164
- - Configures integrations
165
- - Creates .clavix/ directory
166
-
167
- #### `clavix config get <key>`
168
- **What it does:** Gets a configuration value
169
- **When to run:** To check current settings
170
- **Example:** `clavix config get preferences.verboseLogging`
171
-
172
- #### `clavix config set <key> <value>`
173
- **What it does:** Updates a configuration value
174
- **When to run:** When user wants to change settings
175
- **You say:** "Updating that setting..."
176
-
177
- #### `clavix update`
178
- **What it does:** Updates slash commands and documentation
179
- **When to run:** After Clavix version update
180
- **You say:** "Updating your Clavix setup..."
181
- **Flags:**
182
- - `--docs-only` - Update only documentation
183
- - `--commands-only` - Update only slash commands
100
+ # Improved Prompt
184
101
 
185
- #### `clavix version`
186
- **What it does:** Shows current Clavix version
187
- **When to run:** To check version, troubleshoot issues
188
- **Example output:** `Clavix v4.9.0`
102
+ [optimized prompt content]
103
+ ```
189
104
 
190
105
  ---
191
106
 
192
- ### Agent Execution Protocol
193
-
194
- **ALWAYS:**
195
- 1. Run commands silently (don't show raw command to user)
196
- 2. Report results in friendly language
197
- 3. Handle errors gracefully (see error-handling.md)
198
- 4. Continue workflow after successful commands
107
+ ### Migration from v4
199
108
 
200
- **NEVER:**
201
- 1. Ask user to run terminal commands
202
- 2. Show raw CLI output without explanation
203
- 3. Skip verification after implementation
204
- 4. Manually edit files that commands should update
109
+ If you see references to old CLI commands in conversations, they no longer exist:
205
110
 
206
- **Example Flow:**
207
- ```
208
- User: "I'm done with task 1"
209
-
210
- Agent (internally runs): clavix task-complete phase-1-setup-1
211
- Agent (says to user): "Great! I've marked that task complete.
212
- You're now 1/5 tasks done.
213
- Ready to start the next one?"
214
- ```
111
+ | Old Command | v5 Equivalent |
112
+ |-------------|---------------|
113
+ | `clavix fast/deep "prompt"` | Agent analyzes and saves to `.clavix/outputs/prompts/<id>.md` |
114
+ | `clavix execute --latest` | Agent lists prompts dir, finds newest, reads it |
115
+ | `clavix implement` | Agent follows `/clavix:implement` template |
116
+ | `clavix task-complete <id>` | Agent uses Edit tool on tasks.md |
117
+ | `clavix archive <name>` | Agent moves directory with Bash tool |
118
+ | `clavix prompts list` | Agent lists `.clavix/outputs/prompts/*.md` files |
@@ -87,10 +87,10 @@ These are issues you can't fix. Stop completely and explain what they need to do
87
87
  ### How to Explain Problems
88
88
 
89
89
  **Don't say this:**
90
- > "ENOENT: no such file or directory, open '.clavix/outputs/prompts/fast/.index.json'"
90
+ > "ENOENT: no such file or directory, open '.clavix/outputs/prompts/'"
91
91
 
92
92
  **Say this:**
93
- > "Setting up your prompt storage..." (then just create the file)
93
+ > "Setting up your prompt storage..." (then just create the directory)
94
94
 
95
95
  **Don't say this:**
96
96
  > "Error: EACCES: permission denied, mkdir '/usr/local/clavix'"
@@ -1,4 +1,4 @@
1
- ## File Format Reference
1
+ ## File Format Reference (v5 Agentic-First)
2
2
 
3
3
  ### .clavix-implement-config.json
4
4
 
@@ -37,8 +37,8 @@ Implementation state configuration file.
37
37
 
38
38
  **Agent Usage Rules:**
39
39
  - READ this file to determine current state
40
- - NEVER modify directly - use `clavix task-complete` to update
41
- - IF missing: Run `clavix implement` to initialize
40
+ - UPDATE using Edit tool when marking tasks complete
41
+ - IF missing: Create with initial state
42
42
  - IF corrupted: Report as UNRECOVERABLE error
43
43
 
44
44
  ### tasks.md Format
@@ -97,33 +97,46 @@ Created: {timestamp}
97
97
  - `Phase-1-Setup-1` - Must be lowercase
98
98
  - `phase-1-setup` - Missing task number
99
99
 
100
- ### .index.json (Prompts)
100
+ ### Prompt Files (v5 Format)
101
101
 
102
- Index file for saved prompts.
102
+ Individual prompt files with frontmatter metadata.
103
103
 
104
- **Location:** `.clavix/outputs/prompts/{type}/.index.json`
104
+ **Location:** `.clavix/outputs/prompts/<id>.md`
105
105
 
106
- **Schema:**
107
- ```json
108
- {
109
- "version": "1.0",
110
- "prompts": [
111
- {
112
- "id": "fast-20240115-103000-a1b2c3",
113
- "filename": "fast-20240115-103000-a1b2c3.md",
114
- "created": "2024-01-15T10:30:00.000Z",
115
- "intent": "code-generation",
116
- "quality": {
117
- "original": 42,
118
- "optimized": 78
119
- },
120
- "executed": false,
121
- "executedAt": null
122
- }
123
- ]
124
- }
106
+ **Format:**
107
+ ```markdown
108
+ ---
109
+ id: std-20250127-143022-a3f2
110
+ timestamp: 2025-01-27T14:30:22Z
111
+ executed: false
112
+ originalPrompt: "the user's original prompt text"
113
+ depthUsed: standard|comprehensive
114
+ ---
115
+
116
+ # Improved Prompt
117
+
118
+ <optimized prompt content>
119
+
120
+ ## Quality Scores
121
+ - **Clarity**: 85%
122
+ - **Efficiency**: 80%
123
+ - **Structure**: 90%
124
+ - **Completeness**: 75%
125
+ - **Actionability**: 88%
126
+ - **Overall**: 84% (good)
127
+
128
+ ## Original Prompt
129
+ ```
130
+ <user's original prompt>
131
+ ```
125
132
  ```
126
133
 
134
+ **Agent Usage:**
135
+ - LIST prompts: `ls .clavix/outputs/prompts/*.md`
136
+ - READ prompt: Use Read tool on `.clavix/outputs/prompts/<id>.md`
137
+ - FIND latest: Sort files by timestamp in filename
138
+ - MARK executed: Edit frontmatter to set `executed: true`
139
+
127
140
  ### PRD Files
128
141
 
129
142
  **Full PRD:** `.clavix/outputs/{project}/full-prd.md`
@@ -138,42 +151,13 @@ Index file for saved prompts.
138
151
  - From /clavix:summarize
139
152
  - Extracted from conversation
140
153
 
141
- ### Session Files
142
-
143
- **Location:** `.clavix/sessions/{session-id}.json`
144
-
145
- **Schema:**
146
- ```json
147
- {
148
- "id": "session-uuid",
149
- "projectName": "optional-name",
150
- "status": "active" | "completed",
151
- "created": "2024-01-15T10:00:00.000Z",
152
- "updated": "2024-01-15T11:30:00.000Z",
153
- "messages": [
154
- {
155
- "role": "user" | "assistant",
156
- "content": "message text",
157
- "timestamp": "2024-01-15T10:05:00.000Z"
158
- }
159
- ],
160
- "tags": ["feature", "auth"],
161
- "description": "Optional session description"
162
- }
163
- ```
164
-
165
- ### Directory Structure Overview
154
+ ### Directory Structure Overview (v5)
166
155
 
167
156
  ```
168
157
  .clavix/
169
158
  ├── outputs/
170
159
  │ ├── prompts/
171
- │ │ ├── fast/
172
- │ │ │ ├── .index.json
173
- │ │ │ └── fast-{timestamp}-{hash}.md
174
- │ │ └── deep/
175
- │ │ ├── .index.json
176
- │ │ └── deep-{timestamp}-{hash}.md
160
+ │ │ └── *.md # Prompt files (metadata in frontmatter)
177
161
  │ ├── {project-name}/
178
162
  │ │ ├── full-prd.md
179
163
  │ │ ├── quick-prd.md
@@ -181,7 +165,5 @@ Index file for saved prompts.
181
165
  │ │ └── .clavix-implement-config.json
182
166
  │ └── archive/
183
167
  │ └── {archived-project}/
184
- ├── sessions/
185
- │ └── {session-id}.json
186
- └── config.json (global config)
168
+ └── config.json # Global config
187
169
  ```
@@ -38,7 +38,7 @@ Implementation: [BLOCKED|ALLOWED]
38
38
  ```
39
39
  **CLAVIX MODE: Improve**
40
40
  Mode: planning
41
- Purpose: Optimizing user prompt with Clavix Intelligence
41
+ Purpose: Optimizing user prompt with pattern-based analysis
42
42
  Implementation: BLOCKED - I will analyze and improve the prompt, not implement it
43
43
  ```
44
44
 
@@ -1,6 +1,6 @@
1
1
  ## Intent Types Reference
2
2
 
3
- Clavix Intelligence™ detects 11 primary intent types. This reference is synchronized with `src/core/intelligence/types.ts`.
3
+ Clavix detects 11 primary intent types using pattern-based analysis. This reference is synchronized with `src/core/intelligence/types.ts`.
4
4
 
5
5
  ### Intent Categories
6
6