clavix 7.1.0 → 7.2.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/dist/templates/agents/agents 2.md +200 -0
- package/dist/templates/agents/agents 3.md +200 -0
- package/dist/templates/agents/agents 5.md +200 -0
- package/dist/templates/agents/octo 2.md +237 -0
- package/dist/templates/agents/octo 3.md +237 -0
- package/dist/templates/agents/octo 4.md +237 -0
- package/dist/templates/slash-commands/_canonical/archive.md +1 -1
- package/dist/templates/slash-commands/_canonical/implement.md +1 -1
- package/dist/templates/slash-commands/_canonical/improve.md +2 -2
- package/dist/templates/slash-commands/_canonical/plan.md +1 -1
- package/dist/templates/slash-commands/_canonical/prd.md +1 -1
- package/dist/templates/slash-commands/_canonical/refine.md +1 -1
- package/dist/templates/slash-commands/_canonical/review.md +1 -1
- package/dist/templates/slash-commands/_canonical/start.md +1 -1
- package/dist/templates/slash-commands/_canonical/summarize.md +1 -1
- package/dist/templates/slash-commands/_canonical/verify.md +1 -1
- package/package.json +1 -1
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Clavix Instructions for Generic Agents
|
|
2
|
+
|
|
3
|
+
This guide is for agents that can only read documentation (no slash-command support). If your platform supports custom slash commands, use those instead.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ⛔ CLAVIX MODE ENFORCEMENT
|
|
8
|
+
|
|
9
|
+
**CRITICAL: Know which mode you're in and STOP at the right point.**
|
|
10
|
+
|
|
11
|
+
**OPTIMIZATION workflows** (NO CODE ALLOWED):
|
|
12
|
+
- Improve mode - Prompt optimization only (auto-selects depth)
|
|
13
|
+
- Your role: Analyze, optimize, show improved prompt, **STOP**
|
|
14
|
+
- ❌ DO NOT implement the prompt's requirements
|
|
15
|
+
- ✅ After showing optimized prompt, tell user: "Run `/clavix:implement --latest` to implement"
|
|
16
|
+
|
|
17
|
+
**PLANNING workflows** (NO CODE ALLOWED):
|
|
18
|
+
- Conversational mode, requirement extraction, PRD generation
|
|
19
|
+
- Your role: Ask questions, create PRDs/prompts, extract requirements
|
|
20
|
+
- ❌ DO NOT implement features during these workflows
|
|
21
|
+
|
|
22
|
+
**IMPLEMENTATION workflows** (CODE ALLOWED):
|
|
23
|
+
- Only after user runs execute/implement commands
|
|
24
|
+
- Your role: Write code, execute tasks, implement features
|
|
25
|
+
- ✅ DO implement code during these workflows
|
|
26
|
+
|
|
27
|
+
**If unsure, ASK:** "Should I implement this now, or continue with planning?"
|
|
28
|
+
|
|
29
|
+
See `.clavix/instructions/core/clavix-mode.md` for complete mode documentation.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 📁 Detailed Workflow Instructions
|
|
34
|
+
|
|
35
|
+
For complete step-by-step workflows, see `.clavix/instructions/`:
|
|
36
|
+
|
|
37
|
+
| Workflow | Instruction File | Purpose |
|
|
38
|
+
|----------|-----------------|---------|
|
|
39
|
+
| **Conversational Mode** | `workflows/start.md` | Natural requirements gathering through discussion |
|
|
40
|
+
| **Extract Requirements** | `workflows/summarize.md` | Analyze conversation → mini-PRD + optimized prompts |
|
|
41
|
+
| **Prompt Optimization** | `workflows/improve.md` | Intent detection + quality assessment + auto-depth selection |
|
|
42
|
+
| **PRD Generation** | `workflows/prd.md` | Socratic questions → full PRD + quick PRD |
|
|
43
|
+
| **Mode Boundaries** | `core/clavix-mode.md` | Planning vs implementation distinction |
|
|
44
|
+
| **File Operations** | `core/file-operations.md` | File creation patterns |
|
|
45
|
+
| **Verification** | `core/verification.md` | Post-implementation verification |
|
|
46
|
+
|
|
47
|
+
**Troubleshooting:**
|
|
48
|
+
- `troubleshooting/jumped-to-implementation.md` - If you started coding during planning
|
|
49
|
+
- `troubleshooting/skipped-file-creation.md` - If files weren't created
|
|
50
|
+
- `troubleshooting/mode-confusion.md` - When unclear about planning vs implementation
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 🔍 Workflow Detection Keywords
|
|
55
|
+
|
|
56
|
+
| Keywords in User Request | Recommended Workflow | File Reference |
|
|
57
|
+
|---------------------------|---------------------|----------------|
|
|
58
|
+
| "improve this prompt", "make it better", "optimize" | Improve mode → Auto-depth optimization | `workflows/improve.md` |
|
|
59
|
+
| "analyze thoroughly", "edge cases", "alternatives" | Improve mode (--comprehensive) | `workflows/improve.md` |
|
|
60
|
+
| "create a PRD", "product requirements" | PRD mode → Socratic questioning | `workflows/prd.md` |
|
|
61
|
+
| "let's discuss", "not sure what I want" | Conversational mode → Start gathering | `workflows/start.md` |
|
|
62
|
+
| "summarize our conversation" | Extract mode → Analyze thread | `workflows/summarize.md` |
|
|
63
|
+
| "refine", "update PRD", "change requirements", "modify prompt" | Refine mode → Update existing content | `workflows/refine.md` |
|
|
64
|
+
| "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
|
|
65
|
+
|
|
66
|
+
**When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 📋 Clavix Commands (v5)
|
|
71
|
+
|
|
72
|
+
### Setup Commands (CLI)
|
|
73
|
+
| Command | Purpose |
|
|
74
|
+
|---------|---------|
|
|
75
|
+
| `clavix init` | Initialize Clavix in a project |
|
|
76
|
+
| `clavix update` | Update templates after package update |
|
|
77
|
+
| `clavix diagnose` | Check installation health |
|
|
78
|
+
| `clavix version` | Show version |
|
|
79
|
+
|
|
80
|
+
### Workflow Commands (Slash Commands)
|
|
81
|
+
All workflows are executed via slash commands that AI agents read and follow:
|
|
82
|
+
|
|
83
|
+
> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
|
|
84
|
+
|
|
85
|
+
| Slash Command | Purpose |
|
|
86
|
+
|---------------|---------|
|
|
87
|
+
| `/clavix:improve` | Optimize prompts (auto-selects depth) |
|
|
88
|
+
| `/clavix:prd` | Generate PRD through guided questions |
|
|
89
|
+
| `/clavix:plan` | Create task breakdown from PRD |
|
|
90
|
+
| `/clavix:implement` | Execute tasks or prompts (auto-detects source) |
|
|
91
|
+
| `/clavix:start` | Begin conversational session |
|
|
92
|
+
| `/clavix:summarize` | Extract requirements from conversation |
|
|
93
|
+
| `/clavix:refine` | Refine existing PRD or saved prompt |
|
|
94
|
+
|
|
95
|
+
### Agentic Utilities (Project Management)
|
|
96
|
+
These utilities provide structured workflows for project completion:
|
|
97
|
+
|
|
98
|
+
| Utility | Purpose |
|
|
99
|
+
|---------|---------|
|
|
100
|
+
| `/clavix:verify` | Check implementation against PRD requirements, run validation |
|
|
101
|
+
| `/clavix:archive` | Archive completed work to `.clavix/archive/` for reference |
|
|
102
|
+
|
|
103
|
+
**Quick start:**
|
|
104
|
+
```bash
|
|
105
|
+
npm install -g clavix
|
|
106
|
+
clavix init
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**How it works:** Slash commands are markdown templates. When invoked, the agent reads the template and follows its instructions using native tools (Read, Write, Edit, Bash).
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 🔄 Standard Workflow
|
|
114
|
+
|
|
115
|
+
**Clavix follows this progression:**
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
PRD Creation → Task Planning → Implementation → Archive
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Detailed steps:**
|
|
122
|
+
|
|
123
|
+
1. **Planning Phase**
|
|
124
|
+
- Run: `/clavix:prd` or `/clavix:start` → `/clavix:summarize`
|
|
125
|
+
- Output: `.clavix/outputs/{project}/full-prd.md` + `quick-prd.md`
|
|
126
|
+
- Mode: PLANNING
|
|
127
|
+
|
|
128
|
+
2. **Task Preparation**
|
|
129
|
+
- Run: `/clavix:plan` transforms PRD into curated task list
|
|
130
|
+
- Output: `.clavix/outputs/{project}/tasks.md`
|
|
131
|
+
- Mode: PLANNING (Pre-Implementation)
|
|
132
|
+
|
|
133
|
+
3. **Implementation Phase**
|
|
134
|
+
- Run: `/clavix:implement`
|
|
135
|
+
- Agent executes tasks systematically
|
|
136
|
+
- Mode: IMPLEMENTATION
|
|
137
|
+
- Agent edits tasks.md directly to mark progress (`- [ ]` → `- [x]`)
|
|
138
|
+
|
|
139
|
+
4. **Completion**
|
|
140
|
+
- Run: `/clavix:archive`
|
|
141
|
+
- Archives completed work
|
|
142
|
+
- Mode: Management
|
|
143
|
+
|
|
144
|
+
**Key principle:** Planning workflows create documents. Implementation workflows write code.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## 💡 Best Practices for Generic Agents
|
|
149
|
+
|
|
150
|
+
1. **Always reference instruction files** - Don't recreate workflow steps inline, point to `.clavix/instructions/workflows/`
|
|
151
|
+
|
|
152
|
+
2. **Respect mode boundaries** - Planning mode = no code, Implementation mode = write code
|
|
153
|
+
|
|
154
|
+
3. **Use checkpoints** - Follow the CHECKPOINT pattern from instruction files to track progress
|
|
155
|
+
|
|
156
|
+
4. **Create files explicitly** - Use Write tool for every file, verify with ls, never skip file creation
|
|
157
|
+
|
|
158
|
+
5. **Ask when unclear** - If mode is ambiguous, ask: "Should I implement or continue planning?"
|
|
159
|
+
|
|
160
|
+
6. **Track complexity** - Use conversational mode for complex requirements (15+ exchanges, 5+ features, 3+ topics)
|
|
161
|
+
|
|
162
|
+
7. **Label improvements** - When optimizing prompts, mark changes with [ADDED], [CLARIFIED], [STRUCTURED], [EXPANDED], [SCOPED]
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## ⚠️ Common Mistakes
|
|
167
|
+
|
|
168
|
+
### ❌ Jumping to implementation during planning
|
|
169
|
+
**Wrong:** User discusses feature → agent generates code immediately
|
|
170
|
+
|
|
171
|
+
**Right:** User discusses feature → agent asks questions → creates PRD/prompt → asks if ready to implement
|
|
172
|
+
|
|
173
|
+
### ❌ Skipping file creation
|
|
174
|
+
**Wrong:** Display content in chat, don't write files
|
|
175
|
+
|
|
176
|
+
**Right:** Create directory → Write files → Verify existence → Display paths
|
|
177
|
+
|
|
178
|
+
### ❌ Recreating workflow instructions inline
|
|
179
|
+
**Wrong:** Copy entire fast mode workflow into response
|
|
180
|
+
|
|
181
|
+
**Right:** Reference `.clavix/instructions/workflows/improve.md` and follow its steps
|
|
182
|
+
|
|
183
|
+
### ❌ Not using instruction files
|
|
184
|
+
**Wrong:** Make up workflow steps or guess at process
|
|
185
|
+
|
|
186
|
+
**Right:** Read corresponding `.clavix/instructions/workflows/*.md` file and follow exactly
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
**Artifacts stored under `.clavix/`:**
|
|
191
|
+
- `.clavix/outputs/<project>/` - PRDs, tasks, prompts
|
|
192
|
+
- `.clavix/templates/` - Custom overrides
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
**For complete workflows:** Always reference `.clavix/instructions/workflows/{workflow}.md`
|
|
197
|
+
|
|
198
|
+
**For troubleshooting:** Check `.clavix/instructions/troubleshooting/`
|
|
199
|
+
|
|
200
|
+
**For mode clarification:** See `.clavix/instructions/core/clavix-mode.md`
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Clavix Instructions for Generic Agents
|
|
2
|
+
|
|
3
|
+
This guide is for agents that can only read documentation (no slash-command support). If your platform supports custom slash commands, use those instead.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ⛔ CLAVIX MODE ENFORCEMENT
|
|
8
|
+
|
|
9
|
+
**CRITICAL: Know which mode you're in and STOP at the right point.**
|
|
10
|
+
|
|
11
|
+
**OPTIMIZATION workflows** (NO CODE ALLOWED):
|
|
12
|
+
- Improve mode - Prompt optimization only (auto-selects depth)
|
|
13
|
+
- Your role: Analyze, optimize, show improved prompt, **STOP**
|
|
14
|
+
- ❌ DO NOT implement the prompt's requirements
|
|
15
|
+
- ✅ After showing optimized prompt, tell user: "Run `/clavix:implement --latest` to implement"
|
|
16
|
+
|
|
17
|
+
**PLANNING workflows** (NO CODE ALLOWED):
|
|
18
|
+
- Conversational mode, requirement extraction, PRD generation
|
|
19
|
+
- Your role: Ask questions, create PRDs/prompts, extract requirements
|
|
20
|
+
- ❌ DO NOT implement features during these workflows
|
|
21
|
+
|
|
22
|
+
**IMPLEMENTATION workflows** (CODE ALLOWED):
|
|
23
|
+
- Only after user runs execute/implement commands
|
|
24
|
+
- Your role: Write code, execute tasks, implement features
|
|
25
|
+
- ✅ DO implement code during these workflows
|
|
26
|
+
|
|
27
|
+
**If unsure, ASK:** "Should I implement this now, or continue with planning?"
|
|
28
|
+
|
|
29
|
+
See `.clavix/instructions/core/clavix-mode.md` for complete mode documentation.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 📁 Detailed Workflow Instructions
|
|
34
|
+
|
|
35
|
+
For complete step-by-step workflows, see `.clavix/instructions/`:
|
|
36
|
+
|
|
37
|
+
| Workflow | Instruction File | Purpose |
|
|
38
|
+
|----------|-----------------|---------|
|
|
39
|
+
| **Conversational Mode** | `workflows/start.md` | Natural requirements gathering through discussion |
|
|
40
|
+
| **Extract Requirements** | `workflows/summarize.md` | Analyze conversation → mini-PRD + optimized prompts |
|
|
41
|
+
| **Prompt Optimization** | `workflows/improve.md` | Intent detection + quality assessment + auto-depth selection |
|
|
42
|
+
| **PRD Generation** | `workflows/prd.md` | Socratic questions → full PRD + quick PRD |
|
|
43
|
+
| **Mode Boundaries** | `core/clavix-mode.md` | Planning vs implementation distinction |
|
|
44
|
+
| **File Operations** | `core/file-operations.md` | File creation patterns |
|
|
45
|
+
| **Verification** | `core/verification.md` | Post-implementation verification |
|
|
46
|
+
|
|
47
|
+
**Troubleshooting:**
|
|
48
|
+
- `troubleshooting/jumped-to-implementation.md` - If you started coding during planning
|
|
49
|
+
- `troubleshooting/skipped-file-creation.md` - If files weren't created
|
|
50
|
+
- `troubleshooting/mode-confusion.md` - When unclear about planning vs implementation
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 🔍 Workflow Detection Keywords
|
|
55
|
+
|
|
56
|
+
| Keywords in User Request | Recommended Workflow | File Reference |
|
|
57
|
+
|---------------------------|---------------------|----------------|
|
|
58
|
+
| "improve this prompt", "make it better", "optimize" | Improve mode → Auto-depth optimization | `workflows/improve.md` |
|
|
59
|
+
| "analyze thoroughly", "edge cases", "alternatives" | Improve mode (--comprehensive) | `workflows/improve.md` |
|
|
60
|
+
| "create a PRD", "product requirements" | PRD mode → Socratic questioning | `workflows/prd.md` |
|
|
61
|
+
| "let's discuss", "not sure what I want" | Conversational mode → Start gathering | `workflows/start.md` |
|
|
62
|
+
| "summarize our conversation" | Extract mode → Analyze thread | `workflows/summarize.md` |
|
|
63
|
+
| "refine", "update PRD", "change requirements", "modify prompt" | Refine mode → Update existing content | `workflows/refine.md` |
|
|
64
|
+
| "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
|
|
65
|
+
|
|
66
|
+
**When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 📋 Clavix Commands (v5)
|
|
71
|
+
|
|
72
|
+
### Setup Commands (CLI)
|
|
73
|
+
| Command | Purpose |
|
|
74
|
+
|---------|---------|
|
|
75
|
+
| `clavix init` | Initialize Clavix in a project |
|
|
76
|
+
| `clavix update` | Update templates after package update |
|
|
77
|
+
| `clavix diagnose` | Check installation health |
|
|
78
|
+
| `clavix version` | Show version |
|
|
79
|
+
|
|
80
|
+
### Workflow Commands (Slash Commands)
|
|
81
|
+
All workflows are executed via slash commands that AI agents read and follow:
|
|
82
|
+
|
|
83
|
+
> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
|
|
84
|
+
|
|
85
|
+
| Slash Command | Purpose |
|
|
86
|
+
|---------------|---------|
|
|
87
|
+
| `/clavix:improve` | Optimize prompts (auto-selects depth) |
|
|
88
|
+
| `/clavix:prd` | Generate PRD through guided questions |
|
|
89
|
+
| `/clavix:plan` | Create task breakdown from PRD |
|
|
90
|
+
| `/clavix:implement` | Execute tasks or prompts (auto-detects source) |
|
|
91
|
+
| `/clavix:start` | Begin conversational session |
|
|
92
|
+
| `/clavix:summarize` | Extract requirements from conversation |
|
|
93
|
+
| `/clavix:refine` | Refine existing PRD or saved prompt |
|
|
94
|
+
|
|
95
|
+
### Agentic Utilities (Project Management)
|
|
96
|
+
These utilities provide structured workflows for project completion:
|
|
97
|
+
|
|
98
|
+
| Utility | Purpose |
|
|
99
|
+
|---------|---------|
|
|
100
|
+
| `/clavix:verify` | Check implementation against PRD requirements, run validation |
|
|
101
|
+
| `/clavix:archive` | Archive completed work to `.clavix/archive/` for reference |
|
|
102
|
+
|
|
103
|
+
**Quick start:**
|
|
104
|
+
```bash
|
|
105
|
+
npm install -g clavix
|
|
106
|
+
clavix init
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**How it works:** Slash commands are markdown templates. When invoked, the agent reads the template and follows its instructions using native tools (Read, Write, Edit, Bash).
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 🔄 Standard Workflow
|
|
114
|
+
|
|
115
|
+
**Clavix follows this progression:**
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
PRD Creation → Task Planning → Implementation → Archive
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Detailed steps:**
|
|
122
|
+
|
|
123
|
+
1. **Planning Phase**
|
|
124
|
+
- Run: `/clavix:prd` or `/clavix:start` → `/clavix:summarize`
|
|
125
|
+
- Output: `.clavix/outputs/{project}/full-prd.md` + `quick-prd.md`
|
|
126
|
+
- Mode: PLANNING
|
|
127
|
+
|
|
128
|
+
2. **Task Preparation**
|
|
129
|
+
- Run: `/clavix:plan` transforms PRD into curated task list
|
|
130
|
+
- Output: `.clavix/outputs/{project}/tasks.md`
|
|
131
|
+
- Mode: PLANNING (Pre-Implementation)
|
|
132
|
+
|
|
133
|
+
3. **Implementation Phase**
|
|
134
|
+
- Run: `/clavix:implement`
|
|
135
|
+
- Agent executes tasks systematically
|
|
136
|
+
- Mode: IMPLEMENTATION
|
|
137
|
+
- Agent edits tasks.md directly to mark progress (`- [ ]` → `- [x]`)
|
|
138
|
+
|
|
139
|
+
4. **Completion**
|
|
140
|
+
- Run: `/clavix:archive`
|
|
141
|
+
- Archives completed work
|
|
142
|
+
- Mode: Management
|
|
143
|
+
|
|
144
|
+
**Key principle:** Planning workflows create documents. Implementation workflows write code.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## 💡 Best Practices for Generic Agents
|
|
149
|
+
|
|
150
|
+
1. **Always reference instruction files** - Don't recreate workflow steps inline, point to `.clavix/instructions/workflows/`
|
|
151
|
+
|
|
152
|
+
2. **Respect mode boundaries** - Planning mode = no code, Implementation mode = write code
|
|
153
|
+
|
|
154
|
+
3. **Use checkpoints** - Follow the CHECKPOINT pattern from instruction files to track progress
|
|
155
|
+
|
|
156
|
+
4. **Create files explicitly** - Use Write tool for every file, verify with ls, never skip file creation
|
|
157
|
+
|
|
158
|
+
5. **Ask when unclear** - If mode is ambiguous, ask: "Should I implement or continue planning?"
|
|
159
|
+
|
|
160
|
+
6. **Track complexity** - Use conversational mode for complex requirements (15+ exchanges, 5+ features, 3+ topics)
|
|
161
|
+
|
|
162
|
+
7. **Label improvements** - When optimizing prompts, mark changes with [ADDED], [CLARIFIED], [STRUCTURED], [EXPANDED], [SCOPED]
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## ⚠️ Common Mistakes
|
|
167
|
+
|
|
168
|
+
### ❌ Jumping to implementation during planning
|
|
169
|
+
**Wrong:** User discusses feature → agent generates code immediately
|
|
170
|
+
|
|
171
|
+
**Right:** User discusses feature → agent asks questions → creates PRD/prompt → asks if ready to implement
|
|
172
|
+
|
|
173
|
+
### ❌ Skipping file creation
|
|
174
|
+
**Wrong:** Display content in chat, don't write files
|
|
175
|
+
|
|
176
|
+
**Right:** Create directory → Write files → Verify existence → Display paths
|
|
177
|
+
|
|
178
|
+
### ❌ Recreating workflow instructions inline
|
|
179
|
+
**Wrong:** Copy entire fast mode workflow into response
|
|
180
|
+
|
|
181
|
+
**Right:** Reference `.clavix/instructions/workflows/improve.md` and follow its steps
|
|
182
|
+
|
|
183
|
+
### ❌ Not using instruction files
|
|
184
|
+
**Wrong:** Make up workflow steps or guess at process
|
|
185
|
+
|
|
186
|
+
**Right:** Read corresponding `.clavix/instructions/workflows/*.md` file and follow exactly
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
**Artifacts stored under `.clavix/`:**
|
|
191
|
+
- `.clavix/outputs/<project>/` - PRDs, tasks, prompts
|
|
192
|
+
- `.clavix/templates/` - Custom overrides
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
**For complete workflows:** Always reference `.clavix/instructions/workflows/{workflow}.md`
|
|
197
|
+
|
|
198
|
+
**For troubleshooting:** Check `.clavix/instructions/troubleshooting/`
|
|
199
|
+
|
|
200
|
+
**For mode clarification:** See `.clavix/instructions/core/clavix-mode.md`
|
|
@@ -0,0 +1,200 @@
|
|
|
1
|
+
# Clavix Instructions for Generic Agents
|
|
2
|
+
|
|
3
|
+
This guide is for agents that can only read documentation (no slash-command support). If your platform supports custom slash commands, use those instead.
|
|
4
|
+
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
## ⛔ CLAVIX MODE ENFORCEMENT
|
|
8
|
+
|
|
9
|
+
**CRITICAL: Know which mode you're in and STOP at the right point.**
|
|
10
|
+
|
|
11
|
+
**OPTIMIZATION workflows** (NO CODE ALLOWED):
|
|
12
|
+
- Improve mode - Prompt optimization only (auto-selects depth)
|
|
13
|
+
- Your role: Analyze, optimize, show improved prompt, **STOP**
|
|
14
|
+
- ❌ DO NOT implement the prompt's requirements
|
|
15
|
+
- ✅ After showing optimized prompt, tell user: "Run `/clavix:implement --latest` to implement"
|
|
16
|
+
|
|
17
|
+
**PLANNING workflows** (NO CODE ALLOWED):
|
|
18
|
+
- Conversational mode, requirement extraction, PRD generation
|
|
19
|
+
- Your role: Ask questions, create PRDs/prompts, extract requirements
|
|
20
|
+
- ❌ DO NOT implement features during these workflows
|
|
21
|
+
|
|
22
|
+
**IMPLEMENTATION workflows** (CODE ALLOWED):
|
|
23
|
+
- Only after user runs execute/implement commands
|
|
24
|
+
- Your role: Write code, execute tasks, implement features
|
|
25
|
+
- ✅ DO implement code during these workflows
|
|
26
|
+
|
|
27
|
+
**If unsure, ASK:** "Should I implement this now, or continue with planning?"
|
|
28
|
+
|
|
29
|
+
See `.clavix/instructions/core/clavix-mode.md` for complete mode documentation.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## 📁 Detailed Workflow Instructions
|
|
34
|
+
|
|
35
|
+
For complete step-by-step workflows, see `.clavix/instructions/`:
|
|
36
|
+
|
|
37
|
+
| Workflow | Instruction File | Purpose |
|
|
38
|
+
|----------|-----------------|---------|
|
|
39
|
+
| **Conversational Mode** | `workflows/start.md` | Natural requirements gathering through discussion |
|
|
40
|
+
| **Extract Requirements** | `workflows/summarize.md` | Analyze conversation → mini-PRD + optimized prompts |
|
|
41
|
+
| **Prompt Optimization** | `workflows/improve.md` | Intent detection + quality assessment + auto-depth selection |
|
|
42
|
+
| **PRD Generation** | `workflows/prd.md` | Socratic questions → full PRD + quick PRD |
|
|
43
|
+
| **Mode Boundaries** | `core/clavix-mode.md` | Planning vs implementation distinction |
|
|
44
|
+
| **File Operations** | `core/file-operations.md` | File creation patterns |
|
|
45
|
+
| **Verification** | `core/verification.md` | Post-implementation verification |
|
|
46
|
+
|
|
47
|
+
**Troubleshooting:**
|
|
48
|
+
- `troubleshooting/jumped-to-implementation.md` - If you started coding during planning
|
|
49
|
+
- `troubleshooting/skipped-file-creation.md` - If files weren't created
|
|
50
|
+
- `troubleshooting/mode-confusion.md` - When unclear about planning vs implementation
|
|
51
|
+
|
|
52
|
+
---
|
|
53
|
+
|
|
54
|
+
## 🔍 Workflow Detection Keywords
|
|
55
|
+
|
|
56
|
+
| Keywords in User Request | Recommended Workflow | File Reference |
|
|
57
|
+
|---------------------------|---------------------|----------------|
|
|
58
|
+
| "improve this prompt", "make it better", "optimize" | Improve mode → Auto-depth optimization | `workflows/improve.md` |
|
|
59
|
+
| "analyze thoroughly", "edge cases", "alternatives" | Improve mode (--comprehensive) | `workflows/improve.md` |
|
|
60
|
+
| "create a PRD", "product requirements" | PRD mode → Socratic questioning | `workflows/prd.md` |
|
|
61
|
+
| "let's discuss", "not sure what I want" | Conversational mode → Start gathering | `workflows/start.md` |
|
|
62
|
+
| "summarize our conversation" | Extract mode → Analyze thread | `workflows/summarize.md` |
|
|
63
|
+
| "refine", "update PRD", "change requirements", "modify prompt" | Refine mode → Update existing content | `workflows/refine.md` |
|
|
64
|
+
| "verify", "check my implementation" | Verify mode → Implementation verification | `core/verification.md` |
|
|
65
|
+
|
|
66
|
+
**When detected:** Reference the corresponding `.clavix/instructions/workflows/{workflow}.md` file.
|
|
67
|
+
|
|
68
|
+
---
|
|
69
|
+
|
|
70
|
+
## 📋 Clavix Commands (v5)
|
|
71
|
+
|
|
72
|
+
### Setup Commands (CLI)
|
|
73
|
+
| Command | Purpose |
|
|
74
|
+
|---------|---------|
|
|
75
|
+
| `clavix init` | Initialize Clavix in a project |
|
|
76
|
+
| `clavix update` | Update templates after package update |
|
|
77
|
+
| `clavix diagnose` | Check installation health |
|
|
78
|
+
| `clavix version` | Show version |
|
|
79
|
+
|
|
80
|
+
### Workflow Commands (Slash Commands)
|
|
81
|
+
All workflows are executed via slash commands that AI agents read and follow:
|
|
82
|
+
|
|
83
|
+
> **Command Format:** Commands shown with colon (`:`) format. Some tools use hyphen (`-`): Claude Code uses `/clavix:improve`, Cursor uses `/clavix-improve`. Your tool autocompletes the correct format.
|
|
84
|
+
|
|
85
|
+
| Slash Command | Purpose |
|
|
86
|
+
|---------------|---------|
|
|
87
|
+
| `/clavix:improve` | Optimize prompts (auto-selects depth) |
|
|
88
|
+
| `/clavix:prd` | Generate PRD through guided questions |
|
|
89
|
+
| `/clavix:plan` | Create task breakdown from PRD |
|
|
90
|
+
| `/clavix:implement` | Execute tasks or prompts (auto-detects source) |
|
|
91
|
+
| `/clavix:start` | Begin conversational session |
|
|
92
|
+
| `/clavix:summarize` | Extract requirements from conversation |
|
|
93
|
+
| `/clavix:refine` | Refine existing PRD or saved prompt |
|
|
94
|
+
|
|
95
|
+
### Agentic Utilities (Project Management)
|
|
96
|
+
These utilities provide structured workflows for project completion:
|
|
97
|
+
|
|
98
|
+
| Utility | Purpose |
|
|
99
|
+
|---------|---------|
|
|
100
|
+
| `/clavix:verify` | Check implementation against PRD requirements, run validation |
|
|
101
|
+
| `/clavix:archive` | Archive completed work to `.clavix/archive/` for reference |
|
|
102
|
+
|
|
103
|
+
**Quick start:**
|
|
104
|
+
```bash
|
|
105
|
+
npm install -g clavix
|
|
106
|
+
clavix init
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**How it works:** Slash commands are markdown templates. When invoked, the agent reads the template and follows its instructions using native tools (Read, Write, Edit, Bash).
|
|
110
|
+
|
|
111
|
+
---
|
|
112
|
+
|
|
113
|
+
## 🔄 Standard Workflow
|
|
114
|
+
|
|
115
|
+
**Clavix follows this progression:**
|
|
116
|
+
|
|
117
|
+
```
|
|
118
|
+
PRD Creation → Task Planning → Implementation → Archive
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
**Detailed steps:**
|
|
122
|
+
|
|
123
|
+
1. **Planning Phase**
|
|
124
|
+
- Run: `/clavix:prd` or `/clavix:start` → `/clavix:summarize`
|
|
125
|
+
- Output: `.clavix/outputs/{project}/full-prd.md` + `quick-prd.md`
|
|
126
|
+
- Mode: PLANNING
|
|
127
|
+
|
|
128
|
+
2. **Task Preparation**
|
|
129
|
+
- Run: `/clavix:plan` transforms PRD into curated task list
|
|
130
|
+
- Output: `.clavix/outputs/{project}/tasks.md`
|
|
131
|
+
- Mode: PLANNING (Pre-Implementation)
|
|
132
|
+
|
|
133
|
+
3. **Implementation Phase**
|
|
134
|
+
- Run: `/clavix:implement`
|
|
135
|
+
- Agent executes tasks systematically
|
|
136
|
+
- Mode: IMPLEMENTATION
|
|
137
|
+
- Agent edits tasks.md directly to mark progress (`- [ ]` → `- [x]`)
|
|
138
|
+
|
|
139
|
+
4. **Completion**
|
|
140
|
+
- Run: `/clavix:archive`
|
|
141
|
+
- Archives completed work
|
|
142
|
+
- Mode: Management
|
|
143
|
+
|
|
144
|
+
**Key principle:** Planning workflows create documents. Implementation workflows write code.
|
|
145
|
+
|
|
146
|
+
---
|
|
147
|
+
|
|
148
|
+
## 💡 Best Practices for Generic Agents
|
|
149
|
+
|
|
150
|
+
1. **Always reference instruction files** - Don't recreate workflow steps inline, point to `.clavix/instructions/workflows/`
|
|
151
|
+
|
|
152
|
+
2. **Respect mode boundaries** - Planning mode = no code, Implementation mode = write code
|
|
153
|
+
|
|
154
|
+
3. **Use checkpoints** - Follow the CHECKPOINT pattern from instruction files to track progress
|
|
155
|
+
|
|
156
|
+
4. **Create files explicitly** - Use Write tool for every file, verify with ls, never skip file creation
|
|
157
|
+
|
|
158
|
+
5. **Ask when unclear** - If mode is ambiguous, ask: "Should I implement or continue planning?"
|
|
159
|
+
|
|
160
|
+
6. **Track complexity** - Use conversational mode for complex requirements (15+ exchanges, 5+ features, 3+ topics)
|
|
161
|
+
|
|
162
|
+
7. **Label improvements** - When optimizing prompts, mark changes with [ADDED], [CLARIFIED], [STRUCTURED], [EXPANDED], [SCOPED]
|
|
163
|
+
|
|
164
|
+
---
|
|
165
|
+
|
|
166
|
+
## ⚠️ Common Mistakes
|
|
167
|
+
|
|
168
|
+
### ❌ Jumping to implementation during planning
|
|
169
|
+
**Wrong:** User discusses feature → agent generates code immediately
|
|
170
|
+
|
|
171
|
+
**Right:** User discusses feature → agent asks questions → creates PRD/prompt → asks if ready to implement
|
|
172
|
+
|
|
173
|
+
### ❌ Skipping file creation
|
|
174
|
+
**Wrong:** Display content in chat, don't write files
|
|
175
|
+
|
|
176
|
+
**Right:** Create directory → Write files → Verify existence → Display paths
|
|
177
|
+
|
|
178
|
+
### ❌ Recreating workflow instructions inline
|
|
179
|
+
**Wrong:** Copy entire fast mode workflow into response
|
|
180
|
+
|
|
181
|
+
**Right:** Reference `.clavix/instructions/workflows/improve.md` and follow its steps
|
|
182
|
+
|
|
183
|
+
### ❌ Not using instruction files
|
|
184
|
+
**Wrong:** Make up workflow steps or guess at process
|
|
185
|
+
|
|
186
|
+
**Right:** Read corresponding `.clavix/instructions/workflows/*.md` file and follow exactly
|
|
187
|
+
|
|
188
|
+
---
|
|
189
|
+
|
|
190
|
+
**Artifacts stored under `.clavix/`:**
|
|
191
|
+
- `.clavix/outputs/<project>/` - PRDs, tasks, prompts
|
|
192
|
+
- `.clavix/templates/` - Custom overrides
|
|
193
|
+
|
|
194
|
+
---
|
|
195
|
+
|
|
196
|
+
**For complete workflows:** Always reference `.clavix/instructions/workflows/{workflow}.md`
|
|
197
|
+
|
|
198
|
+
**For troubleshooting:** Check `.clavix/instructions/troubleshooting/`
|
|
199
|
+
|
|
200
|
+
**For mode clarification:** See `.clavix/instructions/core/clavix-mode.md`
|