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

# Compose the prompt before choosing the agent

A cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.

## Related working material

- [Compose the prompt before choosing the agent — prompts and exercises](/topics/factory-prompt-builder-practice/)
- [Compose the prompt before choosing the agent — questions and tradeoffs](/topics/factory-prompt-builder-questions/)
- [Compose the prompt before choosing the agent — worked example](/topics/factory-prompt-builder-worked-example/)

## TL;DR

- `prompt-builder` (alias `p`) is a terminal composer that gives your prompt its own tool: `$` skill lookup, `@` file search, and `Ctrl+R` cross-agent history in front of Pi, Codex, and Claude Code.
- You walk away with a compose-first loop: one composer, your own launch targets, and shell functions promoted to launch targets via handoff mode.
- The one move: compose in `p`, Tab to `Target ‹name›`, cycle agents with Space — and inspect any launch first with `--dry-run --print-command`.

 Have your agent set this up — paste this into it:

``` text
Fetch https://shiny-bloom-f8hv.here.now/agent.md?raw and follow it to set this up in my current project. Run the success check at the end and show me the result.
```

## One composer in front of every agent

Count where your prompts get written: for most agent-CLI users, all of them live inside one agent's interactive loop. The prompt — the thing that carries your intent — has no home of its own; switch agents and you abandon your history, paste handling, and muscle memory.

prompt-builder is a small Ratatui composer whose only job is composing: skill lookup, file search, slash commands, paste handling, and history that follows *you*, not the agent — it reads Codex's own `~/.codex/history.jsonl` alongside its private file, so prompts from either tool come back with `Ctrl+R`. The agent is just a selector at the bottom of the screen. Targets are named launch profiles — binary, env vars, model, default args — stored in `~/.prompt-builder/targets.toml`; a different `CODEX_HOME` or `CLAUDE_CONFIG_DIR` is a different identity.

``` text
$ prompt-builder target list
pi              pi      bin=pi
codex           codex   bin=codex
claude          claude  bin=claude
work-profile    codex   bin=codex   CODEX_HOME=~/.codex-work
second-account  claude  bin=claude  CLAUDE_CONFIG_DIR=~/.claude-second
```

The test for whether this matters: the next time you re-type a prompt into a second agent because the first one stalled, you've found the cost this tool removes.

## Every launch is inspectable before it runs

A tool that launches agents for you earns trust only if you can see exactly what it would run. Every launch path has a dry-run twin: `--print-command` shows the exact argv; `--print-launch-json` emits a stable `schema_version: 1` manifest for scripts.

``` text
$ prompt-builder --dry-run --print-command "hello"
pi hello

$ prompt-builder --dry-run --print-launch-json "hello"
{
  "schema_version": 1,
  "mode": "pi",
  "command": "pi",
  "argv": ["pi", "hello"],
  "env": {},
  "prompt": "hello",
  "pi": {"cwd": ".", "session_name": null}
}
```

Codex and Claude targets launch with permission-bypass flags — only point them at directories where you accept the agent modifying files and running commands (details in the appendix). Before trusting any target you add, run it once with `--dry-run --print-command` and read the argv aloud.

## Handoff mode turns shell functions into launch targets

The interesting move is handoff mode: `--handoff-command` with repeatable `--handoff-arg` makes the composer call *any* command with the submitted prompt as the final argv element — passed as data, never through shell eval.

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

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

Those `--fork-from`/`--compact` flags render as checkbox toggles in the TUI — the wrapper declares its own UI. Two patterns run daily in the author's shell: `fixit` bakes a debugger persona into the composer, and `p-f` composes a prompt, then forks the latest Codex session and resumes it with that prompt. Here is the workshop's copy of both, complete — this page is the file's source (the repo's `examples/` ships only `fixit.zsh`; lift `p-wrap.zsh` from the block below):

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

