aia 2.0.0.0.pre.alpha → 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 (236) hide show
  1. checksums.yaml +4 -4
  2. data/.version +1 -1
  3. data/CHANGELOG.md +151 -228
  4. data/README.md +42 -19
  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 +24 -66
  10. data/lib/aia/config/cli_parser.rb +164 -123
  11. data/lib/aia/config/defaults.yml +12 -39
  12. data/lib/aia/config/mcp_parser.rb +42 -40
  13. data/lib/aia/config/model_spec.rb +8 -14
  14. data/lib/aia/config/validator.rb +144 -156
  15. data/lib/aia/config/value_caster.rb +76 -0
  16. data/lib/aia/config.rb +72 -54
  17. data/lib/aia/content_extractor.rb +2 -0
  18. data/lib/aia/cost_calculator.rb +1 -0
  19. data/lib/aia/crew.rb +29 -19
  20. data/lib/aia/debate_handler.rb +45 -20
  21. data/lib/aia/delegate_handler.rb +7 -3
  22. data/lib/aia/directive.rb +10 -8
  23. data/lib/aia/directives/configuration_directives.rb +164 -109
  24. data/lib/aia/directives/context_directives.rb +55 -40
  25. data/lib/aia/directives/execution_directives.rb +25 -25
  26. data/lib/aia/directives/model_directives.rb +112 -195
  27. data/lib/aia/directives/trakflow_directives.rb +27 -9
  28. data/lib/aia/directives/utility_directives.rb +86 -87
  29. data/lib/aia/directives/web_and_file_directives.rb +83 -63
  30. data/lib/aia/fact_asserter.rb +3 -3
  31. data/lib/aia/history_transfer.rb +64 -24
  32. data/lib/aia/layered_orchestrator.rb +66 -43
  33. data/lib/aia/logger.rb +27 -62
  34. data/lib/aia/mcp_config_normalizer.rb +27 -14
  35. data/lib/aia/mcp_connection_manager.rb +193 -186
  36. data/lib/aia/mcp_discovery.rb +43 -15
  37. data/lib/aia/mcp_grouper.rb +2 -1
  38. data/lib/aia/mcp_server_config.rb +48 -0
  39. data/lib/aia/mcp_utility.rb +28 -20
  40. data/lib/aia/mention_router.rb +22 -52
  41. data/lib/aia/modality_query.rb +36 -0
  42. data/lib/aia/model_alias_registry.rb +11 -11
  43. data/lib/aia/model_registry.rb +75 -0
  44. data/lib/aia/network_builder.rb +17 -11
  45. data/lib/aia/network_memory_manager.rb +6 -6
  46. data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
  47. data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
  48. data/lib/aia/pipeline_orchestrator.rb +88 -45
  49. data/lib/aia/plugin_monitor.rb +9 -6
  50. data/lib/aia/prompt_decomposer.rb +6 -4
  51. data/lib/aia/prompt_handler.rb +90 -69
  52. data/lib/aia/provider_registry.rb +105 -0
  53. data/lib/aia/robot_builder.rb +1 -1
  54. data/lib/aia/robot_factory.rb +77 -69
  55. data/lib/aia/robot_namer.rb +2 -8
  56. data/lib/aia/robot_sync.rb +79 -0
  57. data/lib/aia/role_catalog.rb +89 -0
  58. data/lib/aia/session.rb +32 -14
  59. data/lib/aia/session_tracker.rb +39 -41
  60. data/lib/aia/similarity_scorer.rb +5 -3
  61. data/lib/aia/skill_utils.rb +60 -19
  62. data/lib/aia/spawn_handler.rb +16 -4
  63. data/lib/aia/spawn_spec_parser.rb +6 -7
  64. data/lib/aia/special_mode_handler.rb +80 -57
  65. data/lib/aia/speech.rb +103 -0
  66. data/lib/aia/startup_coordinator.rb +17 -91
  67. data/lib/aia/streaming_runner.rb +16 -5
  68. data/lib/aia/system_prompt_assembler.rb +20 -15
  69. data/lib/aia/task_board.rb +60 -0
  70. data/lib/aia/task_coordinator.rb +10 -5
  71. data/lib/aia/timing.rb +15 -0
  72. data/lib/aia/tool_approver.rb +205 -0
  73. data/lib/aia/tool_filter.rb +1 -9
  74. data/lib/aia/tool_filter_strategy.rb +39 -25
  75. data/lib/aia/tool_introspection.rb +25 -0
  76. data/lib/aia/tool_loader.rb +71 -31
  77. data/lib/aia/tool_utility.rb +6 -5
  78. data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
  79. data/lib/aia/tools/recruit_robot_tool.rb +12 -12
  80. data/lib/aia/tools/reskill_robot_tool.rb +7 -7
  81. data/lib/aia/tools/task_board_tool.rb +17 -16
  82. data/lib/aia/trakflow_bridge.rb +19 -11
  83. data/lib/aia/turn_state.rb +32 -8
  84. data/lib/aia/ui_presenter.rb +83 -59
  85. data/lib/aia/utility.rb +8 -24
  86. data/lib/aia/variable_input_collector.rb +1 -3
  87. data/lib/aia/verification_network.rb +10 -12
  88. data/lib/aia.rb +49 -8
  89. metadata +27 -162
  90. data/.better-commits.json +0 -150
  91. data/.config/tocer/configuration.yml +0 -6
  92. data/.envrc +0 -15
  93. data/.loki +0 -231
  94. data/.quality/flay_baseline.txt +0 -1
  95. data/.quality/flog_baseline.txt +0 -29
  96. data/.quality/reek_baseline.txt +0 -80
  97. data/.rubocop.yml +0 -116
  98. data/COMMITS.md +0 -196
  99. data/IMPLEMENTATION_PLAN.md +0 -506
  100. data/Rakefile +0 -160
  101. data/architecture_review.md +0 -314
  102. data/docs/AGENTS.md +0 -40
  103. data/docs/advanced-prompting.md +0 -814
  104. data/docs/assets/images/aia.png +0 -0
  105. data/docs/cli-reference.md +0 -1241
  106. data/docs/configuration.md +0 -747
  107. data/docs/contributing.md +0 -386
  108. data/docs/directives-reference.md +0 -1145
  109. data/docs/examples/index.md +0 -277
  110. data/docs/examples/mcp/index.md +0 -475
  111. data/docs/examples/prompts/analysis/index.md +0 -78
  112. data/docs/examples/prompts/automation/index.md +0 -109
  113. data/docs/examples/prompts/development/index.md +0 -125
  114. data/docs/examples/prompts/index.md +0 -333
  115. data/docs/examples/prompts/learning/index.md +0 -127
  116. data/docs/examples/prompts/writing/index.md +0 -62
  117. data/docs/examples/tools/index.md +0 -282
  118. data/docs/faq.md +0 -578
  119. data/docs/guides/available-models.md +0 -366
  120. data/docs/guides/basic-usage.md +0 -478
  121. data/docs/guides/chat.md +0 -680
  122. data/docs/guides/crew.md +0 -239
  123. data/docs/guides/executable-prompts.md +0 -331
  124. data/docs/guides/first-prompt.md +0 -454
  125. data/docs/guides/getting-started.md +0 -455
  126. data/docs/guides/image-generation.md +0 -507
  127. data/docs/guides/index.md +0 -48
  128. data/docs/guides/local-models.md +0 -306
  129. data/docs/guides/migrate-prompts.md +0 -335
  130. data/docs/guides/models.md +0 -1017
  131. data/docs/guides/shared-tools.md +0 -254
  132. data/docs/guides/tools.md +0 -831
  133. data/docs/index.md +0 -259
  134. data/docs/installation.md +0 -274
  135. data/docs/mcp-integration.md +0 -603
  136. data/docs/prompt_management.md +0 -665
  137. data/docs/security.md +0 -674
  138. data/docs/special_projects_guide.md +0 -386
  139. data/docs/tools-and-mcp-examples.md +0 -1211
  140. data/docs/workflows-and-pipelines.md +0 -636
  141. data/examples/.gitignore +0 -2
  142. data/examples/00_setup_aia.sh +0 -111
  143. data/examples/01_basic_usage.sh +0 -23
  144. data/examples/02_frontmatter.sh +0 -33
  145. data/examples/03_shell_integration.sh +0 -55
  146. data/examples/04_erb_templating.sh +0 -56
  147. data/examples/05_shell_then_erb.sh +0 -38
  148. data/examples/06_prompt_chaining.sh +0 -59
  149. data/examples/07_pipeline.sh +0 -46
  150. data/examples/08_context_files.sh +0 -43
  151. data/examples/09_roles.sh +0 -67
  152. data/examples/10_stdin_piping.sh +0 -49
  153. data/examples/11_multi_model.sh +0 -65
  154. data/examples/12_token_usage.sh +0 -52
  155. data/examples/13_cost_tracking.sh +0 -68
  156. data/examples/14_output_file.sh +0 -91
  157. data/examples/15_parameters.sh +0 -68
  158. data/examples/16_directives.sh +0 -113
  159. data/examples/17_require_and_conditionals.sh +0 -68
  160. data/examples/18_tools.sh +0 -61
  161. data/examples/19_local_tools.sh +0 -34
  162. data/examples/20_mcp_servers.sh +0 -102
  163. data/examples/21_executable_prompts.sh +0 -78
  164. data/examples/22_chat_mode.sh +0 -217
  165. data/examples/23_verify.sh +0 -139
  166. data/examples/24_decompose.sh +0 -139
  167. data/examples/25_spawn.sh +0 -139
  168. data/examples/26_debate.sh +0 -97
  169. data/examples/27_mention_routing.sh +0 -157
  170. data/examples/28_model_switching.sh +0 -106
  171. data/examples/29_agent_harness.sh +0 -177
  172. data/examples/README.md +0 -321
  173. data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
  174. data/examples/aia_config.yml +0 -22
  175. data/examples/aia_config_orchestrator.yml +0 -45
  176. data/examples/aia_config_with_mcp.yml +0 -21
  177. data/examples/common.sh +0 -39
  178. data/examples/context/project_goals.md +0 -6
  179. data/examples/context/tech_stack.md +0 -7
  180. data/examples/directives/timestamp_directive.rb +0 -22
  181. data/examples/mcp/filesystem.json +0 -9
  182. data/examples/prompts_dir/analyze.md +0 -2
  183. data/examples/prompts_dir/brainstorm.md +0 -2
  184. data/examples/prompts_dir/conditional.md +0 -17
  185. data/examples/prompts_dir/creative.md +0 -4
  186. data/examples/prompts_dir/erbinfo.md +0 -5
  187. data/examples/prompts_dir/erbinfo_raw.md +0 -8
  188. data/examples/prompts_dir/evaluate.md +0 -2
  189. data/examples/prompts_dir/explain_joke.md +0 -1
  190. data/examples/prompts_dir/explain_recursion.md +0 -1
  191. data/examples/prompts_dir/fun_fact +0 -3
  192. data/examples/prompts_dir/greeting.md +0 -8
  193. data/examples/prompts_dir/greeting_required.md +0 -7
  194. data/examples/prompts_dir/hello.md +0 -1
  195. data/examples/prompts_dir/includes/ruby_facts.md +0 -4
  196. data/examples/prompts_dir/limerick.md +0 -1
  197. data/examples/prompts_dir/list_with_mcp.md +0 -3
  198. data/examples/prompts_dir/pick_best.md +0 -2
  199. data/examples/prompts_dir/project_summary +0 -12
  200. data/examples/prompts_dir/quiz_with_include.md +0 -6
  201. data/examples/prompts_dir/require_demo.md +0 -5
  202. data/examples/prompts_dir/roles/formal.md +0 -3
  203. data/examples/prompts_dir/roles/orchestrator.md +0 -21
  204. data/examples/prompts_dir/roles/pirate.md +0 -3
  205. data/examples/prompts_dir/shell_then_erb.md +0 -6
  206. data/examples/prompts_dir/sort_compare.md +0 -2
  207. data/examples/prompts_dir/summarize_context.md +0 -2
  208. data/examples/prompts_dir/sysinfo.md +0 -5
  209. data/examples/prompts_dir/sysinfo_raw.md +0 -8
  210. data/examples/prompts_dir/tagline.md +0 -1
  211. data/examples/prompts_dir/tell_joke.md +0 -1
  212. data/examples/prompts_dir/tell_joke_with_next.md +0 -4
  213. data/examples/prompts_dir/use_local_tool.md +0 -8
  214. data/examples/prompts_dir/use_tools.md +0 -8
  215. data/examples/prompts_dir/weather.md +0 -2
  216. data/examples/prompts_dir/whats_new.md +0 -2
  217. data/examples/prompts_dir/with_timestamp.md +0 -5
  218. data/examples/requirements/sinatra_taskflow_app.md +0 -139
  219. data/examples/rules/01_classify_ruby.rb +0 -16
  220. data/examples/rules/02_prefer_claude_for_code.rb +0 -19
  221. data/examples/rules/03_gate_prompt_length.rb +0 -19
  222. data/examples/rules/04_tool_selection.rb +0 -41
  223. data/examples/rules/README.md +0 -30
  224. data/examples/run_all.sh +0 -294
  225. data/examples/tools/word_count_tool.rb +0 -30
  226. data/lib/AGENTS.md +0 -57
  227. data/lib/aia/model_switch_handler.rb +0 -100
  228. data/mcp_servers/README.md +0 -110
  229. data/mcp_servers/apple-mcp.json +0 -8
  230. data/mcp_servers/filesystem.json +0 -9
  231. data/mcp_servers/mcp_server_chart.json +0 -11
  232. data/mcp_servers/playwright_one.json +0 -8
  233. data/mcp_servers/playwright_server_definition.json +0 -9
  234. data/mcp_servers/playwright_two.json +0 -8
  235. data/mcp_servers/tavily_mcp_server.json +0 -8
  236. data/mkdocs.yml +0 -169
