@aiderdesk/aiderdesk 0.72.0 → 0.74.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (81) hide show
  1. package/out/cli.js +982 -13
  2. package/out/renderer/assets/{AgentSettings-CEw1Tgyu.js → AgentSettings-B-793Wr6.js} +4561 -3203
  3. package/out/renderer/assets/{InfoIcon-B6bij_VJ.js → InfoIcon-cuLXzJtV.js} +1 -1
  4. package/out/renderer/assets/{Onboarding-C2CtQOko.js → Onboarding-xrPWRnXm.js} +4 -4
  5. package/out/renderer/assets/{ProviderHeader-BCrdzdGT.js → ProviderHeader-CMVyqpPa.js} +226 -275
  6. package/out/renderer/assets/{SettingsPage-CNCsKRS7.js → SettingsPage-BBtDhv80.js} +17 -11
  7. package/out/renderer/assets/{UsageDashboard-DtZ8GTj6.js → UsageDashboard-CGI4iwCD.js} +3 -3
  8. package/out/renderer/assets/{arc-DnyT8oZ2.js → arc-CFENq1wJ.js} +1 -1
  9. package/out/renderer/assets/{architectureDiagram-3BPJPVTR-Dus_2n--.js → architectureDiagram-3BPJPVTR-BRG_9Mao.js} +3 -3
  10. package/out/renderer/assets/{blockDiagram-GPEHLZMM-A3REgcbw.js → blockDiagram-GPEHLZMM-B3c7WMY4.js} +4 -4
  11. package/out/renderer/assets/{c4Diagram-AAUBKEIU-DksErR7z.js → c4Diagram-AAUBKEIU-BYQrxMcW.js} +2 -2
  12. package/out/renderer/assets/{channel-DkjNDJNa.js → channel-DPxL1rpa.js} +1 -1
  13. package/out/renderer/assets/{chunk-2J33WTMH-CrUC6pnQ.js → chunk-2J33WTMH-C-kk05Nj.js} +1 -1
  14. package/out/renderer/assets/{chunk-4BX2VUAB-BulXGa1B.js → chunk-4BX2VUAB-BV8PWxnG.js} +1 -1
  15. package/out/renderer/assets/{chunk-55IACEB6-pQjPbAe9.js → chunk-55IACEB6-Cj6KHkUp.js} +1 -1
  16. package/out/renderer/assets/{chunk-727SXJPM-BcqphFMh.js → chunk-727SXJPM-BaIkuSPr.js} +5 -5
  17. package/out/renderer/assets/{chunk-AQP2D5EJ-DCREtqoW.js → chunk-AQP2D5EJ-DVZR_bfB.js} +3 -3
  18. package/out/renderer/assets/{chunk-FMBD7UC4-LFUgit2t.js → chunk-FMBD7UC4-CNrb2a0a.js} +1 -1
  19. package/out/renderer/assets/{chunk-ND2GUHAM-Bkunzp-9.js → chunk-ND2GUHAM-ClOnPDjy.js} +1 -1
  20. package/out/renderer/assets/{chunk-QZHKN3VN-foWYS4_y.js → chunk-QZHKN3VN-B2sJx9j2.js} +1 -1
  21. package/out/renderer/assets/{classDiagram-4FO5ZUOK-CVbKiC6R.js → classDiagram-4FO5ZUOK-ZzwWMcLO.js} +6 -6
  22. package/out/renderer/assets/{classDiagram-v2-Q7XG4LA2-CVbKiC6R.js → classDiagram-v2-Q7XG4LA2-ZzwWMcLO.js} +6 -6
  23. package/out/renderer/assets/{cose-bilkent-S5V4N54A-Bw7reEuM.js → cose-bilkent-S5V4N54A-DBx-UiMU.js} +1 -1
  24. package/out/renderer/assets/{dagre-BM42HDAG-oGURKg82.js → dagre-BM42HDAG-B_vMvYpz.js} +3 -3
  25. package/out/renderer/assets/{diagram-2AECGRRQ-kaoJ1YpU.js → diagram-2AECGRRQ-Do-w2xXO.js} +3 -3
  26. package/out/renderer/assets/{diagram-5GNKFQAL-EvoHkNwk.js → diagram-5GNKFQAL-JzG77sgb.js} +4 -4
  27. package/out/renderer/assets/{diagram-KO2AKTUF-D5N5hwBV.js → diagram-KO2AKTUF-CGMx2nPP.js} +3 -3
  28. package/out/renderer/assets/{diagram-LMA3HP47-kKi9mSGe.js → diagram-LMA3HP47-BqXnQeNu.js} +3 -3
  29. package/out/renderer/assets/{diagram-OG6HWLK6-BWJ9L5AP.js → diagram-OG6HWLK6-BR4e0lIb.js} +4 -4
  30. package/out/renderer/assets/{erDiagram-TEJ5UH35-d1W9ONuu.js → erDiagram-TEJ5UH35-B7QK0XSy.js} +4 -4
  31. package/out/renderer/assets/{flowDiagram-I6XJVG4X-u5Xk-TTj.js → flowDiagram-I6XJVG4X-BOySqejA.js} +6 -6
  32. package/out/renderer/assets/{ganttDiagram-6RSMTGT7-DiheBMSM.js → ganttDiagram-6RSMTGT7-BORAleML.js} +3 -3
  33. package/out/renderer/assets/{gitGraphDiagram-PVQCEYII-B7hUlCNM.js → gitGraphDiagram-PVQCEYII-DTReLiJT.js} +4 -4
  34. package/out/renderer/assets/{graph-D7JlCUW0.js → graph-Bf8U9r0n.js} +1 -1
  35. package/out/renderer/assets/{index-ClS76F34.js → index-5i67azF0.js} +1 -1
  36. package/out/renderer/assets/{index-DJwDiyPe.css → index-7NwOg_q_.css} +8 -40
  37. package/out/renderer/assets/{index-BgXUknVd.js → index-BOQBc3Qj.js} +6 -4
  38. package/out/renderer/assets/{index-DcFrLBMu.js → index-BS5vy5uH.js} +1 -1
  39. package/out/renderer/assets/{index-gnQtDa4r.js → index-COyr1I0o.js} +1 -1
  40. package/out/renderer/assets/{index-D8P2TG70.js → index-CmQY2QKE.js} +1 -1
  41. package/out/renderer/assets/{index-CzGef_M5.js → index-D3R9tjiT.js} +1 -1
  42. package/out/renderer/assets/{index-DOl0MdBC.js → index-D6b3rMtW.js} +1 -1
  43. package/out/renderer/assets/{index-3OKQF96N.js → index-DUoUqcJ_.js} +1 -1
  44. package/out/renderer/assets/{index-biM8l5ZN.js → index-Dq3ldCAy.js} +10286 -2422
  45. package/out/renderer/assets/{index-Duwg55fn.js → index-Dtxgil7l.js} +1 -1
  46. package/out/renderer/assets/{infoDiagram-5YYISTIA-BNOwcP8d.js → infoDiagram-5YYISTIA-Ryv-Emth.js} +2 -2
  47. package/out/renderer/assets/{ishikawaDiagram-YF4QCWOH-DZGvMXcI.js → ishikawaDiagram-YF4QCWOH-Blzp6JLN.js} +1 -1
  48. package/out/renderer/assets/{journeyDiagram-JHISSGLW-BF-SCAHN.js → journeyDiagram-JHISSGLW--KB4ASET.js} +4 -4
  49. package/out/renderer/assets/{jsx-dev-runtime-BZnUoQef.js → jsx-dev-runtime-DAzw_Red.js} +1 -1
  50. package/out/renderer/assets/{kanban-definition-UN3LZRKU-Cp9SfO9v.js → kanban-definition-UN3LZRKU-BzNpCu_x.js} +2 -2
  51. package/out/renderer/assets/{layout-BxWwRUTm.js → layout-BQu4M-KW.js} +2 -2
  52. package/out/renderer/assets/{linear-Cpdxqlgb.js → linear-DNZEF2Al.js} +1 -1
  53. package/out/renderer/assets/{mindmap-definition-RKZ34NQL-BtGsJF8k.js → mindmap-definition-RKZ34NQL-CxQjZIps.js} +3 -3
  54. package/out/renderer/assets/{pieDiagram-4H26LBE5-choZS41J.js → pieDiagram-4H26LBE5-qJt7eGwM.js} +4 -4
  55. package/out/renderer/assets/{quadrantDiagram-W4KKPZXB-CSEwIgFD.js → quadrantDiagram-W4KKPZXB-mMOhLjN_.js} +2 -2
  56. package/out/renderer/assets/{requirementDiagram-4Y6WPE33-sCdLoMf0.js → requirementDiagram-4Y6WPE33-GLhMtLW7.js} +3 -3
  57. package/out/renderer/assets/{sankeyDiagram-5OEKKPKP-DunA5v4o.js → sankeyDiagram-5OEKKPKP-Kcd8qR8y.js} +1 -1
  58. package/out/renderer/assets/{sequenceDiagram-3UESZ5HK-Cwz8rZA1.js → sequenceDiagram-3UESZ5HK-CpmBIgMJ.js} +3 -3
  59. package/out/renderer/assets/{stateDiagram-AJRCARHV-VCMhb3e-.js → stateDiagram-AJRCARHV-D00qZ9cQ.js} +6 -6
  60. package/out/renderer/assets/{stateDiagram-v2-BHNVJYJU-B9OcfdsH.js → stateDiagram-v2-BHNVJYJU-CkEgNJrB.js} +4 -4
  61. package/out/renderer/assets/{time-CtsiuOCL.js → time-CQSoUo1N.js} +1 -1
  62. package/out/renderer/assets/{timeline-definition-PNZ67QCA-B36Hc_gQ.js → timeline-definition-PNZ67QCA-CmydTbH6.js} +2 -2
  63. package/out/renderer/assets/{vennDiagram-CIIHVFJN-Dt2oWHz0.js → vennDiagram-CIIHVFJN-B4QGhnvI.js} +1 -1
  64. package/out/renderer/assets/{wardley-L42UT6IY-DkWaUY9X.js → wardley-L42UT6IY-B-mpW52K.js} +1 -1
  65. package/out/renderer/assets/{wardleyDiagram-YWT4CUSO-BHFM3JNH.js → wardleyDiagram-YWT4CUSO-Cz1pK1MY.js} +3 -3
  66. package/out/renderer/assets/{xychartDiagram-2RQKCTM6-2wqqMVJ7.js → xychartDiagram-2RQKCTM6-H-Q9Zv48.js} +2 -2
  67. package/out/renderer/index.html +2 -2
  68. package/out/resources/skills/agent-creator/SKILL.md +223 -0
  69. package/out/resources/skills/agent-creator/assets/examples/sample-profile.json +47 -0
  70. package/out/resources/skills/agent-creator/assets/templates/config.json.template +47 -0
  71. package/out/resources/skills/agent-creator/references/agent-profile-schema.md +294 -0
  72. package/out/resources/skills/agent-creator/references/profile-examples.md +490 -0
  73. package/out/resources/skills/agent-creator/references/subagent-guide.md +317 -0
  74. package/out/resources/skills/agent-creator/references/tool-approval-guide.md +484 -0
  75. package/out/resources/skills/extension-creator/SKILL.md +5 -5
  76. package/out/resources/skills/extension-creator/references/in-repo-flow.md +4 -4
  77. package/out/resources/skills/extension-creator/references/install-targets.md +2 -2
  78. package/out/resources/skills/extension-creator/references/project-global-flow.md +1 -1
  79. package/out/runner.js +10879 -10158
  80. package/package.json +3 -2
  81. package/scripts/generate-package.mjs +1 -0
