aia 2.0.0.0.pre.beta2 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (225) hide show
  1. checksums.yaml +4 -4
  2. data/.version +1 -1
  3. data/CHANGELOG.md +146 -228
  4. data/README.md +41 -18
  5. data/bin/aia +8 -3
  6. data/lib/aia/aia_completion.bash +2 -3
  7. data/lib/aia/aia_completion.fish +6 -5
  8. data/lib/aia/aia_completion.zsh +2 -3
  9. data/lib/aia/chat_loop.rb +16 -14
  10. data/lib/aia/config/cli_parser.rb +123 -91
  11. data/lib/aia/config/defaults.yml +12 -39
  12. data/lib/aia/config/mcp_parser.rb +30 -36
  13. data/lib/aia/config/model_spec.rb +8 -14
  14. data/lib/aia/config/validator.rb +102 -103
  15. data/lib/aia/config/value_caster.rb +76 -0
  16. data/lib/aia/config.rb +70 -53
  17. data/lib/aia/crew.rb +29 -19
  18. data/lib/aia/debate_handler.rb +27 -10
  19. data/lib/aia/directives/configuration_directives.rb +55 -14
  20. data/lib/aia/directives/context_directives.rb +24 -12
  21. data/lib/aia/directives/execution_directives.rb +18 -23
  22. data/lib/aia/directives/model_directives.rb +41 -104
  23. data/lib/aia/directives/utility_directives.rb +16 -17
  24. data/lib/aia/directives/web_and_file_directives.rb +21 -14
  25. data/lib/aia/fact_asserter.rb +3 -3
  26. data/lib/aia/history_transfer.rb +64 -24
  27. data/lib/aia/logger.rb +10 -45
  28. data/lib/aia/mcp_config_normalizer.rb +27 -14
  29. data/lib/aia/mcp_connection_manager.rb +181 -184
  30. data/lib/aia/mcp_discovery.rb +43 -15
  31. data/lib/aia/mcp_grouper.rb +2 -1
  32. data/lib/aia/mcp_server_config.rb +20 -2
  33. data/lib/aia/mcp_utility.rb +24 -19
  34. data/lib/aia/mention_router.rb +15 -2
  35. data/lib/aia/modality_query.rb +36 -0
  36. data/lib/aia/model_alias_registry.rb +11 -11
  37. data/lib/aia/model_registry.rb +75 -0
  38. data/lib/aia/network_builder.rb +8 -7
  39. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  40. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  41. data/lib/aia/pipeline_orchestrator.rb +71 -38
  42. data/lib/aia/prompt_decomposer.rb +1 -1
  43. data/lib/aia/prompt_handler.rb +56 -29
  44. data/lib/aia/provider_registry.rb +105 -0
  45. data/lib/aia/robot_builder.rb +1 -1
  46. data/lib/aia/robot_factory.rb +67 -63
  47. data/lib/aia/robot_sync.rb +79 -0
  48. data/lib/aia/role_catalog.rb +89 -0
  49. data/lib/aia/session.rb +25 -11
  50. data/lib/aia/skill_utils.rb +60 -19
  51. data/lib/aia/spawn_handler.rb +16 -4
  52. data/lib/aia/spawn_spec_parser.rb +6 -7
  53. data/lib/aia/special_mode_handler.rb +28 -25
  54. data/lib/aia/speech.rb +70 -34
  55. data/lib/aia/startup_coordinator.rb +17 -92
  56. data/lib/aia/streaming_runner.rb +10 -2
  57. data/lib/aia/system_prompt_assembler.rb +12 -11
  58. data/lib/aia/task_board.rb +60 -0
  59. data/lib/aia/tool_approver.rb +205 -0
  60. data/lib/aia/tool_filter.rb +1 -10
  61. data/lib/aia/tool_filter_strategy.rb +12 -1
  62. data/lib/aia/tool_introspection.rb +9 -1
  63. data/lib/aia/tool_loader.rb +67 -33
  64. data/lib/aia/tool_utility.rb +6 -5
  65. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  66. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  67. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  68. data/lib/aia/tools/task_board_tool.rb +16 -16
  69. data/lib/aia/trakflow_bridge.rb +14 -8
  70. data/lib/aia/turn_state.rb +31 -8
  71. data/lib/aia/ui_presenter.rb +16 -0
  72. data/lib/aia/utility.rb +6 -24
  73. data/lib/aia/variable_input_collector.rb +0 -3
  74. data/lib/aia/verification_network.rb +9 -10
  75. data/lib/aia.rb +33 -8
  76. metadata +19 -160
  77. data/.better-commits.json +0 -150
  78. data/.config/tocer/configuration.yml +0 -6
  79. data/.envrc +0 -19
  80. data/.loki +0 -11
  81. data/.reek.yml +0 -160
  82. data/.rubocop.yml +0 -116
  83. data/.rubocop_strict.yml +0 -15
  84. data/COMMITS.md +0 -196
  85. data/IMPLEMENTATION_PLAN.md +0 -506
  86. data/Rakefile +0 -47
  87. data/_typos.toml +0 -10
  88. data/aia.gemspec +0 -92
  89. data/architecture_review.md +0 -314
  90. data/config/aia.yml +0 -13
  91. data/docs/AGENTS.md +0 -40
  92. data/docs/advanced-prompting.md +0 -814
  93. data/docs/assets/images/aia.png +0 -0
  94. data/docs/cli-reference.md +0 -1241
  95. data/docs/configuration.md +0 -747
  96. data/docs/contributing.md +0 -386
  97. data/docs/directives-reference.md +0 -1145
  98. data/docs/examples/index.md +0 -277
  99. data/docs/examples/mcp/index.md +0 -475
  100. data/docs/examples/prompts/analysis/index.md +0 -78
  101. data/docs/examples/prompts/automation/index.md +0 -109
  102. data/docs/examples/prompts/development/index.md +0 -125
  103. data/docs/examples/prompts/index.md +0 -333
  104. data/docs/examples/prompts/learning/index.md +0 -127
  105. data/docs/examples/prompts/writing/index.md +0 -62
  106. data/docs/examples/tools/index.md +0 -282
  107. data/docs/faq.md +0 -578
  108. data/docs/guides/available-models.md +0 -366
  109. data/docs/guides/basic-usage.md +0 -478
  110. data/docs/guides/chat.md +0 -680
  111. data/docs/guides/crew.md +0 -239
  112. data/docs/guides/executable-prompts.md +0 -331
  113. data/docs/guides/first-prompt.md +0 -454
  114. data/docs/guides/getting-started.md +0 -455
  115. data/docs/guides/image-generation.md +0 -507
  116. data/docs/guides/index.md +0 -48
  117. data/docs/guides/local-models.md +0 -306
  118. data/docs/guides/migrate-prompts.md +0 -335
  119. data/docs/guides/models.md +0 -1017
  120. data/docs/guides/shared-tools.md +0 -254
  121. data/docs/guides/tools.md +0 -831
  122. data/docs/index.md +0 -259
  123. data/docs/installation.md +0 -274
  124. data/docs/mcp-integration.md +0 -603
  125. data/docs/prompt_management.md +0 -665
  126. data/docs/security.md +0 -674
  127. data/docs/special_projects_guide.md +0 -386
  128. data/docs/tools-and-mcp-examples.md +0 -1211
  129. data/docs/workflows-and-pipelines.md +0 -636
  130. data/examples/.gitignore +0 -2
  131. data/examples/00_setup_aia.sh +0 -111
  132. data/examples/01_basic_usage.sh +0 -23
  133. data/examples/02_frontmatter.sh +0 -33
  134. data/examples/03_shell_integration.sh +0 -55
  135. data/examples/04_erb_templating.sh +0 -56
  136. data/examples/05_shell_then_erb.sh +0 -38
  137. data/examples/06_prompt_chaining.sh +0 -59
  138. data/examples/07_pipeline.sh +0 -46
  139. data/examples/08_context_files.sh +0 -43
  140. data/examples/09_roles.sh +0 -67
  141. data/examples/10_stdin_piping.sh +0 -49
  142. data/examples/11_multi_model.sh +0 -65
  143. data/examples/12_token_usage.sh +0 -52
  144. data/examples/13_cost_tracking.sh +0 -68
  145. data/examples/14_output_file.sh +0 -91
  146. data/examples/15_parameters.sh +0 -68
  147. data/examples/16_directives.sh +0 -113
  148. data/examples/17_require_and_conditionals.sh +0 -68
  149. data/examples/18_tools.sh +0 -61
  150. data/examples/19_local_tools.sh +0 -34
  151. data/examples/20_mcp_servers.sh +0 -102
  152. data/examples/21_executable_prompts.sh +0 -78
  153. data/examples/22_chat_mode.sh +0 -217
  154. data/examples/23_verify.sh +0 -139
  155. data/examples/24_decompose.sh +0 -139
  156. data/examples/25_spawn.sh +0 -139
  157. data/examples/26_debate.sh +0 -97
  158. data/examples/27_mention_routing.sh +0 -157
  159. data/examples/28_model_switching.sh +0 -106
  160. data/examples/29_agent_harness.sh +0 -177
  161. data/examples/README.md +0 -321
  162. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  163. data/examples/aia_config.yml +0 -22
  164. data/examples/aia_config_orchestrator.yml +0 -45
  165. data/examples/aia_config_with_mcp.yml +0 -21
  166. data/examples/common.sh +0 -39
  167. data/examples/context/project_goals.md +0 -6
  168. data/examples/context/tech_stack.md +0 -7
  169. data/examples/directives/timestamp_directive.rb +0 -22
  170. data/examples/mcp/filesystem.json +0 -9
  171. data/examples/prompts_dir/analyze.md +0 -2
  172. data/examples/prompts_dir/brainstorm.md +0 -2
  173. data/examples/prompts_dir/conditional.md +0 -17
  174. data/examples/prompts_dir/creative.md +0 -4
  175. data/examples/prompts_dir/erbinfo.md +0 -5
  176. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  177. data/examples/prompts_dir/evaluate.md +0 -2
  178. data/examples/prompts_dir/explain_joke.md +0 -1
  179. data/examples/prompts_dir/explain_recursion.md +0 -1
  180. data/examples/prompts_dir/fun_fact +0 -3
  181. data/examples/prompts_dir/greeting.md +0 -8
  182. data/examples/prompts_dir/greeting_required.md +0 -7
  183. data/examples/prompts_dir/hello.md +0 -1
  184. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  185. data/examples/prompts_dir/limerick.md +0 -1
  186. data/examples/prompts_dir/list_with_mcp.md +0 -3
  187. data/examples/prompts_dir/pick_best.md +0 -2
  188. data/examples/prompts_dir/project_summary +0 -12
  189. data/examples/prompts_dir/quiz_with_include.md +0 -6
  190. data/examples/prompts_dir/require_demo.md +0 -5
  191. data/examples/prompts_dir/roles/formal.md +0 -3
  192. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  193. data/examples/prompts_dir/roles/pirate.md +0 -3
  194. data/examples/prompts_dir/shell_then_erb.md +0 -6
  195. data/examples/prompts_dir/sort_compare.md +0 -2
  196. data/examples/prompts_dir/summarize_context.md +0 -2
  197. data/examples/prompts_dir/sysinfo.md +0 -5
  198. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  199. data/examples/prompts_dir/tagline.md +0 -1
  200. data/examples/prompts_dir/tell_joke.md +0 -1
  201. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  202. data/examples/prompts_dir/use_local_tool.md +0 -8
  203. data/examples/prompts_dir/use_tools.md +0 -8
  204. data/examples/prompts_dir/weather.md +0 -2
  205. data/examples/prompts_dir/whats_new.md +0 -2
  206. data/examples/prompts_dir/with_timestamp.md +0 -5
  207. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  208. data/examples/rules/01_classify_ruby.rb +0 -16
  209. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  210. data/examples/rules/03_gate_prompt_length.rb +0 -19
  211. data/examples/rules/04_tool_selection.rb +0 -41
  212. data/examples/rules/README.md +0 -30
  213. data/examples/run_all.sh +0 -294
  214. data/examples/tools/word_count_tool.rb +0 -30
  215. data/lib/AGENTS.md +0 -57
  216. data/lib/aia/model_switch_handler.rb +0 -100
  217. data/mcp_servers/README.md +0 -110
  218. data/mcp_servers/apple-mcp.json +0 -8
  219. data/mcp_servers/filesystem.json +0 -9
  220. data/mcp_servers/mcp_server_chart.json +0 -11
  221. data/mcp_servers/playwright_one.json +0 -8
  222. data/mcp_servers/playwright_server_definition.json +0 -9
  223. data/mcp_servers/playwright_two.json +0 -8
  224. data/mcp_servers/tavily_mcp_server.json +0 -8
  225. data/mkdocs.yml +0 -169
@@ -1,1145 +0,0 @@
1
- <!-- Tocer[start]: Auto-generated, don't remove. -->
2
-
3
- ## Table of Contents
4
-
5
- - [Directives Reference](#directives-reference)
6
- - [Quick Reference](#quick-reference)
7
- - [Directive Syntax](#directive-syntax)
8
- - [Configuration Directives](#configuration-directives)
9
- - [`/config`](#config)
10
- - [`/model`](#model)
11
- - [`/temperature`](#temperature)
12
- - [`/top_p`](#top_p)
13
- - [`/cost`](#cost)
14
- - [File and Web Directives](#file-and-web-directives)
15
- - [`/include`](#include)
16
- - [`/paste`](#paste)
17
- - [`/webpage`](#webpage)
18
- - [`/skill`](#skill)
19
- - [`/skills`](#skills)
20
- - [Execution Directives](#execution-directives)
21
- - [`/ruby`](#ruby)
22
- - [`/say`](#say)
23
- - [`/concurrent`](#concurrent)
24
- - [`/verify`](#verify)
25
- - [`/decompose`](#decompose)
26
- - [`/debate`](#debate)
27
- - [`/delegate`](#delegate)
28
- - [`/spawn`](#spawn)
29
- - [`/add_recruit`](#add_recruit)
30
- - [`/reskill`](#reskill)
31
- - [`/drop_recruit`](#drop_recruit)
32
- - [Utility Directives](#utility-directives)
33
- - [`/tools`](#tools)
34
- - [`/next`](#next)
35
- - [`/pipeline`](#pipeline)
36
- - [`/mcp`](#mcp)
37
- - [`/robots`](#robots)
38
- - [`/terse`](#terse)
39
- - [`/robot`](#robot)
40
- - [Context Management Directives](#context-management-directives)
41
- - [`/checkpoint`](#checkpoint)
42
- - [`/restore`](#restore)
43
- - [`/clear`](#clear)
44
- - [`/review`](#review)
45
- - [`/checkpoints_list`](#checkpoints_list)
46
- - [TrakFlow Directives](#trakflow-directives)
47
- - [`/tasks`](#tasks)
48
- - [`/plan`](#plan)
49
- - [`/task`](#task)
50
- - [Model and Information Directives](#model-and-information-directives)
51
- - [`/available_models`](#available_models)
52
- - [`/compare`](#compare)
53
- - [`/help`](#help)
54
- - [Directive Processing Order](#directive-processing-order)
55
- - [Advanced Usage Patterns](#advanced-usage-patterns)
56
- - [Combining Directives](#combining-directives)
57
- - [Dynamic Configuration](#dynamic-configuration)
58
- - [Conditional Execution](#conditional-execution)
59
- - [Workflow Automation](#workflow-automation)
60
- - [Error Handling](#error-handling)
61
- - [Common Errors](#common-errors)
62
- - [Custom Directives](#custom-directives)
63
- - [Best Practices](#best-practices)
64
- - [Security Considerations](#security-considerations)
65
- - [Safe Usage Tips](#safe-usage-tips)
66
- - [Environment Variables for Directives](#environment-variables-for-directives)
67
- - [Related Documentation](#related-documentation)
68
-
69
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
70
-
71
- # Directives Reference
72
-
73
- Directives are slash commands available during interactive chat sessions. All directives begin with `/` and are processed before the prompt is sent to the AI model.
74
-
75
- Use `/help` at any time to see all available directives.
76
-
77
- ## Quick Reference
78
-
79
- | Directive | Aliases | Description |
80
- |-----------|---------|-------------|
81
- | `/config` | `/cfg` | View or set configuration values |
82
- | `/model` | | View or change the AI model |
83
- | `/temperature` | `/temp` | Set temperature parameter |
84
- | `/top_p` | `/topp` | Set top_p parameter |
85
- | `/cost` | | Dump session cost/token metrics as CSV |
86
- | `//include` | `//import` | Include file content at prompt load time (prompt_manager, not chat-time) |
87
- | `/webpage` | `/website`, `/web` | Fetch and include web content |
88
- | `/skill` | | Include a Claude Code skill |
89
- | `/skills` | | List available Claude Code skills |
90
- | `/paste` | `/clipboard` | Paste from system clipboard |
91
- | `/ruby` | `/rb` | Execute Ruby code |
92
- | `/say` | | Text-to-speech |
93
- | `/concurrent` | `/conc` | Concurrent MCP server access |
94
- | `/verify` | | Verification network (two answers + reconciliation) |
95
- | `/decompose` | | Decompose prompt into parallel sub-tasks |
96
- | `/debate` | | Multi-round debate between robots |
97
- | `/delegate` | `/del` | Delegate subtasks via TrakFlow plan |
98
- | `/spawn` | | Spawn a one-shot specialist robot for the next prompt |
99
- | `/add_recruit` | `/add` | Recruit a persistent, `@mention`-able robot (optionally skilled) into the crew |
100
- | `/drop_recruit` | `/drop` | Remove a robot from the crew |
101
- | `/reskill` | | Reset a crew member to a clean slate and give it a new skill/role |
102
- | `/tools` | | List available tools |
103
- | `/mcp` | | MCP server connection status |
104
- | `/robots` | | Show active robot configuration |
105
- | `/robot` | | ASCII robot art |
106
- | `/help` | | Show directive help |
107
- | `/checkpoint` | `/ckp`, `/cp` | Create a conversation checkpoint |
108
- | `/restore` | | Restore to a checkpoint |
109
- | `/clear` | | Clear conversation context |
110
- | `/review` | `/context` | Review conversation with checkpoint markers |
111
- | `/checkpoints_list` | `/checkpoints` | List all checkpoints |
112
- | `/tasks` | `/tf` | Show TrakFlow ready tasks |
113
- | `/plan` | | Create a TrakFlow plan |
114
- | `/task` | | Create a TrakFlow task |
115
- | `/available_models` | `/am`, `/available`, `/all_models`, `/models`, `/llms` | List available AI models |
116
- | `/compare` | `/cmp` | Compare responses from multiple models |
117
- | `next` | | YAML front matter key: set next prompt in workflow (prompt_manager) |
118
- | `pipeline` | `workflow` | YAML front matter key: define prompt workflow sequence (prompt_manager) |
119
-
120
- ## Directive Syntax
121
-
122
- ```markdown
123
- /directive_name arguments
124
- ```
125
-
126
- Examples:
127
- ```markdown
128
- /config temperature 0.8
129
- /model gpt-4o, claude-sonnet-4
130
- /debate
131
- Should we use a monolith or microservices?
132
- ```
133
-
134
- ## Configuration Directives
135
-
136
- ### `/config`
137
- Configure AIA settings from within prompts.
138
-
139
- **Syntax**: `/config [option] [value]`
140
-
141
- **Examples**:
142
- ```markdown
143
- /config model gpt-4
144
- /config temperature 0.8
145
- /config max_tokens 2000
146
- /config verbose true
147
- ```
148
-
149
- **Usage**:
150
- - `/config` - Display all configuration
151
- - `/config option` - Display specific configuration option
152
- - `/config option value` - Set configuration option
153
-
154
- **Aliases**: `/cfg`
155
-
156
- ### `/model`
157
- Display or switch the AI model. Changes take effect immediately — the client is recreated with the new model(s) without restarting the session.
158
-
159
- **Syntax**: `/model [model_spec]`
160
-
161
- **Examples**:
162
- ```markdown
163
- /model # Show current model details
164
- /model gpt-4o-mini # Switch to a single model
165
- /model claude-sonnet-4 # Switch provider (Anthropic)
166
- /model gpt-4o, claude-sonnet-4 # Switch to multi-model
167
- /model gpt-4o=architect, claude=security # Multi-model with roles
168
- ```
169
-
170
- **Usage**:
171
- - `/model` - Display current model configuration and details
172
- - `/model name` - Switch to a single model (any provider)
173
- - `/model name1, name2` - Switch to multi-model configuration
174
- - `/model name1=role1, name2=role2` - Multi-model with per-model roles
175
-
176
- Comma-separated values follow the same `MODEL[=ROLE]` syntax used by the `--model` CLI flag.
177
-
178
- For single-model display, shows full model details including provider, context window, pricing, and capabilities.
179
-
180
- For multi-model configurations, displays:
181
- - Model count and primary model
182
- - Consensus mode status
183
- - Detailed information for each model including provider, context window, costs, and capabilities
184
-
185
- ### `/temperature`
186
- Set the creativity/randomness of AI responses.
187
-
188
- **Syntax**: `/temperature value`
189
-
190
- **Examples**:
191
- ```markdown
192
- /temperature 0.1 # Very focused
193
- /temperature 0.7 # Balanced (default)
194
- /temperature 1.2 # Creative
195
- /temperature 2.0 # Very creative
196
- ```
197
-
198
- **Aliases**: `/temp`
199
-
200
- ### `/top_p`
201
- Set nucleus sampling parameter (alternative to temperature).
202
-
203
- **Syntax**: `/top_p value`
204
-
205
- **Examples**:
206
- ```markdown
207
- /top_p 0.1 # Very focused
208
- /top_p 0.9 # More diverse
209
- ```
210
-
211
- **Aliases**: `/topp`
212
-
213
- ### `/cost`
214
- Dump session cost and token metrics as CSV.
215
-
216
- **Syntax**: `/cost`
217
-
218
- **Example Output**:
219
- ```
220
- model,input_tokens,output_tokens,total_tokens,cost,elapsed,similarity
221
- gpt-4o,1234,567,1801,$0.01234,2.3s,ref
222
- claude-sonnet-4-20250514,1234,890,2124,$0.00987,3.1s,87.2%
223
- TOTAL,2468,1457,3925,$0.02221,3.1s,
224
- ```
225
-
226
- **Features**:
227
- - Shows per-turn breakdown: model, token counts, cost, elapsed time
228
- - Includes similarity scores when multi-model mode is active
229
- - Appends CSV to output file when `--output` is configured
230
- - Totals row at the bottom summarizes the session
231
-
232
- ## File and Web Directives
233
-
234
- ### `/include`
235
- Include content from files into a prompt file.
236
-
237
- > **Note**: `/include` (also written as `//include` in prompt files) is handled by the
238
- > `prompt_manager` gem **during prompt loading**, before AIA processes the prompt.
239
- > It is NOT a chat-time directive — you cannot type `/include` at the chat prompt and
240
- > have it evaluated interactively. The inclusion happens when the prompt file is read
241
- > from disk, so the included content is already present by the time AIA sees the prompt.
242
-
243
- **Syntax** (inside a `.md` prompt file): `//include path_or_url`
244
-
245
- **Examples** (in prompt files):
246
- ```markdown
247
- //include README.md
248
- //include /path/to/config.yml
249
- //include ~/Documents/notes.md
250
- ```
251
-
252
- **Features**:
253
- - Supports tilde (`~`) and environment variable expansion
254
- - Prevents circular inclusions
255
- - Handles both absolute and relative file paths
256
-
257
- **Aliases**: `//import`
258
-
259
- ### `/paste`
260
- Insert content from the system clipboard.
261
-
262
- **Syntax**: `/paste`
263
-
264
- **Examples**:
265
- ```markdown
266
- /paste
267
- ```
268
-
269
- **Features**:
270
- - Inserts the current clipboard contents directly into the prompt
271
- - Useful for quickly including copied text, code, or data
272
- - Works across different platforms (macOS, Linux, Windows)
273
- - Handles multi-line clipboard content
274
-
275
- **Aliases**: `/clipboard`
276
-
277
- ### `/webpage`
278
- Include content from web pages (requires PUREMD_API_KEY).
279
-
280
- **Syntax**: `/webpage url`
281
-
282
- **Examples**:
283
- ```markdown
284
- /webpage https://docs.example.com/api
285
- /webpage https://github.com/user/repo/blob/main/README.md
286
- ```
287
-
288
- **Prerequisites**:
289
- Set the PUREMD_API_KEY environment variable:
290
- ```bash
291
- export PUREMD_API_KEY="your_api_key"
292
- ```
293
-
294
- **Aliases**: `/website`, `/web`
295
-
296
- ### `/skill`
297
- Include an AIA skill into the conversation context.
298
-
299
- **Syntax**: `/skill skill_name`
300
-
301
- **Examples**:
302
- ```markdown
303
- /skill code-quality # Exact match
304
- /skill code # Prefix match (finds first alphabetical match starting with "code")
305
- /skill frontend-design # Exact match
306
- /skill front # Prefix match (finds "frontend-design")
307
- ```
308
-
309
- **Features**:
310
- - Reads `SKILL.md` from `<skills_dir>/<skill_name>/`
311
- - Skills directory: `AIA.config.skills.dir` (default `~/.prompts/skills`); if `AIA_PROMPTS__SKILLS_PREFIX` is set, appended to `AIA_PROMPTS__DIR` to form the base
312
- - Supports prefix matching: `/skill code` finds the first subdirectory starting with "code"
313
- - Exact matches take priority over prefix matches
314
- - Returns the full `SKILL.md` content for inclusion in the prompt
315
-
316
- **Error Handling**:
317
- Errors are printed to stdout (visible to the user) and return `nil` so nothing is injected into the AI prompt:
318
- - Missing skill name: `Error: /skill requires a skill name. Use /skills to list available skills.`
319
- - No matching directory: `Error: No skill matching 'name' found in <skills_dir>. Use /skills to list available skills.`
320
- - Directory exists but no SKILL.md: `Error: Skill 'name' has no SKILL.md in <skills_dir>.`
321
-
322
- ### `/skills`
323
- List available AIA skills, optionally filtered by search terms.
324
-
325
- **Syntax**: `/skills [search_terms...]`
326
-
327
- **Example Output** (`/skills`):
328
- ```
329
- code-assist: Code Assist
330
- Help with coding tasks.
331
-
332
- code-quality: Code Quality
333
- Enforce SOLID principles and clean code guidelines across all
334
- language targets.
335
-
336
- frontend-design: Frontend Design
337
- Build interfaces.
338
-
339
- ```
340
-
341
- **Search Term Filtering**:
342
- - `/skills ruby arch` — show only skills whose YAML front matter contains both `ruby` AND `arch` (AND logic, case-insensitive substring match)
343
- - Prefix `+` is treated as positive (same as bare term): `/skills +ruby`
344
- - Prefix `-`, `~`, or `!` is AND NOT — excludes matching skills: `/skills ruby -test`
345
- - Multiple negative terms each exclude independently
346
-
347
- **Features**:
348
- - Only lists subdirectories that contain a `SKILL.md` file; plain files and dirs without `SKILL.md` are ignored
349
- - Skills directory: `AIA.config.skills.dir` (default `~/.prompts/skills`); if `AIA_PROMPTS__SKILLS_PREFIX` is set, appended to `AIA_PROMPTS__DIR` to form the base
350
- - Results sorted alphabetically by skill ID
351
- - Descriptions are word-wrapped to terminal width with 2-space indent on continuation lines
352
- - Displays to STDOUT only (does not inject content into the AI prompt)
353
-
354
- ## Execution Directives
355
-
356
- ### `/ruby`
357
- Execute arbitrary Ruby code and insert the result.
358
-
359
- > **Security note:** `/ruby` executes the provided expression via `eval()` with no sandboxing. It has full access to the Ruby environment, the filesystem, and all loaded gems — equivalent to running arbitrary Ruby code in your terminal. Only use `/ruby` in prompts you trust. Do not share prompts containing `/ruby` unless you have reviewed their content.
360
-
361
- **Syntax**: `/ruby expression`
362
-
363
- **Examples**:
364
- ```markdown
365
- /ruby Time.now.strftime('%Y-%m-%d')
366
- /ruby Dir.glob('*.rb').size
367
- /ruby ENV['USER']
368
- ```
369
-
370
- **Features**:
371
- - Evaluates the Ruby expression and inserts the string result into the prompt
372
- - Has full access to the Ruby environment and loaded gems
373
- - Returns error details if execution fails
374
-
375
- **Aliases**: `/rb`
376
-
377
- ### `/say`
378
- Speak text using system text-to-speech (macOS/Linux).
379
-
380
- **Syntax**: `/say text to speak`
381
-
382
- **Examples**:
383
- ```markdown
384
- /say Build completed successfully
385
- /say Warning: Check the logs
386
- ```
387
-
388
- **Platform Support**:
389
- - macOS: Uses built-in `say` command
390
- - Linux: Requires `espeak` or similar TTS software
391
-
392
- ### `/concurrent`
393
- Execute the next prompt with concurrent MCP server access. AIA groups independent MCP servers and queries them in parallel, then synthesizes the results.
394
-
395
- **Syntax**: `/concurrent`
396
-
397
- **Examples**:
398
- ```markdown
399
- /concurrent
400
- What files changed this week and are there any open issues related to them?
401
- ```
402
-
403
- **Features**:
404
- - Enables concurrent MCP mode for the next prompt only
405
- - Independent MCP servers are queried in parallel
406
- - A "Weaver" synthesizer robot merges the results
407
- - Requires at least 2 MCP servers to be connected
408
-
409
- **Aliases**: `/conc`
410
-
411
- ### `/verify`
412
- Run the next prompt through a verification network. Two independent robots answer the same question, then a reconciler compares and merges the responses.
413
-
414
- **Syntax**: `/verify`
415
-
416
- **Examples**:
417
- ```markdown
418
- /verify
419
- Is this SQL query safe from injection attacks?
420
- ```
421
-
422
- **Features**:
423
- - Two robots independently answer the prompt
424
- - A third robot reconciles any differences
425
- - Increases confidence in factual or analytical answers
426
- - Requires a multi-model or network configuration
427
-
428
- ### `/decompose`
429
- Decompose the next prompt into independent, concurrently-executable sub-tasks. The prompt is analyzed by a coordinator model, broken into pieces that have **no dependencies on each other**, each solved in parallel via `Async::Barrier`, and the results synthesized into a single response.
430
-
431
- **Syntax**: `/decompose`
432
-
433
- **Examples**:
434
- ```markdown
435
- /decompose
436
- Analyze this codebase: review the test coverage, check for security issues, and assess performance.
437
- ```
438
-
439
- **Features**:
440
- - Sub-tasks returned are **always guaranteed to be independent** — they can all run concurrently without waiting on each other
441
- - If the prompt cannot be split into parallel work (e.g., tasks that must run sequentially or build on each other's output), the model returns an **empty subtasks array** and the prompt executes normally as a single request
442
- - 2–5 sub-tasks maximum; single-step prompts are never decomposed
443
- - Results from all parallel branches are synthesized into one coherent final response by the coordinator
444
- - Best for prompts with multiple truly distinct aspects (e.g., "review X, analyze Y, and summarize Z" where X, Y, Z are independent)
445
- - **Not suitable for sequential workflows** — use `/pipeline` or `/next` when tasks must chain
446
-
447
- > **Design guarantee**: The decomposition model is explicitly instructed to return an empty `subtasks` array whenever any sub-task depends on the result of another. Parallelism is never approximated — it is either fully concurrent or the prompt runs as a whole.
448
-
449
- ### `/debate`
450
- Enable multi-round debate between robots in the network. Robots argue different perspectives and converge toward a consensus answer.
451
-
452
- **Syntax**: `/debate`
453
-
454
- **Examples**:
455
- ```markdown
456
- /debate
457
- Should we use microservices or a monolith for this project?
458
- ```
459
-
460
- **Features**:
461
- - Runs up to 5 rounds of debate between network robots
462
- - Each robot sees all previous arguments before responding
463
- - Debate ends early when robots signal convergence (CONVERGED keyword)
464
- - Results include all debate rounds formatted as markdown
465
- - Writes debate history to network memory for context
466
- - Requires a multi-model network (2+ models)
467
-
468
- ### `/delegate`
469
- Delegate subtasks to specific robots via a structured TrakFlow plan. The lead robot decomposes the prompt into a JSON task plan, and robots execute steps sequentially.
470
-
471
- **Syntax**: `/delegate`
472
-
473
- **Examples**:
474
- ```markdown
475
- /delegate
476
- Build a REST API with authentication, rate limiting, and documentation.
477
- ```
478
-
479
- **Features**:
480
- - Lead robot creates a structured task decomposition (JSON)
481
- - TaskCoordinator creates a TrakFlow plan from the decomposition
482
- - Each subtask is assigned to and executed by a specific robot
483
- - Prior step results flow as context into subsequent steps
484
- - Creates a full execution trace with per-step results
485
- - Requires a multi-model network
486
-
487
- **Aliases**: `/del`
488
-
489
- ### `/spawn`
490
- Spawn a specialist robot for the **next prompt only**. The specialist is a
491
- one-shot helper — it does not join the crew. To add a persistent, `@mention`-able
492
- member instead, use [`/add_recruit`](#add_recruit).
493
-
494
- **Syntax**: `/spawn` | `/spawn <type>` | `/spawn <name> <provider/model> <system prompt...>`
495
-
496
- **Examples**:
497
- ```markdown
498
- # Auto-detect the best specialist type from the prompt
499
- /spawn
500
- Write a comprehensive test suite for the User model.
501
-
502
- # Named specialist type
503
- /spawn security
504
- Audit this authentication module for vulnerabilities.
505
-
506
- # Fully explicit: name, provider/model, and system prompt
507
- /spawn researcher ollama/qwen3.6:latest You are careful and cite sources.
508
- Summarize the latest changes to the locking strategy.
509
- ```
510
-
511
- **Features**:
512
- - No arguments: auto-detects the best specialist type from the prompt content.
513
- - A single `<type>` argument: spawns a specialist of that type (e.g., `security`, `testing`, `performance`), inheriting the current model with a domain-specific system prompt.
514
- - Explicit form (`<name> <provider/model> <system prompt>`): sets the name, model/provider, and system prompt directly. Use `-` or `inherit` as the model token to keep the parent's model; `lms/...` maps to the `openai` provider.
515
- - Specialist robots are cached and reused within the session.
516
- - Creates a TrakFlow task when task coordination is active.
517
-
518
- ### `/add_recruit`
519
- Recruit a new robot into the crew. Unlike `/spawn`, a recruit **persists** for
520
- the rest of the session, appears in [`/robots`](#robots), and answers to
521
- `@name`. Recruits inherit the chief's local tools and connected MCP servers.
522
-
523
- **Aliases**: `/add`
524
-
525
- **Syntax**: `/add_recruit <name> [provider/model] [skill:<id>...] [system prompt...]`
526
-
527
- **Examples**:
528
- ```markdown
529
- # Inherit the chief's model and a default persona
530
- /add_recruit researcher
531
-
532
- # Explicit provider/model plus a system prompt
533
- /add_recruit critic anthropic/claude-3-5-sonnet You are a ruthless design critic.
534
-
535
- # A local-model member
536
- /add_recruit local ollama/qwen3.6:latest You are concise and fast.
537
-
538
- # Assign a skill as the member's role (divides labor across the crew)
539
- /add_recruit reviewer skill:security-review
540
- /add_recruit reviewer - skill:security-review,ruby-style focus on the auth module
541
- ```
542
-
543
- **Features**:
544
- - `<name>` is required and must be unique within the crew. `crew` is reserved (it is the broadcast handle, `@crew`).
545
- - Omit `provider/model` to inherit the chief's model and provider; use `-` or `inherit` to inherit explicitly while still supplying skills or a system prompt.
546
- - A `skill:<id>` token (anywhere after the name; comma-separate or repeat for several) assigns one or more [skills](guides/crew.md#giving-a-recruit-a-role-with-skills) as the member's role. The skill bodies become its system prompt; an unknown id is reported.
547
- - Everything else after the model becomes the member's system prompt, appended after any skills.
548
- - Address the recruit afterward with `@name`, or broadcast to the whole crew with `@crew`.
549
-
550
- ### `/reskill`
551
- Reset a crew member to a clean slate (a fresh conversation) and give it a new
552
- role. The member keeps its `@name` and model. The chief cannot be reskilled.
553
-
554
- **Syntax**: `/reskill <name> [skill:<id>...] [system prompt...]`
555
-
556
- **Examples**:
557
- ```markdown
558
- # Repurpose a member with a different skill
559
- /reskill larry skill:test-writing
560
-
561
- # Or hand it a freeform role
562
- /reskill larry you now summarize the other members' findings
563
- ```
564
-
565
- **Features**:
566
- - Same `skill:<id>` and trailing-system-prompt handling as `/add_recruit` (there is no model token — the member's existing model is preserved).
567
- - Useful for recovering a member that drifted off task, or moving the crew through phases (review → fix → summarize) without re-creating robots.
568
-
569
- ### `/drop_recruit`
570
- Remove a robot from the crew by name. The chief (the session's lead robot)
571
- cannot be dropped.
572
-
573
- **Aliases**: `/drop`
574
-
575
- **Syntax**: `/drop_recruit <name>`
576
-
577
- **Examples**:
578
- ```markdown
579
- /drop_recruit researcher
580
- ```
581
-
582
- See the [Crews guide](guides/crew.md) for `@mention` routing, `@crew`
583
- broadcast, and concurrent vs. sequential execution.
584
-
585
- ## Utility Directives
586
-
587
- ### `/tools`
588
- Display available RubyLLM tools with optional filtering.
589
-
590
- **Syntax**: `/tools [filter]`
591
-
592
- **Parameters**:
593
- - `filter` (optional) - Case-insensitive substring to filter tool names
594
-
595
- **Examples**:
596
- ```markdown
597
- /tools # List all available tools
598
- /tools file # List tools with "file" in the name
599
- /tools analyzer # List tools with "analyzer" in the name
600
- ```
601
-
602
- **Example Output** (unfiltered):
603
- ```
604
- Available Tools
605
- ===============
606
-
607
- FileReader
608
- ----------
609
- Read and analyze file contents with support for multiple formats
610
- including text, JSON, YAML, and CSV files.
611
-
612
- WebScraper
613
- ----------
614
- Extract and parse content from web pages with customizable
615
- selectors and filters.
616
- ```
617
-
618
- **Example Output** (filtered with `/tools file`):
619
- ```
620
- Available Tools (filtered by 'file')
621
- ====================================
622
-
623
- FileReader
624
- ----------
625
- Read and analyze file contents with support for multiple formats
626
- including text, JSON, YAML, and CSV files.
627
- ```
628
-
629
- **Notes**:
630
- - When no tools match the filter, displays "No tools match the filter: [filter]"
631
- - Filtering is case-insensitive (e.g., "File", "FILE", and "file" all match)
632
-
633
- ### `/next`
634
- Declare the next prompt to execute after this one in a workflow.
635
-
636
- > **Note**: `next` is a **YAML front matter key** written at the top of a `.md` prompt
637
- > file, not a chat-time slash command. It is processed by the prompt loader when the
638
- > file is read, not interactively during a chat session.
639
-
640
- **Syntax** (YAML front matter in a prompt file):
641
- ```yaml
642
- ---
643
- next: analyze_results
644
- ---
645
- Your prompt body here.
646
- ```
647
-
648
- **Examples** (prompt files with `next` front matter):
649
- ```yaml
650
- ---
651
- next: generate_report
652
- ---
653
- Summarize the extracted data.
654
- ```
655
-
656
- ```yaml
657
- ---
658
- next: finalize
659
- ---
660
- Analyze the results and identify key findings.
661
- ```
662
-
663
- **Usage**: When AIA finishes running a prompt that has a `next` key in its front
664
- matter, it automatically loads and executes the named prompt next.
665
-
666
- ### `/pipeline`
667
- Declare an ordered sequence of prompts to run as a workflow.
668
-
669
- > **Note**: `pipeline` is a **YAML front matter key** written at the top of a `.md`
670
- > prompt file, not a chat-time slash command. It is processed by the prompt loader
671
- > when the file is read, not interactively during a chat session. The alias
672
- > `workflow` is also accepted as a front matter key.
673
-
674
- **Syntax** (YAML front matter in a prompt file):
675
- ```yaml
676
- ---
677
- pipeline: prompt1, prompt2, prompt3
678
- ---
679
- Your prompt body here.
680
- ```
681
-
682
- **Examples** (prompt files with `pipeline` front matter):
683
- ```yaml
684
- ---
685
- pipeline: extract_data, analyze, report
686
- ---
687
- Begin the automated data processing workflow.
688
- ```
689
-
690
- ```yaml
691
- ---
692
- workflow: code_review, optimize, test
693
- ---
694
- Start the code quality pipeline.
695
- ```
696
-
697
- **Usage**: When AIA loads a prompt that has a `pipeline` (or `workflow`) key in its
698
- front matter, it queues all listed prompts in order and runs them sequentially.
699
-
700
- **Aliases**: `workflow` (as a front matter key)
701
-
702
- ### `/mcp`
703
- Show MCP server connection status and available tools per server.
704
-
705
- **Syntax**: `/mcp`
706
-
707
- **Example Output**:
708
- ```
709
- MCP Server Status
710
- =================
711
- Defined: 5 Connected: 3 Failed: 2
712
-
713
- Connected Servers:
714
- github (12 tools)
715
- - github_create_issue
716
- - github_list_repos
717
- ...
718
- filesystem (4 tools)
719
- - read_file
720
- - write_file
721
- ...
722
-
723
- Failed Servers:
724
- slack: Connection refused
725
- jira: Authentication failed
726
- ```
727
-
728
- **Features**:
729
- - Shows count of defined, connected, and failed MCP servers
730
- - Lists each connected server with its tool count and tool names
731
- - Shows error details for failed server connections
732
- - Respects `--mcp-use` and `--mcp-skip` filtering
733
-
734
- ### `/robots`
735
- Show active robot configuration — the current robot or network topology.
736
-
737
- **Syntax**: `/robots`
738
-
739
- **Example Output** (single robot):
740
- ```
741
- Active Robot
742
- ============
743
- Mode: Single
744
-
745
- Tobor
746
- Model: gpt-4o (openai)
747
- Wage: $0.0050 in / $0.0150 out per 1K tokens
748
- Tools: 8 (3 local, 5 mcp)
749
- Role: (default)
750
- ```
751
-
752
- **Example Output** (multi-model network):
753
- ```
754
- Active Robots
755
- =============
756
- Mode: Consensus Network (3 robots)
757
-
758
- Tobor
759
- Model: gpt-4o (openai)
760
- Wage: $0.0050 in / $0.0150 out per 1K tokens
761
- Tools: 5 (2 local, 3 mcp)
762
- Role: architect
763
-
764
- Spark
765
- Model: claude-sonnet-4-20250514 (anthropic)
766
- Wage: $0.0030 in / $0.0150 out per 1K tokens
767
- Tools: 5 (2 local, 3 mcp)
768
- Role: security
769
-
770
- Weaver
771
- Model: gpt-4o (openai)
772
- Wage: $0.0050 in / $0.0150 out per 1K tokens
773
- Tools: 0
774
- Role: (default)
775
- ```
776
-
777
- **Features**:
778
- - Shows mode: Single, Parallel, Consensus, or Pipeline
779
- - Displays robot name, model, provider, cost, tools, and role
780
- - For networks, shows all robots including the Weaver synthesizer
781
-
782
- ### `/terse`
783
- *Deprecated.* Previously added an instruction for concise responses. Now a no-op.
784
-
785
- ### `/robot`
786
- Generate ASCII art robot.
787
-
788
- **Syntax**: `/robot`
789
-
790
- Inserts a fun ASCII robot character for visual breaks in prompts.
791
-
792
- ## Context Management Directives
793
-
794
- ### `/checkpoint`
795
- Create a named checkpoint of the current conversation context.
796
-
797
- **Syntax**: `/checkpoint [name]`
798
-
799
- **Examples**:
800
- ```markdown
801
- /checkpoint # Auto-named checkpoint (1, 2, 3...)
802
- /checkpoint important_decision # Named checkpoint
803
- /checkpoint before_refactor # Descriptive name
804
- ```
805
-
806
- **Features**:
807
- - **Auto-naming**: If no name provided, uses incrementing integers (1, 2, 3...)
808
- - **Named checkpoints**: Use meaningful names for easy identification
809
- - **Deep copying**: Safely stores complete conversation state
810
- - **Chat mode only**: Only available during interactive chat sessions
811
-
812
- **Usage**:
813
- - `/checkpoint` - Create an auto-named checkpoint
814
- - `/checkpoint name` - Create a checkpoint with specific name
815
-
816
- **Aliases**: `/ckp`, `/cp`
817
-
818
- ### `/restore`
819
- Restore conversation context to a previously saved checkpoint.
820
-
821
- **Syntax**: `/restore [name]`
822
-
823
- **Examples**:
824
- ```markdown
825
- /restore # Restore to last checkpoint
826
- /restore important_decision # Restore to named checkpoint
827
- /restore 1 # Restore to auto-named checkpoint
828
- ```
829
-
830
- **Features**:
831
- - **Default behavior**: Without a name, restores to the most recent checkpoint
832
- - **Named restoration**: Restore to any previously saved checkpoint
833
- - **Context truncation**: Removes all messages added after the checkpoint
834
- - **Client refresh**: Automatically refreshes AI client context
835
-
836
- **Usage**:
837
- - `/restore` - Restore to the last checkpoint created
838
- - `/restore name` - Restore to a specific named checkpoint
839
- - Returns error message if checkpoint doesn't exist
840
-
841
- ### `/clear`
842
- Clear conversation context in chat mode.
843
-
844
- **Syntax**: `/clear`
845
-
846
- **Usage**: Only available during chat sessions. Clears the conversation history and all checkpoints while keeping the session active.
847
-
848
- ### `/review`
849
- Display current conversation context with checkpoint markers.
850
-
851
- **Syntax**: `/review`
852
-
853
- **Aliases**: `/context`
854
-
855
- **Example Output**:
856
- ```
857
- === Chat Context ===
858
- Total messages: 5
859
- Checkpoints: ruby_basics, oop_concepts
860
-
861
- 1. [System]: You are a helpful assistant
862
- 2. [User]: Tell me about Ruby programming
863
- 3. [Assistant]: Ruby is a dynamic programming language...
864
-
865
- 📍 [Checkpoint: ruby_basics]
866
- ----------------------------------------
867
- 4. [User]: Now explain object-oriented programming
868
- 5. [Assistant]: Object-oriented programming (OOP) is...
869
-
870
- 📍 [Checkpoint: oop_concepts]
871
- ----------------------------------------
872
- === End of Context ===
873
- ```
874
-
875
- **Features**:
876
- - Shows complete conversation history with message numbers
877
- - Displays checkpoint markers (📍) at their exact positions
878
- - Lists all available checkpoints
879
- - Truncates long messages for readability (200 characters)
880
- - Shows total message count and checkpoint summary
881
-
882
- ### `/checkpoints_list`
883
- List all saved checkpoints with their positions and timestamps.
884
-
885
- **Syntax**: `/checkpoints_list`
886
-
887
- **Example Output**:
888
- ```
889
- === Available Checkpoints ===
890
- 1: position 4, created 14:32:07
891
- → "Tell me about Ruby programming"
892
- before_refactor: position 8, created 14:45:22
893
- → "Now refactor the User model"
894
- === End of Checkpoints ===
895
- ```
896
-
897
- **Features**:
898
- - Shows checkpoint name, conversation position, and creation time
899
- - Includes a preview of the last user message at the checkpoint
900
- - Displays "No checkpoints available." when none exist
901
-
902
- **Aliases**: `/checkpoints`
903
-
904
- ## TrakFlow Directives
905
-
906
- TrakFlow is AIA's built-in task tracking system for managing multi-step work.
907
-
908
- ### `/tasks`
909
- Show TrakFlow ready tasks and project summary.
910
-
911
- **Syntax**: `/tasks [summary]`
912
-
913
- **Examples**:
914
- ```markdown
915
- /tasks # Show ready tasks
916
- /tasks summary # Show project summary
917
- ```
918
-
919
- **Features**:
920
- - Without arguments: lists tasks that are ready to be worked on
921
- - With `summary`: shows the overall project status
922
- - Returns an initialization message if TrakFlow is not set up
923
-
924
- **Aliases**: `/tf`
925
-
926
- ### `/plan`
927
- Create a TrakFlow plan from a description. The description is decomposed into actionable tasks.
928
-
929
- **Syntax**: `/plan description`
930
-
931
- **Examples**:
932
- ```markdown
933
- /plan Build user authentication with login, signup, and password reset
934
- /plan Refactor the payment module into separate service objects
935
- ```
936
-
937
- ### `/task`
938
- Create a single TrakFlow task.
939
-
940
- **Syntax**: `/task title`
941
-
942
- **Examples**:
943
- ```markdown
944
- /task Add input validation to the registration form
945
- /task Write integration tests for the API endpoints
946
- ```
947
-
948
- ## Model and Information Directives
949
-
950
- ### `/available_models`
951
- List available AI models with filtering.
952
-
953
- **Syntax**: `/available_models [filter1,filter2,...]`
954
-
955
- **Examples**:
956
- ```markdown
957
- /available_models
958
- /available_models openai
959
- /available_models gpt,4
960
- /available_models text_to_image
961
- /available_models claude,sonnet
962
- ```
963
-
964
- **Filter Options**:
965
- - Provider names: `openai`, `anthropic`, `google`, etc.
966
- - Model names: `gpt`, `claude`, `gemini`, etc.
967
- - Capabilities: `vision`, `function_calling`, `image_generation`
968
- - Modalities: `text_to_text`, `text_to_image`, `image_to_text`
969
-
970
- **Output includes**:
971
- - Model name and provider
972
- - Input cost per million tokens
973
- - Context window size
974
- - Input/output modalities
975
- - Capabilities
976
-
977
- **Aliases**: `/am`, `/available`, `/models`, `/all_models`, `/llms`
978
-
979
- ### `/compare`
980
- Compare responses from multiple models.
981
-
982
- **Syntax**: `/compare prompt --models model1,model2,model3`
983
-
984
- **Examples**:
985
- ```markdown
986
- /compare "Explain quantum computing" --models gpt-4,claude-3-sonnet,gemini-pro
987
- /compare "Write a Python function to sort a list" --models gpt-3.5-turbo,gpt-4,claude-3-haiku
988
- ```
989
-
990
- **Features**:
991
- - Side-by-side model comparison
992
- - Error handling for unavailable models
993
- - Formatted output with clear model labels
994
-
995
- **Aliases**: `/cmp`
996
-
997
- ### `/help`
998
- Display available directives and their descriptions.
999
-
1000
- **Syntax**: `/help`
1001
-
1002
- **Output**: Complete list of all directives with descriptions and aliases.
1003
-
1004
- ## Directive Processing Order
1005
-
1006
- Directives are processed in the order they appear in the prompt:
1007
-
1008
- 1. **Configuration directives** (like `/config`, `/model`) are processed first
1009
- 2. **File inclusion directives** (`/include`, `/webpage`) are processed next
1010
- 3. **ERB directives** (`<%= %>`) are processed
1011
- 4. **Utility directives** are processed last
1012
-
1013
- ## Advanced Usage Patterns
1014
-
1015
- ### Combining Directives
1016
-
1017
- ```markdown
1018
- /config model gpt-4
1019
- /config temperature 0.3
1020
- /include project_context.md
1021
-
1022
- Based on the project information above:
1023
- <%= `git log --oneline -5` %>
1024
-
1025
- Analyze these recent commits and suggest improvements.
1026
- ```
1027
-
1028
- ### Dynamic Configuration
1029
-
1030
- ```markdown
1031
- <% model_name = ENV['PREFERRED_MODEL'] || 'gpt-3.5-turbo' %>
1032
- /config model <%= model_name %>
1033
- /config temperature <%= ENV['AI_TEMPERATURE'] || '0.7' %>
1034
-
1035
- Process this data with optimized settings.
1036
- ```
1037
-
1038
- ### Conditional Execution
1039
-
1040
- ```markdown
1041
- <% if File.exist?('production.yml') %>
1042
- /include production.yml
1043
- <% else %>
1044
- /include development.yml
1045
- <% end %>
1046
-
1047
- Configure the system based on environment.
1048
- ```
1049
-
1050
- ### Workflow Automation
1051
-
1052
- ```markdown
1053
- /pipeline data_extraction,data_cleaning,analysis,reporting
1054
- /config model claude-3-sonnet
1055
- /config temperature 0.2
1056
-
1057
- Begin automated data processing workflow.
1058
- ```
1059
-
1060
- ## Error Handling
1061
-
1062
- ### Common Errors
1063
-
1064
- **File Not Found**:
1065
- ```
1066
- Error: File 'missing.md' is not accessible
1067
- ```
1068
-
1069
- **Ruby Execution Error**:
1070
- ```
1071
- This ruby code failed: invalid_syntax
1072
- SyntaxError: unexpected token
1073
- ```
1074
-
1075
- **Web Access Error**:
1076
- ```
1077
- ERROR: PUREMD_API_KEY is required in order to include a webpage
1078
- ```
1079
-
1080
- ### Custom Directives
1081
-
1082
- You can extend AIA with custom directives by subclassing `AIA::Directive`:
1083
-
1084
- ```ruby
1085
- # examples/directives/timestamp_directive.rb
1086
- module AIA
1087
- class CustomDirectives < Directive
1088
- desc "Insert current timestamp (optional strftime format, default: %Y-%m-%d %H:%M:%S)"
1089
- def timestamp(args = [], context_manager = nil)
1090
- format = args.empty? ? '%Y-%m-%d %H:%M:%S' : args.join(' ')
1091
- Time.now.strftime(format)
1092
- end
1093
- end
1094
- end
1095
- ```
1096
-
1097
- **Usage:** Load custom directives with the `--tools` option:
1098
-
1099
- ```bash
1100
- # Load custom directive
1101
- aia --tools examples/directives/timestamp_directive.rb --chat
1102
-
1103
- # Use in chat mode
1104
- /timestamp
1105
- /timestamp %Y-%m-%d
1106
- ```
1107
-
1108
- See `examples/directives/` for more examples.
1109
-
1110
- ### Best Practices
1111
-
1112
- 1. **Test directives individually** before combining them
1113
- 2. **Use absolute paths** for file includes when possible
1114
- 3. **Handle errors gracefully** with conditional Ruby code
1115
- 4. **Validate environment variables** before using them
1116
- 5. **Use appropriate models** for different task types
1117
-
1118
- ## Security Considerations
1119
-
1120
- - **ERB shell execution** (`<%= \`...\` %>`) executes with your user permissions
1121
- - **ERB Ruby code** (`<%= ... %>`) has full access to the Ruby environment
1122
- - **File inclusion** can access any readable file
1123
- - **Web access** requires API keys and network access
1124
-
1125
- ### Safe Usage Tips
1126
-
1127
- 1. **Avoid ERB shell commands** that modify system state in shared prompts
1128
- 2. **Use environment variables** for sensitive data, not hardcoded values
1129
- 3. **Validate inputs** in ERB code before execution
1130
- 4. **Limit file access** to necessary directories only
1131
- 5. **Review prompts** from untrusted sources before execution
1132
-
1133
- ## Environment Variables for Directives
1134
-
1135
- - `PUREMD_API_KEY` - Required for web page inclusion
1136
- - `PREFERRED_MODEL` - Default model selection
1137
- - `AI_TEMPERATURE` - Default temperature setting
1138
- - `AI_MAX_TOKENS` - Default token limit
1139
-
1140
- ## Related Documentation
1141
-
1142
- - [CLI Reference](cli-reference.md) - Command-line options
1143
- - [Configuration](configuration.md) - Configuration file options
1144
- - [Advanced Prompting](advanced-prompting.md) - Advanced prompt techniques
1145
- - [Getting Started](guides/getting-started.md) - Basic usage tutorial