{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-prompt-builder",
  "slug": "prompt-builder",
  "title": "Compose the prompt before choosing the agent",
  "summary": "A cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.",
  "category": "Context",
  "tags": [
    "prompt",
    "factory"
  ],
  "sources": [
    {
      "label": "Compose the prompt before choosing the agent",
      "url": "https://shiny-bloom-f8hv.here.now/"
    },
    {
      "label": "Companion lesson",
      "url": "https://proud-anchor-53zn.here.now/learn.html#q2-prompt-composer"
    }
  ],
  "sourceUnits": [
    "04-prompt-builder/index.html#TL;DR",
    "04-prompt-builder/index.html#One composer in front of every agent",
    "04-prompt-builder/index.html#Appendix",
    "04-prompt-builder/index.html#Every launch is inspectable before it runs",
    "04-prompt-builder/index.html#Handoff mode turns shell functions into launch targets",
    "04-prompt-builder/index.html#A wrapper is a file format waiting to happen",
    "learn.html#q2-prompt-composer"
  ],
  "collection": "factory",
  "categoryId": "context",
  "wordCount": 1704,
  "url": "/topics/factory-prompt-builder/",
  "markdownUrl": "/markdown/factory-prompt-builder.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-prompt-builder.json",
  "headings": [
    {
      "id": "related-working-material",
      "text": "Related working material",
      "level": 2
    },
    {
      "id": "tl-dr",
      "text": "TL;DR",
      "level": 2
    },
    {
      "id": "one-composer-in-front-of-every-agent",
      "text": "One composer in front of every agent",
      "level": 2
    },
    {
      "id": "every-launch-is-inspectable-before-it-runs",
      "text": "Every launch is inspectable before it runs",
      "level": 2
    },
    {
      "id": "handoff-mode-turns-shell-functions-into-launch-targets",
      "text": "Handoff mode turns shell functions into launch targets",
      "level": 2
    },
    {
      "id": "a-wrapper-is-a-file-format-waiting-to-happen",
      "text": "A wrapper is a file format waiting to happen",
      "level": 2
    },
    {
      "id": "appendix",
      "text": "Appendix",
      "level": 2
    },
    {
      "id": "limits-caveats",
      "text": "Limits & caveats",
      "level": 3
    },
    {
      "id": "operating-practice",
      "text": "Operating practice",
      "level": 2
    },
    {
      "id": "compose-only-the-evidence-the-task-needs",
      "text": "Compose only the evidence the task needs",
      "level": 3
    },
    {
      "id": "what-to-notice",
      "text": "What to notice",
      "level": 4
    },
    {
      "id": "try-this",
      "text": "Try this",
      "level": 4
    },
    {
      "id": "concept",
      "text": "Concept",
      "level": 4
    },
    {
      "id": "reflection",
      "text": "Reflection",
      "level": 4
    },
    {
      "id": "links-shared-for-this-topic",
      "text": "Links shared for this topic",
      "level": 4
    }
  ],
  "markdown": "# Compose the prompt before choosing the agent\n\nA cross-agent composer, named launch profiles, exact argv previews, and safe handoff patterns.\n\n## Related working material\n\n- [Compose the prompt before choosing the agent — prompts and exercises](/topics/factory-prompt-builder-practice/)\n- [Compose the prompt before choosing the agent — questions and tradeoffs](/topics/factory-prompt-builder-questions/)\n- [Compose the prompt before choosing the agent — worked example](/topics/factory-prompt-builder-worked-example/)\n\n## TL;DR\n\n- `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.\n- You walk away with a compose-first loop: one composer, your own launch targets, and shell functions promoted to launch targets via handoff mode.\n- The one move: compose in `p`, Tab to `Target ‹name›`, cycle agents with Space — and inspect any launch first with `--dry-run --print-command`.\n\n Have your agent set this up — paste this into it:\n\n``` text\nFetch 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.\n```\n\n## One composer in front of every agent\n\nCount 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.\n\nprompt-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.\n\n``` text\n$ prompt-builder target list\npi              pi      bin=pi\ncodex           codex   bin=codex\nclaude          claude  bin=claude\nwork-profile    codex   bin=codex   CODEX_HOME=~/.codex-work\nsecond-account  claude  bin=claude  CLAUDE_CONFIG_DIR=~/.claude-second\n```\n\nThe 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.\n\n## Every launch is inspectable before it runs\n\nA 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.\n\n``` text\n$ prompt-builder --dry-run --print-command \"hello\"\npi hello\n\n$ prompt-builder --dry-run --print-launch-json \"hello\"\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\nCodex 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.\n\n## Handoff mode turns shell functions into launch targets\n\nThe 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.\n\n``` text\n$ prompt-builder --submit --dry-run --handoff-command /bin/echo \"hello from handoff\"\n/bin/echo 'hello from handoff'\n\n$ prompt-builder --submit --dry-run --handoff-command /bin/echo \\\n    --fork-from last --compact \"continue\"\n/bin/echo --fork-from last --compact continue\n```\n\nThose `--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):\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\nTo 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.)\n\n## A wrapper is a file format waiting to happen\n\nLook 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:\n\n``` text\n--- flows/fixit.codex.md ---\nengine: codex\n---\nYou're an expert debugger. Bug report: {{ _1 }}\n```\n\nThe 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):\n\n``` text\nmkdir -p skill-src/fixit\ncurl -fsSL \"https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw\" -o skill-src/fixit/SKILL.md\nnpx skills add ./skill-src --skill fixit -y\n```\n\nThe 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.\n\n## Appendix\n\n### Limits & caveats\n\n- **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.\n- 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`).\n- The `fixit` persona references `$fusion`, the author's personal skill. Swap in a skill you actually have, or drop that clause.\n- `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.\n- 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.\n- 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.\n- 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.\n- 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.\n\n## Operating practice\n\n### Compose only the evidence the task needs\n\n#### What to notice\n\nBuild a prompt packet from text, files, images, and fresh state without smuggling in an entire stale session.\n\n#### Try this\n\nList the **minimum sources** needed to decide, act, and verify; remove everything that cannot change one of those steps.\n\n> “How can I consolidate that into something that's gonna manage it for me?”\n\nJohn Lindquist · [02:37:56](https://proud-anchor-53zn.here.now/watch.html?t=9476#recording-player)\n\n#### Concept\n\nInput 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.\n\n#### Reflection\n\nA large packet is not automatically a complete packet. Prefer relevant, current, and inspectable evidence.\n\n**Recording evidence:** listen at 02:34:33.\n\n> “I usually spend the most amount of time preparing that initial prompt.”\n\nJohn Lindquist · [02:39:00](https://proud-anchor-53zn.here.now/watch.html?t=9540#recording-player)\n\n[Open Prompt Builder](https://shiny-bloom-f8hv.here.now/)\n\n#### Links shared for this topic\n\n- [Prompt Builder source](https://github.com/johnlindquist/prompt-builder) — The repository for composing text, files, and other evidence into prompts.\n\n[Watch chapter](https://proud-anchor-53zn.here.now/watch.html?t=9273#q2-prompt-composer)"
}
