{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "codex-prompt-builder",
  "slug": "prompt-builder",
  "title": "Compose the first prompt before launch",
  "summary": "The first prompt does more than start a chat. It names the work, chooses the launch path, loads useful references, and decides whether this is a fresh thread, a fork, a compacted branch, or a wrapper handoff.",
  "category": "Planning",
  "tags": [
    "prompt-builder",
    "preflight",
    "prompts"
  ],
  "sources": [
    {
      "label": "Codex workflows companion",
      "url": "https://lapis-fossil-vsbc.here.now/#prompt-builder"
    },
    {
      "label": "Published workshop recording",
      "url": "https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0"
    }
  ],
  "sourceUnits": [
    "src/content/final/chunk-08-compose-before-the-agent-starts.md",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Start With A Name",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Compose Before Launch",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Use Prompt Builder For Preflight",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Use Hooks For Every-Turn Behavior",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Use Imps For Repeated Specialized Jobs",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Optional Patterns: Fork, Compact, Handoff",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Copyable Artifact: First Prompt Preflight Checklist",
    "src/content/final/chunk-08-compose-before-the-agent-starts.md#Compose The First Prompt Before The Agent Starts/Verify Commands Before Use",
    "src/lib/content/sections.ts",
    "src/lib/content/sections.ts#prompt-builder",
    "src/lib/content/sections.ts#recordingSpans"
  ],
  "collection": "codex",
  "categoryId": "planning",
  "wordCount": 874,
  "url": "/topics/codex-prompt-builder/",
  "markdownUrl": "/markdown/codex-prompt-builder.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/codex-prompt-builder.json",
  "headings": [
    {
      "id": "start-with-a-name",
      "text": "Start With A Name",
      "level": 2
    },
    {
      "id": "compose-before-launch",
      "text": "Compose Before Launch",
      "level": 2
    },
    {
      "id": "use-prompt-builder-for-preflight",
      "text": "Use Prompt Builder For Preflight",
      "level": 2
    },
    {
      "id": "use-hooks-for-every-turn-behavior",
      "text": "Use Hooks For Every-Turn Behavior",
      "level": 2
    },
    {
      "id": "use-imps-for-repeated-specialized-jobs",
      "text": "Use Imps For Repeated Specialized Jobs",
      "level": 2
    },
    {
      "id": "optional-patterns-fork-compact-handoff",
      "text": "Optional Patterns: Fork, Compact, Handoff",
      "level": 2
    },
    {
      "id": "copyable-artifact-first-prompt-preflight-checklist",
      "text": "Copyable Artifact: First Prompt Preflight Checklist",
      "level": 2
    },
    {
      "id": "verify-commands-before-use",
      "text": "Verify Commands Before Use",
      "level": 2
    },
    {
      "id": "related-resources",
      "text": "Related resources",
      "level": 2
    }
  ],
  "markdown": "# Compose the first prompt before launch\n\nThe first prompt does more than start a chat. It names the work, chooses the launch path, loads useful references, and decides whether this is a fresh thread, a fork, a compacted branch, or a wrapper handoff.\n\nDo the deliberate setup before the agent session starts. Use **[hooks](https://developers.openai.com/codex/hooks)** for repeated interception during the session. Use **[imps](https://github.com/johnlindquist/codex-imps)** or CLI helpers for reusable specialist behavior.\n\n## Start With A Name\n\n**Unnamed sessions decay quickly.** A name gives search, resumption, review, and reporting something stable to grab.\n\n> The thing I like about this is that I can just give a conversation a name from the start. And it kind of forces me to think about what the conversation is going to be about.\n>\n> — John Lindquist\n\nGood names sound like software work:\n\n- Checkout saved payment methods\n- Billing webhook retry audit\n- Auth session rotation review\n- Settings empty-state cleanup\n\nThe name does not need to be clever. It needs to be **short, searchable, and tied to the work**.\n\n## Compose Before Launch\n\nThe core loop is:\n\n```text\nintent -> name -> prompt -> references -> preview -> submit\n```\n\n**[Prompt Builder](https://github.com/johnlindquist/prompt-builder)** is useful because it **moves composition before the full launch path**. You can shape the prompt, add the name, include the references, inspect the launch, and then hand the result to [Codex](https://developers.openai.com/codex) or a wrapper command.\n\n> Pre-flight, preload, pre-plan. Sessions before, before anything about the agents kicks in, before the system prompt kicks in, before anything.\n>\n> — John Lindquist\n\n## Use Prompt Builder For Preflight\n\nUse a preflight surface when the setup belongs to the first prompt.\n\nFeature kickoff:\n\n```text\nName:\nCheckout saved payment methods\n\nPrompt:\nInspect the checkout flow, list the files likely involved, identify the smallest safe implementation plan, and name the first verification command.\n\nDo not edit yet.\n```\n\nBug-fix preflight:\n\n```text\nName:\nBilling webhook retry bug\n\nPrompt:\nUse the failing test output and billing webhook files to identify the likely regression.\n\nReturn the smallest patch plan and the verification command before editing.\n```\n\nArchitecture review:\n\n```text\nName:\nAuth session rotation review\n\nPrompt:\nReview the auth/session architecture and find risks around token rotation, stale sessions, and logout behavior.\n\nReturn findings grouped by risk and proof needed.\n```\n\n## Use Hooks For Every-Turn Behavior\n\nPrompt Builder helps before the session starts. Hooks are a better fit when something must happen **on every prompt or at a lifecycle checkpoint**.\n\nFor voice-to-text cleanup:\n\n- Use Prompt Builder when cleanup only needs to happen before the first prompt.\n- Use a prompt-submit hook when cleanup must happen on every turn.\n- Use an imp or CLI helper when cleanup belongs to a reusable specialist command.\n\nExample boundaries:\n\n- Initial only: clean up a dictated feature kickoff, apply a glossary, attach project references, then launch.\n- Every turn: normalize dictated acronyms, product names, ticket IDs, and file names before each prompt reaches the agent.\n- Specialist job: take rough dictated text and return a launch-ready prompt without touching the repo.\n\n## Use Imps For Repeated Specialized Jobs\n\nIf the behavior becomes a reusable tool-shaped job, move it out of the first prompt.\n\nGood candidates:\n\n- prompt cleanup\n- bug triage\n- screenshot capture\n- route inspection\n- dependency audit\n- ticket drafting\n\n**The first prompt should start the work.** It should not become the permanent home for every repeated workflow.\n\n## Optional Patterns: Fork, Compact, Handoff\n\nPrompt Builder can compose first, then hand the prompt to another command. In that mode, fork and compact options are routing choices.\n\nKeep the model simple:\n\n```text\ncompose first -> fork selected session -> compact when needed -> resume with named prompt\ncompose first -> hand off to wrapper -> wrapper owns the routing\n```\n\nTreat this as advanced launch routing. The main lesson is still **preflight**: name the work, shape the request, preview the launch, and submit deliberately.\n\n## Copyable Artifact: First Prompt Preflight Checklist\n\n```text\nBefore launching the agent, fill in:\n\nName:\n[short, searchable task name]\n\nGoal:\n[what should be true when this work is done]\n\nContext:\n[files, logs, screenshots, tickets, or docs to inspect first]\n\nConstraints:\n[files to avoid, behaviors to preserve, risky areas]\n\nLaunch shape:\n[fresh thread / named thread / fork / compact fork / wrapper handoff]\n\nFirst output:\n[plan only / edit / diagnosis / test list / comparison]\n\nProof:\n[command, screenshot, trace, diff, or review artifact required]\n\nStop rule:\n[what should block completion]\n```\n\nExample:\n\n```text\nName:\nCheckout saved payment methods\n\nGoal:\nFix the saved-card selection regression without changing the payment-provider adapter.\n\nContext:\nCheckout route, saved payment method component, failing test output.\n\nConstraints:\nDo not touch provider SDK wrappers.\nDo not rewrite checkout state management.\n\nLaunch shape:\nNamed thread.\n\nFirst output:\nDiagnosis and smallest safe patch plan.\n\nProof:\nRun the checkout component test and billing smoke test.\n```\n\n## Verify Commands Before Use\n\nPrompt Builder command examples are implementation details. Before running them, verify the current binary name, install path, `--name`, dry-run, print, submit, handoff, fork, compact, and launch-option behavior against the current source and CLI help.\n\nThe pattern is stable. Command details can change.\n\n## Related resources\n\n- [Companion reference](https://lapis-fossil-vsbc.here.now/#prompt-builder)\n- [Resource directory and portable download](/topics/codex-resources/)\n- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)"
}
