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.
@@ -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`