Prompt Builder composition and handoff: team walkthrough

Prompt composition and launch inspection through prompt text, shell commands, and JSON; named app-server threads; final-argv handoff; interactive composer controls; zsh helper bridges; and installation, binary-selection, and quoting diagnostics.

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 p exists
  • 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 / xfc versus p-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

  1. State: Prompt Builder is the preflight before an agent launch.
  2. Prove install: which -a prompt-builder p, versions.
  3. Show p --print-prompt "hello".
  4. Show p --dry-run --print-command "hello".
  5. Show named launch JSON with --name.
  6. Show handoff JSON with /bin/echo, --fork-from, and --compact.
  7. Bridge to p-f and p-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 popup
  • Shift+Enter
  • bracketed paste behavior
  • Ctrl+C clear-before-exit

Deep-Dive Walkthrough

Add:

  • --stdin plus prefilled text
  • app-server named thread explanation
  • CODEX_THREAD_NAME
  • PROMPT_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-prompt saves what you said. --print-command shows what a human would run. --print-launch-json gives 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::arg as the final argv element.

On p-f and p-c:

xfl and xfc act now. p-f and p-c let 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-c as 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

Source references