{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-prompt-composition-team-guide",
  "slug": "prompt-composition-team-guide",
  "title": "Prompt Builder composition and handoff: team walkthrough",
  "summary": "Prompt composition and launch inspection through prompt text, shell commands, and JSON; named app-server threads; final-argv handoff; interactive composer controls; zsh helper bridges; and installation, binary-selection, and quoting diagnostics.",
  "category": "Team practice",
  "tags": [
    "prompt-builder",
    "prompts",
    "preflight",
    "team-guide"
  ],
  "sources": [
    {
      "label": "Portable Codex workflow resources",
      "url": "https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle"
    }
  ],
  "sourceUnits": [
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter Goal",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options/10-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options/20-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Timing Options/35-Minute Version",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Things To Say",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/1. Prove The Binary",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/2. Print A Prompt",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/3. Preview A Command",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/4. Preview A Named Thread",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/5. Preview Handoff",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Live Demo Script/6. Prove Zsh Helper Bridge",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Boundaries",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Cut Path",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Debug Paths To Mention",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter Boundaries",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter Checklist",
    "downloads/codex-power-user-workshop-2026-06-27.bundle!/instructor-notes/05-prompt-builder.md#Instructor Notes: 05. Prompt Builder/Presenter References",
    "downloads/codex-power-user-workshop-2026-06-27.bundle"
  ],
  "collection": "codex",
  "categoryId": "team-practice",
  "wordCount": 1205,
  "url": "/topics/codex-prompt-composition-team-guide/",
  "markdownUrl": "/markdown/codex-prompt-composition-team-guide.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-prompt-composition-team-guide.json",
  "headings": [
    {
      "id": "team-learning-goal",
      "text": "Team Learning Goal",
      "level": 2
    },
    {
      "id": "walkthrough-depth",
      "text": "Walkthrough Depth",
      "level": 2
    },
    {
      "id": "essential-walkthrough",
      "text": "Essential Walkthrough",
      "level": 3
    },
    {
      "id": "expanded-walkthrough",
      "text": "Expanded Walkthrough",
      "level": 3
    },
    {
      "id": "deep-dive-walkthrough",
      "text": "Deep-Dive Walkthrough",
      "level": 3
    },
    {
      "id": "talking-points",
      "text": "Talking Points",
      "level": 2
    },
    {
      "id": "live-demo-script",
      "text": "Live Demo Script",
      "level": 2
    },
    {
      "id": "1-prove-the-binary",
      "text": "1. Prove The Binary",
      "level": 3
    },
    {
      "id": "2-print-a-prompt",
      "text": "2. Print A Prompt",
      "level": 3
    },
    {
      "id": "3-preview-a-command",
      "text": "3. Preview A Command",
      "level": 3
    },
    {
      "id": "4-preview-a-named-thread",
      "text": "4. Preview A Named Thread",
      "level": 3
    },
    {
      "id": "5-preview-handoff",
      "text": "5. Preview Handoff",
      "level": 3
    },
    {
      "id": "6-prove-zsh-helper-bridge",
      "text": "6. Prove Zsh Helper Bridge",
      "level": 3
    },
    {
      "id": "boundaries",
      "text": "Boundaries",
      "level": 2
    },
    {
      "id": "minimal-useful-path",
      "text": "Minimal Useful Path",
      "level": 2
    },
    {
      "id": "debug-paths-to-mention",
      "text": "Debug Paths To Mention",
      "level": 2
    },
    {
      "id": "presenter-boundaries",
      "text": "Presenter Boundaries",
      "level": 2
    },
    {
      "id": "team-checklist",
      "text": "Team Checklist",
      "level": 2
    },
    {
      "id": "further-references",
      "text": "Further References",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Prompt Builder composition and handoff: team walkthrough\n\n## Team Learning Goal\n\nTeach Prompt Builder as the composition boundary between routed context and agent execution.\n\nBy the end of this section, the room should understand:\n\n- why `p` exists\n- how it fits after Section 4 routing\n- how to inspect prompt text, command shape, and launch JSON\n- why named launches use app-server thread creation and `thread/name/set`\n- why handoff mode passes the prompt as a safe final argv element\n- when to choose `xfl` / `xfc` versus `p-f` / `p-c`\n- how Section 6 uses one deliberate prompt as a variation seed\n\nKeep this section practical. It is not a Rust code tour.\n\n## Walkthrough Depth\n\n### Essential Walkthrough\n\n1. State: Prompt Builder is the preflight before an agent launch.\n2. Prove install: `which -a prompt-builder p`, versions.\n3. Show `p --print-prompt \"hello\"`.\n4. Show `p --dry-run --print-command \"hello\"`.\n5. Show named launch JSON with `--name`.\n6. Show handoff JSON with `/bin/echo`, `--fork-from`, and `--compact`.\n7. Bridge to `p-f` and `p-c`.\n\nPreserve these commands:\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\np --print-prompt \"Review the checkout flow.\"\np --dry-run --print-command \\\n  \"Debug the billing webhook duplicate-processing bug.\"\np --print-launch-json \\\n  --name \"Auth review\" \\\n  \"Review auth/session architecture.\" \\\n  | jq '.mode, .env, .app_server'\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --fork-from last \\\n  --compact \\\n  \"continue from here\" \\\n  | jq '.mode, .argv'\n```\n\n### Expanded Walkthrough\n\nAdd:\n\n- interactive `p`\n- Name field\n- Tab movement through Name, Prompt, and options\n- `@` file selector\n- `$` skills lookup\n- `/` slash command popup\n- `Shift+Enter`\n- bracketed paste behavior\n- `Ctrl+C` clear-before-exit\n\n### Deep-Dive Walkthrough\n\nAdd:\n\n- `--stdin` plus prefilled text\n- app-server named thread explanation\n- `CODEX_THREAD_NAME`\n- `PROMPT_BUILDER_CODEX_BIN`\n- shell-function handoff through `zsh -lc`\n- debug paths for missing `p`, wrong binary, missing zsh functions, and quoting issues\n- exercise kickoff\n\n## Talking Points\n\nOpening:\n\n> We already solved routing. Now we solve what we are actually sending.\n\nCore sentence:\n\n> Prompt Builder is the checkpoint between \"I have a thought\" and \"I am launching an agent with authority.\"\n\nOn inspection modes:\n\n> `--print-prompt` saves what you said. `--print-command` shows what a human would run. `--print-launch-json` gives scripts the raw shape without parsing shell quotes.\n\nOn `--name`:\n\n> Naming is not a prompt trick. Prompt Builder creates a thread, calls `thread/name/set`, and then resumes that thread with the prompt.\n\nOn handoff:\n\n> Handoff is argv construction, not shell interpolation. The prompt is passed with `Command::arg` as the final argv element.\n\nOn `p-f` and `p-c`:\n\n> `xfl` and `xfc` act now. `p-f` and `p-c` let you compose first.\n\nOn Section 6:\n\n> One careful prompt becomes the seed for controlled variations. A sloppy prompt produces sloppy variations faster.\n\n## Live Demo Script\n\n### 1. Prove The Binary\n\n```bash\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nPresenter note: do not dwell on install paths. The important proof is that both commands resolve and match.\n\n### 2. Print A Prompt\n\n```bash\np --print-prompt \\\n  \"Review the checkout flow for saved payment method regressions.\"\n```\n\nPresenter note: this is the cleanest Section 6 bridge.\n\n### 3. Preview A Command\n\n```bash\np --dry-run --print-command \\\n  \"Debug the failing checkout test and identify the smallest safe fix.\"\n```\n\nPresenter note: point at `-C .` and the final prompt argument.\n\n### 4. Preview A Named Thread\n\n```bash\np --print-launch-json \\\n  --name \"Checkout saved payments\" \\\n  \"Plan the first shippable slice.\" \\\n  | jq '.mode, .env, .app_server'\n```\n\nCall out:\n\n```text\napp-server-named-thread\nCODEX_THREAD_NAME\nthread/name/set\n```\n\n### 5. Preview Handoff\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  --handoff-arg wrapper \\\n  --fork-from last \\\n  --compact \\\n  \"continue from here\" \\\n  | jq '.mode, .argv'\n```\n\nCall out:\n\n```text\nwrapper args first\ntoggle args next\nprompt last\n```\n\n### 6. Prove Zsh Helper Bridge\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w p-f p-c p-cm xfl xfc'\n```\n\nPresenter note: shell functions are not binaries. This is why `p-f` and `p-c` hand off through `zsh -lc`.\n\n## Boundaries\n\n| Prior Section | What It Solved | Prompt Builder Adds |\n| --- | --- | --- |\n| Section 1 | package the right project context | compose the implementation request |\n| Section 2 | make tools visible to Codex | prove `prompt-builder`, `p`, and Codex resolve |\n| Section 3 | classify aliases/functions/executables | hand off safely to zsh functions |\n| Section 4 | route pane/session/fork/export | compose before fork or compact |\n\nBridge line from Section 4:\n\n```text\nSection 4 gets us to the right session. Section 5 makes sure the next prompt is worth sending.\n```\n\nBridge line to Section 6:\n\n```text\nSection 5 ends with a deliberate prompt. Section 6 varies that prompt under control instead of improvising unrelated asks.\n```\n\n## Minimal Useful Path\n\nIf 5 minutes behind, cut:\n\n- `PROMPT_BUILDER_DEBUG_KEYS`\n- detailed slash command list\n- custom `--launch-option`\n- Rust module references\n\nPreserve:\n\n```bash\nwhich -a prompt-builder p\np --print-prompt \"hello\"\np --dry-run --print-command \"hello\"\np --print-launch-json --name \"Demo\" \"hello\" | jq '.mode, .env'\np --print-launch-json --handoff-command /bin/echo --fork-from last --compact \"continue\" | jq '.mode, .argv'\n```\n\nIf 10 minutes behind, skip the interactive composer and say:\n\n```text\nThe TUI matters for real use, but the inspection modes teach the contract fastest.\n```\n\nIf 20 minutes behind, run only:\n\n```bash\nwhich -a prompt-builder p\np --print-launch-json --name \"Demo\" \"hello\" | jq '.mode, .env, .app_server'\np --print-launch-json --handoff-command /bin/echo --fork-from last --compact \"continue\" | jq '.mode, .argv'\n```\n\nClosing line if rushed:\n\n```text\nCompose first, prove the launch shape, then submit.\n```\n\n## Debug Paths To Mention\n\nMissing `p`:\n\n```bash\nwhich -a prompt-builder p\nln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\np --version\n```\n\nWrong build:\n\n```bash\ncargo install --path . --locked --force\nwhich -a prompt-builder p\nprompt-builder --version\np --version\n```\n\nWrong Codex binary:\n\n```bash\nPROMPT_BUILDER_CODEX_BIN=/bin/echo \\\n  p --submit --dry-run --print-command \\\n  \"hello override\"\n```\n\nMissing zsh function:\n\n```zsh\nzsh -lc 'source \"$HOME/.config/zsh/conf.d/40-ai.zsh\" >/dev/null 2>&1; whence -w xfc p-f p-c'\n```\n\nQuoting / final argv:\n\n```bash\np --print-launch-json \\\n  --handoff-command /bin/echo \\\n  \"fix this\nand keep \\$HOME literal\" \\\n  | jq '.argv'\n```\n\n## Presenter Boundaries\n\nDo not over-explain:\n\n- Ratatui internals\n- every slash command\n- full app-server protocol\n- every function in `40-ai.zsh`\n- Rust module architecture beyond what explains behavior\n- every possible Codex flag\n\nEmphasize:\n\n- exact prompt text\n- exact argv\n- exact launch mode\n- named thread flow\n- safe handoff\n- `p-f` / `p-c` as compose-before-action helpers\n- Section 6 seed prompt\n\n## Team Checklist\n\nBefore considering this section ready, confirm the materials include:\n\n```text\nPrompt Builder\npreflight\ncomposition boundary\nprompt-builder\np\nwhich -a prompt-builder p\nprompt-builder --version\np --version\ncargo install --path . --locked --force\n--stdin\n--submit\n--print-prompt\n--print-command\n--print-launch-json\n--dry-run\n--name\nCODEX_THREAD_NAME\napp-server-named-thread\nthread/name/set\n--handoff-command\n--handoff-arg\nCommand::arg\nfinal argv\n--fork-from\n--compact\n--launch-option\np-f\np-c\np-cm\nxfl\nxfc\nzsh -lc\n40-ai.zsh\n@ file selector\nskills\nslash commands\nShift+Enter\nbracketed paste\nCtrl+C\nPROMPT_BUILDER_CODEX_BIN\nSection 6\n```\n\n## Further References\n\n- team-facing file: `cheatsheets/05-prompt-builder.md`\n- Exercises: `exercises/05-prompt-builder.md`\n- Zsh helper file: `zsh/conf.d/40-ai.zsh`\n- Prompt Builder checkout: `README.md`, `src/cli.rs`, `src/main.rs`, `src/handoff.rs`, `src/launch_manifest.rs`, `src/app_server_launch.rs`, `src/composer_input.rs`\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/downloads/codex-power-user-workshop-2026-06-27.bundle)\n- [Resource directory and portable download](/topics/codex-resources/)"
}