@@ -0,0 +1,484 @@
1
+ # Tool Approval Configuration Guide
2
+
3
+ Complete guide to configuring tool approvals for agent profiles in AiderDesk.
4
+
5
+ ## Overview
6
+
7
+ Tool approvals control when and how an agent can use specific tools. Each tool can be set to one of three states:
8
+
9
+ 1. **Always** (`"always"`) - Auto-approve tool usage without prompting
10
+ 2. **Ask** (`"ask"`) - Prompt user for approval each time the tool is used (**DEFAULT**)
11
+ 3. **Never** (`"never"`) - Disable the tool completely
12
+
13
+ **Important**: The default value is "ask". Only explicitly set tools to "always" or "never" based on the agent's needs. Do not include tools that should remain at "ask" in `toolApprovals`.
14
+
15
+ ## Tool Approval States
16
+
17
+ ### Always (`"always"`)
18
+ - Tool executes immediately without user confirmation
19
+ - Best for safe, read-only operations
20
+ - Reduces friction for trusted actions
21
+
22
+ **Use cases:** Reading files, searching code, finding files, retrieving memories
23
+
24
+ ### Ask (`"ask"`)
25
+ - Prompts user before each tool execution
26
+ - Provides transparency and control
27
+ - Ideal for potentially destructive operations
28
+
29
+ **Use cases:** Editing files, running commands, creating/deleting tasks, Aider operations
30
+
31
+ ### Never (`"never"`)
32
+ - Tool is completely disabled for the profile
33
+ - Cannot be used even with manual approval
34
+ - Useful for restricting dangerous capabilities
35
+
36
+ **Use cases:** Shell commands for read-only profiles, file editing in review-only agents
37
+
38
+ ## Tool Groups and Their Tools
39
+
40
+ ### Power Tools (`power---*`) — enabled by `usePowerTools`
41
+
42
+ Direct file system and system operations.
43
+
44
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
45
+ |------|-------------------|---------------------|-------------------|---------------------|
46
+ | `power---file_read` | **always** | Most profiles | Default | Air-gapped systems |
47
+ | `power---file_write` | ask | Trusted contexts | Default | Review-only agents |
48
+ | `power---file_edit` | ask | Trusted contexts | Default | Review-only agents |
49
+ | `power---glob` | **always** | Most profiles | Default | None |
50
+ | `power---grep` | **always** | Most profiles | Default | None |
51
+ | `power---semantic_search` | **always** | Most profiles | Default | None |
52
+ | `power---bash` | ask | Trusted scripts | Default | Read-only profiles |
53
+ | `power---fetch` | ask | Trusted domains | Default | Air-gapped systems |
54
+
55
+ **Recommended Patterns:**
56
+
57
+ ```json
58
+ // Full access profile
59
+ {
60
+ "toolApprovals": {
61
+ "power---file_read": "always",
62
+ "power---glob": "always",
63
+ "power---grep": "always",
64
+ "power---semantic_search": "always"
65
+ }
66
+ }
67
+
68
+ // Read-only profile
69
+ {
70
+ "toolApprovals": {
71
+ "power---file_read": "always",
72
+ "power---file_write": "never",
73
+ "power---file_edit": "never",
74
+ "power---glob": "always",
75
+ "power---grep": "always",
76
+ "power---semantic_search": "always",
77
+ "power---bash": "never"
78
+ }
79
+ }
80
+ ```
81
+
82
+ ### Aider Tools (`aider---*`) — enabled by `useAiderTools`
83
+
84
+ AI-powered code generation via Aider.
85
+
86
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
87
+ |------|-------------------|---------------------|-------------------|---------------------|
88
+ | `aider---get_context_files` | **always** | Always helpful | Default | N/A |
89
+ | `aider---add_context_files` | **always** | Auto-building context | Default | N/A |
90
+ | `aider---drop_context_files` | ask | Bulk operations | Default | N/A |
91
+ | `aider---run` | ask | Trusted contexts | Default | Non-Aider profiles |
92
+
93
+ **Recommended Patterns:**
94
+
95
+ ```json
96
+ // Full Aider profile
97
+ {
98
+ "toolApprovals": {
99
+ "aider---get_context_files": "always",
100
+ "aider---add_context_files": "always"
101
+ }
102
+ }
103
+
104
+ // Aider with auto-approve (advanced users)
105
+ {
106
+ "toolApprovals": {
107
+ "aider---get_context_files": "always",
108
+ "aider---add_context_files": "always",
109
+ "aider---drop_context_files": "always",
110
+ "aider---run": "always"
111
+ }
112
+ }
113
+ ```
114
+
115
+ ### Subagents Tools (`subagents---*`) — enabled by `useSubagents`
116
+
117
+ Task delegation to specialized subagents.
118
+
119
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
120
+ |------|-------------------|---------------------|-------------------|---------------------|
121
+ | `subagents---run_task` | **always** | Trusted subagents | Default | Subagent-free profiles |
122
+
123
+ **Recommended Patterns:**
124
+
125
+ ```json
126
+ // With subagent delegation
127
+ {
128
+ "toolApprovals": {
129
+ "subagents---run_task": "always"
130
+ }
131
+ }
132
+
133
+ // Manual subagent control
134
+ {
135
+ "toolApprovals": {
136
+ "subagents---run_task": "ask"
137
+ }
138
+ }
139
+ ```
140
+
141
+ ### Memory Tools (`memory---*`) — enabled by `useMemoryTools`
142
+
143
+ Persistent information storage and retrieval.
144
+
145
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
146
+ |------|-------------------|---------------------|-------------------|---------------------|
147
+ | `memory---store_memory` | **always** | Learning preferences | Default | Stateless profiles |
148
+ | `memory---retrieve_memory` | **always** | Always helpful | Default | Stateless profiles |
149
+ | `memory---delete_memory` | **never** | Trusted contexts only | Default | Most profiles |
150
+ | `memory---list_memories` | **never** | Admin/debug contexts | Default | Most profiles |
151
+ | `memory---update_memory` | **never** | Trusted contexts only | Default | Most profiles |
152
+
153
+ **Note:** The default profile has `delete_memory`, `list_memories`, and `update_memory` set to `"never"` for safety. Override to `"always"` only for trusted/admin profiles.
154
+
155
+ **Recommended Patterns:**
156
+
157
+ ```json
158
+ // Full memory support (standard)
159
+ {
160
+ "toolApprovals": {
161
+ "memory---store_memory": "always",
162
+ "memory---retrieve_memory": "always"
163
+ }
164
+ }
165
+
166
+ // Full memory control (admin/trusted)
167
+ {
168
+ "toolApprovals": {
169
+ "memory---store_memory": "always",
170
+ "memory---retrieve_memory": "always",
171
+ "memory---delete_memory": "always",
172
+ "memory---list_memories": "always",
173
+ "memory---update_memory": "always"
174
+ }
175
+ }
176
+
177
+ // Stateless profile (no memory)
178
+ {
179
+ "useMemoryTools": false
180
+ }
181
+ ```
182
+
183
+ ### Skills Tools (`skills---*`) — enabled by `useSkillsTools`
184
+
185
+ Access to project-specific and built-in skills.
186
+
187
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
188
+ |------|-------------------|---------------------|-------------------|---------------------|
189
+ | `skills---activate_skill` | **always** | Auto-skills | Default | No custom skills |
190
+
191
+ **Recommended Patterns:**
192
+
193
+ ```json
194
+ // With skills
195
+ {
196
+ "toolApprovals": {
197
+ "skills---activate_skill": "always"
198
+ }
199
+ }
200
+ ```
201
+
202
+ ### Task Tools (`tasks---*`) — enabled by `useTaskTools`
203
+
204
+ Task management and tracking within the project.
205
+
206
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
207
+ |------|-------------------|---------------------|-------------------|---------------------|
208
+ | `tasks---list_tasks` | **always** | Always helpful | Default | N/A |
209
+ | `tasks---get_task` | **always** | Always helpful | Default | N/A |
210
+ | `tasks---get_task_message` | **always** | Always helpful | Default | N/A |
211
+ | `tasks---create_task` | ask | Trusted contexts | Default | N/A |
212
+ | `tasks---delete_task` | ask | Trusted contexts | Default | N/A |
213
+ | `tasks---search_task` | **always** | Always helpful | Default | N/A |
214
+ | `tasks---run_prompt` | ask | Trusted contexts | Default | N/A |
215
+ | `tasks---search_parent_task` | **always** | Always helpful | Default | N/A |
216
+
217
+ **Recommended Patterns:**
218
+
219
+ ```json
220
+ // Standard task tools
221
+ {
222
+ "toolApprovals": {
223
+ "tasks---list_tasks": "always",
224
+ "tasks---get_task": "always",
225
+ "tasks---get_task_message": "always",
226
+ "tasks---search_task": "always",
227
+ "tasks---search_parent_task": "always"
228
+ }
229
+ }
230
+
231
+ // Full task management (trusted)
232
+ {
233
+ "toolApprovals": {
234
+ "tasks---list_tasks": "always",
235
+ "tasks---get_task": "always",
236
+ "tasks---get_task_message": "always",
237
+ "tasks---create_task": "always",
238
+ "tasks---delete_task": "always",
239
+ "tasks---search_task": "always",
240
+ "tasks---run_prompt": "always",
241
+ "tasks---search_parent_task": "always"
242
+ }
243
+ }
244
+ ```
245
+
246
+ ### Todo Tools (`todo---*`) — enabled by `useTodoTools`
247
+
248
+ Todo list management for tracking multi-step work.
249
+
250
+ | Tool | Recommended Default | When to Use "Always" | When to Use "Ask" | When to Use "Never" |
251
+ |------|-------------------|---------------------|-------------------|---------------------|
252
+ | `todo---set_items` | **always** | Always helpful | Default | N/A |
253
+ | `todo---get_items` | **always** | Always helpful | Default | N/A |
254
+ | `todo---update_item_completion` | **always** | Always helpful | Default | N/A |
255
+ | `todo---clear_items` | **always** | Always helpful | Default | N/A |
256
+
257
+ **Recommended Patterns:**
258
+
259
+ ```json
260
+ // Standard todo tools
261
+ {
262
+ "toolApprovals": {
263
+ "todo---set_items": "always",
264
+ "todo---get_items": "always",
265
+ "todo---update_item_completion": "always",
266
+ "todo---clear_items": "always"
267
+ }
268
+ }
269
+ ```
270
+
271
+ ### Extension Tools — enabled by `useExtensionTools`
272
+
273
+ Tools dynamically provided by installed AiderDesk extensions.
274
+
275
+ - Tool keys use `{extensionToolGroupName}---{toolName}` format
276
+ - Group names are defined by each extension individually
277
+ - Tool keys cannot be enumerated statically — they depend on installed extensions
278
+ - Use `disabledExtensionTools: ["extensionId"]` to disable all tools from a specific extension
279
+ - Set `useExtensionTools: false` to disable all extension tools entirely
280
+
281
+ **Configuration:**
282
+
283
+ ```json
284
+ // Extension tools enabled (default), disable specific extension
285
+ {
286
+ "useExtensionTools": true,
287
+ "disabledExtensionTools": ["untrusted-extension"]
288
+ }
289
+
290
+ // All extension tools disabled
291
+ {
292
+ "useExtensionTools": false,
293
+ "disabledExtensionTools": []
294
+ }
295
+ ```
296
+
297
+ **Note:** Extension tool approval keys can be added to `toolApprovals` if you know the extension's tool group name and tool names. Check the extension's documentation for the exact tool keys.
298
+
299
+ ## Tool Settings
300
+
301
+ Some tools support additional configuration beyond approval states.
302
+
303
+ ### Bash Tool Settings
304
+
305
+ Control which shell commands can be executed via `toolSettings`.
306
+
307
+ ```json
308
+ {
309
+ "toolSettings": {
310
+ "power---bash": {
311
+ "allowedPattern": "^(git|npm|ls|cat|echo)\\s",
312
+ "deniedPattern": "(rm -rf|dd|mkfs|format)"
313
+ }
314
+ }
315
+ }
316
+ ```
317
+
318
+ **Components:**
319
+ - `allowedPattern` - Regex pattern for allowed commands (empty string = all allowed)
320
+ - `deniedPattern` - Regex pattern for denied commands (overrides allowed pattern)
321
+
322
+ **Examples:**
323
+
324
+ ```json
325
+ // Allow only git commands
326
+ {
327
+ "power---bash": {
328
+ "allowedPattern": "^git\\s",
329
+ "deniedPattern": ""
330
+ }
331
+ }
332
+
333
+ // Block dangerous commands
334
+ {
335
+ "power---bash": {
336
+ "allowedPattern": "",
337
+ "deniedPattern": "(rm -rf|--force|dd|mkfs|format)"
338
+ }
339
+ }
340
+ ```
341
+
342
+ ## Best Practices
343
+
344
+ ### 1. Start Conservative
345
+ Begin with "ask" for most tools, then relax as trust builds. Only set "always" for safe read-only operations.
346
+
347
+ ### 2. Profile-Specific Defaults
348
+ Different profiles need different defaults:
349
+
350
+ - **Code Reviewer**: Read-only, always for search tools, never for edits
351
+ - **Developer**: Ask for edits, always for read operations
352
+ - **Auditor**: Never for destructive tools, always for analysis
353
+ - **Orchestrator**: Always for subagent delegation, ask for direct operations
354
+
355
+ ### 3. Group-Level Control
356
+ Use tool group toggles (`usePowerTools`, `useAiderTools`, etc.) before configuring individual tools. If a group is disabled, its tools are not available regardless of `toolApprovals`.
357
+
358
+ ### 4. Context Awareness
359
+ Consider:
360
+ - Environment (development vs production)
361
+ - User expertise level
362
+ - Project criticality
363
+ - Security requirements
364
+
365
+ ### 5. Review Regularly
366
+ Periodically audit tool approvals:
367
+ - Remove unused "never" tools
368
+ - Relax "ask" to "always" for trusted operations
369
+ - Add restrictions for security concerns
370
+
371
+ ## Common Configurations
372
+
373
+ ### Safe Development Profile
374
+ ```json
375
+ {
376
+ "usePowerTools": true,
377
+ "useTodoTools": true,
378
+ "useMemoryTools": true,
379
+ "useSkillsTools": true,
380
+ "useExtensionTools": true,
381
+ "toolApprovals": {
382
+ "power---file_read": "always",
383
+ "power---glob": "always",
384
+ "power---grep": "always",
385
+ "power---semantic_search": "always",
386
+ "memory---store_memory": "always",
387
+ "memory---retrieve_memory": "always",
388
+ "todo---set_items": "always",
389
+ "todo---get_items": "always",
390
+ "todo---update_item_completion": "always",
391
+ "todo---clear_items": "always",
392
+ "skills---activate_skill": "always"
393
+ }
394
+ }
395
+ ```
396
+
397
+ ### Read-Only Auditor Profile
398
+ ```json
399
+ {
400
+ "usePowerTools": true,
401
+ "useMemoryTools": true,
402
+ "useExtensionTools": false,
403
+ "toolApprovals": {
404
+ "power---file_read": "always",
405
+ "power---file_write": "never",
406
+ "power---file_edit": "never",
407
+ "power---glob": "always",
408
+ "power---grep": "always",
409
+ "power---semantic_search": "always",
410
+ "power---bash": "never",
411
+ "memory---store_memory": "always",
412
+ "memory---retrieve_memory": "always"
413
+ }
414
+ }
415
+ ```
416
+
417
+ ### Full Access Orchestrator Profile
418
+ ```json
419
+ {
420
+ "usePowerTools": true,
421
+ "useTodoTools": true,
422
+ "useSubagents": true,
423
+ "useTaskTools": true,
424
+ "useMemoryTools": true,
425
+ "useSkillsTools": true,
426
+ "useExtensionTools": true,
427
+ "toolApprovals": {
428
+ "power---file_read": "always",
429
+ "power---file_write": "always",
430
+ "power---file_edit": "always",
431
+ "power---glob": "always",
432
+ "power---grep": "always",
433
+ "power---semantic_search": "always",
434
+ "subagents---run_task": "always",
435
+ "tasks---list_tasks": "always",
436
+ "tasks---get_task": "always",
437
+ "tasks---get_task_message": "always",
438
+ "tasks---search_task": "always",
439
+ "tasks---search_parent_task": "always",
440
+ "memory---store_memory": "always",
441
+ "memory---retrieve_memory": "always",
442
+ "skills---activate_skill": "always",
443
+ "todo---set_items": "always",
444
+ "todo---get_items": "always",
445
+ "todo---update_item_completion": "always",
446
+ "todo---clear_items": "always"
447
+ }
448
+ }
449
+ ```
450
+
451
+ ## Troubleshooting
452
+
453
+ ### Tool Not Available
454
+ **Issue:** Agent tries to use a tool that doesn't work.
455
+
456
+ **Solution:**
457
+ 1. Verify the tool group is enabled (e.g., `usePowerTools: true`)
458
+ 2. Check `toolApprovals` — the tool might be set to "never"
459
+ 3. For extension tools, verify `useExtensionTools: true` and extension is not in `disabledExtensionTools`
460
+ 4. Verify the tool key format: `{group}---{tool}` (three dashes)
461
+
462
+ ### Excessive Prompts
463
+ **Issue:** Too many approval prompts during workflow.
464
+
465
+ **Solution:**
466
+ 1. Identify frequently-used tools
467
+ 2. Change "ask" to "always" for trusted operations
468
+ 3. Consider creating specialized profiles for different tasks
469
+
470
+ ### Tool Executes Unexpectedly
471
+ **Issue:** Tool runs without confirmation.
472
+
473
+ **Solution:**
474
+ 1. Review `toolApprovals` for "always" settings
475
+ 2. Change to "ask" for better control
476
+ 3. Implement `toolSettings` restrictions if needed
477
+
478
+ ### Bash Command Blocked
479
+ **Issue:** Shell command is denied.
480
+
481
+ **Solution:**
482
+ 1. Check `allowedPattern` regex in `toolSettings`
483
+ 2. Review `deniedPattern` restrictions
484
+ 3. Adjust patterns to permit necessary commands
@@ -68,7 +68,7 @@ Do not use when:
68
68
  3. Implement Extension interface methods
69
69
  4. Export metadata and default class
70
70
  5. **Register in `packages/extensions/extensions.json`**
71
- 6. **Document in `docs-site/docs/extensions/examples.md`**
71
+ 6. **Document in `docs-site/docs/extensions/extensions-gallery.md`**
72
72
  7. Install npm dependencies if folder extension
73
73
  8. Verify with type checking
74
74
 
@@ -154,13 +154,13 @@ Do not use when:
154
154
 
155
155
  **Must:** Set `hasDependencies: true` for folder extensions
156
156
 
157
- **Then:** Add entry to `docs-site/docs/extensions/examples.md` table
157
+ **Then:** Add entry to `docs-site/docs/extensions/extensions-gallery.md` table
158
158
 
159
159
  **Must:** Include extension name, description, capabilities, and type
160
160
 
161
161
  **When:** Target is Project or Global
162
162
 
163
- **Then:** Do NOT modify `extensions.json` or `examples.md` — these are only for built-in extensions
163
+ **Then:** Do NOT modify `extensions.json` or `extensions-gallery.md` — these are only for built-in extensions
164
164
 
165
165
  ### Rule: Use proper TypeScript config for folders
166
166
 
@@ -204,7 +204,7 @@ Do not use when:
204
204
  4. Implement Extension interface methods
