These exercises practice composing, inspecting, naming, and handing off prompts before launching agents.
Use a real software project when possible. Prefer dry-runs and print modes until the prompt is specific enough to submit.
Exercise 1: Identity Check
Run:
which -a prompt-builder p
prompt-builder --version
p --version
Fill out:
# Prompt Builder Identity
- `prompt-builder` path:
- `p` path:
- versions match? yes/no
- expected install location:
- action needed:
If working from a local Prompt Builder checkout, run:
cargo install --path . --locked --force
which -a prompt-builder p
p --version
Exercise 2: Print A Prompt
Create a prompt for a real software task.
mkdir -p artifacts/prompt-builder
p --print-prompt \
"Review the checkout flow for saved payment method regressions. Identify the smallest safe implementation slice and the tests to run." \
> artifacts/prompt-builder/checkout.prompt.md
test -s artifacts/prompt-builder/checkout.prompt.md && echo "prompt:OK"
cat artifacts/prompt-builder/checkout.prompt.md
Fill out:
# Printed Prompt
- command:
- output path:
- prompt non-empty? yes/no
- software goal:
- files or subsystems named:
- verification command named:
- one improvement before launch:
Exercise 3: Compare Prompt, Command, And Launch JSON
Run:
mkdir -p artifacts/prompt-builder
p --print-prompt "hello checkout" \
> artifacts/prompt-builder/hello.prompt.txt
p --dry-run --print-command "hello checkout" \
> artifacts/prompt-builder/hello.command.txt
p --print-launch-json "hello checkout" \
> artifacts/prompt-builder/hello.launch.json
cat artifacts/prompt-builder/hello.prompt.txt
cat artifacts/prompt-builder/hello.command.txt
jq '.mode, .command, .argv, .env, .prompt' artifacts/prompt-builder/hello.launch.json
Fill out:
# Inspection Mode Comparison
| Mode | What It Shows | When To Use |
| --- | --- | --- |
| `--print-prompt` | | |
| `--print-command` | | |
| `--print-launch-json` | | |
| `--dry-run` | | |
- direct launch mode:
- final argv:
- prompt value:
Exercise 4: Stdin Plus Prefill
Run a small stdin test:
printf 'failing test output\nline two\n' \
| p --stdin --print-prompt \
"Debug this checkout test failure." \
> artifacts/prompt-builder/stdin-prefill.prompt.md
cat artifacts/prompt-builder/stdin-prefill.prompt.md
Then try with a project command:
pnpm test checkout -- --runInBand 2>&1 \
| p --stdin --print-prompt \
"Debug this checkout test failure. Identify the smallest safe fix and the command to confirm it worked." \
> artifacts/prompt-builder/checkout-test.prompt.md
Fill out:
# Stdin Plus Prefill
- prefill instruction:
- stdin producer:
- separator present? yes/no
- final prompt starts with:
- final prompt includes command output? yes/no
- would you submit this as-is? yes/no
- what to trim or add:
Exercise 5: Named Thread Manifest
Run:
p --print-launch-json \
--name "Billing webhook review" \
"Review duplicate billing webhook processing and propose the smallest safe fix." \
> artifacts/prompt-builder/named-thread.launch.json
jq '.mode, .env, .app_server' artifacts/prompt-builder/named-thread.launch.json
Fill out:
# Named Thread Manifest
- mode:
- `CODEX_THREAD_NAME`:
- app-server create method:
- app-server name method:
- where `thread/name/set` appears:
- why this is different from direct Codex launch:
Exercise 6: Handoff Final Arg
Run:
p --print-launch-json \
--handoff-command /bin/echo \
--handoff-arg wrapper \
--fork-from last \
--compact \
"fix this and keep \$HOME literal" \
> artifacts/prompt-builder/handoff.launch.json
jq '.mode, .handoff, .argv' artifacts/prompt-builder/handoff.launch.json
Fill out:
# Handoff Final Arg
- mode:
- command:
- static handoff args:
- toggled args:
- final argv element:
- does `$HOME` stay literal? yes/no
- why `Command::arg` matters:
- shell eval used? yes/no
Exercise 7: Handoff With Newlines And Quotes
Run:
p --print-launch-json \
--handoff-command /bin/echo \
"Fix the billing webhook.
Keep \"invoice paid\" idempotent.
Do not shell-eval \$HOME or pipes | here." \
> artifacts/prompt-builder/handoff-multiline.launch.json
jq '.argv' artifacts/prompt-builder/handoff-multiline.launch.json
Fill out:
# Multiline Handoff
- number of argv elements:
- final argv element contains newlines? yes/no
- final argv element contains quotes? yes/no
- final argv element contains `$HOME` literally? yes/no
- what would break if a wrapper re-split the final argument:
Exercise 8: Shell Function Handoff
Prove the functions exist when the zsh helper file is sourced:
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'
Then preview a handoff to xfc:
p --submit --dry-run --print-command \
--handoff-command zsh \
--handoff-arg -lc \
--handoff-arg 'source "$HOME/.config/zsh/conf.d/40-ai.zsh" >/dev/null 2>&1; xfc "$@"' \
--handoff-arg xfc \
"Continue from this compact fork and focus only on the failing checkout test."
Fill out:
# Zsh Function Handoff
- sourced file:
- function called:
- why `zsh -lc` is required:
- prompt position:
- dry-run command:
- what would fail with `--handoff-command xfc`:
Exercise 9: Map xfl / xfc To p-f / p-c
Inspect:
rg -n 'xfl|xfc|p-f|p-c|p-cm|_p_handoff_zsh|_codex_prompt_builder_fork' zsh/conf.d/40-ai.zsh
Fill out:
# Section 4 To Section 5 Bridge
| Helper | Direct action or compose-first? | Fork? | Compact? | Uses Prompt Builder? |
| --- | --- | --- | --- | --- |
| `xfl` | | | | |
| `xfc` | | | | |
| `p-f` | | | | |
| `p-c` | | | | |
| `p-cm` | | | | |
- when to use `xfl`:
- when to use `xfc`:
- when to use `p-f`:
- when to use `p-c`:
Exercise 10: File Selector Drill
Open:
p
Type:
Review @
Select a file from the popup. Use a project example such as:
Review @src/checkout/CheckoutForm.tsx for saved payment method regressions.
Fill out:
# @ File Selector
- cwd:
- selected path:
- why this path matters:
- did the inserted path match the real file? yes/no
- why selecting beats typing from memory:
Exercise 11: Skills And Slash Commands Drill
Open:
p
Try the skills popup:
$
Then try a slash command at the prompt start:
/re
Accept /review.
Fill out:
# Composer Vocabulary
- skill mention inserted:
- slash command inserted:
- what triggered skills:
- what triggered slash commands:
- why slash commands belong at the prompt start:
- what `Shift+Enter` does:
- what `Ctrl+C` does with text:
- what `Ctrl+C` does when empty:
Exercise 12: Preview Wrapper Toggles
Run:
p --print-launch-json \
--handoff-command /bin/echo \
--handoff-arg wrapper \
--fork-from last \
--compact \
--launch-option "trace=--trace-app-server" \
--launch-option "debug=--debug" \
"Continue the auth/session review." \
> artifacts/prompt-builder/toggles.launch.json
jq '.handoff.enabled_launch_options, .argv' artifacts/prompt-builder/toggles.launch.json
Fill out:
# Wrapper Toggles
- enabled launch options:
- argv order:
- where static handoff args appear:
- where toggle args appear:
- where prompt appears:
- why options are ignored without `--handoff-command`:
Exercise 13: Override The Codex Binary
Run:
PROMPT_BUILDER_CODEX_BIN=/bin/echo \
p --submit --dry-run --print-command \
"hello override" \
> artifacts/prompt-builder/override-command.txt
cat artifacts/prompt-builder/override-command.txt
Fill out:
# Codex Binary Override
- env var:
- command used:
- output:
- why this is useful for safe demos:
- how to remove the override:
Exercise 14: Debug A Broken Prompt Builder Flow
Pick one failure and write the debug commands.
| Failure | Useful Checks |
|---|---|
p: command not found |
which -a prompt-builder p, symlink check |
| wrong Prompt Builder version | --version, cargo install --path . --locked --force |
| wrong Codex binary | PROMPT_BUILDER_CODEX_BIN, --codex-bin, --print-command |
| named thread missing | --print-launch-json --name ..., check .mode |
xfc: command not found |
zsh -lc 'source ...40-ai.zsh; whence -w xfc' |
| prompt split into args | --print-launch-json, inspect .argv |
| fork/compact ignored | check whether --handoff-command is present |
Fill out:
# Debug Notes
- failure chosen:
- first proof command:
- expected output:
- likely cause:
- smallest fix:
- confirmation command:
Exercise 15: Create A Section 6 Seed Prompt
Use Prompt Builder to save one deliberate prompt for controlled variations.
RUN_ID="checkout-seed"
ROOT="artifacts/variations/$RUN_ID"
mkdir -p "$ROOT/prompts" "$ROOT/launch"
p --print-prompt \
"Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes." \
> "$ROOT/prompts/base.prompt.md"
p --print-launch-json \
"Generate three controlled implementations for saved payment methods in checkout. Keep the database contract and provider API fixed. Vary only the UI integration strategy. Each option must include files to edit, tests to run, risks, and rollback notes." \
> "$ROOT/launch/base.launch.json"
test -s "$ROOT/prompts/base.prompt.md" && echo "base-prompt:OK"
jq '.mode, .prompt' "$ROOT/launch/base.launch.json"
Fill out:
# Section 6 Seed
- prompt path:
- launch JSON path:
- software goal:
- invariant 1:
- invariant 2:
- variable under test:
- required verification:
- ready for controlled variations? yes/no
- what would make this prompt stronger:
Exercise 16: Write A Better Implementation Prompt
Bad prompt:
fix checkout
Rewrite it for Prompt Builder:
Implement saved payment methods in checkout.
Scope:
- inspect:
- change:
- do not change:
Constraints:
- invariant:
- security concern:
- migration concern:
Verification:
- command:
- what passing means:
Return:
- first shippable slice:
- files changed:
- risks:
Then print it:
cat artifacts/prompt-builder/better-checkout.prompt.md \
| p --stdin --print-prompt \
"Use this implementation prompt as the final composed prompt." \
> artifacts/prompt-builder/better-checkout.final.prompt.md
Fill out:
# Better Prompt Review
- original was weak because:
- rewritten prompt names files/subsystems? yes/no
- rewritten prompt names verification? yes/no
- rewritten prompt limits scope? yes/no
- final prompt path: