Skip to main content
Prompt construction is split across two layers: The gateway decides which previous conversation messages should be included. The agent compiles the system prompt and current turn runtime context. The provider adapter then maps the common ChatRequest into the provider-specific API shape. This split is deliberate. Conversation history is durable thread state, so the gateway owns loading, summarizing, and truncating it. Runtime instructions are turn-scoped, so the agent owns skills, memory prompt context, retry instructions, task orchestration policy, and runtime facts. Provider adapters should only translate the already-built request into API-specific payloads.
If you are debugging “why did the model say that?”, start here, then inspect the turn’s PromptManifest, the thread history, and the provider request shape described in Provider System.

​
Why Prompt Compilation Is A Separate Crate

Prompt behavior changes the product more than most internal refactors. Small wording changes can affect tool use, recovery, task delegation, and user trust. Keeping prompt compilation in pioneer-promt makes it testable and reviewable as its own layer instead of hiding it in the middle of the agent loop. The compiler also gives Pioneer stable/dynamic prompt separation. Stable sections can be fingerprinted and potentially cached by providers. Dynamic sections can change between rounds when skills, retry instructions, continuation hints, or runtime facts change.

​
Conversation History

Historical context is loaded by MessageProcessor::load_conversation_history in crates/gateway/src/message/provider_handlers.rs. The gateway loads up to 200 completed conversation entries from CrudStore::get_thread_conversation_history. It also loads the thread summary if one exists. Token counting uses tiktoken-rs with cl100k_base as a provider-agnostic approximation. The budget is derived from gateway thread config: 
history_budget = max_context_tokens - response_reserve_tokens
If the estimated history is under 80% of that budget, Pioneer sends the existing summary plus all loaded entries. If it reaches 80%, the gateway asks the configured summary model, or the thread model if no summary model is configured, to compress the conversation into roughly 10% of the history budget. If compression succeeds, the model receives one system message: 
Summary of earlier conversation:
...
If compression fails, the gateway falls back to truncating recent turns to fit the budget. The compression policy optimizes for continuity over raw transcript length. Once a thread becomes too large, sending every old message is less useful than preserving decisions, file paths, user corrections, and unresolved work in a compact summary. The summary is stored on the thread and reused on later turns.

​
Prompt Compiler

The system prompt compiler lives in crates/promt. The crate name is intentionally promt in the current workspace. compile_prompt receives PromptCompileInput:
InputMeaning
workspace_rootBootstrap root where canonical prompt files are read. In the main agent flow this is the gateway runtime home from home_directory.
profilePrompt profile: full, minimal, or none. Agent turns use AssistantFull.
skills_promptDynamic skills section built after skill resolution.
retry_instructionDynamic instruction inserted after recoverable tool failures or loop budget exhaustion.
include_tool_recovery_policyAdds stable tool failure recovery instructions.
include_task_orchestration_policyAdds task/subagent orchestration guidance when task tools are available.
continue_generation_hintAdds continuation guidance during recovery.
dynamic_contextDynamic context contributed by hook-driven domains and runtime systems.
extra_systemRuntime facts such as local date/time and OS.
limitsCharacter budgets for bootstrap files.

​
Prompt Sections

The compiler builds ordered sections:
SectionStabilitySource
IdentityStableBuilt-in identity base.
SafetyStableBuilt-in safety lines.
Soul CoreStableSOUL.md from runtime home when present.
Identity CoreStableIDENTITY.md from runtime home when present.
User PersonaStableUSER.md if present.
Tool Recovery PolicyStableBuilt-in policy when enabled.
Task OrchestrationDynamicBuilt-in policy when task tools are materialized.
Memory RecallDynamicMemory prompt contract rendered from hook prompt context when memory policy allows it.
Hidden Tool DomainsDynamicCompact request_tools catalog listing hidden domain names and exact tools when tool calling is enabled.
AGENTS.mdDynamicEffective thread-tree AGENTS.md rendered by the AGENTS.md prompt hook when an active file exists.
Recovery ContinuationDynamicBuilt-in continuation hint when requested.
Skills RuntimeDynamicActive skills prompt for the turn.
Retry InstructionDynamicTool retry or final-answer instruction.
Dynamic ContextDynamicOptional caller-provided context.
Extra SystemDynamicCurrent runtime date/time and OS.
Stable and dynamic sections are rendered separately. The final prompt is: 
stable_system_text
PROMT_CACHE_BOUNDARY
dynamic_system_text
The provider receives both the split form and full_system_text through CompiledPromptPayload. Adapters can use this to support provider-side prompt caching where available.

​
Bootstrap Files

For agent turns, bootstrap files are read from the gateway runtime home. The runtime home is the OS user home joined with home_directory, for example ~/.pioneer. On gateway startup, Pioneer ensures the runtime home contains:
  • SOUL.md
  • IDENTITY.md
