---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-prompt-builder-worked-example"
title: "Compose the prompt before choosing the agent — worked example"
---

# Compose the prompt before choosing the agent — worked example

Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.

## Part 1 — Compose first, inspect every launch

You

Install prompt-builder and alias it to `p`. Before it launches anything real, show me exactly what it would run.

Agent

Installed from the public repo — `--locked` matters, the lockfile pins patched `crossterm`/`ratatui` revisions — then asked for the launch without running it:

``` text
cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
alias p=prompt-builder
prompt-builder --dry-run --print-command "hello"
```

``` text
pi hello
```

The first beat of every session with this tool: `--dry-run --print-command`. Nothing is hidden behind the TUI — the exact argv is printable before anything runs.

You

I keep a second Codex identity by exporting `CODEX_HOME` by hand every time. Make it a launch target.

Agent

One command; it appends to the targets file and preserves whatever is already there:

``` text
prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'
```

On a fresh machine `~/.prompt-builder/targets.toml` now reads exactly:

``` text
[[targets]]
name = "pi"
kind = "pi"

[[targets]]
name = "codex"
kind = "codex"

[[targets]]
name = "claude"
kind = "claude"

[[targets]]
name = "work-profile"
kind = "codex"

[targets.env]
CODEX_HOME = "~/.codex-work"
```

A target is a named launch profile — binary + env + default args. A different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity; in the TUI it's just Tab to `Target ‹name›`, Space to cycle.

You

And what would that target actually launch?

Agent

``` text
prompt-builder --dry-run --target work-profile --print-command "hello"
```

``` text
CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello
```

Read that line closely: explicit Codex targets launch with a permission-bypass flag. That is the reason dry-run comes first.

The safety beat, verbatim from the session: only point `p` at directories where you accept the selected agent modifying files and running commands. In real output the env path expands to your full home directory.

You

I script against my tools. Give me the launch as data, not a string.

Agent

``` text
prompt-builder --dry-run --print-launch-json "hello"
```

``` text
{
  "schema_version": 1,
  "mode": "pi",
  "command": "pi",
  "argv": ["pi", "hello"],
  "env": {},
  "prompt": "hello",
  "pi": {"cwd": ".", "session_name": null}
}
```

A stable `schema_version: 1` manifest — the same launch the TUI would perform, consumable by scripts. This is what "the composer is inspectable" means in practice.

## Part 2 — Handoff: your shell functions become launch targets

You

Composer-to-agent is fine. But my daily move is a shell function — fork my latest Codex session and resume it. Can `p` hand the composed prompt to *any* command?

Agent

That's handoff mode. Proof with `/bin/echo` substituted in as the "launcher":

``` text
prompt-builder --submit --dry-run --handoff-command /bin/echo "hello from handoff"
```

``` text
/bin/echo 'hello from handoff'
```

The substitution proof: the composed prompt appears verbatim as the final argv element — passed as data (`Command::arg`), never through shell eval. Run this before wiring in any real command.

You

My fork helper takes flags — `--fork-from`, `--compact`. Do those survive?

Agent

``` text
prompt-builder --submit --dry-run --handoff-command /bin/echo --fork-from last --compact "continue"
```

``` text
/bin/echo --fork-from last --compact continue
```

They pass through — and in the interactive TUI they render as checkbox toggles.

The wrapper declares its own UI: `--fork-from` / `--compact` / `--launch-option` become toggles in the composer. Your function's flags are now form controls.

You

Now wrap it for real: bake my debugger persona into one function, and make another that composes a prompt, forks my latest Codex session, and resumes with it.

Agent

Both patterns landed in one file — pattern 1 bakes instructions into the composer; pattern 2 makes your shell function the launcher:

``` text
# Wrapping "p" (prompt-builder) with custom tools — the two patterns.
# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh
# and the p-f/p-c family in your zsh config.

# ── Pattern 1: bake instructions into the composer ─────────────────
# The composer opens normally, but the launch carries your persona/context.
fixit() {
  prompt-builder \
    --target codex \
    -C "$PWD" \
    --developer-instructions "You're an expert debugger who always starts with the \$fusion skill. The user will pass a terse bug; investigate the behavior and fix it."
}

# ── Pattern 2: handoff mode — your shell function IS the launcher ──
# prompt-builder composes, then calls your command with the prompt as
# the final argv element (Command::arg, no shell eval).
_p_handoff_zsh() {
  local fn="${1:?Usage: _p_handoff_zsh <function> [p-args...]}"
  shift
  p \
    --handoff-command zsh \
    --handoff-arg -lc \
    --handoff-arg "source \"\$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; ${fn} \"\$@\"" \
    --handoff-arg "$fn" \
    "$@"
}

# Compose a prompt, then fork the latest Codex session and resume with it.
p-f() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" "$@"
}

# Same, but compact the forked session before resuming.
p-c() {
  local source="${CODEX_FORK_SESSION_ID:-last}"
  _p_handoff_zsh _codex_prompt_builder_fork --fork-from "$source" --compact "$@"
}

# ── The mdflow lead-in ──────────────────────────────────────────────
# Every wrapper above is: instructions + context + a launch decision.
# Declare that in a markdown file instead of a shell function and you
# get an mdflow flow — reviewable, diffable, evaluable:
#
#   flows/fixit.codex.md
#   ---
#   engine: codex
#   ---
#   You're an expert debugger. Bug report: {{ _1 }}
#
# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter
# for the fuzzy picker; flow `_inputs` render as form fields.
```

File landed. `fixit` runs daily; `p-f` is compose → fork → resume in one keystroke family.

Read the tail of that file again: every wrapper is instructions + context + a launch decision. Declare that in a markdown file instead of a shell function and you've invented mdflow — which is exactly where section 05 picks up. (`p-f` calls a private fork helper — supply your own; the pattern is the point.)

## Original references

- [Compose the prompt before choosing the agent — worked example](https://shiny-bloom-f8hv.here.now/replay.html)
