---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "codex-prompt-builder"
title: "Compose the first prompt before launch"
---

# Compose the first prompt before launch

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.

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

## Start With A Name

**Unnamed sessions decay quickly.** A name gives search, resumption, review, and reporting something stable to grab.

> 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.
>
> — John Lindquist

Good names sound like software work:

- Checkout saved payment methods
- Billing webhook retry audit
- Auth session rotation review
- Settings empty-state cleanup

The name does not need to be clever. It needs to be **short, searchable, and tied to the work**.

## Compose Before Launch

The core loop is:

```text
intent -> name -> prompt -> references -> preview -> submit
```

**[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.

> Pre-flight, preload, pre-plan. Sessions before, before anything about the agents kicks in, before the system prompt kicks in, before anything.
>
> — John Lindquist

## Use Prompt Builder For Preflight

Use a preflight surface when the setup belongs to the first prompt.

Feature kickoff:

```text
Name:
Checkout saved payment methods

Prompt:
Inspect the checkout flow, list the files likely involved, identify the smallest safe implementation plan, and name the first verification command.

Do not edit yet.
```

Bug-fix preflight:

```text
Name:
Billing webhook retry bug

Prompt:
Use the failing test output and billing webhook files to identify the likely regression.

Return the smallest patch plan and the verification command before editing.
```

Architecture review:

```text
Name:
Auth session rotation review

Prompt:
Review the auth/session architecture and find risks around token rotation, stale sessions, and logout behavior.

Return findings grouped by risk and proof needed.
```

## Use Hooks For Every-Turn Behavior

Prompt Builder helps before the session starts. Hooks are a better fit when something must happen **on every prompt or at a lifecycle checkpoint**.

For voice-to-text cleanup:

- Use Prompt Builder when cleanup only needs to happen before the first prompt.
- Use a prompt-submit hook when cleanup must happen on every turn.
- Use an imp or CLI helper when cleanup belongs to a reusable specialist command.

Example boundaries:

- Initial only: clean up a dictated feature kickoff, apply a glossary, attach project references, then launch.
- Every turn: normalize dictated acronyms, product names, ticket IDs, and file names before each prompt reaches the agent.
- Specialist job: take rough dictated text and return a launch-ready prompt without touching the repo.

## Use Imps For Repeated Specialized Jobs

If the behavior becomes a reusable tool-shaped job, move it out of the first prompt.

Good candidates:

- prompt cleanup
- bug triage
- screenshot capture
- route inspection
- dependency audit
- ticket drafting

**The first prompt should start the work.** It should not become the permanent home for every repeated workflow.

## Optional Patterns: Fork, Compact, Handoff

Prompt Builder can compose first, then hand the prompt to another command. In that mode, fork and compact options are routing choices.

Keep the model simple:

```text
compose first -> fork selected session -> compact when needed -> resume with named prompt
compose first -> hand off to wrapper -> wrapper owns the routing
```

Treat this as advanced launch routing. The main lesson is still **preflight**: name the work, shape the request, preview the launch, and submit deliberately.

## Copyable Artifact: First Prompt Preflight Checklist

```text
Before launching the agent, fill in:

Name:
[short, searchable task name]

Goal:
[what should be true when this work is done]

Context:
[files, logs, screenshots, tickets, or docs to inspect first]

Constraints:
[files to avoid, behaviors to preserve, risky areas]

Launch shape:
[fresh thread / named thread / fork / compact fork / wrapper handoff]

First output:
[plan only / edit / diagnosis / test list / comparison]

Proof:
[command, screenshot, trace, diff, or review artifact required]

Stop rule:
[what should block completion]
```

Example:

```text
Name:
Checkout saved payment methods

Goal:
Fix the saved-card selection regression without changing the payment-provider adapter.

Context:
Checkout route, saved payment method component, failing test output.

Constraints:
Do not touch provider SDK wrappers.
Do not rewrite checkout state management.

Launch shape:
Named thread.

First output:
Diagnosis and smallest safe patch plan.

Proof:
Run the checkout component test and billing smoke test.
```

## Verify Commands Before Use

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

The pattern is stable. Command details can change.

## Related resources

- [Companion reference](https://lapis-fossil-vsbc.here.now/#prompt-builder)
- [Resource directory and portable download](/topics/codex-resources/)
- [Published recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)

## Original references

- [Codex workflows companion](https://lapis-fossil-vsbc.here.now/#prompt-builder)
- [Published workshop recording](https://www.dropbox.com/scl/fi/3m5p2dwkx0imuyu0dq5os/GMT20260626-155513_Recording_gallery_1920x1080.mp4?rlkey=60j5649let6pt4fdxpggozv1q&st=qhbuo513&dl=0)
