clavix 5.1.0 → 5.1.1
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/dist/cli/commands/config.js +1 -1
- package/dist/core/adapters/gemini-adapter.js +3 -1
- package/dist/core/adapters/llxprt-adapter.js +3 -1
- package/dist/templates/slash-commands/_canonical/archive.md +4 -7
- package/dist/templates/slash-commands/_canonical/implement.md +4 -7
- package/dist/templates/slash-commands/_canonical/improve.md +4 -7
- package/dist/templates/slash-commands/_canonical/plan.md +4 -7
- package/dist/templates/slash-commands/_canonical/prd.md +4 -7
- package/dist/templates/slash-commands/_canonical/start.md +3 -6
- package/dist/templates/slash-commands/_canonical/summarize.md +3 -6
- package/dist/templates/slash-commands/_canonical/verify.md +4 -7
- package/dist/templates/slash-commands/_components/agent-protocols/AGENT_MANUAL.md +284 -0
- package/dist/types/agent.d.ts +0 -4
- package/dist/types/config.js +1 -1
- package/dist/utils/agent-error-messages.d.ts +5 -5
- package/dist/utils/agent-error-messages.js +5 -5
- package/dist/utils/error-utils.d.ts +1 -7
- package/dist/utils/error-utils.js +12 -11
- package/dist/utils/toml-templates.js +4 -1
- package/package.json +2 -7
|
@@ -420,7 +420,7 @@ export default class Config extends Command {
|
|
|
420
420
|
}
|
|
421
421
|
displayConfig(config) {
|
|
422
422
|
this.log(` ${chalk.gray('Version:')} ${config.version}`);
|
|
423
|
-
this.log(` ${chalk.gray('Integrations:')} ${config.integrations.map(p => chalk.cyan(p)).join(', ') || chalk.gray('(none)')}`);
|
|
423
|
+
this.log(` ${chalk.gray('Integrations:')} ${config.integrations.map((p) => chalk.cyan(p)).join(', ') || chalk.gray('(none)')}`);
|
|
424
424
|
if (config.preferences) {
|
|
425
425
|
this.log(`\n ${chalk.bold('Preferences:')}`);
|
|
426
426
|
this.log(` ${chalk.gray('Auto-open outputs:')} ${config.preferences.autoOpenOutputs ? chalk.green('yes') : chalk.gray('no')}`);
|
|
@@ -22,7 +22,9 @@ export class GeminiAdapter extends BaseAdapter {
|
|
|
22
22
|
}
|
|
23
23
|
get directory() {
|
|
24
24
|
const useNamespace = this.options.useNamespace ?? true;
|
|
25
|
-
return useNamespace
|
|
25
|
+
return useNamespace
|
|
26
|
+
? path.join('.gemini', 'commands', 'clavix')
|
|
27
|
+
: path.join('.gemini', 'commands');
|
|
26
28
|
}
|
|
27
29
|
async detectProject() {
|
|
28
30
|
if (await FileSystem.exists('.gemini')) {
|
|
@@ -22,7 +22,9 @@ export class LlxprtAdapter extends BaseAdapter {
|
|
|
22
22
|
}
|
|
23
23
|
get directory() {
|
|
24
24
|
const useNamespace = this.options.useNamespace ?? true;
|
|
25
|
-
return useNamespace
|
|
25
|
+
return useNamespace
|
|
26
|
+
? path.join('.llxprt', 'commands', 'clavix')
|
|
27
|
+
: path.join('.llxprt', 'commands');
|
|
26
28
|
}
|
|
27
29
|
async detectProject() {
|
|
28
30
|
if (await FileSystem.exists('.llxprt')) {
|
|
@@ -234,18 +234,15 @@ Result: Project permanently deleted
|
|
|
234
234
|
|
|
235
235
|
## Agent Transparency (v5.1)
|
|
236
236
|
|
|
237
|
-
###
|
|
238
|
-
{{INCLUDE:agent-protocols/
|
|
237
|
+
### Agent Manual (Universal Protocols)
|
|
238
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
239
239
|
|
|
240
|
-
###
|
|
241
|
-
{{INCLUDE:agent-protocols/
|
|
240
|
+
### CLI Reference
|
|
241
|
+
{{INCLUDE:agent-protocols/cli-reference.md}}
|
|
242
242
|
|
|
243
243
|
### Recovery Patterns
|
|
244
244
|
{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
|
|
245
245
|
|
|
246
|
-
### Agent Decision Rules
|
|
247
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
248
|
-
|
|
249
246
|
## Workflow Navigation
|
|
250
247
|
|
|
251
248
|
**You are here:** Archive (Project Cleanup)
|
|
@@ -473,21 +473,18 @@ I'll explain what's wrong and what you might need to do:
|
|
|
473
473
|
|
|
474
474
|
## Agent Transparency (v5.1)
|
|
475
475
|
|
|
476
|
+
### Agent Manual (Universal Protocols)
|
|
477
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
478
|
+
|
|
476
479
|
### Workflow State Detection
|
|
477
480
|
{{INCLUDE:agent-protocols/state-awareness.md}}
|
|
478
481
|
|
|
479
|
-
### Error Handling
|
|
480
|
-
{{INCLUDE:agent-protocols/error-handling.md}}
|
|
481
|
-
|
|
482
482
|
### Task Blocking Protocol
|
|
483
483
|
{{INCLUDE:agent-protocols/task-blocking.md}}
|
|
484
484
|
|
|
485
|
-
### CLI Reference
|
|
485
|
+
### CLI Reference
|
|
486
486
|
{{INCLUDE:agent-protocols/cli-reference.md}}
|
|
487
487
|
|
|
488
|
-
### Agent Decision Rules
|
|
489
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
490
|
-
|
|
491
488
|
### Recovery Patterns
|
|
492
489
|
{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
|
|
493
490
|
|
|
@@ -508,7 +508,10 @@ Wait for the user to decide what to do next.
|
|
|
508
508
|
|
|
509
509
|
## Agent Transparency (v5.1)
|
|
510
510
|
|
|
511
|
-
###
|
|
511
|
+
### Agent Manual (Universal Protocols)
|
|
512
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
513
|
+
|
|
514
|
+
### CLI Reference
|
|
512
515
|
{{INCLUDE:agent-protocols/cli-reference.md}}
|
|
513
516
|
|
|
514
517
|
### How to Explain Improvements
|
|
@@ -523,12 +526,6 @@ Wait for the user to decide what to do next.
|
|
|
523
526
|
### What Made the Biggest Difference
|
|
524
527
|
{{INCLUDE:sections/pattern-impact.md}}
|
|
525
528
|
|
|
526
|
-
### Agent Decision Rules
|
|
527
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
528
|
-
|
|
529
|
-
### Error Handling
|
|
530
|
-
{{INCLUDE:agent-protocols/error-handling.md}}
|
|
531
|
-
|
|
532
529
|
---
|
|
533
530
|
|
|
534
531
|
## Tips
|
|
@@ -291,18 +291,15 @@ The generated `tasks.md` will look like:
|
|
|
291
291
|
|
|
292
292
|
## Agent Transparency (v5.1)
|
|
293
293
|
|
|
294
|
+
### Agent Manual (Universal Protocols)
|
|
295
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
296
|
+
|
|
294
297
|
### Workflow State Detection
|
|
295
298
|
{{INCLUDE:agent-protocols/state-awareness.md}}
|
|
296
299
|
|
|
297
|
-
### CLI Reference
|
|
300
|
+
### CLI Reference
|
|
298
301
|
{{INCLUDE:agent-protocols/cli-reference.md}}
|
|
299
302
|
|
|
300
|
-
### Agent Decision Rules
|
|
301
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
302
|
-
|
|
303
|
-
### Error Handling
|
|
304
|
-
{{INCLUDE:agent-protocols/error-handling.md}}
|
|
305
|
-
|
|
306
303
|
### Recovery Patterns
|
|
307
304
|
{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
|
|
308
305
|
|
|
@@ -330,6 +330,9 @@ The validation ensures generated PRDs are immediately usable for AI consumption
|
|
|
330
330
|
|
|
331
331
|
## Agent Transparency (v5.1)
|
|
332
332
|
|
|
333
|
+
### Agent Manual (Universal Protocols)
|
|
334
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
335
|
+
|
|
333
336
|
### PRD Examples
|
|
334
337
|
{{INCLUDE:sections/prd-examples.md}}
|
|
335
338
|
|
|
@@ -339,15 +342,9 @@ The validation ensures generated PRDs are immediately usable for AI consumption
|
|
|
339
342
|
### Workflow State Detection
|
|
340
343
|
{{INCLUDE:agent-protocols/state-awareness.md}}
|
|
341
344
|
|
|
342
|
-
### CLI Reference
|
|
345
|
+
### CLI Reference
|
|
343
346
|
{{INCLUDE:agent-protocols/cli-reference.md}}
|
|
344
347
|
|
|
345
|
-
### Agent Decision Rules
|
|
346
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
347
|
-
|
|
348
|
-
### Error Handling
|
|
349
|
-
{{INCLUDE:agent-protocols/error-handling.md}}
|
|
350
|
-
|
|
351
348
|
---
|
|
352
349
|
|
|
353
350
|
## Troubleshooting
|
|
@@ -204,18 +204,15 @@ The goal is natural exploration of requirements, not a rigid questionnaire. Foll
|
|
|
204
204
|
|
|
205
205
|
## Agent Transparency (v5.1)
|
|
206
206
|
|
|
207
|
+
### Agent Manual (Universal Protocols)
|
|
208
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
209
|
+
|
|
207
210
|
### Conversational Companion
|
|
208
211
|
{{INCLUDE:agent-protocols/supportive-companion.md}}
|
|
209
212
|
|
|
210
213
|
### Conversation Examples
|
|
211
214
|
{{INCLUDE:sections/conversation-examples.md}}
|
|
212
215
|
|
|
213
|
-
### Agent Decision Rules
|
|
214
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
215
|
-
|
|
216
|
-
### Error Handling
|
|
217
|
-
{{INCLUDE:agent-protocols/error-handling.md}}
|
|
218
|
-
|
|
219
216
|
### Recovery Patterns
|
|
220
217
|
{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
|
|
221
218
|
|
|
@@ -373,6 +373,9 @@ Implementation: BLOCKED - I will extract requirements, not implement them
|
|
|
373
373
|
|
|
374
374
|
## Agent Transparency (v5.1)
|
|
375
375
|
|
|
376
|
+
### Agent Manual (Universal Protocols)
|
|
377
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
378
|
+
|
|
376
379
|
### How to Explain Improvements
|
|
377
380
|
{{INCLUDE:sections/improvement-explanations.md}}
|
|
378
381
|
|
|
@@ -382,12 +385,6 @@ Implementation: BLOCKED - I will extract requirements, not implement them
|
|
|
382
385
|
### Workflow State Detection
|
|
383
386
|
{{INCLUDE:agent-protocols/state-awareness.md}}
|
|
384
387
|
|
|
385
|
-
### Agent Decision Rules
|
|
386
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
387
|
-
|
|
388
|
-
### Error Handling
|
|
389
|
-
{{INCLUDE:agent-protocols/error-handling.md}}
|
|
390
|
-
|
|
391
388
|
### Recovery Patterns
|
|
392
389
|
{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
|
|
393
390
|
|
|
@@ -388,18 +388,15 @@ I generate different checklists based on what you're building:
|
|
|
388
388
|
|
|
389
389
|
## Agent Transparency (v5.1)
|
|
390
390
|
|
|
391
|
-
###
|
|
392
|
-
{{INCLUDE:agent-protocols/
|
|
391
|
+
### Agent Manual (Universal Protocols)
|
|
392
|
+
{{INCLUDE:agent-protocols/AGENT_MANUAL.md}}
|
|
393
393
|
|
|
394
|
-
###
|
|
395
|
-
{{INCLUDE:agent-protocols/
|
|
394
|
+
### CLI Reference
|
|
395
|
+
{{INCLUDE:agent-protocols/cli-reference.md}}
|
|
396
396
|
|
|
397
397
|
### Recovery Patterns
|
|
398
398
|
{{INCLUDE:troubleshooting/vibecoder-recovery.md}}
|
|
399
399
|
|
|
400
|
-
### Agent Decision Rules
|
|
401
|
-
{{INCLUDE:agent-protocols/decision-rules.md}}
|
|
402
|
-
|
|
403
400
|
---
|
|
404
401
|
|
|
405
402
|
## Verification Confidence Levels
|
|
@@ -0,0 +1,284 @@
|
|
|
1
|
+
# Clavix Agent Manual (v5.1)
|
|
2
|
+
|
|
3
|
+
This is the consolidated agent protocol reference. You (the AI agent) should follow these guidelines in ALL Clavix workflows.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## Core Principle: Agentic-First Architecture
|
|
8
|
+
|
|
9
|
+
Clavix v5 follows an **agentic-first architecture**. This means:
|
|
10
|
+
|
|
11
|
+
1. **You execute workflows directly** using your native tools (Write, Read, Edit, Bash)
|
|
12
|
+
2. **Slash commands are templates** that you read and follow - not CLI commands
|
|
13
|
+
3. **CLI commands are ONLY for setup** (`clavix init`, `clavix update`, `clavix config`)
|
|
14
|
+
4. **You save outputs to `.clavix/outputs/`** using your Write tool
|
|
15
|
+
|
|
16
|
+
**DO NOT:**
|
|
17
|
+
- Try to run `clavix` CLI commands during workflows (they don't exist for workflows)
|
|
18
|
+
- Ask the user to run terminal commands for workflow operations
|
|
19
|
+
- Skip verification after completing work
|
|
20
|
+
|
|
21
|
+
---
|
|
22
|
+
|
|
23
|
+
## File System Structure
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
.clavix/
|
|
27
|
+
├── config.json # Project configuration
|
|
28
|
+
├── outputs/
|
|
29
|
+
│ ├── prompts/ # Saved prompts from /clavix:improve
|
|
30
|
+
│ │ └── *.md # Individual prompts (metadata in frontmatter)
|
|
31
|
+
│ ├── <project-name>/ # PRD projects
|
|
32
|
+
│ │ ├── full-prd.md # Comprehensive PRD
|
|
33
|
+
│ │ ├── quick-prd.md # AI-optimized summary
|
|
34
|
+
│ │ └── tasks.md # Implementation tasks
|
|
35
|
+
│ └── archive/ # Archived projects
|
|
36
|
+
└── commands/ # Slash command templates (managed by clavix update)
|
|
37
|
+
```
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
## REQUIRED: Output Verification Protocol
|
|
42
|
+
|
|
43
|
+
**After EVERY file operation, verify success:**
|
|
44
|
+
|
|
45
|
+
| Step | Action | How to Verify |
|
|
46
|
+
|------|--------|---------------|
|
|
47
|
+
| 1 | Write file | Use Write tool |
|
|
48
|
+
| 2 | Verify exists | Use Read tool to confirm file was created |
|
|
49
|
+
| 3 | Report to user | Show ACTUAL file path (not placeholder) |
|
|
50
|
+
|
|
51
|
+
**⚠️ Never tell the user a file was saved without verifying it exists.**
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
## Handling Problems Gracefully
|
|
56
|
+
|
|
57
|
+
When something goes wrong, fix it yourself when possible. When you can't, explain simply and offer options.
|
|
58
|
+
|
|
59
|
+
### Three Types of Problems
|
|
60
|
+
|
|
61
|
+
#### 1. Small Hiccups (Fix Yourself)
|
|
62
|
+
|
|
63
|
+
These are minor issues you can handle automatically. Fix them and move on.
|
|
64
|
+
|
|
65
|
+
| What Happened | What You Do |
|
|
66
|
+
|---------------|-------------|
|
|
67
|
+
| Folder doesn't exist | Create it |
|
|
68
|
+
| Index file missing | Create empty one |
|
|
69
|
+
| No saved prompts yet | Normal state - inform user |
|
|
70
|
+
| Old settings file | Still works - use it |
|
|
71
|
+
|
|
72
|
+
**Your approach:**
|
|
73
|
+
1. Fix the issue automatically
|
|
74
|
+
2. Maybe mention it briefly: "Setting things up..."
|
|
75
|
+
3. Continue with what you were doing
|
|
76
|
+
|
|
77
|
+
#### 2. Need User Input (Ask Nicely)
|
|
78
|
+
|
|
79
|
+
These need a decision from the user. Stop, explain simply, and offer clear choices.
|
|
80
|
+
|
|
81
|
+
| What Happened | What You Ask |
|
|
82
|
+
|---------------|--------------|
|
|
83
|
+
| Can't find that task | "I can't find task [X]. Let me show you what's available..." |
|
|
84
|
+
| Multiple projects found | "I found a few projects. Which one should we work on?" |
|
|
85
|
+
| Not sure what you want | "I want to make sure I understand - is this about [A] or [B]?" |
|
|
86
|
+
| File already exists | "This file already exists. Replace, rename, or cancel?" |
|
|
87
|
+
|
|
88
|
+
**Your approach:**
|
|
89
|
+
1. Stop what you're doing
|
|
90
|
+
2. Explain the situation simply
|
|
91
|
+
3. Give 2-3 clear options
|
|
92
|
+
4. Wait for their answer
|
|
93
|
+
|
|
94
|
+
#### 3. Real Problems (Need Their Help)
|
|
95
|
+
|
|
96
|
+
These are issues you can't fix. Stop completely and explain what they need to do.
|
|
97
|
+
|
|
98
|
+
| What Happened | What You Say |
|
|
99
|
+
|---------------|--------------|
|
|
100
|
+
| Permission denied | "I can't write to that folder - it looks like a permissions issue." |
|
|
101
|
+
| Config file broken | "Settings file got corrupted. You might need to delete it and start fresh." |
|
|
102
|
+
| Git conflict | "There's a git conflict that needs your attention." |
|
|
103
|
+
| Disk full | "Disk is full - I can't save anything." |
|
|
104
|
+
|
|
105
|
+
**Your approach:**
|
|
106
|
+
1. Stop immediately
|
|
107
|
+
2. Explain what went wrong (simply!)
|
|
108
|
+
3. Tell them what needs to happen to fix it
|
|
109
|
+
|
|
110
|
+
### The Golden Rules
|
|
111
|
+
|
|
112
|
+
1. **Fix it yourself if you can** - Don't bother users with small stuff
|
|
113
|
+
2. **Explain simply when you can't** - No error codes, no jargon
|
|
114
|
+
3. **Always offer a path forward** - Never leave them stuck
|
|
115
|
+
4. **Preserve their work** - Never lose what they've done
|
|
116
|
+
5. **Stay calm and friendly** - Problems happen, no big deal
|
|
117
|
+
|
|
118
|
+
---
|
|
119
|
+
|
|
120
|
+
## Agent Decision Rules
|
|
121
|
+
|
|
122
|
+
These rules define deterministic agent behavior. Follow exactly.
|
|
123
|
+
|
|
124
|
+
### Rule 1: Quality-Based Decisions
|
|
125
|
+
|
|
126
|
+
```
|
|
127
|
+
IF quality < 60%:
|
|
128
|
+
→ ACTION: Suggest comprehensive analysis
|
|
129
|
+
→ SAY: "Quality is [X]%. Consider comprehensive depth."
|
|
130
|
+
|
|
131
|
+
IF quality >= 60% AND quality < 80%:
|
|
132
|
+
→ ACTION: Proceed with optimization
|
|
133
|
+
→ SHOW: Improvement suggestions
|
|
134
|
+
|
|
135
|
+
IF quality >= 80%:
|
|
136
|
+
→ ACTION: Ready to use
|
|
137
|
+
→ SAY: "Quality is good ([X]%). Ready to proceed."
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
### Rule 2: Intent Confidence
|
|
141
|
+
|
|
142
|
+
```
|
|
143
|
+
IF confidence >= 85%:
|
|
144
|
+
→ ACTION: Proceed with detected intent
|
|
145
|
+
|
|
146
|
+
IF confidence 70-84%:
|
|
147
|
+
→ ACTION: Proceed, note secondary intent if >25%
|
|
148
|
+
|
|
149
|
+
IF confidence 50-69%:
|
|
150
|
+
→ ACTION: Ask user to confirm
|
|
151
|
+
|
|
152
|
+
IF confidence < 50%:
|
|
153
|
+
→ ACTION: Cannot proceed autonomously
|
|
154
|
+
→ ASK: "I'm unclear on intent. Is this: [A] | [B] | [C]?"
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
### Rule 3: File Operations
|
|
158
|
+
|
|
159
|
+
```
|
|
160
|
+
BEFORE writing files:
|
|
161
|
+
→ CHECK: Target directory exists
|
|
162
|
+
→ IF not exists: Create directory first
|
|
163
|
+
|
|
164
|
+
AFTER writing files:
|
|
165
|
+
→ VERIFY: File was created successfully
|
|
166
|
+
→ IF failed: Report error, suggest manual action
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
### Rule 4: Task Completion (Implementation Mode)
|
|
170
|
+
|
|
171
|
+
```
|
|
172
|
+
AFTER implementing task:
|
|
173
|
+
→ EDIT tasks.md: Change - [ ] to - [x] for completed task
|
|
174
|
+
|
|
175
|
+
IF edit succeeds:
|
|
176
|
+
→ SHOW: Next task automatically
|
|
177
|
+
→ CONTINUE with next task
|
|
178
|
+
|
|
179
|
+
IF edit fails:
|
|
180
|
+
→ SHOW error to user
|
|
181
|
+
→ ASK: "Task completion failed. How to proceed?"
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
### Rule 5: Error Recovery
|
|
185
|
+
|
|
186
|
+
```
|
|
187
|
+
IF pattern application fails:
|
|
188
|
+
→ LOG: Which pattern failed
|
|
189
|
+
→ CONTINUE: With remaining patterns
|
|
190
|
+
→ REPORT: "Pattern [X] skipped due to error"
|
|
191
|
+
|
|
192
|
+
IF file write fails:
|
|
193
|
+
→ RETRY: Once with alternative path
|
|
194
|
+
→ IF still fails: Report error with manual steps
|
|
195
|
+
|
|
196
|
+
IF user prompt is empty/invalid:
|
|
197
|
+
→ ASK: For valid input
|
|
198
|
+
→ NEVER: Proceed with assumption
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
### Rule 6: Execution Verification
|
|
202
|
+
|
|
203
|
+
```
|
|
204
|
+
BEFORE completing response:
|
|
205
|
+
→ VERIFY all checkpoints met for current mode
|
|
206
|
+
→ IF any checkpoint failed:
|
|
207
|
+
→ REPORT which checkpoint failed
|
|
208
|
+
→ EXPLAIN why it failed
|
|
209
|
+
→ SUGGEST recovery action
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
---
|
|
213
|
+
|
|
214
|
+
## What You Should NEVER Do
|
|
215
|
+
|
|
216
|
+
❌ **Don't silently skip tasks** - Always tell user if something was skipped
|
|
217
|
+
❌ **Don't make assumptions** - When in doubt, ask
|
|
218
|
+
❌ **Don't give up too easily** - Try to recover first
|
|
219
|
+
❌ **Don't overwhelm with options** - Max 3 choices
|
|
220
|
+
❌ **Don't use technical language** - Keep it friendly
|
|
221
|
+
❌ **Don't blame the user** - Even if they caused the issue
|
|
222
|
+
❌ **Don't claim features don't exist** - Check before saying no
|
|
223
|
+
❌ **Don't output "saved" without verification** - That's lying to the user
|
|
224
|
+
|
|
225
|
+
---
|
|
226
|
+
|
|
227
|
+
## Mode Boundaries
|
|
228
|
+
|
|
229
|
+
Each Clavix command has a specific mode. Stay within your mode:
|
|
230
|
+
|
|
231
|
+
| Mode | What You DO | What You DON'T DO |
|
|
232
|
+
|------|-------------|-------------------|
|
|
233
|
+
| **Improve** | Analyze and optimize prompts | Implement the feature described |
|
|
234
|
+
| **PRD** | Guide strategic questions, create PRD | Write implementation code |
|
|
235
|
+
| **Plan** | Generate task breakdown | Start implementing tasks |
|
|
236
|
+
| **Implement** | Build tasks/prompts | Skip to next task without marking complete |
|
|
237
|
+
| **Start** | Gather requirements conversationally | Start implementing |
|
|
238
|
+
| **Summarize** | Extract requirements from conversation | Implement the requirements |
|
|
239
|
+
| **Verify** | Check implementation, run tests | Fix issues (only report them) |
|
|
240
|
+
| **Archive** | Move completed projects | Delete without confirmation |
|
|
241
|
+
|
|
242
|
+
**If you catch yourself crossing mode boundaries:**
|
|
243
|
+
1. STOP immediately
|
|
244
|
+
2. Say: "I apologize - I was [mistake]. Let me return to [correct mode]."
|
|
245
|
+
3. Resume correct workflow
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
## Communication Style
|
|
250
|
+
|
|
251
|
+
**Don't say this:**
|
|
252
|
+
> "ENOENT: no such file or directory, open '.clavix/outputs/prompts/'"
|
|
253
|
+
|
|
254
|
+
**Say this:**
|
|
255
|
+
> "Setting up your prompt storage..." (then just create the directory)
|
|
256
|
+
|
|
257
|
+
**Don't say this:**
|
|
258
|
+
> "Error: EACCES: permission denied"
|
|
259
|
+
|
|
260
|
+
**Say this:**
|
|
261
|
+
> "I can't create files in that location - it needs different permissions."
|
|
262
|
+
|
|
263
|
+
**Don't say this:**
|
|
264
|
+
> "SyntaxError: Unexpected token } in JSON"
|
|
265
|
+
|
|
266
|
+
**Say this:**
|
|
267
|
+
> "The settings file got corrupted. I can start fresh if you want."
|
|
268
|
+
|
|
269
|
+
---
|
|
270
|
+
|
|
271
|
+
## Verification Block Template
|
|
272
|
+
|
|
273
|
+
At the end of workflows that produce output, include verification:
|
|
274
|
+
|
|
275
|
+
```
|
|
276
|
+
## Clavix Execution Verification
|
|
277
|
+
- [x] Mode: {improve|prd|plan|implement|verify|archive}
|
|
278
|
+
- [x] Output created: {actual file path}
|
|
279
|
+
- [x] Verification: {how you verified it exists}
|
|
280
|
+
```
|
|
281
|
+
|
|
282
|
+
---
|
|
283
|
+
|
|
284
|
+
*This manual is included in all Clavix slash command templates. Version 5.1*
|
package/dist/types/agent.d.ts
CHANGED
|
@@ -26,10 +26,6 @@ export interface IntegrationFeatures {
|
|
|
26
26
|
separator: ':' | '-';
|
|
27
27
|
};
|
|
28
28
|
}
|
|
29
|
-
/**
|
|
30
|
-
* @deprecated Use IntegrationFeatures instead. Will be removed in v4.0.0
|
|
31
|
-
*/
|
|
32
|
-
export type ProviderFeatures = IntegrationFeatures;
|
|
33
29
|
export interface ValidationResult {
|
|
34
30
|
valid: boolean;
|
|
35
31
|
errors?: string[];
|
package/dist/types/config.js
CHANGED
|
@@ -20,12 +20,12 @@ export declare class AgentErrorMessages {
|
|
|
20
20
|
static noTasksFound(projectName: string): string;
|
|
21
21
|
/**
|
|
22
22
|
* Error: .clavix-implement-config.json not found
|
|
23
|
-
* Used by:
|
|
23
|
+
* Used by: implement workflow
|
|
24
24
|
*/
|
|
25
25
|
static configNotFound(): string;
|
|
26
26
|
/**
|
|
27
27
|
* Error: Specified task ID not found in tasks.md
|
|
28
|
-
* Used by:
|
|
28
|
+
* Used by: implement workflow
|
|
29
29
|
*/
|
|
30
30
|
static taskNotFound(taskId: string, availableTasks: Array<{
|
|
31
31
|
id: string;
|
|
@@ -54,7 +54,7 @@ export declare class AgentErrorMessages {
|
|
|
54
54
|
static tasksExistWithProgress(completedCount: number, totalCount: number): string;
|
|
55
55
|
/**
|
|
56
56
|
* Error: Git repository not initialized
|
|
57
|
-
* Used by: implement
|
|
57
|
+
* Used by: implement workflow when git features expected
|
|
58
58
|
*/
|
|
59
59
|
static gitNotInitialized(): string;
|
|
60
60
|
/**
|
|
@@ -74,7 +74,7 @@ export declare class AgentErrorMessages {
|
|
|
74
74
|
static cliExecutionFailed(command: string, exitCode: number, stderr?: string): string;
|
|
75
75
|
/**
|
|
76
76
|
* Error: Invalid task ID format
|
|
77
|
-
* Used by:
|
|
77
|
+
* Used by: implement workflow
|
|
78
78
|
*/
|
|
79
79
|
static invalidTaskIdFormat(taskId: string): string;
|
|
80
80
|
/**
|
|
@@ -84,7 +84,7 @@ export declare class AgentErrorMessages {
|
|
|
84
84
|
static sessionNotFound(sessionId: string): string;
|
|
85
85
|
/**
|
|
86
86
|
* Warning: Task already completed
|
|
87
|
-
* Used by:
|
|
87
|
+
* Used by: implement workflow when marking already-done task
|
|
88
88
|
*/
|
|
89
89
|
static taskAlreadyCompleted(taskId: string): string;
|
|
90
90
|
}
|
|
@@ -33,7 +33,7 @@ export class AgentErrorMessages {
|
|
|
33
33
|
}
|
|
34
34
|
/**
|
|
35
35
|
* Error: .clavix-implement-config.json not found
|
|
36
|
-
* Used by:
|
|
36
|
+
* Used by: implement workflow
|
|
37
37
|
*/
|
|
38
38
|
static configNotFound() {
|
|
39
39
|
return ('Configuration file not found: .clavix-implement-config.json\n\n' +
|
|
@@ -45,7 +45,7 @@ export class AgentErrorMessages {
|
|
|
45
45
|
}
|
|
46
46
|
/**
|
|
47
47
|
* Error: Specified task ID not found in tasks.md
|
|
48
|
-
* Used by:
|
|
48
|
+
* Used by: implement workflow
|
|
49
49
|
*/
|
|
50
50
|
static taskNotFound(taskId, availableTasks) {
|
|
51
51
|
const taskList = availableTasks
|
|
@@ -114,7 +114,7 @@ export class AgentErrorMessages {
|
|
|
114
114
|
}
|
|
115
115
|
/**
|
|
116
116
|
* Error: Git repository not initialized
|
|
117
|
-
* Used by: implement
|
|
117
|
+
* Used by: implement workflow when git features expected
|
|
118
118
|
*/
|
|
119
119
|
static gitNotInitialized() {
|
|
120
120
|
return ('Git repository not detected\n\n' +
|
|
@@ -168,7 +168,7 @@ export class AgentErrorMessages {
|
|
|
168
168
|
}
|
|
169
169
|
/**
|
|
170
170
|
* Error: Invalid task ID format
|
|
171
|
-
* Used by:
|
|
171
|
+
* Used by: implement workflow
|
|
172
172
|
*/
|
|
173
173
|
static invalidTaskIdFormat(taskId) {
|
|
174
174
|
return (`Invalid task ID format: ${taskId}\n\n` +
|
|
@@ -194,7 +194,7 @@ export class AgentErrorMessages {
|
|
|
194
194
|
}
|
|
195
195
|
/**
|
|
196
196
|
* Warning: Task already completed
|
|
197
|
-
* Used by:
|
|
197
|
+
* Used by: implement workflow when marking already-done task
|
|
198
198
|
*/
|
|
199
199
|
static taskAlreadyCompleted(taskId) {
|
|
200
200
|
return (`Task already completed: ${taskId}\n\n` +
|
|
@@ -32,12 +32,6 @@ interface NodeJSError extends Error {
|
|
|
32
32
|
* Type guard to check if error is a NodeJS error with code property
|
|
33
33
|
*/
|
|
34
34
|
export declare function isNodeError(error: unknown): error is NodeJSError;
|
|
35
|
-
|
|
36
|
-
* Handles CLI errors, formatting OCLIF errors nicely and falling back to default handler.
|
|
37
|
-
* @param error The error to handle
|
|
38
|
-
* @param defaultHandler The default handler function (usually handle from @oclif/core)
|
|
39
|
-
* @param exitFn Optional exit function (defaults to process.exit)
|
|
40
|
-
*/
|
|
41
|
-
export declare function handleCliError(error: any, defaultHandler: (err: any) => Promise<void>, exitFn?: (code: number) => void): Promise<void>;
|
|
35
|
+
export declare function handleCliError(error: unknown, defaultHandler: (err: unknown) => Promise<void>, exitFn?: (code: number) => void): Promise<void>;
|
|
42
36
|
export {};
|
|
43
37
|
//# sourceMappingURL=error-utils.d.ts.map
|
|
@@ -61,22 +61,23 @@ export function toError(error) {
|
|
|
61
61
|
* Type guard to check if error is a NodeJS error with code property
|
|
62
62
|
*/
|
|
63
63
|
export function isNodeError(error) {
|
|
64
|
-
return
|
|
65
|
-
'code' in error &&
|
|
66
|
-
typeof error.code === 'string');
|
|
64
|
+
return isError(error) && 'code' in error && typeof error.code === 'string';
|
|
67
65
|
}
|
|
68
|
-
/**
|
|
69
|
-
* Handles CLI errors, formatting OCLIF errors nicely and falling back to default handler.
|
|
70
|
-
* @param error The error to handle
|
|
71
|
-
* @param defaultHandler The default handler function (usually handle from @oclif/core)
|
|
72
|
-
* @param exitFn Optional exit function (defaults to process.exit)
|
|
73
|
-
*/
|
|
74
66
|
export async function handleCliError(error, defaultHandler, exitFn = process.exit) {
|
|
67
|
+
// Type guard for OCLIF errors
|
|
68
|
+
const isOclifError = (err) => {
|
|
69
|
+
return (err !== null &&
|
|
70
|
+
typeof err === 'object' &&
|
|
71
|
+
'oclif' in err &&
|
|
72
|
+
err.oclif !== null &&
|
|
73
|
+
typeof err.oclif === 'object' &&
|
|
74
|
+
'exit' in err.oclif);
|
|
75
|
+
};
|
|
75
76
|
// For CLIError, show only the formatted message
|
|
76
|
-
if (error
|
|
77
|
+
if (isOclifError(error)) {
|
|
77
78
|
// Format error message (hints are now included in error.message)
|
|
78
79
|
console.error(' › Error: ' + error.message);
|
|
79
|
-
exitFn(error.oclif
|
|
80
|
+
exitFn(error.oclif?.exit ?? 1);
|
|
80
81
|
return;
|
|
81
82
|
}
|
|
82
83
|
// For other errors, use default handler
|
|
@@ -23,7 +23,10 @@ export function parseTomlSlashCommand(content, templateName, providerName) {
|
|
|
23
23
|
while (promptLines.length > 0 && /^\s*(description\s*=|prompt\s*=)/.test(promptLines[0])) {
|
|
24
24
|
promptLines.shift();
|
|
25
25
|
}
|
|
26
|
-
promptBody = promptLines
|
|
26
|
+
promptBody = promptLines
|
|
27
|
+
.join('\n')
|
|
28
|
+
.replace(/^\n+/, '')
|
|
29
|
+
.replace(/[\s]+$/, '');
|
|
27
30
|
return {
|
|
28
31
|
description: descriptionMatch ? descriptionMatch[2] : '',
|
|
29
32
|
prompt: promptBody,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "clavix",
|
|
3
|
-
"version": "5.1.
|
|
3
|
+
"version": "5.1.1",
|
|
4
4
|
"description": "Agentic-first prompt workflows. Markdown templates that teach AI agents how to optimize prompts, create PRDs, and manage implementation. Works with Claude Code, Cursor, Windsurf, and 19+ other AI coding tools.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.js",
|
|
@@ -70,20 +70,15 @@
|
|
|
70
70
|
"@oclif/plugin-help": "^6.2.35",
|
|
71
71
|
"chalk": "^5.6.2",
|
|
72
72
|
"fs-extra": "^11.3.2",
|
|
73
|
-
"
|
|
74
|
-
"inquirer": "^12.11.1",
|
|
75
|
-
"json5": "^2.2.3",
|
|
76
|
-
"uuid": "^9.0.1"
|
|
73
|
+
"inquirer": "^12.11.1"
|
|
77
74
|
},
|
|
78
75
|
"devDependencies": {
|
|
79
76
|
"@eslint/js": "^9.17.0",
|
|
80
77
|
"@oclif/test": "^4.1.15",
|
|
81
78
|
"@types/fs-extra": "^11.0.4",
|
|
82
|
-
"@types/handlebars": "^4.0.40",
|
|
83
79
|
"@types/inquirer": "^9.0.9",
|
|
84
80
|
"@types/jest": "^30.0.0",
|
|
85
81
|
"@types/node": "^24.10.1",
|
|
86
|
-
"@types/uuid": "^10.0.0",
|
|
87
82
|
"@typescript-eslint/eslint-plugin": "^8.46.4",
|
|
88
83
|
"@typescript-eslint/parser": "^8.46.4",
|
|
89
84
|
"copyfiles": "^2.4.1",
|