Compose the prompt before choosing the agent — prompts and exercises

Complete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.

Complete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.

Quick start

# needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs
cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
alias p=prompt-builder
p --dry-run --print-command "hello"    # prints the exact launch: pi hello
p                                      # open the composer: $ skills · @ files · Ctrl+R history

Prompt library

The fixit debugger persona

  • Agent: Codex, launched through p --target codex --developer-instructions "…"
  • Working directory: the project with the bug
  • Expected result: the composer opens; whatever terse bug you type launches Codex carrying this persona
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.

Have your agent write you a handoff wrapper

  • Agent: any coding agent (Claude Code, Codex, Pi)
  • Working directory: wherever your shell config lives
  • Expected result: a new shell function whose launch is proven with the /bin/echo substitution test before anything real runs
Write me a zsh wrapper function that opens prompt-builder in handoff mode and hands my composed prompt to my own shell function. Use this pattern: prompt-builder --handoff-command <cmd> --handoff-arg <arg> passes the prompt as the final argv element with no shell eval. Before wiring in the real command, prove the wrapper with: prompt-builder --submit --dry-run --handoff-command /bin/echo "test" — my prompt must appear verbatim as the final echoed argument. Show me that proof, then swap the real command in. The repeated move I want to wrap: <describe your move>.

Add a second-account launch target

  • Agent: any coding agent with shell access
  • Working directory: anywhere
  • Expected result: a new target in targets.toml and a printed launch command carrying CLAUDE_CONFIG_DIR
Add a prompt-builder launch target for a second Claude Code account: run prompt-builder target add second-account --kind claude --env 'CLAUDE_CONFIG_DIR=~/.claude-second' and then verify it with prompt-builder --dry-run --target second-account --print-command "hello". Show me the printed command so I can read the exact argv before any real launch.

Set it up (agent guide)

  1. Install the composer and alias it to p. Keep --locked: the lockfile pins patched crossterm/ratatui revisions.

    cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
    echo 'alias p=prompt-builder' >> ~/.zshrc
    source ~/.zshrc
    
  2. Add one launch target for an agent or account you already switch to by hand.

    prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'
    

    This writes ~/.prompt-builder/targets.toml. On a fresh machine the file now reads exactly:

    [[targets]]
    name = "pi"
    kind = "pi"
    
    [[targets]]
    name = "codex"
    kind = "codex"
    
    [[targets]]
    name = "claude"
    kind = "claude"
    
    [[targets]]
    name = "work-profile"
    kind = "codex"
    
    [targets.env]
    CODEX_HOME = "~/.codex-work"
    

Success check: print the launches without running anything, then list the targets.

prompt-builder --dry-run --print-command "hello"
prompt-builder --dry-run --target work-profile --print-command "hello"
prompt-builder target list
pi hello
CODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello
pi            pi      bin=pi
codex         codex   bin=codex
claude        claude  bin=claude
work-profile  codex   bin=codex   CODEX_HOME=~/.codex-work

In real output the CODEX_HOME path appears expanded to your full home directory. Read the second line closely — that bypass flag is the reason dry-run comes first.

Complete reusable setup contract

Prompt Builder (p) — agent setup guide

Following this file sets up: the prompt-builder terminal composer, aliased to p, with one custom launch target, verified end-to-end with dry-run flags (no agent is ever launched by these steps).

Placeholders used below: ~ = the user's home directory. All other paths are literal.

Prerequisites

Check each before starting:

cargo --version

Expected: a Rust toolchain from rustup (the repo pins Rust 1.95.0; any recent stable cargo can build it). If cargo is missing, stop and tell your user to install rustup from https://rustup.rs — do not proceed.

The Pi, Codex, and Claude Code CLIs are NOT required for these steps: every verification below uses --dry-run/print flags, which work with no agent CLIs installed.

Steps

  1. Install the composer from the public repo. Keep --locked — the lockfile pins patched crossterm and ratatui revisions, so unlocked installs may behave differently in the terminal.

    cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked
    

    This compiles from source and can take a few minutes.

  2. Alias the binary to p. For zsh:

    echo 'alias p=prompt-builder' >> ~/.zshrc
    

    For other shells, either add the equivalent alias to that shell's rc file, or use a shell-independent symlink:

    ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p
    
  3. Add one launch target (a named launch profile: binary + env vars + default args). This example creates a Codex profile with its own CODEX_HOME, i.e. a separate identity:

    prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'
    

    On a fresh machine this writes ~/.prompt-builder/targets.toml with exactly this content:

    [[targets]]
    name = "pi"
    kind = "pi"
    
    [[targets]]
    name = "codex"
    kind = "codex"
    
    [[targets]]
    name = "claude"
    kind = "claude"
    
    [[targets]]
    name = "work-profile"
    kind = "codex"
    
    [targets.env]
    CODEX_HOME = "~/.codex-work"
    

    If the user already has a targets.toml, target add appends to it instead; existing targets are preserved.

Success check

Run:

prompt-builder --dry-run --print-command "hello"
prompt-builder --dry-run --target work-profile --print-command "hello"
prompt-builder target list

Expected observable result:

  • Line 1 prints exactly: pi hello
  • Line 2 prints: CODEX_HOME=<expanded home>/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello
  • target list shows four targets: pi, codex, claude, work-profile (the last with CODEX_HOME=~/.codex-work)

Report to your user: what you installed, the exact printed launch commands, and — importantly — that the Codex line contains --dangerously-bypass-approvals-and-sandbox. Real (non-dry-run) Codex and Claude launches use permission-bypass flags, so p should only be pointed at directories where the user accepts the agent modifying files and running commands.

Notes for agents

  • If cargo install fails on dependency resolution, you probably dropped --locked. Re-run with it.
  • If target add fails with a duplicate-name error, the user already has a work-profile target; pick another name and adjust the success check to match.
  • target add defaults to --kind pi — always pass --kind explicitly when creating codex/claude targets.
  • The default target is Pi. Real submissions (without --dry-run) fail if the pi CLI is not on PATH; that does not affect any step in this file.
  • The composer's interactive features ($ skills, @ files, Ctrl+R history, Tab to the Target ‹name› selector) need a real TTY; don't try to drive the TUI from a non-interactive shell. Verify with the print flags above instead.
  • Full docs and updates: https://github.com/johnlindquist/prompt-builder (page version of this guide: https://shiny-bloom-f8hv.here.now/)
  • The guide's fixit wrapper also ships as a skills.sh-format agent skill hosted on this site (same job, third form of the wrapper: zsh function → mdflow flow → SKILL.md). Machine-fetch URL: https://shiny-bloom-f8hv.here.now/skills/fixit/SKILL.md?raw (?raw required — the bare URL serves an HTML viewer). Install only if your user prefers skills: stage anywhere EXCEPT a dir named skills/ (the skills CLI claims that name and you'd install an empty skill), e.g. mkdir -p skill-src/fixit && curl -fsSL "<url above>" -o skill-src/fixit/SKILL.md && npx skills add ./skill-src --skill fixit -y.
  • Two presentation pages accompany the guide, for humans walking through the section: https://shiny-bloom-f8hv.here.now/replay.html (Session Replay — the annotated transcript of the sessions that set up and wrapped p) and https://shiny-bloom-f8hv.here.now/dialogue.html (Socratic Dialogue — attendee questions driving the same material). They contain the same commands plus the complete wrapper file p-wrap.zsh, provided by those pages as a liftable code block. Note: that file does NOT exist in the prompt-builder repo — the repo's examples/ directory ships only fixit.zsh — so copy p-wrap.zsh from the workshop pages, not from the repo. This file remains the canonical machine copy for setup.

Source references