{
  "schemaVersion": "1",
  "revision": "22ce5d34dbcb5a78",
  "id": "factory-prompt-builder-practice",
  "slug": "prompt-builder-practice",
  "title": "Compose the prompt before choosing the agent — prompts and exercises",
  "summary": "Complete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.",
  "category": "Context",
  "tags": [
    "prompts",
    "exercises",
    "prompt-builder"
  ],
  "sources": [
    {
      "label": "Compose the prompt before choosing the agent",
      "url": "https://shiny-bloom-f8hv.here.now/"
    },
    {
      "label": "Public setup contract",
      "url": "https://shiny-bloom-f8hv.here.now/agent.md"
    }
  ],
  "sourceUnits": [
    "04-prompt-builder/index.html#Quick start",
    "04-prompt-builder/index.html#Prompt library",
    "04-prompt-builder/index.html#Set it up (agent guide)",
    "04-prompt-builder/index.html#The fixit debugger persona",
    "04-prompt-builder/index.html#Have your agent write you a handoff wrapper",
    "04-prompt-builder/index.html#Add a second-account launch target",
    "04-prompt-builder/agent.md"
  ],
  "collection": "factory",
  "categoryId": "context",
  "wordCount": 1309,
  "url": "/topics/factory-prompt-builder-practice/",
  "markdownUrl": "/markdown/factory-prompt-builder-practice.md?raw=1&v=22ce5d34dbcb5a78",
  "jsonUrl": "/api/v1/documents/factory-prompt-builder-practice.json",
  "headings": [
    {
      "id": "quick-start",
      "text": "Quick start",
      "level": 2
    },
    {
      "id": "prompt-library",
      "text": "Prompt library",
      "level": 2
    },
    {
      "id": "the-fixit-debugger-persona",
      "text": "The fixit debugger persona",
      "level": 3
    },
    {
      "id": "have-your-agent-write-you-a-handoff-wrapper",
      "text": "Have your agent write you a handoff wrapper",
      "level": 3
    },
    {
      "id": "add-a-second-account-launch-target",
      "text": "Add a second-account launch target",
      "level": 3
    },
    {
      "id": "set-it-up-agent-guide",
      "text": "Set it up (agent guide)",
      "level": 2
    },
    {
      "id": "complete-reusable-setup-contract",
      "text": "Complete reusable setup contract",
      "level": 2
    },
    {
      "id": "prompt-builder-p-agent-setup-guide",
      "text": "Prompt Builder (p) — agent setup guide",
      "level": 2
    },
    {
      "id": "prerequisites",
      "text": "Prerequisites",
      "level": 2
    },
    {
      "id": "steps",
      "text": "Steps",
      "level": 2
    },
    {
      "id": "success-check",
      "text": "Success check",
      "level": 2
    },
    {
      "id": "notes-for-agents",
      "text": "Notes for agents",
      "level": 2
    }
  ],
  "markdown": "# Compose the prompt before choosing the agent — prompts and exercises\n\nComplete reusable prompts, setup recipes, success checks, and caveats for compose the prompt before choosing the agent.\n\n## Quick start\n\n``` text\n# needs a Rust toolchain (rustup); pi/codex/claude CLIs are optional for dry-runs\ncargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\nalias p=prompt-builder\np --dry-run --print-command \"hello\"    # prints the exact launch: pi hello\np                                      # open the composer: $ skills · @ files · Ctrl+R history\n```\n\n## Prompt library\n\n### The fixit debugger persona\n\n- Agent: Codex, launched through `p --target codex --developer-instructions \"…\"`\n- Working directory: the project with the bug\n- Expected result: the composer opens; whatever terse bug you type launches Codex carrying this persona\n\n``` text\nYou're an expert debugger who always starts with the $fusion skill. The user will pass a terse bug; investigate the behavior and fix it.\n```\n\n### Have your agent write you a handoff wrapper\n\n- Agent: any coding agent (Claude Code, Codex, Pi)\n- Working directory: wherever your shell config lives\n- Expected result: a new shell function whose launch is proven with the /bin/echo substitution test before anything real runs\n\n``` text\nWrite 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>.\n```\n\n### Add a second-account launch target\n\n- Agent: any coding agent with shell access\n- Working directory: anywhere\n- Expected result: a new target in `targets.toml` and a printed launch command carrying `CLAUDE_CONFIG_DIR`\n\n``` text\nAdd 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.\n```\n\n## Set it up (agent guide)\n\n1.  Install the composer and alias it to `p`. Keep `--locked`: the lockfile pins patched `crossterm`/`ratatui` revisions.\n\n    ``` text\n    cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\n    echo 'alias p=prompt-builder' >> ~/.zshrc\n    source ~/.zshrc\n    ```\n\n2.  Add one launch target for an agent or account you already switch to by hand.\n\n    ``` text\n    prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'\n    ```\n\n    This writes `~/.prompt-builder/targets.toml`. On a fresh machine the file now reads exactly:\n\n    ``` text\n    [[targets]]\n    name = \"pi\"\n    kind = \"pi\"\n\n    [[targets]]\n    name = \"codex\"\n    kind = \"codex\"\n\n    [[targets]]\n    name = \"claude\"\n    kind = \"claude\"\n\n    [[targets]]\n    name = \"work-profile\"\n    kind = \"codex\"\n\n    [targets.env]\n    CODEX_HOME = \"~/.codex-work\"\n    ```\n\n**Success check:** print the launches without running anything, then list the targets.\n\n``` text\nprompt-builder --dry-run --print-command \"hello\"\nprompt-builder --dry-run --target work-profile --print-command \"hello\"\nprompt-builder target list\n```\n\n``` text\npi hello\nCODEX_HOME=~/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello\npi            pi      bin=pi\ncodex         codex   bin=codex\nclaude        claude  bin=claude\nwork-profile  codex   bin=codex   CODEX_HOME=~/.codex-work\n```\n\nIn 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.\n\n## Complete reusable setup contract\n\n## Prompt Builder (p) — agent setup guide\n\nFollowing 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).\n\nPlaceholders used below: `~` = the user's home directory. All other paths are literal.\n\n## Prerequisites\n\nCheck each before starting:\n\n```bash\ncargo --version\n```\n\nExpected: 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.\n\nThe 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.\n\n## Steps\n\n1. 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.\n\n   ```bash\n   cargo install --git https://github.com/johnlindquist/prompt-builder.git --locked\n   ```\n\n   This compiles from source and can take a few minutes.\n\n2. Alias the binary to `p`. For zsh:\n\n   ```bash\n   echo 'alias p=prompt-builder' >> ~/.zshrc\n   ```\n\n   For other shells, either add the equivalent alias to that shell's rc file, or use a shell-independent symlink:\n\n   ```bash\n   ln -sf ~/.cargo/bin/prompt-builder ~/.cargo/bin/p\n   ```\n\n3. 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:\n\n   ```bash\n   prompt-builder target add work-profile --kind codex --env 'CODEX_HOME=~/.codex-work'\n   ```\n\n   On a fresh machine this writes `~/.prompt-builder/targets.toml` with exactly this content:\n\n   ```toml\n   [[targets]]\n   name = \"pi\"\n   kind = \"pi\"\n\n   [[targets]]\n   name = \"codex\"\n   kind = \"codex\"\n\n   [[targets]]\n   name = \"claude\"\n   kind = \"claude\"\n\n   [[targets]]\n   name = \"work-profile\"\n   kind = \"codex\"\n\n   [targets.env]\n   CODEX_HOME = \"~/.codex-work\"\n   ```\n\n   If the user already has a `targets.toml`, `target add` appends to it instead; existing targets are preserved.\n\n## Success check\n\nRun:\n\n```bash\nprompt-builder --dry-run --print-command \"hello\"\nprompt-builder --dry-run --target work-profile --print-command \"hello\"\nprompt-builder target list\n```\n\nExpected observable result:\n\n- Line 1 prints exactly: `pi hello`\n- Line 2 prints: `CODEX_HOME=<expanded home>/.codex-work codex --dangerously-bypass-approvals-and-sandbox -C . -- hello`\n- `target list` shows four targets: `pi`, `codex`, `claude`, `work-profile` (the last with `CODEX_HOME=~/.codex-work`)\n\nReport 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.\n\n## Notes for agents\n\n- If `cargo install` fails on dependency resolution, you probably dropped `--locked`. Re-run with it.\n- 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.\n- `target add` defaults to `--kind pi` — always pass `--kind` explicitly when creating codex/claude targets.\n- 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.\n- 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.\n- Full docs and updates: https://github.com/johnlindquist/prompt-builder (page version of this guide: https://shiny-bloom-f8hv.here.now/)\n- 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`.\n- 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."
}
