# Pi Prompt & Context Sources (Pi-level) This document explains where prompt/context comes from in Pi, and how this `pi-openapi-tools` extension participates. > **Verification date:** 2026-05-12 > > **Primary sources consulted:** > > - Pi docs: `@earendil-works/pi-coding-agent/docs/extensions.md` > - Pi docs: `@earendil-works/pi-coding-agent/docs/prompt-templates.md` > - Pi docs: `@earendil-works/pi-coding-agent/docs/sdk.md` > - Repo code: `extensions/index.ts` > - Repo docs: `README.md`, `CLAUDE.md` ## Scope - **Pi-level**: how Pi builds model context and system prompt before each turn. - **Extension-level**: how this repository (`pi-openapi-tools`) plugs into that flow. --- ## 1) Who builds the system prompt? Pi runtime builds the turn system prompt. The extension in this repo does **not** directly own a system-prompt template. In Pi's extension API, `before_agent_start` receives: - `event.systemPrompt` (current chained prompt) - `event.systemPromptOptions` (structured inputs used by Pi) `systemPromptOptions` includes (from Pi docs): - `customPrompt` (from `--system-prompt`, `SYSTEM.md`, or custom templates) - `selectedTools` - `toolSnippets` - `promptGuidelines` - `appendSystemPrompt` - `cwd` - `contextFiles` - `skills` So Pi composes prompt/context first, then extensions may modify it if they implement `before_agent_start`. **Source evidence (2026-05-12):** - `docs/extensions.md` → `before_agent_start` section documents `event.systemPrompt` and `event.systemPromptOptions`. - `docs/extensions.md` → shows that handlers may return `systemPrompt` to modify per-turn prompt text. --- ## 2) What files augment prompt/context (Pi-level) These are the practical file/config sources that can affect prompt/context in Pi. ### A. Context files - `AGENTS.md` files (project/ancestor/global discovery by Pi) These are loaded as context files and can influence model behavior. **Source evidence (2026-05-12):** - `docs/sdk.md` → resource loading and directory behavior describe AGENTS/context-file discovery. - `docs/extensions.md` → `systemPromptOptions.contextFiles` availability. ### B. Prompt templates Markdown templates that expand when invoked with `/template-name`. Discovery locations include: - `~/.pi/agent/prompts/*.md` (global) - `.pi/prompts/*.md` (project) - package-provided prompts (`prompts/` or `pi.prompts` in package.json) - explicit settings/CLI paths (`prompts`, `--prompt-template`) **Source evidence (2026-05-12):** - `docs/prompt-templates.md` → `Locations`, `Usage`, and `Loading Rules` sections. ### C. Skills Skills are additional instruction bundles discovered by Pi from user/project locations and package paths. **Source evidence (2026-05-12):** - `docs/extensions.md` and `docs/sdk.md` describe resource discovery and skill exposure to prompt construction (`systemPromptOptions.skills`). ### D. System prompt overrides/appends Configured via Pi options/resources, including: - `--system-prompt` - `SYSTEM.md` - `--append-system-prompt` **Source evidence (2026-05-12):** - `docs/extensions.md` (`before_agent_start`) describes `customPrompt` and `appendSystemPrompt` origins. --- ## 3) How this extension is injected into model context `pi-openapi-tools` contributes to context primarily through **registered tools**, which reach the model on two distinct channels: 1. Extension loads and registers commands/tools (`/swagger-tools`, `generate_swagger_tools`, etc.). 2. Running `/swagger-tools --prefix ` dynamically registers OpenAPI operation tools. 3. Pi exposes registered tools two ways per turn: - **Tool schemas (`tools[]`)** — every registered tool's JSON schema is sent on the provider API call. This is what the model needs to *call* a tool, but it isn't surfaced in the prompt body. - **Prompt-body "Available tools:" section (`toolSnippets`)** — only tools that set `ToolDefinition.promptSnippet` appear here. Per the Pi SDK type docs: *"Custom tools are omitted from that section when this is not provided."* Without a snippet, the model can still call the tool by name if it knows about it, but it won't see the tool listed alongside the built-ins (`read`, `write`, `edit`, `bash`, …) in the prompt. So injection is tool-based, not by editing a static prompt template in this repo — but discoverability in the prompt body requires `promptSnippet` on each registered tool. **Source evidence (2026-05-12):** - `extensions/index.ts` → `pi.registerTool(...)` for `generate_swagger_tools` and per-operation dynamic tools in `registerToolsFromSpec(...)`, both setting `promptSnippet`. - Pi SDK: `node_modules/@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts` → `ToolDefinition.promptSnippet` doc comment. - Pi SDK: `node_modules/@earendil-works/pi-coding-agent/dist/core/agent-session.js` → `_normalizePromptSnippet` collapses the value to a single line. - `docs/extensions.md` → `before_agent_start` / `systemPromptOptions.selectedTools` and `toolSnippets`. - `README.md` → `/swagger-tools ... --prefix ...` usage documents dynamic generation behavior. --- ## 4) What this repo does **not** use for Pi runtime prompting - `.claude/settings.local.json` is for Claude Code local command permissions only. - `README.md`, `docs/*.md`, and `CLAUDE.md` are documentation/developer guidance, not automatically merged into Pi system prompt unless explicitly loaded through Pi mechanisms. **Source evidence (2026-05-12):** - `.claude/settings.local.json` contains local command permission allowlist entries. - Pi prompt/context ingestion behavior is documented in `docs/extensions.md`, `docs/prompt-templates.md`, and `docs/sdk.md`; these do not treat repo docs as automatic system-prompt inputs. --- ## 5) Current repo-specific behavior In `extensions/index.ts`, this extension: - registers commands and tools - sets `promptSnippet` on every registered tool — `generate_swagger_tools` has a static one-liner; each dynamically generated operation tool gets `": — "` (collapsed to one line, truncated to 160 chars) via `buildPromptSnippet(...)` - handles tool execution and API calls - does **not** register a `before_agent_start` hook to rewrite `event.systemPrompt` Therefore, prompt construction stays in Pi runtime defaults + user/project Pi resources — this extension only contributes by registering tools and their snippets. **Source evidence (2026-05-12):** - `extensions/index.ts` has command and tool registration blocks, but no `pi.on("before_agent_start", ...)` handler. - `CLAUDE.md` architecture section describes this extension as command/tool registration plus HTTP execution path. --- ## 6) Notes on evidence quality - This document is based on the local Pi documentation files and repository sources listed above as of **2026-05-12**. - If Pi SDK/docs change, re-validate this file against the same source paths.