aia 2.0.0.0.pre.beta2 → 2.0.1
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.
- checksums.yaml +4 -4
- data/CHANGELOG.md +152 -223
- data/README.md +41 -18
- data/bin/aia +8 -3
- data/lib/aia/aia_completion.bash +2 -3
- data/lib/aia/aia_completion.fish +6 -5
- data/lib/aia/aia_completion.zsh +2 -3
- data/lib/aia/chat_loop.rb +16 -14
- data/lib/aia/config/cli_parser.rb +123 -91
- data/lib/aia/config/defaults.yml +18 -40
- data/lib/aia/config/mcp_parser.rb +30 -36
- data/lib/aia/config/model_spec.rb +8 -14
- data/lib/aia/config/validator.rb +102 -103
- data/lib/aia/config/value_caster.rb +76 -0
- data/lib/aia/config.rb +70 -53
- data/lib/aia/crew.rb +29 -19
- data/lib/aia/debate_handler.rb +27 -10
- data/lib/aia/directives/configuration_directives.rb +55 -14
- data/lib/aia/directives/context_directives.rb +24 -12
- data/lib/aia/directives/execution_directives.rb +18 -23
- data/lib/aia/directives/model_directives.rb +41 -104
- data/lib/aia/directives/utility_directives.rb +16 -17
- data/lib/aia/directives/web_and_file_directives.rb +21 -14
- data/lib/aia/fact_asserter.rb +3 -3
- data/lib/aia/history_transfer.rb +64 -24
- data/lib/aia/logger.rb +14 -46
- data/lib/aia/mcp_config_normalizer.rb +27 -14
- data/lib/aia/mcp_connection_manager.rb +181 -184
- data/lib/aia/mcp_discovery.rb +43 -15
- data/lib/aia/mcp_grouper.rb +2 -1
- data/lib/aia/mcp_server_config.rb +20 -2
- data/lib/aia/mcp_utility.rb +24 -19
- data/lib/aia/mention_router.rb +15 -2
- data/lib/aia/modality_query.rb +36 -0
- data/lib/aia/model_alias_registry.rb +11 -11
- data/lib/aia/model_registry.rb +75 -0
- data/lib/aia/network_builder.rb +8 -7
- data/lib/aia/patches/mcp_stdio_stderr.rb +102 -0
- data/lib/aia/patches/ruby_llm_streaming_error.rb +21 -4
- data/lib/aia/patches/ruby_llm_tool_param_compat.rb +18 -0
- data/lib/aia/pipeline_orchestrator.rb +71 -38
- data/lib/aia/prompt_decomposer.rb +1 -1
- data/lib/aia/prompt_handler.rb +56 -29
- data/lib/aia/provider_registry.rb +105 -0
- data/lib/aia/robot_builder.rb +1 -1
- data/lib/aia/robot_factory.rb +67 -63
- data/lib/aia/robot_sync.rb +79 -0
- data/lib/aia/role_catalog.rb +89 -0
- data/lib/aia/session.rb +25 -11
- data/lib/aia/skill_utils.rb +60 -19
- data/lib/aia/spawn_handler.rb +16 -4
- data/lib/aia/spawn_spec_parser.rb +6 -7
- data/lib/aia/special_mode_handler.rb +28 -25
- data/lib/aia/speech.rb +70 -34
- data/lib/aia/startup_coordinator.rb +17 -92
- data/lib/aia/streaming_runner.rb +10 -2
- data/lib/aia/system_prompt_assembler.rb +12 -11
- data/lib/aia/task_board.rb +60 -0
- data/lib/aia/tool_approver.rb +205 -0
- data/lib/aia/tool_filter.rb +1 -10
- data/lib/aia/tool_filter_strategy.rb +12 -1
- data/lib/aia/tool_introspection.rb +9 -1
- data/lib/aia/tool_loader.rb +67 -33
- data/lib/aia/tool_utility.rb +6 -5
- data/lib/aia/tools/delegate_to_foreman_tool.rb +6 -4
- data/lib/aia/tools/recruit_robot_tool.rb +12 -12
- data/lib/aia/tools/reskill_robot_tool.rb +7 -7
- data/lib/aia/tools/task_board_tool.rb +16 -16
- data/lib/aia/trakflow_bridge.rb +14 -8
- data/lib/aia/turn_state.rb +31 -8
- data/lib/aia/ui_presenter.rb +16 -0
- data/lib/aia/utility.rb +6 -24
- data/lib/aia/variable_input_collector.rb +0 -3
- data/lib/aia/verification_network.rb +9 -10
- data/lib/aia/version.rb +1 -9
- data/lib/aia.rb +34 -8
- metadata +20 -161
- data/.better-commits.json +0 -150
- data/.config/tocer/configuration.yml +0 -6
- data/.envrc +0 -19
- data/.loki +0 -11
- data/.reek.yml +0 -160
- data/.rubocop.yml +0 -116
- data/.rubocop_strict.yml +0 -15
- data/.version +0 -1
- data/COMMITS.md +0 -196
- data/IMPLEMENTATION_PLAN.md +0 -506
- data/Rakefile +0 -47
- data/_typos.toml +0 -10
- data/aia.gemspec +0 -92
- data/architecture_review.md +0 -314
- data/config/aia.yml +0 -13
- data/docs/AGENTS.md +0 -40
- data/docs/advanced-prompting.md +0 -814
- data/docs/assets/images/aia.png +0 -0
- data/docs/cli-reference.md +0 -1241
- data/docs/configuration.md +0 -747
- data/docs/contributing.md +0 -386
- data/docs/directives-reference.md +0 -1145
- data/docs/examples/index.md +0 -277
- data/docs/examples/mcp/index.md +0 -475
- data/docs/examples/prompts/analysis/index.md +0 -78
- data/docs/examples/prompts/automation/index.md +0 -109
- data/docs/examples/prompts/development/index.md +0 -125
- data/docs/examples/prompts/index.md +0 -333
- data/docs/examples/prompts/learning/index.md +0 -127
- data/docs/examples/prompts/writing/index.md +0 -62
- data/docs/examples/tools/index.md +0 -282
- data/docs/faq.md +0 -578
- data/docs/guides/available-models.md +0 -366
- data/docs/guides/basic-usage.md +0 -478
- data/docs/guides/chat.md +0 -680
- data/docs/guides/crew.md +0 -239
- data/docs/guides/executable-prompts.md +0 -331
- data/docs/guides/first-prompt.md +0 -454
- data/docs/guides/getting-started.md +0 -455
- data/docs/guides/image-generation.md +0 -507
- data/docs/guides/index.md +0 -48
- data/docs/guides/local-models.md +0 -306
- data/docs/guides/migrate-prompts.md +0 -335
- data/docs/guides/models.md +0 -1017
- data/docs/guides/shared-tools.md +0 -254
- data/docs/guides/tools.md +0 -831
- data/docs/index.md +0 -259
- data/docs/installation.md +0 -274
- data/docs/mcp-integration.md +0 -603
- data/docs/prompt_management.md +0 -665
- data/docs/security.md +0 -674
- data/docs/special_projects_guide.md +0 -386
- data/docs/tools-and-mcp-examples.md +0 -1211
- data/docs/workflows-and-pipelines.md +0 -636
- data/examples/.gitignore +0 -2
- data/examples/00_setup_aia.sh +0 -111
- data/examples/01_basic_usage.sh +0 -23
- data/examples/02_frontmatter.sh +0 -33
- data/examples/03_shell_integration.sh +0 -55
- data/examples/04_erb_templating.sh +0 -56
- data/examples/05_shell_then_erb.sh +0 -38
- data/examples/06_prompt_chaining.sh +0 -59
- data/examples/07_pipeline.sh +0 -46
- data/examples/08_context_files.sh +0 -43
- data/examples/09_roles.sh +0 -67
- data/examples/10_stdin_piping.sh +0 -49
- data/examples/11_multi_model.sh +0 -65
- data/examples/12_token_usage.sh +0 -52
- data/examples/13_cost_tracking.sh +0 -68
- data/examples/14_output_file.sh +0 -91
- data/examples/15_parameters.sh +0 -68
- data/examples/16_directives.sh +0 -113
- data/examples/17_require_and_conditionals.sh +0 -68
- data/examples/18_tools.sh +0 -61
- data/examples/19_local_tools.sh +0 -34
- data/examples/20_mcp_servers.sh +0 -102
- data/examples/21_executable_prompts.sh +0 -78
- data/examples/22_chat_mode.sh +0 -217
- data/examples/23_verify.sh +0 -139
- data/examples/24_decompose.sh +0 -139
- data/examples/25_spawn.sh +0 -139
- data/examples/26_debate.sh +0 -97
- data/examples/27_mention_routing.sh +0 -157
- data/examples/28_model_switching.sh +0 -106
- data/examples/29_agent_harness.sh +0 -177
- data/examples/README.md +0 -321
- data/examples/advanced_multi_robot_capabilities_without_examples.md +0 -106
- data/examples/aia_config.yml +0 -22
- data/examples/aia_config_orchestrator.yml +0 -45
- data/examples/aia_config_with_mcp.yml +0 -21
- data/examples/common.sh +0 -39
- data/examples/context/project_goals.md +0 -6
- data/examples/context/tech_stack.md +0 -7
- data/examples/directives/timestamp_directive.rb +0 -22
- data/examples/mcp/filesystem.json +0 -9
- data/examples/prompts_dir/analyze.md +0 -2
- data/examples/prompts_dir/brainstorm.md +0 -2
- data/examples/prompts_dir/conditional.md +0 -17
- data/examples/prompts_dir/creative.md +0 -4
- data/examples/prompts_dir/erbinfo.md +0 -5
- data/examples/prompts_dir/erbinfo_raw.md +0 -8
- data/examples/prompts_dir/evaluate.md +0 -2
- data/examples/prompts_dir/explain_joke.md +0 -1
- data/examples/prompts_dir/explain_recursion.md +0 -1
- data/examples/prompts_dir/fun_fact +0 -3
- data/examples/prompts_dir/greeting.md +0 -8
- data/examples/prompts_dir/greeting_required.md +0 -7
- data/examples/prompts_dir/hello.md +0 -1
- data/examples/prompts_dir/includes/ruby_facts.md +0 -4
- data/examples/prompts_dir/limerick.md +0 -1
- data/examples/prompts_dir/list_with_mcp.md +0 -3
- data/examples/prompts_dir/pick_best.md +0 -2
- data/examples/prompts_dir/project_summary +0 -12
- data/examples/prompts_dir/quiz_with_include.md +0 -6
- data/examples/prompts_dir/require_demo.md +0 -5
- data/examples/prompts_dir/roles/formal.md +0 -3
- data/examples/prompts_dir/roles/orchestrator.md +0 -21
- data/examples/prompts_dir/roles/pirate.md +0 -3
- data/examples/prompts_dir/shell_then_erb.md +0 -6
- data/examples/prompts_dir/sort_compare.md +0 -2
- data/examples/prompts_dir/summarize_context.md +0 -2
- data/examples/prompts_dir/sysinfo.md +0 -5
- data/examples/prompts_dir/sysinfo_raw.md +0 -8
- data/examples/prompts_dir/tagline.md +0 -1
- data/examples/prompts_dir/tell_joke.md +0 -1
- data/examples/prompts_dir/tell_joke_with_next.md +0 -4
- data/examples/prompts_dir/use_local_tool.md +0 -8
- data/examples/prompts_dir/use_tools.md +0 -8
- data/examples/prompts_dir/weather.md +0 -2
- data/examples/prompts_dir/whats_new.md +0 -2
- data/examples/prompts_dir/with_timestamp.md +0 -5
- data/examples/requirements/sinatra_taskflow_app.md +0 -139
- data/examples/rules/01_classify_ruby.rb +0 -16
- data/examples/rules/02_prefer_claude_for_code.rb +0 -19
- data/examples/rules/03_gate_prompt_length.rb +0 -19
- data/examples/rules/04_tool_selection.rb +0 -41
- data/examples/rules/README.md +0 -30
- data/examples/run_all.sh +0 -294
- data/examples/tools/word_count_tool.rb +0 -30
- data/lib/AGENTS.md +0 -57
- data/lib/aia/model_switch_handler.rb +0 -100
- data/mcp_servers/README.md +0 -110
- data/mcp_servers/apple-mcp.json +0 -8
- data/mcp_servers/filesystem.json +0 -9
- data/mcp_servers/mcp_server_chart.json +0 -11
- data/mcp_servers/playwright_one.json +0 -8
- data/mcp_servers/playwright_server_definition.json +0 -9
- data/mcp_servers/playwright_two.json +0 -8
- data/mcp_servers/tavily_mcp_server.json +0 -8
- 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
|