205
205
  5. Export metadata and default class
206
206
  6. **Register in `packages/extensions/extensions.json`**
207
- 7. **Document in `docs-site/docs/extensions/examples.md`**
207
+ 7. **Document in `docs-site/docs/extensions/extensions-gallery.md`**
208
208
  8. Run `npm install` in `packages/extensions/` (folder extensions)
209
209
  9. Verify with type checking
210
210
 
@@ -236,7 +236,7 @@ After completing this skill, verify:
236
236
  - Default export is the extension class
237
237
  - No `@/` imports used
238
238
  - **If In-Repo:** extensions.json updated correctly
239
- - **If In-Repo:** docs-site/docs/extensions/examples.md updated
239
+ - **If In-Repo:** docs-site/docs/extensions/extensions-gallery.md updated
240
240
  - **If In-Repo:** Type checking passes
241
241
  - Extension loads without errors
242
242
  - Extension appears in extensions list
@@ -16,7 +16,7 @@ Only when:
16
16
  3. **Implement Extension interface methods**
17
17
  4. **Export metadata and default class**
18
18
  5. **Update `packages/extensions/extensions.json`** — register the extension
19
- 6. **Update `docs-site/docs/extensions/examples.md`** — document it
19
+ 6. **Update `docs-site/docs/extensions/extensions-gallery.md`** — document it
20
20
  7. **Verify with type checking and code-checker**
