# pi use cases + starter prompts

Ideation catalog for putting pi to work from Claude Code. Every starter prompt is
addressed **to Claude Code** — paste it and Claude Code sets up and runs the pi
workflow. Routing follows the tested reality: **text-out by default** (pipe files
in, pi returns content as text, Claude Code applies it); use tools only via
`gpt-oss-120b`, or `gpt-oss-20b` with explicit "use the X tool" phrasing.

## Programmatic (Claude Code drives pi as a subprocess)

### 1. Recon-and-synthesize
Claude Code greps the repo itself, pipes the hits to pi for a structured map — no pi tool loop, so it's cheap and reliable.
- **Model:** `gpt-oss-20b` (text-out) · **Why:** input-light synthesis, zero tool-loop risk.
- **Starter:** "Use pi to map how org memberships are read across `src/routes` and `src/durable-objects`. Grep the hits yourself, pipe them into pi (gpt-oss-20b, `-nt` text-out) and have it return a structured list of every read path with a one-line purpose each. Show me the map."

### 2. Mechanical edit fan-out (text-out, you apply)
You write a precise per-file changeset; pi returns each full new file as text; you review and Write.
- **Model:** `gpt-oss-20b` (text-out) · **Why:** cheapest, and you stay in control of what lands on disk.
- **Starter:** "I want an additive optional `source` field on the income schema mirroring expense. Write the exact change, then for each of `src/schemas/income.ts` and its route + DO handler, run pi (`-nt`, gpt-oss-20b) to return the complete new file, diff each against the original, and apply the ones that look right. Don't let pi write files itself."

### 3. Test generation from a spec
You write the plan and one exemplar Vitest case; pi generates the parametric rest; you run the suite; only failures come back to you.
- **Model:** `gpt-oss-20b` (text-out) · **Why:** high-volume boilerplate you shouldn't spend Opus tokens on.
- **Starter:** "Pick one handler in `src/durable-objects/handlers`, write an exemplar Vitest case and a short test plan, then fan pi out (gpt-oss-20b, text-out) to draft the remaining cases per handler. Write them, run `npm run test`, and bring only the failing cases back to me."

### 4. Long-context digest → brief
Hand pi a pile of docs; get a tight brief back; plan from the distillate instead of paying Opus rates to read raw.
- **Model:** `gemma-4-26b-a4b-it` (text-out, 256k) · **Why:** largest cheap context window.
- **Starter:** "Pipe the whole `taskNotes/accounts-balance-formula/` folder into pi (gemma-4, `-nt`) and have it return a ≤300-word brief of the open decisions and their current status. Give me the brief, then your read on what's still unresolved."

### 5. Scaffold from an existing pattern
Generate a new route/handler skeleton that mirrors a chosen exemplar.
- **Model:** `gpt-oss-20b` (text-out) · **Why:** pattern-following, low judgment.
- **Starter:** "Using `src/routes/income.ts` as the pattern, have pi (gpt-oss-20b, text-out) draft a parallel skeleton for a new `advances` route with the same OpenAPI + handler structure but no business logic. Return it as a file; I'll review before it lands."

### 6. Cheap bulk diff review (single lens)
Point pi at a diff to flag one specific class of issue; you triage what it surfaces.
- **Model:** `gpt-oss-120b` (text-out) · **Why:** more reasoning depth for review, still no tool loop.
- **Starter:** "Take `git diff main...HEAD`, pipe it to pi (gpt-oss-120b, `-nt`) with the single instruction to flag only missing input validation on new endpoints. Bring me its list; I'll decide which are real."

### 7. Agentic repo exploration (pi uses tools)
When you genuinely want pi to navigate the repo itself rather than you feeding it context.
- **Model:** `gpt-oss-120b` (tools) · **Why:** the one model with a tested-reliable gateway tool loop. Smoke-test first if you swap models.
- **Starter:** "Let pi explore on its own: run gpt-oss-120b with `-t read,grep,find,ls` and the instruction to *use the grep and read tools* to find every place we do a Firebase-ms-to-seconds conversion and report the file:line list. If it returns nothing, fall back to grepping yourself and piping hits to text-out."

### 8. Commit-message / changelog drafting
Turn a diff into a conventional-commit message or changelog entry.
- **Model:** `qwen3-30b-a3b-fp8` (text-out) · **Why:** cheapest input; a diff is input-heavy, output is tiny.
- **Starter:** "Pipe the staged diff into pi (qwen3-30b, `-nt`) and have it draft a conventional-commit message with an emoji prefix in this repo's style. Show me the draft; I'll tweak and commit."

## Non-programmatic (you run pi directly, or ad-hoc)

### 9. Cheap second opinion / rubber-duck
Talk through a design tradeoff with a fresh model before committing Opus to it.
- **Model:** `gpt-oss-120b` interactive · **Why:** decent reasoning, near-free; escalate to `glm-5.2` for a one-off hard question.
- **Starter:** "Give me a ready-to-run interactive `pi` command (gpt-oss-120b) preloaded with a prompt to pressure-test whether client income should fold into the accounts balance or stay separate. I'll run it in my other tmux window and bring back what it says."

### 10. Scratch exploration of an API/library
Throwaway questions where you don't want to spend Opus context.
- **Model:** `gpt-oss-20b` interactive · **Why:** cheap and fast for quick Q&A.
- **Starter:** "Set me up an interactive pi session (gpt-oss-20b) scoped to read-only tools for poking at how Hono's OpenAPIHono validates responses. Just hand me the command."

### 11. Learn-a-concept explainer
Get a concept explained cheaply, on demand.
- **Model:** `gemma-4-26b-a4b-it` interactive · **Why:** long context if you paste docs; cheap.
- **Starter:** "Give me a `pi` one-liner (gemma-4) that explains how Durable Object SQLite migrations version and replay, grounded in our `src/durable-objects` setup — I'll paste a file in and ask follow-ups myself."

### 12. Draft docs / README section (text-out)
First-draft prose you'll edit, generated off the cheap pool.
- **Model:** `gpt-oss-20b` (text-out) · **Why:** drafting is exactly the token-heavy work to offload.
- **Starter:** "Have pi (gpt-oss-20b, text-out) draft a README section documenting the income categories and their payment-method behavior, using `src/schemas/income.ts` as ground truth. Return markdown; I'll edit it down."

### 13. Naming / bulk-rename brainstorm
Cheap ideation for a set of names before you commit to one.
- **Model:** `gpt-oss-20b` (text-out) · **Why:** pure ideation, no repo mutation.
- **Starter:** "Ask pi (gpt-oss-20b) for 8 candidate names for the new 'advance against salary' concept that fit our existing income/expense vocabulary. Just list them for me to pick."

---

**Guardrails baked in:** default to text-out (`-nt`); tools only via gpt-oss-120b (or gpt-oss-20b with explicit "use the X tool"); never default to glm-5.2/kimi; scope every run; verify current models with `pi --list-models`.