Team Learning Goal
Teach Prompt Builder as the composition boundary between routed context and agent execution.
By the end of this section, the room should understand:
- why
pexists - how it fits after Section 4 routing
- how to inspect prompt text, command shape, and launch JSON
- why named launches use app-server thread creation and
thread/name/set - why handoff mode passes the prompt as a safe final argv element
- when to choose
xfl/xfcversusp-f/p-c - how Section 6 uses one deliberate prompt as a variation seed
Keep this section practical. It is not a Rust code tour.
Walkthrough Depth
Essential Walkthrough
- State: Prompt Builder is the preflight before an agent launch.
- Prove install:
which -a prompt-builder p, versions. - Show
p --print-prompt "hello". - Show
p --dry-run --print-command "hello". - Show named launch JSON with
--name. - Show handoff JSON with
/bin/echo,--fork-from, and--compact. - Bridge to
p-fandp-c.
Preserve these commands:
which -a prompt-builder p
prompt-builder --version
p --version
p --print-prompt "Review the checkout flow."
p --dry-run --print-command \
"Debug the billing webhook duplicate-processing bug."
p --print-launch-json \
--name "Auth review" \
"Review auth/session architecture." \
| jq '.mode, .env, .app_server'
p --print-launch-json \
--handoff-command /bin/echo \
--fork-from last \
--compact \
"continue from here" \
| jq '.mode, .argv'
Expanded Walkthrough
Add:
- interactive
p - Name field
- Tab movement through Name, Prompt, and options
@file selector$skills lookup/slash command popupShift+Enter- bracketed paste behavior
Ctrl+Cclear-before-exit
Deep-Dive Walkthrough
Add:
--stdinplus prefilled text- app-server named thread explanation
CODEX_THREAD_NAMEPROMPT_BUILDER_CODEX_BIN- shell-function handoff through
zsh -lc - debug paths for missing
p, wrong binary, missing zsh functions, and quoting issues - exercise kickoff
Talking Points
Opening:
We already solved routing. Now we solve what we are actually sending.
Core sentence:
Prompt Builder is the checkpoint between "I have a thought" and "I am launching an agent with authority."
On inspection modes:
--print-promptsaves what you said.--print-commandshows what a human would run.--print-launch-jsongives scripts the raw shape without parsing shell quotes.
On --name:
Naming is not a prompt trick. Prompt Builder creates a thread, calls
thread/name/set, and then resumes that thread with the prompt.
On handoff:
Handoff is argv construction, not shell interpolation. The prompt is passed with
Command::argas the final argv element.
On p-f and p-c:
xflandxfcact now.p-fandp-clet you compose first.
On Section 6:
One careful prompt becomes the seed for controlled variations. A sloppy prompt produces sloppy variations faster.
Live Demo Script
1. Prove The Binary
which -a prompt-builder p
prompt-builder --version
p --version
Presenter note: do not dwell on install paths. The important proof is that both commands resolve and match.
2. Print A Prompt
p --print-prompt \
"Review the checkout flow for saved payment method regressions."
Presenter note: this is the cleanest Section 6 bridge.
3. Preview A Command
p --dry-run --print-command \
"Debug the failing checkout test and identify the smallest safe fix."
Presenter note: point at -C . and the final prompt argument.
4. Preview A Named Thread
p --print-launch-json \
--name "Checkout saved payments" \
"Plan the first shippable slice." \
| jq '.mode, .env, .app_server'
Call out:
app-server-named-thread
CODEX_THREAD_NAME
thread/name/set
5. Preview Handoff
p --print-launch-json \
--handoff-command /bin/echo \
--handoff-arg wrapper \
--fork-from last \
--compact \
"continue from here" \
| jq '.mode, .argv'
Call out:
wrapper args first
toggle args next
prompt last
6. Prove Zsh Helper Bridge
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'
Presenter note: shell functions are not binaries. This is why p-f and p-c hand off through zsh -lc.
Boundaries
| Prior Section | What It Solved | Prompt Builder Adds |
|---|---|---|
| Section 1 | package the right project context | compose the implementation request |
| Section 2 | make tools visible to Codex | prove prompt-builder, p, and Codex resolve |
| Section 3 | classify aliases/functions/executables | hand off safely to zsh functions |
| Section 4 | route pane/session/fork/export | compose before fork or compact |
Bridge line from Section 4:
Section 4 gets us to the right session. Section 5 makes sure the next prompt is worth sending.
Bridge line to Section 6:
Section 5 ends with a deliberate prompt. Section 6 varies that prompt under control instead of improvising unrelated asks.
Minimal Useful Path
If 5 minutes behind, cut:
PROMPT_BUILDER_DEBUG_KEYS- detailed slash command list
- custom
--launch-option - Rust module references
Preserve:
which -a prompt-builder p
p --print-prompt "hello"
p --dry-run --print-command "hello"
p --print-launch-json --name "Demo" "hello" | jq '.mode, .env'
p --print-launch-json --handoff-command /bin/echo --fork-from last --compact "continue" | jq '.mode, .argv'
If 10 minutes behind, skip the interactive composer and say:
The TUI matters for real use, but the inspection modes teach the contract fastest.
If 20 minutes behind, run only:
which -a prompt-builder p
p --print-launch-json --name "Demo" "hello" | jq '.mode, .env, .app_server'
p --print-launch-json --handoff-command /bin/echo --fork-from last --compact "continue" | jq '.mode, .argv'
Closing line if rushed:
Compose first, prove the launch shape, then submit.
Debug Paths To Mention
Missing p:
which -a prompt-builder p
ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
p --version
Wrong build:
cargo install --path . --locked --force
which -a prompt-builder p
prompt-builder --version
p --version
Wrong Codex binary:
PROMPT_BUILDER_CODEX_BIN=/bin/echo \
p --submit --dry-run --print-command \
"hello override"
Missing zsh function:
zsh -lc 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; whence -w xfc p-f p-c'
Quoting / final argv:
p --print-launch-json \
--handoff-command /bin/echo \
"fix this
and keep \$HOME literal" \
| jq '.argv'
Presenter Boundaries
Do not over-explain:
- Ratatui internals
- every slash command
- full app-server protocol
- every function in
40-ai.zsh - Rust module architecture beyond what explains behavior
- every possible Codex flag
Emphasize:
- exact prompt text
- exact argv
- exact launch mode
- named thread flow
- safe handoff
p-f/p-cas compose-before-action helpers- Section 6 seed prompt
Team Checklist
Before considering this section ready, confirm the materials include:
Prompt Builder
preflight
composition boundary
prompt-builder
p
which -a prompt-builder p
prompt-builder --version
p --version
cargo install --path . --locked --force
--stdin
--submit
--print-prompt
--print-command
--print-launch-json
--dry-run
--name
CODEX_THREAD_NAME
app-server-named-thread
thread/name/set
--handoff-command
--handoff-arg
Command::arg
final argv
--fork-from
--compact
--launch-option
p-f
p-c
p-cm
xfl
xfc
zsh -lc
40-ai.zsh
@ file selector
skills
slash commands
Shift+Enter
bracketed paste
Ctrl+C
PROMPT_BUILDER_CODEX_BIN
Section 6
Further References
- team-facing file:
cheatsheets/05-prompt-builder.md - Exercises:
exercises/05-prompt-builder.md - Zsh helper file:
zsh/conf.d/40-ai.zsh - Prompt Builder checkout:
README.md,src/cli.rs,src/main.rs,src/handoff.rs,src/launch_manifest.rs,src/app_server_launch.rs,src/composer_input.rs