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.
- package/README.md +72 -60
- package/dist/cli/commands/update.js +9 -10
- package/dist/templates/agents/agents.md +14 -8
- package/dist/templates/agents/copilot-instructions.md +1 -1
- package/dist/templates/instructions/core/verification.md +2 -2
- package/dist/templates/slash-commands/_canonical/archive.md +83 -121
- package/dist/templates/slash-commands/_canonical/execute.md +32 -42
- package/dist/templates/slash-commands/_canonical/implement.md +32 -44
- package/dist/templates/slash-commands/_canonical/improve.md +14 -53
- package/dist/templates/slash-commands/_canonical/start.md +1 -1
- package/dist/templates/slash-commands/_canonical/summarize.md +8 -8
- package/dist/templates/slash-commands/_components/agent-protocols/cli-reference.md +84 -180
- package/dist/templates/slash-commands/_components/agent-protocols/error-handling.md +2 -2
- package/dist/templates/slash-commands/_components/agent-protocols/file-formats.md +41 -59
- package/dist/templates/slash-commands/_components/agent-protocols/state-assertion.md +1 -1
- package/dist/templates/slash-commands/_components/references/intent-types.md +1 -1
- package/dist/templates/slash-commands/_components/sections/file-saving-protocol.md +20 -27
- package/dist/templates/slash-commands/_components/sections/pattern-visibility.md +29 -46
- package/dist/templates/slash-commands/_components/troubleshooting/file-not-saved.md +4 -5
- package/dist/types/config.d.ts +57 -0
- package/dist/utils/legacy-command-cleanup.js +31 -4
- package/package.json +5 -4
- package/dist/cli/commands/analyze.d.ts +0 -17
- package/dist/cli/commands/analyze.js +0 -133
- package/dist/cli/commands/archive.d.ts +0 -36
- package/dist/cli/commands/archive.js +0 -266
- package/dist/cli/commands/deep.d.ts +0 -17
- package/dist/cli/commands/deep.js +0 -170
- package/dist/cli/commands/execute.d.ts +0 -15
- package/dist/cli/commands/execute.js +0 -168
- package/dist/cli/commands/fast.d.ts +0 -18
- package/dist/cli/commands/fast.js +0 -219
- package/dist/cli/commands/implement.d.ts +0 -24
- package/dist/cli/commands/implement.js +0 -289
- package/dist/cli/commands/improve.d.ts +0 -32
- package/dist/cli/commands/improve.js +0 -250
- package/dist/cli/commands/list.d.ts +0 -17
- package/dist/cli/commands/list.js +0 -217
- package/dist/cli/commands/plan.d.ts +0 -21
- package/dist/cli/commands/plan.js +0 -297
- package/dist/cli/commands/prd.d.ts +0 -24
- package/dist/cli/commands/prd.js +0 -321
- package/dist/cli/commands/prompts/clear.d.ts +0 -16
- package/dist/cli/commands/prompts/clear.js +0 -222
- package/dist/cli/commands/prompts/list.d.ts +0 -8
- package/dist/cli/commands/prompts/list.js +0 -88
- package/dist/cli/commands/show.d.ts +0 -21
- package/dist/cli/commands/show.js +0 -191
- package/dist/cli/commands/start.d.ts +0 -40
- package/dist/cli/commands/start.js +0 -210
- package/dist/cli/commands/summarize.d.ts +0 -17
- package/dist/cli/commands/summarize.js +0 -196
- package/dist/cli/commands/task-complete.d.ts +0 -27
- package/dist/cli/commands/task-complete.js +0 -269
- package/dist/cli/commands/verify.d.ts +0 -28
- package/dist/cli/commands/verify.js +0 -349
- package/dist/core/archive-manager.d.ts +0 -100
- package/dist/core/archive-manager.js +0 -302
- package/dist/core/basic-checklist-generator.d.ts +0 -35
- package/dist/core/basic-checklist-generator.js +0 -344
- package/dist/core/checklist-parser.d.ts +0 -48
- package/dist/core/checklist-parser.js +0 -238
- package/dist/core/config-manager.d.ts +0 -149
- package/dist/core/config-manager.js +0 -230
- package/dist/core/conversation-analyzer.d.ts +0 -86
- package/dist/core/conversation-analyzer.js +0 -387
- package/dist/core/conversation-quality-tracker.d.ts +0 -81
- package/dist/core/conversation-quality-tracker.js +0 -195
- package/dist/core/git-manager.d.ts +0 -126
- package/dist/core/git-manager.js +0 -282
- package/dist/core/intelligence/confidence-calculator.d.ts +0 -93
- package/dist/core/intelligence/confidence-calculator.js +0 -124
- package/dist/core/intelligence/index.d.ts +0 -11
- package/dist/core/intelligence/index.js +0 -15
- package/dist/core/intelligence/intent-detector.d.ts +0 -54
- package/dist/core/intelligence/intent-detector.js +0 -723
- package/dist/core/intelligence/pattern-library.d.ts +0 -104
- package/dist/core/intelligence/pattern-library.js +0 -339
- package/dist/core/intelligence/patterns/actionability-enhancer.d.ts +0 -27
- package/dist/core/intelligence/patterns/actionability-enhancer.js +0 -192
- package/dist/core/intelligence/patterns/alternative-phrasing-generator.d.ts +0 -29
- package/dist/core/intelligence/patterns/alternative-phrasing-generator.js +0 -239
- package/dist/core/intelligence/patterns/ambiguity-detector.d.ts +0 -22
- package/dist/core/intelligence/patterns/ambiguity-detector.js +0 -196
- package/dist/core/intelligence/patterns/assumption-explicitizer.d.ts +0 -30
- package/dist/core/intelligence/patterns/assumption-explicitizer.js +0 -296
- package/dist/core/intelligence/patterns/base-pattern.d.ts +0 -192
- package/dist/core/intelligence/patterns/base-pattern.js +0 -103
- package/dist/core/intelligence/patterns/completeness-validator.d.ts +0 -27
- package/dist/core/intelligence/patterns/completeness-validator.js +0 -221
- package/dist/core/intelligence/patterns/conciseness-filter.d.ts +0 -20
- package/dist/core/intelligence/patterns/conciseness-filter.js +0 -92
- package/dist/core/intelligence/patterns/context-precision.d.ts +0 -32
- package/dist/core/intelligence/patterns/context-precision.js +0 -389
- package/dist/core/intelligence/patterns/conversation-summarizer.d.ts +0 -30
- package/dist/core/intelligence/patterns/conversation-summarizer.js +0 -277
- package/dist/core/intelligence/patterns/dependency-identifier.d.ts +0 -23
- package/dist/core/intelligence/patterns/dependency-identifier.js +0 -166
- package/dist/core/intelligence/patterns/domain-context-enricher.d.ts +0 -21
- package/dist/core/intelligence/patterns/domain-context-enricher.js +0 -198
- package/dist/core/intelligence/patterns/edge-case-identifier.d.ts +0 -30
- package/dist/core/intelligence/patterns/edge-case-identifier.js +0 -269
- package/dist/core/intelligence/patterns/error-tolerance-enhancer.d.ts +0 -22
- package/dist/core/intelligence/patterns/error-tolerance-enhancer.js +0 -179
- package/dist/core/intelligence/patterns/implicit-requirement-extractor.d.ts +0 -24
- package/dist/core/intelligence/patterns/implicit-requirement-extractor.js +0 -259
- package/dist/core/intelligence/patterns/objective-clarifier.d.ts +0 -22
- package/dist/core/intelligence/patterns/objective-clarifier.js +0 -126
- package/dist/core/intelligence/patterns/output-format-enforcer.d.ts +0 -22
- package/dist/core/intelligence/patterns/output-format-enforcer.js +0 -151
- package/dist/core/intelligence/patterns/prd-structure-enforcer.d.ts +0 -23
- package/dist/core/intelligence/patterns/prd-structure-enforcer.js +0 -183
- package/dist/core/intelligence/patterns/prerequisite-identifier.d.ts +0 -23
- package/dist/core/intelligence/patterns/prerequisite-identifier.js +0 -221
- package/dist/core/intelligence/patterns/requirement-prioritizer.d.ts +0 -24
- package/dist/core/intelligence/patterns/requirement-prioritizer.js +0 -134
- package/dist/core/intelligence/patterns/scope-definer.d.ts +0 -26
- package/dist/core/intelligence/patterns/scope-definer.js +0 -236
- package/dist/core/intelligence/patterns/step-decomposer.d.ts +0 -31
- package/dist/core/intelligence/patterns/step-decomposer.js +0 -242
- package/dist/core/intelligence/patterns/structure-organizer.d.ts +0 -31
- package/dist/core/intelligence/patterns/structure-organizer.js +0 -218
- package/dist/core/intelligence/patterns/success-criteria-enforcer.d.ts +0 -22
- package/dist/core/intelligence/patterns/success-criteria-enforcer.js +0 -165
- package/dist/core/intelligence/patterns/success-metrics-enforcer.d.ts +0 -24
- package/dist/core/intelligence/patterns/success-metrics-enforcer.js +0 -165
- package/dist/core/intelligence/patterns/technical-context-enricher.d.ts +0 -25
- package/dist/core/intelligence/patterns/technical-context-enricher.js +0 -165
- package/dist/core/intelligence/patterns/topic-coherence-analyzer.d.ts +0 -26
- package/dist/core/intelligence/patterns/topic-coherence-analyzer.js +0 -300
- package/dist/core/intelligence/patterns/user-persona-enricher.d.ts +0 -24
- package/dist/core/intelligence/patterns/user-persona-enricher.js +0 -141
- package/dist/core/intelligence/patterns/validation-checklist-creator.d.ts +0 -31
- package/dist/core/intelligence/patterns/validation-checklist-creator.js +0 -242
- package/dist/core/intelligence/quality-assessor.d.ts +0 -51
- package/dist/core/intelligence/quality-assessor.js +0 -505
- package/dist/core/intelligence/types.d.ts +0 -111
- package/dist/core/intelligence/types.js +0 -3
- package/dist/core/intelligence/universal-optimizer.d.ts +0 -84
- package/dist/core/intelligence/universal-optimizer.js +0 -371
- package/dist/core/prd-generator.d.ts +0 -76
- package/dist/core/prd-generator.js +0 -173
- package/dist/core/prompt-manager.d.ts +0 -110
- package/dist/core/prompt-manager.js +0 -274
- package/dist/core/prompt-optimizer.d.ts +0 -268
- package/dist/core/prompt-optimizer.js +0 -959
- package/dist/core/question-engine.d.ts +0 -167
- package/dist/core/question-engine.js +0 -356
- package/dist/core/session-manager.d.ts +0 -139
- package/dist/core/session-manager.js +0 -365
- package/dist/core/task-manager.d.ts +0 -211
- package/dist/core/task-manager.js +0 -981
- package/dist/core/verification-hooks.d.ts +0 -67
- package/dist/core/verification-hooks.js +0 -309
- package/dist/core/verification-manager.d.ts +0 -107
- package/dist/core/verification-manager.js +0 -415
- package/dist/index 2.js +0 -13
- package/dist/index.d 2.ts +0 -4
- package/dist/types/session.d.ts +0 -78
- package/dist/types/session.js +0 -8
- package/dist/types/verification.d.ts +0 -205
- 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
|
|
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 |
|
|
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-
|
|
442
|
+
**After completing Steps 1-3, you MUST verify the save succeeded.**
|
|
471
443
|
|
|
472
|
-
### Verification
|
|
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
|
|
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
|
-
- [ ]
|
|
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
|
-
**
|
|
542
|
-
-
|
|
543
|
-
-
|
|
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 (
|
|
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:
|
|
590
|
-
|
|
591
|
-
|
|
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
|
|
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
|
|
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
|
|
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
|
-
##
|
|
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. **
|
|
277
|
-
- After extracting the prompt, analyze using
|
|
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
|
|
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
|
-
**🎯
|
|
328
|
-
Applied [N]
|
|
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 (
|
|
1
|
+
## CLI Commands Reference (v5.0 - Agentic-First)
|
|
2
2
|
|
|
3
|
-
|
|
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
|
-
###
|
|
9
|
+
### Setup Commands (User runs these)
|
|
8
10
|
|
|
9
|
-
|
|
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
|
|
19
|
-
**What it does:**
|
|
20
|
-
**When
|
|
21
|
-
**
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
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
|
|
28
|
-
**What it does:**
|
|
29
|
-
**When
|
|
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
|
-
- `--
|
|
26
|
+
- `--docs-only` - Update only documentation
|
|
27
|
+
- `--commands-only` - Update only slash commands
|
|
38
28
|
|
|
39
|
-
#### `clavix
|
|
40
|
-
**What it does:**
|
|
41
|
-
**
|
|
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
|
|
51
|
-
**What it does:**
|
|
52
|
-
**
|
|
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
|
|
56
|
-
**What it does:**
|
|
57
|
-
**
|
|
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
|
-
###
|
|
43
|
+
### How Workflows Execute (Agentic-First)
|
|
63
44
|
|
|
64
|
-
|
|
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
|
-
|
|
97
|
-
|
|
98
|
-
**
|
|
99
|
-
**
|
|
100
|
-
**
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
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
|
-
###
|
|
59
|
+
### Agent Execution Protocol (v5)
|
|
111
60
|
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
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
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
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
|
-
|
|
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
|
-
|
|
186
|
-
|
|
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
|
-
###
|
|
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
|
-
|
|
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
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
210
|
-
Agent
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
|
|
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/
|
|
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
|
|
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
|
-
-
|
|
41
|
-
- IF missing:
|
|
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
|
-
###
|
|
100
|
+
### Prompt Files (v5 Format)
|
|
101
101
|
|
|
102
|
-
|
|
102
|
+
Individual prompt files with frontmatter metadata.
|
|
103
103
|
|
|
104
|
-
**Location:** `.clavix/outputs/prompts
|
|
104
|
+
**Location:** `.clavix/outputs/prompts/<id>.md`
|
|
105
105
|
|
|
106
|
-
**
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
117
|
-
|
|
118
|
-
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
|
|
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
|
-
###
|
|
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
|
-
│ │
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
|