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
data/docs/guides/crew.md DELETED
@@ -1,239 +0,0 @@
1
- # Crews
2
-
3
- Every AIA chat session is a **crew** — a small team of robots that share the
4
- conversation. Even when you start with a single model, that model is the crew's
5
- **chief**, and you can add more members on the fly, address them individually or
6
- together, and have them build on each other's answers.
7
-
8
- This guide covers how the crew works, how to address members, and how to grow or
9
- shrink the crew while you chat.
10
-
11
- ## What a crew is
12
-
13
- A crew is a network of robots backing one chat session:
14
-
15
- - The **chief** is the lead robot — the first (or only) model you started with.
16
- It answers plain turns and is the model your `/model`, consensus, and
17
- history-transfer behavior revolve around.
18
- - **Members** (also called recruits) are additional robots you add during the
19
- session. Each has a name, a provider/model, and its own system prompt, and is
20
- reachable by `@name`.
21
-
22
- A single-model session is simply a crew of one. Multi-model sessions
23
- (`-m model1,model2,...`) start as a crew with one member per model.
24
-
25
- <svg width="640" height="280" viewBox="0 0 640 280" xmlns="http://www.w3.org/2000/svg" role="img" aria-label="Crew topology: a chief robot with recruited members addressed by @mention">
26
- <style>
27
- .lbl { font: 13px -apple-system, Segoe UI, sans-serif; fill: #e6e6e6; }
28
- .sub { font: 11px -apple-system, Segoe UI, sans-serif; fill: #9aa4b2; }
29
- .chief { fill: #1f6feb; }
30
- .member { fill: #2ea043; }
31
- .you { fill: #8957e5; }
32
- .edge { stroke: #6e7681; stroke-width: 1.5; fill: none; }
33
- .edge-bc { stroke: #d29922; stroke-width: 1.5; stroke-dasharray: 5 4; fill: none; }
34
- </style>
35
- <!-- You -->
36
- <rect class="you" x="20" y="120" rx="8" width="110" height="44"/>
37
- <text class="lbl" x="75" y="140" text-anchor="middle">You</text>
38
- <text class="sub" x="75" y="156" text-anchor="middle">the prompt</text>
39
- <!-- Chief -->
40
- <rect class="chief" x="250" y="120" rx="8" width="130" height="44"/>
41
- <text class="lbl" x="315" y="140" text-anchor="middle">chief</text>
42
- <text class="sub" x="315" y="156" text-anchor="middle">lead robot</text>
43
- <!-- Members -->
44
- <rect class="member" x="490" y="30" rx="8" width="130" height="44"/>
45
- <text class="lbl" x="555" y="50" text-anchor="middle">@researcher</text>
46
- <text class="sub" x="555" y="66" text-anchor="middle">gpt-4o</text>
47
- <rect class="member" x="490" y="120" rx="8" width="130" height="44"/>
48
- <text class="lbl" x="555" y="140" text-anchor="middle">@critic</text>
49
- <text class="sub" x="555" y="156" text-anchor="middle">claude</text>
50
- <rect class="member" x="490" y="210" rx="8" width="130" height="44"/>
51
- <text class="lbl" x="555" y="230" text-anchor="middle">@local</text>
52
- <text class="sub" x="555" y="246" text-anchor="middle">ollama/qwen</text>
53
- <!-- edges -->
54
- <path class="edge" d="M130 142 H250"/>
55
- <path class="edge" d="M380 142 C 430 142, 440 52, 490 52"/>
56
- <path class="edge" d="M380 142 H490"/>
57
- <path class="edge" d="M380 142 C 430 142, 440 232, 490 232"/>
58
- <text class="sub" x="190" y="135" text-anchor="middle">plain turn</text>
59
- <text class="sub" x="435" y="120" text-anchor="middle">@name / @crew</text>
60
- </svg>
61
-
62
- ## Seeing the crew
63
-
64
- Use `/robots` to list the active crew, each member's model, and its `@mention`
65
- handle:
66
-
67
- ```text
68
- /robots
69
- ```
70
-
71
- By default a robot's name is derived from its model name; recruited robots use
72
- the name you give them.
73
-
74
- ## Addressing members with @mention
75
-
76
- Prefix a name with `@` to direct a prompt at one member instead of the chief:
77
-
78
- ```text
79
- > @critic Does this API design have any obvious flaws?
80
- ```
81
-
82
- Only the addressed robot responds; the `@critic` prefix is stripped before the
83
- prompt reaches it. Unknown names are reported (with the list of available
84
- members) rather than silently broadcast.
85
-
86
- ### Addressing several members at once
87
-
88
- You can mention more than one member. **Where** the mentions appear changes how
89
- they run:
90
-
91
- - **Leading address → concurrent.** When the prompt is nothing but `@names`
92
- followed by the message, every addressee runs at the same time, each in its
93
- own thread, and replies render as they finish:
94
-
95
- ```text
96
- > @researcher @critic what are the trade-offs of optimistic locking?
97
- ```
98
-
99
- - **Body mention → sequential pipeline.** When a `@name` is woven into the body
100
- of the message, the mentioned members run one at a time, and each reply is
101
- injected into the other members' conversations so later members build on what
102
- earlier ones said:
103
-
104
- ```text
105
- > draft a plan @researcher then have @critic poke holes in it
106
- ```
107
-
108
- Here `@researcher` runs first; its answer is shared into `@critic`'s context
109
- before `@critic` runs, so the critique responds to the actual draft.
110
-
111
- ### Broadcasting to the whole crew
112
-
113
- `@crew` is a reserved handle that broadcasts the message to **every** member,
114
- concurrently:
115
-
116
- ```text
117
- > @crew in one sentence, what is your specialty?
118
- ```
119
-
120
- Because `crew` is reserved for broadcast, you cannot name a member `crew`.
121
-
122
- > **Local models and concurrency.** A leading-address or `@crew` broadcast runs
123
- > its members **concurrently** — several HTTP requests at once. When every member
124
- > shares one local model server (e.g. all on `ollama/qwen3.6:latest`), those
125
- > requests compete for the same instance: the server processes only
126
- > `OLLAMA_NUM_PARALLEL` at a time and the rest queue, so a big task can blow past
127
- > the per-request timeout and you'll see `Net::ReadTimeout` for several members.
128
- > If you hit this, raise Ollama's parallelism (`OLLAMA_NUM_PARALLEL=4`,
129
- > `OLLAMA_MAX_LOADED_MODELS=1`), give each member a smaller scoped task (see
130
- > [skills](#giving-a-recruit-a-role-with-skills)), or address members one at a
131
- > time (a body mention runs them sequentially) instead of broadcasting.
132
-
133
- ## Building a crew at runtime
134
-
135
- ### Recruiting a member
136
-
137
- `/add_recruit` (alias `/add`) adds a persistent member to the crew. It stays for
138
- the rest of the session and is reachable by `@name`.
139
-
140
- ```text
141
- # Inherit the chief's model; give it a default persona
142
- /add_recruit researcher
143
-
144
- # Pick an explicit provider/model and write its system prompt
145
- /add_recruit critic anthropic/claude-3-5-sonnet You are a ruthless design critic. Find flaws.
146
-
147
- # A local model member
148
- /add_recruit local ollama/qwen3.6:latest You are concise and fast.
149
- ```
150
-
151
- Syntax:
152
-
153
- ```text
154
- /add_recruit <name> [provider/model] [system prompt...]
155
- ```
156
-
157
- - **`<name>`** — required, unique within the crew (and not `crew`).
158
- - **`provider/model`** — optional. Omit it (give only a name) to inherit the
159
- chief's model and provider. Use `-` or `inherit` as the model token to inherit
160
- explicitly while still supplying a system prompt. `lms/...` maps to the
161
- `openai` provider for LM Studio.
162
- - **system prompt** — everything after the model becomes the member's system
163
- prompt. Without one, the member gets a simple default persona.
164
-
165
- Recruits inherit the chief's local tools and any connected MCP servers, so a new
166
- member can do the same file/shell/MCP work the chief can without reopening
167
- connections.
168
-
169
- ### Giving a recruit a role with skills
170
-
171
- A bare crew of identical robots all do the same undifferentiated work. To divide
172
- labor, assign each member a **skill** — a named, reusable system prompt (the same
173
- skills used by `--skill` and `/skill`; list them with `/skills`). A skill becomes
174
- the recruit's role:
175
-
176
- ```text
177
- # One skill as the recruit's role
178
- /add_recruit reviewer skill:security-review
179
-
180
- # Skill + explicit model, then an extra instruction appended after the skill
181
- /add_recruit reviewer ollama/qwen3.6:latest skill:security-review focus on the auth module
182
-
183
- # Several skills at once (repeat the token or comma-separate)
184
- /add_recruit reviewer - skill:security-review,ruby-style
185
- ```
186
-
187
- The `skill:<id>` token may appear anywhere after the name; everything else is
188
- parsed as the model (position 1) and an optional trailing system prompt. The
189
- final role is the skill bodies joined, followed by any explicit prompt. An
190
- unknown skill id is reported rather than silently ignored, so the recruit always
191
- gets the role you intended.
192
-
193
- This is how you turn a `@crew` broadcast from four identical answers into a real
194
- division of labor — e.g. a security reviewer, a performance reviewer, a test
195
- reviewer, and a style reviewer, each with its own skill.
196
-
197
- ### Re-skilling a member
198
-
199
- `/reskill` resets a member to a **clean slate** (a fresh conversation) and gives
200
- it a new role. The member keeps its `@name` and model:
201
-
202
- ```text
203
- # Repurpose larry for the next phase
204
- /reskill larry skill:test-writing
205
-
206
- # Or hand it a freeform role
207
- /reskill larry - you now summarize the other members' findings
208
- ```
209
-
210
- Use it to recover a member that drifted off task, or to move the crew through
211
- phases (review → fix → summarize) without re-creating robots.
212
-
213
- ### Dropping a member
214
-
215
- `/drop_recruit` (alias `/drop`) removes a member by name:
216
-
217
- ```text
218
- /drop_recruit researcher
219
- ```
220
-
221
- The chief cannot be dropped — it is the session's lead robot.
222
-
223
- ## Recruits vs. spawned specialists
224
-
225
- `/add_recruit` and `/spawn` look similar but serve different needs:
226
-
227
- | | `/add_recruit` (`/add`) | `/spawn` |
228
- |---|---|---|
229
- | Lifetime | Persists for the whole session | One-shot, for the **next** prompt only |
230
- | Joins the crew | Yes — shows in `/robots`, answers to `@name` | No — handles a single subtask, then is set aside |
231
- | Best for | A standing teammate you'll address repeatedly | A throwaway specialist for one focused task |
232
-
233
- Both accept the same explicit `name provider/model system prompt` form, so a
234
- specialist you find yourself reaching for repeatedly is a good candidate to
235
- promote from `/spawn` to `/add_recruit`.
236
-
237
- See the [Directives Reference](../directives-reference.md) for the full
238
- directive list and the [Working with Models](models.md) guide for multi-model
239
- sessions, consensus mode, and dynamic model switching.
@@ -1,331 +0,0 @@
1
- # Executable Prompts
2
-
3
- Transform your prompts into standalone executable scripts that can be run directly from the command line, integrated into shell workflows, and used as command-line tools. You can also pipe or redirect any prompt file to AIA without making it executable.
4
-
5
- ## What Are Executable Prompts?
6
-
7
- Executable prompts are prompt files with a shebang line (`#!`) and executable permission (`chmod +x`) that can be run directly from the command line. When you run an executable prompt, AIA strips the shebang, parses YAML front matter for configuration, processes directives, and sends the body to the AI model.
8
-
9
- Any prompt file can also be piped or redirected to AIA without a shebang line or executable permission — see [Piping and Redirection](#piping-and-redirection) below.
10
-
11
- ## Creating Executable Prompts
12
-
13
- ### Basic Structure
14
-
15
- ```markdown
16
- #!/usr/bin/env aia --no-output
17
- ---
18
- description: What this prompt does
19
- ---
20
- Your prompt content here...
21
- ```
22
-
23
- ### Key Components
24
-
25
- 1. **Shebang Line**: `#!/usr/bin/env aia` followed by any AIA CLI options
26
- 2. **YAML Front Matter** (optional): Configuration between `---` delimiters
27
- 3. **Prompt Body**: The actual text sent to the AI model
28
- 4. **Executable Permission**: `chmod +x your_prompt.md`
29
-
30
- ### Minimal Example
31
-
32
- ```markdown
33
- #!/usr/bin/env aia --no-output
34
- Tell me today's date and what historical events occurred on this day.
35
- ```
36
-
37
- Save as `daily_history`, make executable, and run:
38
-
39
- ```bash
40
- chmod +x daily_history
41
- ./daily_history
42
- ```
43
-
44
- ## Shebang Options
45
-
46
- The shebang line accepts any AIA CLI option. Common patterns:
47
-
48
- ```bash
49
- #!/usr/bin/env aia --no-output # Output to STDOUT
50
- #!/usr/bin/env aia --no-output --no-mcp # No MCP servers
51
- #!/usr/bin/env aia --no-output -m claude-sonnet-4 # Specific model
52
- #!/usr/bin/env aia -o report.md # Output to file
53
- #!/usr/bin/env aia --no-output --chat # Start chat after prompt
54
- ```
55
-
56
- ## Adding CLI Options at Runtime
57
-
58
- When running an executable prompt, you can append additional AIA options:
59
-
60
- ```bash
61
- # Run with defaults from the shebang
62
- ./weather_report
63
-
64
- # Override the model
65
- ./weather_report -m gpt-4
66
-
67
- # Add verbose output
68
- ./weather_report --verbose
69
-
70
- # Disable MCP servers for this run
71
- ./weather_report --no-mcp
72
-
73
- # Send output to a file instead of STDOUT
74
- ./weather_report -o weather.md
75
- ```
76
-
77
- Options specified at runtime override those in the shebang line.
78
-
79
- ## YAML Front Matter
80
-
81
- Use front matter for prompt metadata and configuration:
82
-
83
- ```markdown
84
- #!/usr/bin/env aia --no-output
85
- ---
86
- description: Analyze code quality
87
- model: claude-sonnet-4
88
- temperature: 0.3
89
- ---
90
- Review the following code for quality, security, and best practices.
91
- ```
92
-
93
- Supported front matter keys include `model`, `temperature`, `top_p`, `next`, `pipeline`, `shell`, and `erb`. See [Configuration](../configuration.md) for details.
94
-
95
- ## Piping and Redirection
96
-
97
- Prompt files do not need a shebang line or executable permission to be processed by AIA. Any prompt file — plain text, YAML front matter, ERB, directives — can be piped or redirected directly:
98
-
99
- ### Pipe a Prompt File
100
-
101
- ```bash
102
- cat my_prompt.md | aia --no-output
103
- cat my_prompt.md | aia --no-output --no-mcp
104
- cat my_prompt.md | aia --no-output -m gpt-4
105
- ```
106
-
107
- ### STDIN Redirection
108
-
109
- ```bash
110
- aia --no-output < my_prompt.md
111
- aia --no-output --no-mcp < my_prompt.md
112
- ```
113
-
114
- ### Inline Prompts
115
-
116
- ```bash
117
- echo "Explain the theory of relativity in one paragraph." | aia --no-output
118
- ```
119
-
120
- When content is piped or redirected, AIA automatically detects it and processes it as the prompt — no prompt ID argument is needed. The shebang line is only required when making a file directly executable with `chmod +x`. If piped content happens to start with a shebang line (`#!`), that line is stripped before processing.
121
-
122
- ## Practical Examples
123
-
124
- ### Weather Report
125
-
126
- ```markdown
127
- #!/usr/bin/env aia --no-output
128
- ---
129
- description: Atlantic storm activity summary
130
- model: gpt-4o-mini
131
- temperature: 0.3
132
- ---
133
- Summarize the tropical storm outlook for the Atlantic, Caribbean Sea and
134
- Gulf of America.
135
-
136
- /webpage https://www.nhc.noaa.gov/text/refresh/MIATWOAT+shtml/MIATWOAT.shtml
137
- ```
138
-
139
- ### System Status Monitor
140
-
141
- ```markdown
142
- #!/usr/bin/env aia --no-output
143
- ---
144
- description: System health check
145
- temperature: 0.3
146
- ---
147
- Analyze the current system status and provide recommendations:
148
-
149
- System Information:
150
- <%= `uname -a` %>
151
-
152
- Disk Usage:
153
- <%= `df -h` %>
154
-
155
- Top Processes:
156
- <%= `ps aux | head -20` %>
157
-
158
- Provide analysis and recommendations for system optimization.
159
- ```
160
-
161
- ### Daily Standup Generator
162
-
163
- ```markdown
164
- #!/usr/bin/env aia --no-output
165
- ---
166
- description: Generate standup report from git activity
167
- model: gpt-4o-mini
168
- temperature: 0.5
169
- ---
170
- Generate a daily standup report based on recent git activity:
171
-
172
- Yesterday's Commits:
173
- <%= `git log --since="1 day ago" --author="$(git config user.name)" --oneline` %>
174
-
175
- Current Branch Status:
176
- <%= `git status --short` %>
177
-
178
- Based on the above activity, what should be the key focus areas for today?
179
- Provide a structured standup report.
180
- ```
181
-
182
- ### Code Quality Checker
183
-
184
- ```markdown
185
- #!/usr/bin/env aia --no-output
186
- ---
187
- description: Analyze code quality for the current directory
188
- model: gpt-4
189
- temperature: 0.3
190
- ---
191
- Review the code structure and quality in this project:
192
-
193
- Project Structure:
194
- <%= `find . -type f -name "*.rb" -o -name "*.py" -o -name "*.js" | head -20` %>
195
-
196
- Git Status:
197
- <%= `git status --short 2>/dev/null || echo "Not a git repository"` %>
198
-
199
- Recent Commits:
200
- <%= `git log --oneline -10 2>/dev/null || echo "No git history available"` %>
201
-
202
- Provide code quality assessment and improvement recommendations.
203
- ```
204
-
205
- ## Integration with Shell Workflows
206
-
207
- ### Piping Output
208
-
209
- ```bash
210
- # Pipe to a markdown viewer
211
- ./weather_report | glow
212
-
213
- # Save and view
214
- ./code_review > review.md && open review.md
215
-
216
- # Chain with other tools
217
- ./summarize_logs | mail -s "Daily Summary" team@example.com
218
- ```
219
-
220
- ### In Makefiles
221
-
222
- ```makefile
223
- analyze-code:
224
- @./scripts/code_analyzer
225
-
226
- deploy-check:
227
- @./scripts/deployment_check | tee deploy-report.md
228
-
229
- .PHONY: analyze-code deploy-check
230
- ```
231
-
232
- ### As Git Hooks
233
-
234
- ```markdown
235
- #!/usr/bin/env aia --no-output
236
- ---
237
- description: Pre-commit code review
238
- temperature: 0.2
239
- ---
240
- Analyze the staged changes and suggest improvements:
241
-
242
- Staged Changes:
243
- <%= `git diff --cached --stat` %>
244
-
245
- <%= `git diff --cached` %>
246
-
247
- Provide commit message suggestions and code quality feedback.
248
- ```
249
-
250
- ```bash
251
- # Install as git hook
252
- cp pre_commit_review .git/hooks/pre-commit
253
- chmod +x .git/hooks/pre-commit
254
- ```
255
-
256
- ### In CI/CD Pipelines
257
-
258
- ```yaml
259
- # .github/workflows/ai-analysis.yml
260
- name: AI Code Analysis
261
- on: [pull_request]
262
-
263
- jobs:
264
- analysis:
265
- runs-on: ubuntu-latest
266
- steps:
267
- - uses: actions/checkout@v4
268
- - uses: ruby/setup-ruby@v1
269
- with:
270
- ruby-version: '4.0.0'
271
- - run: gem install aia
272
- - name: Run Analysis
273
- run: cat ./prompts/pr_analyzer.md | aia --no-output --no-mcp
274
- env:
275
- OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
276
- ```
277
-
278
- ## Best Practices
279
-
280
- ### Security
281
-
282
- 1. **Review Before Execution**: Always review executable prompts before running
283
- 2. **Limit Permissions**: Use appropriate file permissions
284
- 3. **Avoid Secrets**: Never hardcode API keys or sensitive data
285
-
286
- ```bash
287
- chmod 750 executable_prompt # Owner can execute, group can read
288
- chmod 700 sensitive_prompt # Owner only
289
- ```
290
-
291
- ### Performance
292
-
293
- Use YAML front matter to tune model parameters:
294
-
295
- ```yaml
296
- ---
297
- model: gpt-4o-mini # Faster model for simple tasks
298
- temperature: 0.3 # Lower temperature for consistent results
299
- ---
300
- ```
301
-
302
- ### Debugging
303
-
304
- Add `--debug` or `--verbose` at runtime to troubleshoot:
305
-
306
- ```bash
307
- ./my_prompt --debug --verbose
308
- ```
309
-
310
- Or pipe with debug flags:
311
-
312
- ```bash
313
- cat my_prompt.md | aia --no-output --debug --verbose
314
- ```
315
-
316
- ### Common Issues
317
-
318
- | Issue | Cause | Solution |
319
- |-------|-------|----------|
320
- | "Permission denied" | File not executable | `chmod +x filename` |
321
- | "Command not found" | AIA not in PATH | Check `gem install aia` |
322
- | Output goes to temp.md | Missing `--no-output` | Add to shebang or CLI |
323
- | Shebang options ignored | Too many shebang args | Use `#!/usr/bin/env -S aia ...` on Linux |
324
-
325
- ## Related Documentation
326
-
327
- - [Getting Started](getting-started.md) - Basic AIA usage
328
- - [Basic Usage](basic-usage.md) - Common usage patterns
329
- - [CLI Reference](../cli-reference.md) - Command-line options
330
- - [Directives Reference](../directives-reference.md) - Available directives
331
- - [Advanced Prompting](../advanced-prompting.md) - Complex prompt techniques