21
21
 
22
22
  ## Directory Structure
@@ -98,9 +98,9 @@ Add an entry to `packages/extensions/extensions.json`:
98
98
 
99
99
  **Important:** Always set `hasDependencies: true` for folder extensions, even if they don't have dependencies yet.
100
100
 
101
- ### Step 5: Document in examples.md
101
+ ### Step 5: Document in extensions-gallery.md
102
102
 
103
- Add an entry to the table in `docs-site/docs/extensions/examples.md`:
103
+ Add an entry to the table in `docs-site/docs/extensions/extensions-gallery.md`:
104
104
 
105
105
  | Extension | Description | Capabilities | Type |
106
106
  |-----------|-------------|-------------|------|
@@ -128,5 +128,5 @@ npm install
128
128
 
129
129
  - Do NOT use `@/` imports in extension files — use relative imports or `@aiderdesk/extensions` package imports only
130
130
  - Do NOT forget to update `extensions.json` — the extension won't load without registration
131
- - Do NOT forget to update `examples.md` — users won't know about the extension
131
+ - Do NOT forget to update `extensions-gallery.md` — users won't know about the extension
132
132
  - Do NOT place files outside `packages/extensions/extensions/` unless there's a specific reason (e.g., shared utilities should go in `packages/extensions/src/`)
