---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-prompt-composition-team-guide"
title: "Prompt Builder composition and handoff: team walkthrough"
---

# Prompt Builder composition and handoff: team walkthrough

## 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:

```bash
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

```bash
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

```bash
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

```bash
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

```bash
p --print-launch-json \
  --name "Checkout saved payments" \
  "Plan the first shippable slice." \
  | jq '.mode, .env, .app_server'
```

Call out:

```text
app-server-named-thread
CODEX_THREAD_NAME
thread/name/set
```

### 5. Preview Handoff

```bash
p --print-launch-json \
  --handoff-command /bin/echo \
  --handoff-arg wrapper \
  --fork-from last \
  --compact \
  "continue from here" \
  | jq '.mode, .argv'
```

Call out:

```text
wrapper args first
toggle args next
prompt last
```

### 6. Prove Zsh Helper Bridge

```zsh
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:

```text
Section 4 gets us to the right session. Section 5 makes sure the next prompt is worth sending.
```

Bridge line to Section 6:

```text
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:

```bash
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:

```text
The TUI matters for real use, but the inspection modes teach the contract fastest.
```

If 20 minutes behind, run only:

```bash
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:

```text
Compose first, prove the launch shape, then submit.
```

## Debug Paths To Mention

Missing `p`:

```bash
which -a prompt-builder p
ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
p --version
```

Wrong build:

```bash
cargo install --path . --locked --force
which -a prompt-builder p
prompt-builder --version
p --version
```

Wrong Codex binary:

```bash
PROMPT_BUILDER_CODEX_BIN=/bin/echo \
  p --submit --dry-run --print-command \
  "hello override"
```

Missing zsh function:

```zsh
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:

```bash
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:

```text
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`

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
- [Resource directory and portable download](/topics/codex-resources/)

## Original references

- [Portable Codex workflow resources](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)