@@ -1,306 +0,0 @@
1
- # Local Models Guide
2
-
3
- Complete guide to using Ollama and LM Studio with AIA for local AI processing.
4
-
5
- ## Why Use Local Models?
6
-
7
- ### Benefits
8
-
9
- - 🔒 **Privacy**: All processing happens on your machine
10
- - 💰 **Cost**: No API fees
11
- - 🚀 **Speed**: No network latency
12
- - 📡 **Offline**: Works without internet
13
- - 🔧 **Control**: Choose exact model and parameters
14
- - 📦 **Unlimited**: No rate limits or quotas
15
-
16
- ### Use Cases
17
-
18
- - Processing confidential business data
19
- - Working with personal information
20
- - Development and testing
21
- - High-volume batch processing
22
- - Air-gapped environments
23
- - Learning and experimentation
24
-
25
- ## Ollama Setup
26
-
27
- ### Installation
28
-
29
- ```bash
30
- # macOS
31
- brew install ollama
32
-
33
- # Linux
34
- curl -fsSL https://ollama.ai/install.sh | sh
35
-
36
- # Windows
37
- # Download installer from https://ollama.ai
38
- ```
39
-
40
- ### Model Management
41
-
42
- ```bash
43
- # List available models
44
- ollama list
45
-
46
- # Pull new models
47
- ollama pull llama3.2
48
- ollama pull mistral
49
- ollama pull codellama
50
-
51
- # Remove models
52
- ollama rm model-name
53
-
54
- # Show model info
55
- ollama show llama3.2
56
- ```
57
-
58
- ### Using with AIA
59
-
60
- ```bash
61
- # Basic usage - prefix with 'ollama/'
62
- aia --model ollama/llama3.2 my_prompt
63
-
64
- # Chat mode
65
- aia --chat --model ollama/mistral
66
-
67
- # Batch processing
68
- for file in *.md; do
69
- aia --model ollama/llama3.2 summarize "$file"
70
- done
71
- ```
72
-
73
- ### Recommended Ollama Models
74
-
75
- #### General Purpose
76
- - `llama3.2` - Versatile, good quality
77
- - `llama3.2:70b` - Higher quality, slower
78
- - `mistral` - Fast, efficient
79
-
80
- #### Code
81
- - `qwen2.5-coder` - Excellent for code
82
- - `codellama` - Code-focused
83
- - `deepseek-coder` - Programming tasks
84
-
85
- #### Specialized
86
- - `mixtral` - High performance
87
- - `phi3` - Small, efficient
88
- - `gemma2` - Google's open model
89
-
90
- ## LM Studio Setup
91
-
92
- ### Installation
93
-
94
- 1. Download from https://lmstudio.ai
95
- 2. Install the application
96
- 3. Launch LM Studio
97
-
98
- ### Model Management
99
-
100
- 1. Click "🔍 Search" tab
101
- 2. Browse or search for models
102
- 3. Click download button
103
- 4. Wait for download to complete
104
-
105
- ### Starting Local Server
106
-
107
- 1. Click "💻 Local Server" tab
108
- 2. Select loaded model from dropdown
109
- 3. Click "Start Server"
110
- 4. Note the endpoint (default: http://localhost:1234/v1)
111
-
112
- ### Using with AIA
113
-
114
- ```bash
115
- # Prefix model name with 'lms/'
116
- aia --model lms/qwen/qwen3-coder-30b my_prompt
117
-
118
- # Chat mode
119
- aia --chat --model lms/llama-3.2-3b-instruct
120
-
121
- # AIA validates model names
122
- # Error shows available models if name is wrong
123
- ```
124
-
125
- ### Popular LM Studio Models
126
-
127
- - `lmsys/vicuna-7b` - Conversation
128
- - `TheBloke/Llama-2-7B-Chat-GGUF` - Chat
129
- - `TheBloke/CodeLlama-7B-GGUF` - Code
130
- - `qwen/qwen3-coder-30b` - Advanced coding
131
-
132
- ## Configuration
133
-
134
- ### Environment Variables
135
-
136
- ```bash
137
- # Ollama custom endpoint
138
- export OLLAMA_API_BASE=http://localhost:11434
139
-
140
- # LM Studio custom endpoint
141
- export LMS_API_BASE=http://localhost:1234/v1
142
- ```
143
-
144
- ### Config File
145
-
146
- ```yaml
147
- # ~/.config/aia/aia.yml
148
- models:
149
- - name: ollama/llama3.2
150
-
151
- # Or for LM Studio
152
- models:
153
- - name: lms/qwen/qwen3-coder-30b
154
- ```
155
-
156
- ### In Prompts
157
-
158
- ```
159
- /config model = ollama/mistral
160
- /config temperature = 0.7
161
-
162
- Your prompt here...
163
- ```
164
-
165
- ## Listing Models
166
-
167
- ### In Chat Session
168
-
169
- ```bash
170
- aia --model ollama/llama3.2 --chat
171
- > /models
172
- ```
173
-
174
- **Ollama Output:**
175
- ```
176
- Local LLM Models:
177
-
178
- Ollama Models (http://localhost:11434):
179
- ------------------------------------------------------------
180
- - ollama/llama3.2:latest (size: 2.0 GB, modified: 2024-10-01)
181
- - ollama/mistral:latest (size: 4.1 GB, modified: 2024-09-28)
182
-
183
- 2 Ollama model(s) available
184
- ```
185
-
186
- **LM Studio Output:**
187
- ```
188
- Local LLM Models:
189
-
190
- LM Studio Models (http://localhost:1234/v1):
191
- ------------------------------------------------------------
192
- - lms/qwen/qwen3-coder-30b
193
- - lms/llama-3.2-3b-instruct
194
-
195
- 2 LM Studio model(s) available
196
- ```
197
-
198
- ## Advanced Usage
199
-
200
- ### Mixed Local/Cloud Models
201
-
202
- ```bash
203
- # Compare local and cloud responses
204
- aia --model ollama/llama3.2,gpt-4o-mini,claude-3-sonnet analysis_prompt
205
-
206
- # Get consensus
207
- aia --model ollama/llama3.2,ollama/mistral,gpt-4 --consensus decision_prompt
208
- ```
209
-
210
- ### Local-First Workflow
211
-
212
- ```bash
213
- # 1. Process with local model (private)
214
- aia --model ollama/llama3.2 --output draft.md sensitive_data.txt
215
-
216
- # 2. Review and sanitize draft.md manually
217
-
218
- # 3. Polish with cloud model
219
- aia --model gpt-4 --include draft.md final_output
220
- ```
221
-
222
- ### Cost Optimization
223
-
224
- ```bash
225
- # Bulk tasks with local model
226
- for i in {1..1000}; do
227
- aia --model ollama/mistral --output "result_$i.md" process "input_$i.txt"
228
- done
229
-
230
- # No API costs!
231
- ```
232
-
233
- ## Troubleshooting
234
-
235
- ### Ollama Issues
236
-
237
- **Problem:** "Cannot connect to Ollama"
238
- ```bash
239
- # Check if Ollama is running
240
- ollama list
241
-
242
- # Start Ollama service (if needed)
243
- ollama serve
244
- ```
245
-
246
- **Problem:** "Model not found"
247
- ```bash
248
- # List installed models
249
- ollama list
250
-
251
- # Pull missing model
252
- ollama pull llama3.2
253
- ```
254
-
255
- ### LM Studio Issues
256
-
257
- **Problem:** "Cannot connect to LM Studio"
258
- 1. Ensure LM Studio is running
259
- 2. Check local server is started
260
- 3. Verify endpoint in settings
261
-
262
- **Problem:** "Model validation failed"
263
- - Check exact model name in LM Studio
264
- - Ensure model is loaded (not just downloaded)
265
- - Use full model path with `lms/` prefix
266
-
267
- **Problem:** "Model not listed"
268
- 1. Load model in LM Studio
269
- 2. Start local server
270
- 3. Run `/models` directive
271
-
272
- ### Performance Issues
273
-
274
- **Slow responses:**
275
- - Use smaller models (7B instead of 70B)
276
- - Reduce max_tokens
277
- - Check system resources (CPU/RAM/GPU)
278
-
279
- **High memory usage:**
280
- - Close other applications
281
- - Use quantized models (Q4, Q5)
282
- - Try smaller model variants
283
-
284
- ## Best Practices
285
-
286
- ### Security
287
- ✅ Keep local models for sensitive data
288
- ✅ Use cloud models for general tasks
289
- ✅ Review outputs before sharing externally
290
-
291
- ### Performance
292
- ✅ Use appropriate model size for task
293
- ✅ Leverage GPU if available
294
- ✅ Cache common responses
295
-
296
- ### Cost Management
297
- ✅ Use local models for development/testing
298
- ✅ Use local models for high-volume processing
299
- ✅ Reserve cloud models for critical tasks
300
-
301
- ## Related Documentation
302
-
303
- - [Models Guide](models.md)
304
- - [Configuration](../configuration.md)
305
- - [Chat Mode](chat.md)
306
- - [CLI Reference](../cli-reference.md)
@@ -1,335 +0,0 @@
1
- # Migrating Prompts
2
-
3
- AIA includes a migration tool for converting prompt files from the legacy prompt_manager v0.5.8 format to the v1.0.0 format. This guide covers the migration process, what changes, and how to handle files that need manual attention.
4
-
5
- ## Why Migrate?
6
-
7
- The prompt_manager gem moved from a two-file format (`.txt` + `.json`) with `[PLACEHOLDER]` syntax to a single `.md` file with YAML front matter and ERB parameters. The new format provides:
8
-
9
- - **Self-contained prompts** — metadata, parameters, and body in one file
10
- - **Standard ERB** — `<%= param %>` instead of custom `[PARAM]` syntax
11
- - **YAML front matter** — structured configuration instead of `/` directives
12
- - **Markdown body** — native rendering support in editors and documentation tools
13
-
14
- ## Format Comparison
15
-
16
- ### Old Format (v0.5.8)
17
-
18
- Two files per prompt:
19
-
20
- **`my_prompt.md`**
21
- ```
22
- # ~/.prompts/my_prompt.md
23
- # Desc: Summarize the given document
24
- /config temperature 0.3
25
- /include shared_context.md
26
-
27
- Summarize the following [DOCUMENT_TYPE] document:
28
-
29
- [CONTENT]
30
- ```
31
-
32
- **`my_prompt.json`** (parameter history)
33
- ```json
34
- {
35
- "[DOCUMENT_TYPE]": ["report", "article", "paper"],
36
- "[CONTENT]": ["..."]
37
- }
38
- ```
39
-
40
- ### New Format (v1.0.0)
41
-
42
- Single file:
43
-
44
- **`my_prompt.md`** (same filename, single file now)
45
- ```markdown
46
- ---
47
- name: my_prompt
48
- description: Summarize the given document
49
- temperature: 0.3
50
- parameters:
51
- document_type: paper
52
- content: null
53
- ---
54
-
55
- <%= include('shared_context.md') %>
56
-
57
- Summarize the following <%= document_type %> document:
58
-
59
- <%= content %>
60
- ```
61
-
62
- ## Running the Migration
63
-
64
- The migration script is at `bin/migrate_prompts`. It requires no external dependencies beyond Ruby's standard library.
65
-
66
- ### Basic Usage
67
-
68
- ```bash
69
- # Scan the entire prompts directory (uses $AIA_PROMPTS__DIR or ~/.prompts)
70
- bin/migrate_prompts
71
-
72
- # Preview changes without modifying files
73
- bin/migrate_prompts --dry-run
74
-
75
- # Migrate with detailed output
76
- bin/migrate_prompts --verbose
77
-
78
- # Migrate specific files or directories
79
- bin/migrate_prompts ~/.prompts/development/
80
- bin/migrate_prompts ~/.prompts/code_review.md ~/.prompts/debug_help.md
81
- ```
82
-
83
- ### CLI Options
84
-
85
- | Option | Description |
86
- |--------|-------------|
87
- | `--dry-run` | Show what would change without modifying any files |
88
- | `--verbose` | Show detailed transformation info for each file |
89
- | `--force` | Overwrite existing `.md` files (default: skip if `.md` exists) |
90
- | `--reprocess` | Re-examine `*.txt-review` files and recover those that now pass |
91
- | `-h`, `--help` | Show usage help |
92
-
93
- ### Environment
94
-
95
- The script uses `AIA_PROMPTS__DIR` to locate the prompts directory. If unset, it defaults to `~/.prompts`.
96
-
97
- ```bash
98
- # Use a custom prompts directory
99
- AIA_PROMPTS__DIR=~/my-prompts bin/migrate_prompts --dry-run
100
- ```
101
-
102
- ## What Gets Migrated
103
-
104
- ### Placeholders
105
-
106
- Standard `[PLACEHOLDER]` tokens become ERB expressions:
107
-
108
- | Old | New |
109
- |-----|-----|
110
- | `[TOPIC]` | `<%= topic %>` |
111
- | `[FILE_NAME]` | `<%= file_name %>` |
112
- | `[TECH STACK]` | `<%= tech_stack %>` (spaces normalized to underscores) |
113
-
114
- ### Directives
115
-
116
- Prompt directives are migrated to YAML front matter or ERB calls:
117
-
118
- | Old Directive | New Location |
119
- |---------------|--------------|
120
- | `/config temperature 0.3` | `temperature: 0.3` in YAML |
121
- | `/config top_p 0.9` | `top_p: 0.9` in YAML |
122
- | `/temp 0.5` | `temperature: 0.5` in YAML |
123
- | `/topp 0.8` | `top_p: 0.8` in YAML |
124
- | `/next follow_up` | `next: follow_up` in YAML |
125
- | `/pipeline step1, step2` | `pipeline: [step1, step2]` in YAML |
126
- | `/include file.md` | `<%= include('file.md') %>` in body |
127
- | `/shell command` | `<%= system('command') %>` in body |
128
- | `/ruby expression` | `<%= expression %>` in body |
129
- | `/backend ...` | Silently removed (deprecated) |
130
-
131
- ### Comments
132
-
133
- Lines beginning with `#` (outside of code fences and ERB blocks) are converted to HTML comments:
134
-
135
- ```
136
- # Old format: this is a comment
137
- ```
138
-
139
- Becomes:
140
-
141
- ```html
142
- <!-- this is a comment -->
143
- ```
144
-
145
- Multi-line comment blocks are grouped:
146
-
147
- ```html
148
- <!--
149
- First line of comment
150
- Second line of comment
151
- -->
152
- ```
153
-
154
- Comments inside code fences (` ``` `) and multi-line ERB blocks (`<% ... %>`) are preserved as-is.
155
-
156
- ### Metadata
157
-
158
- The script extracts metadata from the old format's header conventions:
159
-
160
- - **File path comments** (`# ~/.prompts/name.md`) — removed
161
- - **Description lines** (`# Desc: ...`) — moved to `description:` in YAML front matter
162
- - **Prompt name** — derived from the filename (e.g., `code_review.md` → `name: code_review`)
163
-
164
- ### Parameter History
165
-
166
- If a `.json` file exists alongside the `.md` file, the most recent value for each parameter is used as the default in the YAML `parameters:` block:
167
-
168
- ```yaml
169
- parameters:
170
- document_type: paper # last value from JSON history
171
- content: null # no history available
172
- ```
173
-
174
- ### Content After `__END__`
175
-
176
- Content below an `__END__` marker is wrapped in an HTML comment at the end of the `.md` file:
177
-
178
- ```html
179
- <!--
180
- Original content that was below __END__
181
- -->
182
- ```
183
-
184
- ## Flagged Files
185
-
186
- Files that contain constructs requiring manual review are renamed to `*.txt-review` instead of being migrated. The most common reasons a file gets flagged:
187
-
188
- - **Code fences** (` ``` `) — the script cannot reliably distinguish between code fence content and prompt body text that might contain placeholders
189
- - **Placeholders inside ERB blocks** — `[PARAM]` tokens within `<% ... %>` need manual conversion to Ruby variables
190
- - **Ambiguous bracket expressions** — bracket content that looks like a placeholder but doesn't match the clean `[ALL_CAPS]` pattern
191
-
192
- ### Reviewing Flagged Files
193
-
194
- After the initial migration, check the flagged files:
195
-
196
- ```bash
197
- # List all flagged files
198
- find ~/.prompts -name '*.txt-review'
199
-
200
- # Preview what the migration would produce
201
- bin/migrate_prompts --dry-run --verbose ~/.prompts/my_prompt.txt-review
202
- ```
203
-
204
- For each flagged file, you have three options:
205
-
206
- 1. **Reprocess** — if the issue was transient, use `--reprocess` to try again
207
- 2. **Manual conversion** — create the `.md` file by hand following the new format
208
- 3. **Leave as-is** — flagged files don't affect AIA's operation with existing prompts
209
-
210
- ### Reprocessing Flagged Files
211
-
212
- The `--reprocess` option re-examines all `*.txt-review` files. Files that now pass validation are renamed back to `*.txt` and migrated to `*.md`:
213
-
214
- ```bash
215
- # Preview which files would be recovered
216
- bin/migrate_prompts --reprocess --dry-run
217
-
218
- # Recover files that now pass
219
- bin/migrate_prompts --reprocess
220
- ```
221
-
222
- The reprocess summary shows how many files were recovered versus still flagged:
223
-
224
- ```
225
- Reprocess summary:
226
- Recovered: 22 files (*.txt-review → *.txt → *.md)
227
- Still flagged: 19 files (unchanged)
228
- ```
229
-
230
- ## Step-by-Step Migration Workflow
231
-
232
- ### 1. Preview the Migration
233
-
234
- Start with a dry run to understand the scope of changes:
235
-
236
- ```bash
237
- bin/migrate_prompts --dry-run --verbose
238
- ```
239
-
240
- Review the output. Note how many files will be migrated, flagged, or skipped.
241
-
242
- ### 2. Run the Migration
243
-
244
- ```bash
245
- bin/migrate_prompts --verbose
246
- ```
247
-
248
- The script creates `.md` files alongside the original `.txt` files. It does not delete the originals.
249
-
250
- ### 3. Review the Results
251
-
252
- ```bash
253
- # Check the summary counts
254
- # Verify a few migrated files look correct
255
- cat ~/.prompts/my_prompt.md
256
-
257
- # List flagged files
258
- find ~/.prompts -name '*.txt-review'
259
- ```
260
-
261
- ### 4. Reprocess Flagged Files
262
-
263
- ```bash
264
- bin/migrate_prompts --reprocess --dry-run
265
- bin/migrate_prompts --reprocess
266
- ```
267
-
268
- ### 5. Handle Remaining Flagged Files
269
-
270
- For files still flagged after reprocessing, create `.md` versions manually. Common patterns:
271
-
272
- **Files with outer ` ```markdown ` wrappers** — strip the outer fence, keep nested fences, extract metadata into YAML front matter.
273
-
274
- **Files with placeholders inside ERB** — convert `[PARAM]` to Ruby variable references inside the ERB block:
275
-
276
- ```ruby
277
- # Old
278
- <% path = '[MODEL_FILENAME]' %>
279
-
280
- # New
281
- <% path = model_filename %>
282
- ```
283
-
284
- **Files with `__END__` containing code fences** — wrap the post-`__END__` content in HTML comments or restructure as needed.
285
-
286
- ### 6. Clean Up Originals
287
-
288
- Once you've verified the migration is correct, remove the old files:
289
-
290
- ```bash
291
- # Remove original .txt files that have corresponding .md files
292
- find ~/.prompts -name '*.txt' -exec sh -c '
293
- for f; do
294
- md="${f%.txt}.md"
295
- [ -f "$md" ] && rm "$f"
296
- done
297
- ' _ {} +
298
-
299
- # Remove .json history files
300
- find ~/.prompts -name '*.json' -delete
301
- ```
302
-
303
- ## Troubleshooting
304
-
305
- ### "No .txt files found"
306
-
307
- The script couldn't find any `.txt` files in the prompts directory. Verify the path:
308
-
309
- ```bash
310
- echo $AIA_PROMPTS__DIR
311
- ls ~/.prompts/*.txt
312
- ```
313
-
314
- ### File skipped because .md already exists
315
-
316
- By default, the script skips files that already have a corresponding `.md` file. Use `--force` to overwrite:
317
-
318
- ```bash
319
- bin/migrate_prompts --force ~/.prompts/my_prompt.md
320
- ```
321
-
322
- ### Unrecognized directive warnings
323
-
324
- Directives that the script doesn't know how to convert are preserved in the body as-is and reported as warnings. Review these manually after migration.
325
-
326
- ### Placeholder not converted
327
-
328
- The script only converts clean placeholders matching `[ALL_CAPS_WITH_UNDERSCORES]`. Other bracket patterns (e.g., `[camelCase]`, `[with:colons]`) are left unchanged. This is intentional to avoid converting code that happens to contain brackets.
329
-
330
- ## Related Documentation
331
-
332
- - [Prompt Management](../prompt_management.md) — organizing and managing your prompt collection
333
- - [Advanced Prompting](../advanced-prompting.md) — ERB templates and dynamic prompts
334
- - [Workflows & Pipelines](../workflows-and-pipelines.md) — multi-step prompt sequences
335
- - [Configuration](../configuration.md) — AIA configuration reference