To adopt the pattern, write one wrapper for a move you repeat and prove it with `--submit --dry-run --handoff-command /bin/echo` substituted in: your prompt must appear verbatim as the final echoed argument. When it does, swap the real command back in. (`p-f` calls the author's private fork helper — supply your own; see the appendix.)

## A wrapper is a file format waiting to happen

Look at what every wrapper above actually is: instructions, plus context, plus a launch decision. Why is that a shell function and not a file? Shell functions hide in dotfiles; files can be diffed, reviewed, shared, and gated with evals. That's mdflow: each repeatable agent job as a markdown file, run on the CLI engine you already use. The `fixit` wrapper restated as a flow looks like this:

``` text
--- flows/fixit.codex.md ---
engine: codex
---
You're an expert debugger. Bug report: {{ _1 }}
```

The same job also ships in a third form: an [agent skill](https://www.skills.sh/). The full progression is `fixit.zsh` (shell wrapper) → `flows/fixit.codex.md` (mdflow flow) → `fixit` (SKILL.md) — pick whichever your stack runs on. The skill twin is hosted on this site; install it by staging anywhere *except* a dir named `skills/` (the skills CLI claims that name as its own symlink target and you'd install an empty skill):

``` text
mkdir -p skill-src/fixit
curl -fsSL "https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw" -o skill-src/fixit/SKILL.md
npx skills add ./skill-src --skill fixit -y
```

The bridge already exists in the composer: with the mdflow CLI on `PATH`, a `Flow ‹name›` selector appears beside the target selector, Enter opens a fuzzy picker, and a flow's inputs render as form fields. A ` ignores prompt` badge warns when a flow never references `{{ _1 }}`/`{{ _prompt }}` — mdflow would silently drop your prompt. The promotion rule: when a wrapper survives unchanged for a few weeks, move it into a flow file. If it keeps changing, it isn't ready — keep it in the shell.

## Appendix

### Limits & caveats

- **Permission bypass:** explicit Codex targets launch with `--dangerously-bypass-approvals-and-sandbox`; Claude targets launch with `claude --dangerously-skip-permissions -- <prompt>`. Pi targets add no bypass flag and rely on Pi's own trust settings. Only use these launchers in directories where you accept the selected agent modifying files and running commands.
- The flow file shown in the last story section is a **constructed illustration**, not a file shipped by either project — that's why it carries the "example — don't paste" badge. mdflow's own README shows the same shape (`review.md`, `review.claude.md`, `git diff | explain.md`).
- The `fixit` persona references `$fusion`, the author's personal skill. Swap in a skill you actually have, or drop that clause.
- `p-f`/`p-c` call `_codex_prompt_builder_fork`, a private helper in the author's zsh config. The wrappers are printed as evidence of the pattern; to use them, point `_p_handoff_zsh` at your own function.
- Success-check outputs show `~/.codex-work` for readability; real output expands env paths to your full home directory. Target names `work-profile` and `second-account` are genericized stand-ins for the author's personal profiles.
- All output was captured the recorded snapshot from prompt-builder v0.1.0; TUI details may drift in later versions. Claude targets currently ignore conversation names and Codex-only options with a warning; Claude fork/resume orchestration is future work — that's exactly what handoff wrappers cover today.
- Claims about mdflow are limited to its README introduction. The "wrappers are proto-flows" promotion rule is the author's editorial inference, not something either README states.
- The default target is Pi; real submissions fail without the Pi CLI on `PATH`, though every `--dry-run`/print flag works with no agent CLIs installed.

## Operating practice

### Compose only the evidence the task needs

#### What to notice

Build a prompt packet from text, files, images, and fresh state without smuggling in an entire stale session.

#### Try this

List the **minimum sources** needed to decide, act, and verify; remove everything that cannot change one of those steps.

> “How can I consolidate that into something that's gonna manage it for me?”

John Lindquist · [02:37:56](https://proud-anchor-53zn.here.now/watch.html?t=9476#recording-player)

#### Concept

Input is a task plus evidence. Output is a result with a named check. The tradeoff is simple: extra context can add capability, but it also hides contradictions and consumes review attention.

#### Reflection

A large packet is not automatically a complete packet. Prefer relevant, current, and inspectable evidence.

**Recording evidence:** listen at 02:34:33.

> “I usually spend the most amount of time preparing that initial prompt.”

John Lindquist · [02:39:00](https://proud-anchor-53zn.here.now/watch.html?t=9540#recording-player)

[Open Prompt Builder](https://shiny-bloom-f8hv.here.now/)

#### Links shared for this topic

- [Prompt Builder source](https://github.com/johnlindquist/prompt-builder) — The repository for composing text, files, and other evidence into prompts.

[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=9273#q2-prompt-composer)

## Original references

- [Compose the prompt before choosing the agent](https://shiny-bloom-f8hv.here.now/)
- [Companion lesson](https://proud-anchor-53zn.here.now/learn.html#q2-prompt-composer)