@@ -48,7 +48,7 @@ AiderDesk extensions can be installed in three locations, each with different pu
48
48
  - Ships with the AiderDesk application as a built-in extension
49
49
  - Available to all users by default
50
50
  - Requires updating `packages/extensions/extensions.json` (the extension registry)
51
- - Requires updating documentation in `docs-site/docs/extensions/examples.md`
51
+ - Requires updating documentation in `docs-site/docs/extensions/extensions-gallery.md`
52
52
  - Must follow monorepo conventions (no `@/` imports, proper tsconfig/package.json)
53
53
  - Subject to the full AiderDesk development workflow (type checking, testing, etc.)
54
54
 
@@ -80,7 +80,7 @@ Is the current project the AiderDesk codebase itself?
80
80
  | Scope | This project only | All projects | All users (ships with app) |
81
81
  | Version controlled | Yes (with project) | No | Yes (with AiderDesk) |
82
82
  | Update extensions.json | No | No | **Yes** |
83
- | Update examples.md docs | No | No | **Yes** |
83
+ | Update extensions-gallery.md docs | No | No | **Yes** |
84
84
  | npm install needed | No | No | **Yes** (if folder extension) |
85
85
  | Available immediately | Yes | Yes | After build/restart |
86
86
 
@@ -71,6 +71,6 @@ The extension will be auto-discovered by AiderDesk from the target directory. No
71
71
  ## What NOT to do (Project/Global)
72
72
 
73
73
  - Do NOT modify `packages/extensions/extensions.json` — that registry is only for In-Repo extensions
74
- - Do NOT update `docs-site/docs/extensions/examples.md` — that's for documenting built-in extensions
74
+ - Do NOT update `docs-site/docs/extensions/extensions-gallery.md` — that's for documenting built-in extensions
75
75
  - Do NOT use `@/` imports — they won't resolve outside the AiderDesk monorepo
76
76
  - Do NOT add to `packages/common/src/` or any other AiderDesk source directory