{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-prompt-builder-worked-example",
  "slug": "prompt-builder-worked-example",
  "title": "Compose the prompt before choosing the agent — worked example",
  "summary": "Detailed worked example with concrete prompts, observable outcomes, and the limits of the example.",
  "category": "Context",
  "tags": [
    "prompt-builder",
    "examples"
  ],
  "sources": [
    {
      "label": "Compose the prompt before choosing the agent — worked example",
      "url": "https://shiny-bloom-f8hv.here.now/replay.html"
    }
  ],
  "sourceUnits": [
    "04-prompt-builder/replay.html#Part 1 — Compose first, inspect every launch",
    "04-prompt-builder/replay.html#Part 2 — Handoff: your shell functions become launch targets"
  ],
  "collection": "factory",
  "categoryId": "context",
  "wordCount": 974,
  "url": "/topics/factory-prompt-builder-worked-example/",
  "markdownUrl": "/markdown/factory-prompt-builder-worked-example.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-prompt-builder-worked-example.json",
  "headings": [
    {
      "id": "part-1-compose-first-inspect-every-launch",
      "text": "Part 1 — Compose first, inspect every launch",
      "level": 2
    },
    {
      "id": "part-2-handoff-your-shell-functions-become-launch-targets",
      "text": "Part 2 — Handoff: your shell functions become launch targets",
      "level": 2
    }
  ],
  "markdown": "# Compose the prompt before choosing the agent — worked example\n\nDetailed worked example with concrete prompts, observable outcomes, and the limits of the example.\n\n## Part 1 — Compose first, inspect every launch\n\nYou\n\nInstall prompt-builder and alias it to `p`. Before it launches anything real, show me exactly what it would run.\n\nAgent\n\nInstalled from the public repo — `--locked` matters, the lockfile pins patched `crossterm`/`ratatui` revisions — then asked for the launch without running it:\n\n``` text\ncargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\nalias p=prompt-builder\nprompt-builder --dry-run --print-command \"hello\"\n```\n\n``` text\npi hello\n```\n\nThe 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.\n\nYou\n\nI keep a second Codex identity by exporting `CODEX_HOME` by hand every time. Make it a launch target.\n\nAgent\n\nOne command; it appends to the targets file and preserves whatever is already there:\n\n``` text\nprompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'\n```\n\nOn a fresh machine `~/.prompt-builder/targets.toml` now reads exactly:\n\n``` text\n[[targets]]\nname = \"pi\"\nkind = \"pi\"\n\n[[targets]]\nname = \"codex\"\nkind = \"codex\"\n\n[[targets]]\nname = \"claude\"\nkind = \"claude\"\n\n[[targets]]\nname = \"work-profile\"\nkind = \"codex\"\n\n[targets.env]\nCODEX_HOME = \"~/.codex-work\"\n```\n\nA 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.\n\nYou\n\nAnd what would that target actually launch?\n\nAgent\n\n``` text\nprompt-builder --dry-run --target work-profile --print-command \"hello\"\n```\n\n``` text\nCODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello\n```\n\nRead that line closely: explicit Codex targets launch with a permission-bypass flag. That is the reason dry-run comes first.\n\nThe 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.\n\nYou\n\nI script against my tools. Give me the launch as data, not a string.\n\nAgent\n\n``` text\nprompt-builder --dry-run --print-launch-json \"hello\"\n```\n\n``` text\n{\n  \"schema_version\": 1,\n  \"mode\": \"pi\",\n  \"command\": \"pi\",\n  \"argv\": [\"pi\", \"hello\"],\n  \"env\": {},\n  \"prompt\": \"hello\",\n  \"pi\": {\"cwd\": \".\", \"session_name\": null}\n}\n```\n\nA 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.\n\n## Part 2 — Handoff: your shell functions become launch targets\n\nYou\n\nComposer-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?\n\nAgent\n\nThat's handoff mode. Proof with `/bin/echo` substituted in as the \"launcher\":\n\n``` text\nprompt-builder --submit --dry-run --handoff-command /bin/echo \"hello from handoff\"\n```\n\n``` text\n/bin/echo 'hello from handoff'\n```\n\nThe 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.\n\nYou\n\nMy fork helper takes flags — `--fork-from`, `--compact`. Do those survive?\n\nAgent\n\n``` text\nprompt-builder --submit --dry-run --handoff-command /bin/echo --fork-from last --compact \"continue\"\n```\n\n``` text\n/bin/echo --fork-from last --compact continue\n```\n\nThey pass through — and in the interactive TUI they render as checkbox toggles.\n\nThe wrapper declares its own UI: `--fork-from` / `--compact` / `--launch-option` become toggles in the composer. Your function's flags are now form controls.\n\nYou\n\nNow 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.\n\nAgent\n\nBoth patterns landed in one file — pattern 1 bakes instructions into the composer; pattern 2 makes your shell function the launcher:\n\n``` text\n# Wrapping \"p\" (prompt-builder) with custom tools — the two patterns.\n# Source of truth for the real versions: ~/dev/prompt-builder/examples/fixit.zsh\n# and the p-f/p-c family in your zsh config.\n\n# ── Pattern 1: bake instructions into the composer ─────────────────\n# The composer opens normally, but the launch carries your persona/context.\nfixit() {\n  prompt-builder \\\n    --target codex \\\n    -C \"$PWD\" \\\n    --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.\"\n}\n\n# ── Pattern 2: handoff mode — your shell function IS the launcher ──\n# prompt-builder composes, then calls your command with the prompt as\n# the final argv element (Command::arg, no shell eval).\n_p_handoff_zsh() {\n  local fn=\"${1:?Usage: _p_handoff_zsh <function> [p-args...]}\"\n  shift\n  p \\\n    --handoff-command zsh \\\n    --handoff-arg -lc \\\n    --handoff-arg \"source \\\"\\$HOME/.config/zsh/conf.d/40-ai.zsh\\\" >/dev/null 2>&1; ${fn} \\\"\\$@\\\"\" \\\n    --handoff-arg \"$fn\" \\\n    \"$@\"\n}\n\n# Compose a prompt, then fork the latest Codex session and resume with it.\np-f() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" \"$@\"\n}\n\n# Same, but compact the forked session before resuming.\np-c() {\n  local source=\"${CODEX_FORK_SESSION_ID:-last}\"\n  _p_handoff_zsh _codex_prompt_builder_fork --fork-from \"$source\" --compact \"$@\"\n}\n\n# ── The mdflow lead-in ──────────────────────────────────────────────\n# Every wrapper above is: instructions + context + a launch decision.\n# Declare that in a markdown file instead of a shell function and you\n# get an mdflow flow — reviewable, diffable, evaluable:\n#\n#   flows/fixit.codex.md\n#   ---\n#   engine: codex\n#   ---\n#   You're an expert debugger. Bug report: {{ _1 }}\n#\n# prompt-builder already discovers flows: Tab to `Flow ‹name›`, Enter\n# for the fuzzy picker; flow `_inputs` render as form fields.\n```\n\nFile landed. `fixit` runs daily; `p-f` is compose → fork → resume in one keystroke family.\n\nRead 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.)"
}
