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,665 +0,0 @@
1
- <!-- Tocer[start]: Auto-generated, don't remove. -->
2
-
3
- ## Table of Contents
4
-
5
- - [Prompt Management](#prompt-management)
6
- - [Directory Structure](#directory-structure)
7
- - [Default Structure](#default-structure)
8
- - [Custom Structure](#custom-structure)
9
- - [Prompt File Formats](#prompt-file-formats)
10
- - [Basic Text Prompts](#basic-text-prompts)
11
- - [Available Directives](#available-directives)
12
- - [Prompts with Directives](#prompts-with-directives)
13
- - [ERB Template Prompts](#erb-template-prompts)
14
- - [Executable Prompts](#executable-prompts)
15
- - [Prompt Discovery and Search](#prompt-discovery-and-search)
16
- - [Basic Search](#basic-search)
17
- - [Fuzzy Search (with fzf)](#fuzzy-search-with-fzf)
18
- - [Advanced Search](#advanced-search)
19
- - [Prompt Organization Strategies](#prompt-organization-strategies)
20
- - [By Domain/Category](#by-domaincategory)
21
- - [By Complexity](#by-complexity)
22
- - [By Model Type](#by-model-type)
23
- - [By Workflow Stage](#by-workflow-stage)
24
- - [Parameterized Prompts](#parameterized-prompts)
25
- - [ERB Variables](#erb-variables)
26
- - [Usage with Parameters](#usage-with-parameters)
27
- - [Parameter Extraction](#parameter-extraction)
28
- - [Roles and Context](#roles-and-context)
29
- - [Role Definitions](#role-definitions)
30
- - [Using Roles](#using-roles)
31
- - [Context Layering](#context-layering)
32
- - [Chat Session Checkpoints](#chat-session-checkpoints)
33
- - [Prompt Workflows and Pipelines](#prompt-workflows-and-pipelines)
34
- - [Simple Workflows](#simple-workflows)
35
- - [Complex Pipelines](#complex-pipelines)
36
- - [Conditional Workflows](#conditional-workflows)
37
- - [Version Control for Prompts](#version-control-for-prompts)
38
- - [Git Integration](#git-integration)
39
- - [Backup and Sync](#backup-and-sync)
40
- - [Versioned Prompts](#versioned-prompts)
41
- - [Prompt Sharing and Collaboration](#prompt-sharing-and-collaboration)
42
- - [Team Prompt Libraries](#team-prompt-libraries)
43
- - [Prompt Documentation](#prompt-documentation)
44
- - [Prompt Standards](#prompt-standards)
45
- - [Performance and Optimization](#performance-and-optimization)
46
- - [Prompt Efficiency](#prompt-efficiency)
47
- - [Caching Strategies](#caching-strategies)
48
- - [Batch Processing](#batch-processing)
49
- - [Troubleshooting Prompts](#troubleshooting-prompts)
50
- - [Debugging Tools](#debugging-tools)
51
- - [Common Issues](#common-issues)
52
- - [Missing Parameters](#missing-parameters)
53
- - [File Not Found](#file-not-found)
54
- - [Permission Errors](#permission-errors)
55
- - [Advanced Prompt Techniques](#advanced-prompt-techniques)
56
- - [Dynamic Prompt Generation](#dynamic-prompt-generation)
57
- - [Prompt Composition](#prompt-composition)
58
- - [Adaptive Prompts](#adaptive-prompts)
59
- - [Best Practices](#best-practices)
60
- - [Prompt Design](#prompt-design)
61
- - [Organization](#organization)
62
- - [Recommended Directory Structure](#recommended-directory-structure)
63
- - [Performance](#performance)
64
- - [Related Documentation](#related-documentation)
65
-
66
- <!-- Tocer[finish]: Auto-generated, don't remove. -->
67
-
68
- # Prompt Management
69
-
70
- AIA provides sophisticated prompt management capabilities through the PM gem, enabling you to organize, version, and efficiently use large collections of prompts.
71
-
72
- ## Directory Structure
73
-
74
- ### Default Structure
75
- ```
76
- ~/.prompts/
77
- ├── README.md # Documentation for your prompt collection
78
- ├── roles/ # Role-based prompts for context setting
79
- │ ├── assistant.md
80
- │ ├── code_expert.md
81
- │ └── teacher.md
82
- ├── development/ # Development-related prompts
83
- │ ├── code_review.md
84
- │ ├── debug_help.md
85
- │ └── documentation.md
86
- ├── writing/ # Content creation prompts
87
- │ ├── blog_post.md
88
- │ ├── technical_docs.md
89
- │ └── creative_writing.md
90
- ├── analysis/ # Data and research analysis
91
- │ ├── data_analysis.md
92
- │ ├── research_summary.md
93
- │ └── report_generation.md
94
- └── workflows/ # Multi-step prompt sequences
95
- ├── code_pipeline.md
96
- ├── content_pipeline.md
97
- └── analysis_pipeline.md
98
- ```
99
-
100
- ### Custom Structure
101
- ```bash
102
- # Set custom prompts directory (uses nested naming convention)
103
- export AIA_PROMPTS__DIR="/path/to/custom/prompts"
104
- aia --prompts-dir /path/to/custom/prompts
105
-
106
- # Use project-specific prompts
107
- aia --prompts-dir ./project_prompts my_prompt
108
- ```
109
-
110
- ## Prompt File Formats
111
-
112
- ### Basic Text Prompts
113
- ```markdown
114
- # ~/.prompts/simple_question.md
115
- Please answer this question clearly and concisely:
116
-
117
- <%= question %>
118
-
119
- Provide examples where helpful.
120
- ```
121
-
122
- ### Available Directives
123
-
124
- Key directives available in prompt files:
125
-
126
- - `/config key value` — Set a configuration value for this prompt run
127
- - `/include path` — Insert the contents of a file at this point
128
- - `/shell command` — Execute a shell command and insert its output (prompt_manager feature, processed at load time)
129
- - `/ruby code` — Execute a Ruby one-liner and insert its output
130
- - `/next prompt_id` — Set the next prompt to run in sequence
131
- - `/pipeline id1,id2,...` — Define a multi-step prompt pipeline
132
- - `/paste` — Insert the current system clipboard contents at this point in the conversation
133
- - `/skill name` — Include a Claude Code skill file by name prefix match
134
-
135
- See the [Directives Reference](directives-reference.md) for the full list.
136
-
137
- ### Prompts with Directives
138
- ```markdown
139
- # ~/.prompts/code_analysis.md
140
- /config model gpt-4
141
- /config temperature 0.3
142
-
143
- # Code Analysis and Review
144
-
145
- Analyze the following code for:
146
- - Security vulnerabilities
147
- - Performance issues
148
- - Best practice violations
149
- - Potential bugs
150
-
151
- ## Code to Review:
152
- /include <%= file %>
153
-
154
- Provide specific recommendations with code examples.
155
- ```
156
-
157
- ### ERB Template Prompts
158
- ```erb
159
- # ~/.prompts/blog_post_generator.md
160
- /config model <%= model || "gpt-4" %>
161
- /config temperature <%= creativity || "0.8" %>
162
- /config max_tokens <%= length || "2000" %>
163
-
164
- # Blog Post: <%= title %>
165
-
166
- Write a <%= tone || "professional" %> blog post about <%= topic %>.
167
-
168
- Target audience: <%= audience || "general" %>
169
- Word count: <%= word_count || "1000-1500" %> words
170
-
171
- <% if include_seo %>
172
- Include SEO-friendly headings and meta description.
173
- <% end %>
174
-
175
- <% if code_examples %>
176
- Include practical code examples where relevant.
177
- <% end %>
178
-
179
- Structure:
180
- 1. Engaging introduction
181
- 2. Main content with clear sections
182
- 3. Actionable takeaways
183
- 4. Compelling conclusion
184
- ```
185
-
186
- ### Executable Prompts
187
- ```markdown
188
- # ~/.prompts/system_report.md
189
- /config executable true
190
- /shell hostname
191
- /shell uptime
192
- /shell df -h
193
- /shell free -h
194
- /shell ps aux | head -10
195
-
196
- System Status Report
197
- ===================
198
-
199
- Please analyze this system information and provide:
200
- 1. Overall system health assessment
201
- 2. Potential issues or concerns
202
- 3. Recommendations for optimization
203
- 4. Any immediate actions needed
204
- ```
205
-
206
- ## Prompt Discovery and Search
207
-
208
- ### Basic Search
209
- ```bash
210
- # List all prompts
211
- aia --prompts-dir ~/.prompts
212
-
213
- # Search by pattern
214
- find ~/.prompts -name "*code*" -type f
215
-
216
- # Search content
217
- grep -r "code review" ~/.prompts/
218
- ```
219
-
220
- ### Fuzzy Search (with fzf)
221
- ```bash
222
- # Interactive prompt selection
223
- aia --fuzzy
224
-
225
- # This opens an interactive interface showing:
226
- # - Prompt names and paths
227
- # - Recent usage
228
- # - Preview of prompt content
229
- ```
230
-
231
- ### Advanced Search
232
- ```bash
233
- # Search by category
234
- aia --fuzzy development/
235
-
236
- # Search by role
237
- aia --fuzzy roles/
238
-
239
- # Search in specific subdirectory
240
- aia --prompts-dir ~/.prompts/analysis --fuzzy
241
- ```
242
-
243
- ## Prompt Organization Strategies
244
-
245
- ### By Domain/Category
246
- ```
247
- ~/.prompts/
248
- ├── software_development/
249
- ├── data_science/
250
- ├── content_creation/
251
- ├── business_analysis/
252
- └── personal/
253
- ```
254
-
255
- ### By Complexity
256
- ```
257
- ~/.prompts/
258
- ├── quick_tasks/ # Simple, fast prompts
259
- ├── standard_workflows/ # Regular multi-step processes
260
- ├── complex_analysis/ # Deep analysis prompts
261
- └── specialized/ # Domain-specific expert prompts
262
- ```
263
-
264
- ### By Model Type
265
- ```
266
- ~/.prompts/
267
- ├── gpt4_prompts/ # Prompts optimized for GPT-4
268
- ├── claude_prompts/ # Prompts optimized for Claude
269
- ├── vision_prompts/ # Prompts for vision models
270
- └── code_prompts/ # Prompts for code models
271
- ```
272
-
273
- ### By Workflow Stage
274
- ```
275
- ~/.prompts/
276
- ├── input_processing/ # Initial data/content processing
277
- ├── analysis/ # Analysis and evaluation
278
- ├── generation/ # Content/code generation
279
- ├── review/ # Quality review and validation
280
- └── finalization/ # Final output formatting
281
- ```
282
-
283
- ## Parameterized Prompts
284
-
285
- ### ERB Variables
286
- ```erb
287
- # ~/.prompts/parameterized_analysis.md
288
- /config model <%= model || "gpt-4" %>
289
-
290
- Analyze <%= subject %> focusing on <%= focus_area %>.
291
-
292
- <% if detailed %>
293
- Provide comprehensive analysis including:
294
- - Background context
295
- - Detailed findings
296
- - Implications and recommendations
297
- <% else %>
298
- Provide a concise summary of key findings.
299
- <% end %>
300
-
301
- Context:
302
- /include <%= context_file if context_file %>
303
- ```
304
-
305
- ### Usage with Parameters
306
- ```bash
307
- # Pass parameters via environment or command line
308
- export subject="market trends"
309
- export focus_area="growth opportunities"
310
- export detailed="true"
311
- aia parameterized_analysis
312
-
313
- # Or using AIA's parameter system
314
- aia parameterized_analysis --subject "user behavior" --focus_area "conversion rates"
315
- ```
316
-
317
- ### Parameter Extraction
318
- ```bash
319
- # Use regex to extract parameters from prompts
320
- aia --regex '\{\{(\w+)\}\}' template_prompt
321
- aia --regex '<%=\s*(\w+)\s*%>' erb_prompt
322
- ```
323
-
324
- ## Roles and Context
325
-
326
- ### Role Definitions
327
- ```markdown
328
- # ~/.prompts/roles/software_architect.md
329
- You are a senior software architect with 15+ years of experience designing scalable systems.
330
-
331
- Your expertise includes:
332
- - Microservices architecture
333
- - Cloud-native design patterns
334
- - Performance optimization
335
- - Security best practices
336
- - Team leadership and mentoring
337
-
338
- When providing advice:
339
- - Consider scalability and maintainability
340
- - Suggest industry best practices
341
- - Provide concrete architectural examples
342
- - Address potential trade-offs
343
- - Consider operational aspects
344
-
345
- Communicate in a professional but approachable manner, suitable for both senior and junior developers.
346
- ```
347
-
348
- ### Using Roles
349
- ```bash
350
- # Apply role to prompt
351
- aia --role software_architect system_design
352
-
353
- # Role with specific prompts
354
- aia --role code_expert code_review main.py
355
-
356
- # Custom roles directory
357
- aia --roles-prefix personas --role mentor learning_session
358
- ```
359
-
360
- ### Context Layering
361
- ```markdown
362
- # ~/.prompts/layered_context.md
363
- /include roles/<%= role || "assistant" %>.md
364
-
365
- /config model <%= model || "gpt-4" %>
366
-
367
- Project Context:
368
- /include README.md
369
- /include ARCHITECTURE.md
370
-
371
- Current Task:
372
- <%= task_description %>
373
-
374
- Please provide guidance consistent with the project architecture and your role as <%= role %>.
375
- ```
376
-
377
- ## Chat Session Checkpoints
378
-
379
- In interactive chat sessions, use `/checkpoint [name]` to save the current conversation state, `/restore [name]` to return to it, and `/checkpoints` to list all saved checkpoints. `/clear` resets the conversation entirely.
380
-
381
- ## Prompt Workflows and Pipelines
382
-
383
- ### Simple Workflows
384
- ```markdown
385
- # ~/.prompts/data_workflow_start.md
386
- /next data_cleaning
387
- /pipeline analysis,visualization,reporting
388
-
389
- Begin data processing workflow for: <%= dataset %>
390
-
391
- Initial data examination:
392
- /shell head -10 <%= dataset %>
393
- /shell wc -l <%= dataset %>
394
-
395
- Proceed to data cleaning stage.
396
- ```
397
-
398
- ### Complex Pipelines
399
- ```bash
400
- # Multi-stage analysis pipeline
401
- aia --pipeline "extract_data,validate_data,analyze_patterns,generate_insights,create_report" dataset.csv
402
- ```
403
-
404
- ### Conditional Workflows
405
- ```ruby
406
- # ~/.prompts/adaptive_workflow.md
407
- /ruby
408
- data_size = File.size('<%= input_file %>')
409
- complexity = data_size > 1000000 ? 'complex' : 'simple'
410
-
411
- if complexity == 'complex'
412
- puts "/pipeline prepare_data,chunk_processing,merge_results,final_analysis"
413
- else
414
- puts "/pipeline quick_analysis,summary_report"
415
- end
416
-
417
- puts "Selected #{complexity} workflow for #{data_size} byte dataset"
418
- ```
419
-
420
- ## Version Control for Prompts
421
-
422
- ### Git Integration
423
- ```bash
424
- # Initialize prompt repository
425
- cd ~/.prompts
426
- git init
427
- git add .
428
- git commit -m "Initial prompt collection"
429
-
430
- # Track changes
431
- git add modified_prompt.md
432
- git commit -m "Improved code review prompt with security focus"
433
-
434
- # Branch for experiments
435
- git checkout -b experimental_prompts
436
- # ... make changes ...
437
- git checkout main
438
- git merge experimental_prompts
439
- ```
440
-
441
- ### Backup and Sync
442
- ```bash
443
- # Backup to remote repository
444
- git remote add origin git@github.com:username/my-prompts.git
445
- git push -u origin main
446
-
447
- # Sync across machines
448
- git pull origin main
449
- ```
450
-
451
- ### Versioned Prompts
452
- ```markdown
453
- # ~/.prompts/versioned/code_review_v2.md
454
- /config version 2.0
455
- /config changelog "Added security analysis, improved output format"
456
-
457
- # Code Review v2.0
458
- Enhanced code review with security focus and structured output.
459
- ```
460
-
461
- ## Prompt Sharing and Collaboration
462
-
463
- ### Team Prompt Libraries
464
- ```bash
465
- # Shared team prompts
466
- git clone git@github.com:team/shared-prompts.git ~/.prompts/shared/
467
- aia --prompts-dir ~/.prompts/shared/ team_code_review
468
-
469
- # Personal + shared prompts
470
- export AIA_PROMPTS__DIR="~/.prompts:~/.prompts/shared:./project_prompts"
471
- ```
472
-
473
- ### Prompt Documentation
474
- ```markdown
475
- # ~/.prompts/README.md
476
- # Team Prompt Library
477
-
478
- ## Categories
479
- - `development/` - Code review, debugging, architecture
480
- - `analysis/` - Data analysis, research, reporting
481
- - `content/` - Writing, documentation, marketing
482
-
483
- ## Usage Guidelines
484
- 1. Test prompts before sharing
485
- 2. Include parameter documentation
486
- 3. Add examples in comments
487
- 4. Follow naming conventions
488
-
489
- ## Contributing
490
- 1. Create feature branch
491
- 2. Add/modify prompts
492
- 3. Test thoroughly
493
- 4. Submit pull request
494
- ```
495
-
496
- ### Prompt Standards
497
- ```markdown
498
- # Prompt file header standard
499
- # Title: Brief description
500
- # Purpose: What this prompt accomplishes
501
- # Parameters: List of expected variables
502
- # Models: Recommended models
503
- # Example: aia prompt_name --param value
504
- # Author: Your name
505
- # Version: 1.0
506
- # Updated: YYYY-MM-DD
507
- ```
508
-
509
- ## Performance and Optimization
510
-
511
- ### Prompt Efficiency
512
- ```bash
513
- # Monitor prompt performance
514
- aia --verbose --debug optimized_prompt
515
-
516
- # Compare prompt variations
517
- time aia version1_prompt input.txt
518
- time aia version2_prompt input.txt
519
- ```
520
-
521
- ### Caching Strategies
522
- ```ruby
523
- # Cache expensive computations
524
- /ruby
525
- cache_file = "/tmp/analysis_cache_#{File.basename('<%= input %>')}.json"
526
- if File.exist?(cache_file) && (Time.now - File.mtime(cache_file)) < 3600
527
- cached_data = JSON.parse(File.read(cache_file))
528
- puts "Using cached analysis: #{cached_data}"
529
- else
530
- # Perform expensive analysis
531
- # Save to cache
532
- end
533
- ```
534
-
535
- ### Batch Processing
536
- ```bash
537
- # Batch process multiple files
538
- for file in data/*.csv; do
539
- aia batch_analysis_prompt "$file" --output "results/$(basename $file .csv)_analysis.md"
540
- done
541
-
542
- # Parallel processing
543
- parallel -j4 aia analysis_prompt {} --output {.}_result.md ::: data/*.txt
544
- ```
545
-
546
- ## Troubleshooting Prompts
547
-
548
- ### Debugging Tools
549
- ```bash
550
- # Debug prompt processing
551
- aia --debug --verbose problematic_prompt
552
-
553
- # Test directive processing
554
- aia --debug prompt_with_directives
555
-
556
- # Validate ERB syntax
557
- erb -T - ~/.prompts/template_prompt.md < /dev/null
558
- ```
559
-
560
- ### Common Issues
561
-
562
- #### Missing Parameters
563
- ```bash
564
- # Check required parameters
565
- aia --regex '<%=\s*(\w+)\s*%>' my_prompt
566
- # Ensure all extracted parameters are provided
567
- ```
568
-
569
- #### File Not Found
570
- ```bash
571
- # Verify file paths in /include directives
572
- find ~/.prompts -name "missing_file.md"
573
- # Use absolute paths or verify relative paths
574
- ```
575
-
576
- #### Permission Errors
577
- ```bash
578
- # Check prompt file permissions
579
- ls -la ~/.prompts/problematic_prompt.md
580
- chmod 644 ~/.prompts/problematic_prompt.md
581
- ```
582
-
583
- ## Advanced Prompt Techniques
584
-
585
- ### Dynamic Prompt Generation
586
- ```ruby
587
- # Generate prompts based on context
588
- /ruby
589
- project_type = `git config --get remote.origin.url`.include?('rails') ? 'rails' : 'general'
590
- prompt_template = File.read("templates/#{project_type}_review.md")
591
- puts prompt_template
592
- ```
593
-
594
- ### Prompt Composition
595
- ```markdown
596
- # ~/.prompts/composed_prompt.md
597
- /include base/standard_instructions.md
598
- /include domain/#{<%= domain %>}_expertise.md
599
- /include format/#{<%= output_format %>}_template.md
600
-
601
- Task: <%= specific_task %>
602
- ```
603
-
604
- ### Adaptive Prompts
605
- ```ruby
606
- # Adjust based on model capabilities
607
- /ruby
608
- model = AIA.config.model
609
- if model.include?('gpt-4')
610
- puts "Use advanced reasoning and detailed analysis."
611
- elsif model.include?('3.5')
612
- puts "Focus on clear, direct responses."
613
- end
614
- ```
615
-
616
- ## Best Practices
617
-
618
- ### Prompt Design
619
- 1. **Clear Structure**: Use headers and sections
620
- 2. **Specific Instructions**: Be precise about desired output
621
- 3. **Context Setting**: Provide necessary background
622
- 4. **Parameter Documentation**: Document all variables
623
- 5. **Error Handling**: Account for edge cases
624
-
625
- ### Organization
626
- 1. **Consistent Naming**: Use clear, descriptive names
627
- 2. **Logical Grouping**: Organize by category or purpose
628
- 3. **Version Control**: Track changes and improvements
629
- 4. **Documentation**: Maintain usage guides
630
- 5. **Regular Cleanup**: Remove obsolete prompts
631
-
632
- #### Recommended Directory Structure
633
- ```
634
- ~/.prompts/
635
- ├── daily/ # Daily workflow prompts
636
- ├── development/ # Coding and review prompts
637
- ├── research/ # Research and analysis
638
- ├── roles/ # System prompts
639
- └── workflows/ # Multi-step pipelines
640
- ```
641
-
642
- This organization helps you:
643
- - **Find prompts quickly** by category
644
- - **Maintain logical separation** of different use cases
645
- - **Scale your prompt collection** without confusion
646
- - **Share category-specific prompts** with team members
647
-
648
- ### Performance
649
- 1. **Model Selection**: Choose appropriate models
650
- 2. **Parameter Optimization**: Fine-tune settings
651
- 3. **Caching**: Cache expensive operations
652
- 4. **Batch Processing**: Process multiple items efficiently
653
- 5. **Monitoring**: Track usage and performance
654
-
655
- ## Related Documentation
656
-
657
- - [Getting Started](guides/getting-started.md) - Basic prompt usage
658
- - [Directives Reference](directives-reference.md) - Available directives
659
- - [Advanced Prompting](advanced-prompting.md) - Expert techniques
660
- - [Configuration](configuration.md) - Setup and customization
661
- - [Examples](examples/prompts/index.md) - Real-world prompt examples
662
-
663
- ---
664
-
665
- Effective prompt management is key to maximizing AIA's capabilities. Start with a simple organization structure and evolve it as your prompt collection grows!