If either file is missing, the gateway creates it with the current seed content from pioneer-promt. If a file already exists, Pioneer leaves it untouched, even if it has been customized or emptied. Compile-time defaults are not used anymore. The compiler reads canonical files in this order:
  1. SOUL.md
  2. IDENTITY.md
  3. USER.md
SOUL.md and IDENTITY.md are model-evolvable identity files. When they are inserted into the prompt, Pioneer appends this reminder after each file block: 
This file is yours to evolve. As you learn who you are, update it.
That reminder is rendered into the prompt; it is not written into the files. The file path is already shown in the block heading. USER.md is optional and is not created automatically. If present in runtime home, it becomes the User Persona section. Each file is budgeted with a maximum per-file character limit and a total character limit. Missing files, read errors, file truncation, and total-budget truncation become prompt diagnostics. Missing SOUL.md or IDENTITY.md files do not fall back to Rust constants during compilation. The resulting prompt manifest is persisted on the turn so developers can audit what sections were compiled without storing the entire prompt text as the primary contract.

​
Skills Prompt

Skills are resolved before prompt compilation. pioneer-skills builds a compact [Skills] section listing active skills, their exact read_skill slug, and their descriptions. Composer-selected skills stay compact. They do not expand the full SKILL.md body into the prompt; the model must call read_skill with the exact slug before following specialized instructions. Full skill bodies are only eligible for path-matched skills when few skills are active and the prompt budget allows it. If the prompt budget is tight, the section includes a read_skill hint so the model can load exact skill instructions on demand.

​
Memory Prompt

Memory prompt content is contributed through hooks, not hard-coded in the compiler. In agent mode, memory hooks can:
  • classify the turn memory policy;
  • recall deterministic and active memory context;
  • register memory tools when policy allows them; visibility is selected separately by preflight or request_tools;
  • render the Memory Recall section before prompt compilation.
The rendered memory section tells the model how to use memory proactively, when to search, when to write, when to forget, and what not to store. Recalled facts are marked as context rather than instructions. Current user instructions override recalled memories. The post-turn extractor uses a separate prompt renderer. It is not the main assistant prompt and does not include model-facing memory tools. Its job is to return strict JSON facts for the memory service after a completed turn.

​
AGENTS.md Prompt

AGENTS.md prompt content is also contributed through hooks. The gateway installs an internal hook package that resolves the effective active AGENTS.md for the current thread at turn.pre_prompt_compile. If no active file exists in the thread’s folder ancestry, the hook contributes nothing. If a file exists, it becomes a dynamic AGENTS.md prompt section with hook source metadata in the prompt manifest. See AGENTS.md Architecture for the full storage, inheritance, and protocol model.

​
Tool Definitions Are Separate

Tool definitions are not embedded as prompt prose. The agent passes model-visible tool definitions in ChatRequest.tools. The prompt can explain recovery or task orchestration policy, but the callable JSON schema for tools goes through the provider tool-calling interface. This distinction prevents two common bugs. First, a tool should not become callable just because its name appears in prompt text. Second, removing a tool from the model-visible tool list should actually remove the capability, not merely change an instruction sentence. Tool availability is enforced by the tool router described in Tools System. The Hidden Tool Domains prompt section is only a compact catalog for request_tools. It lists domains such as memory, task, artifact, and computer_use with their exact tool names so the model knows which domain to request if a needed hidden tool is not currently visible. It does not include JSON schemas and does not make those tools callable by itself. MCP follows the same boundary. Composer-selected MCP servers and tools do not create an MCP prompt section. They materialize as dynamic provider tools in ChatRequest.tools and are called through the gateway MCP service.

​
Prompt Manifest

Every prompt compilation emits a PromptManifest durable event with compiler version, profile, section ids, stable/dynamic/full fingerprints, and diagnostics. The gateway persists this metadata on the turn through CrudStore::update_turn_prompt_manifest. The manifest is the audit handle. It tells a developer which prompt shape was sent, whether bootstrap files were missing or truncated, and whether dynamic sections changed between provider rounds. The manifest intentionally stores metadata rather than turning the prompt into the only source of truth. The actual behavior is the combination of prompt sections, conversation messages, tool definitions, provider adapter behavior, and runtime policies.

​
Common Debugging Path

When model behavior looks wrong, check these in order:
  1. Was the thread in chat or agent mode? See Agent Loop.
  2. Was history compressed or truncated by the gateway?
  3. Which prompt sections appear in the PromptManifest?
  4. Were relevant skills resolved, disabled, or non-implicit? See Skills Architecture.
  5. Did memory hooks contribute recall context or memory tools? See Memory Architecture.
  6. Which tools were model-visible for that provider round? See Tools System.
  7. Did the provider adapter map compiled_prompt in the expected way? See Provider System.