---
schema_version: 1
revision: "22ce5d34dbcb5a78"
id: "factory-prompt-builder-practice"
title: "Compose the prompt before choosing the agent — prompts and exercises"
---

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

## Quick start

``` text
# 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

``` text
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

``` text
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`

``` text
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.

    ``` text
    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.

    ``` text
    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:

    ``` text
    [[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.

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

``` text
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:

```bash
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.

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```bash
   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:

   ```toml
   [[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:

```bash
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.

## Original references

- [Compose the prompt before choosing the agent](https://shiny-bloom-f8hv.here.now/)
- [Public setup contract](https://shiny-bloom-f8hv.here.now/agent.md)
