Prompt Pipeline
The prompt pipeline assembles a comprehensive system prompt for each agent session. It gathers environment information, role instructions, tool descriptions, pending messages, beads tasks, and session context into a structured multi-section prompt that guides the agent's behavior.
Overview
The build_prompt() function in prompt.rs orchestrates prompt assembly. Each time an agent transitions to BuildingPrompt, a fresh prompt is assembled from current state — there is no cached or incremental prompt. This ensures the agent always sees the latest messages, tasks, and environment.
Prompt Sections
The prompt is assembled from up to 14 numbered sections, each conditionally included based on available context:
| # | Section | Content | Conditional |
|---|---|---|---|
| 1 | Identity | Agent name, swarm context | Always |
| 2 | Agent Role | The agent's configured prompt text | Always |
| 3 | Mode Instructions | Behavior rules for the agent's execution mode (code, delegate, etc.) | When mode is set |
| 4 | Workflow Context | Current workflow stage, inputs, and constraints | When in a workflow |
| 5 | Project Instructions | Contents of AGENTS.md from the project root | When file exists |
| 6 | Core Mandates | Universal rules: commit discipline, branch hygiene, communication protocol | Always |
| 7 | Doing Tasks | How to approach coding tasks, use tools, handle errors | Always |
| 8 | Tool Usage Policy | Rules for tool selection, permission handling | Always |
| 9 | Swarm Workflow | Inter-agent communication protocol, when to message teammates | Always |
| 10 | Tone & Style | Output formatting guidelines | Always |
| 11 | Environment | Platform, OS, git status, recent commits, working directory | Always |
| 12 | Messages | Pending messages from other agents (consumed from mailbox) | When messages exist |
| 13 | Beads Tasks | Available tasks from bd ready --json | When beads is available |
| 14 | Session Context | Session ID, session sequence, interrupt context | Always |
PromptContext
The PromptContext struct carries all the data needed for prompt assembly:
| Field | Description |
|---|---|
agent_name | Name of the agent being prompted |
agent_prompt | The agent's configured prompt text |
mode | Agent execution mode |
session_id | Current session ID |
session_seq | Session iteration number |
db_path | Path to the SQLite mailbox database |
worktree_path | Agent's worktree directory |
agent_names | List of all agents in the session |
workflow_context | Optional workflow stage context |
interrupt_context | Optional interrupt reason |
Environment Information
The EnvironmentInfo struct gathers runtime context:
| Field | Source |
|---|---|
platform | std::env::consts::OS |
os_version | uname -r output |
shell | $SHELL environment variable |
cwd | Current working directory |
git_status | git status --short output |
recent_commits | git log --oneline -5 output |
date | Current date |
Message Formatting
Pending messages are consumed from the mailbox and formatted with urgency labels:
## Messages from teammates
[URGENT] From backend (2m ago):
The API endpoint /users is returning 500 errors, please check the database migration.
From frontend (5m ago):
I've finished the login page UI, ready for API integration.
Urgent messages are prefixed with [URGENT] to draw the agent's attention.
Beads Task Integration
When the bd CLI is available, the prompt pipeline runs bd ready --json with a timeout to discover available tasks:
## Available Tasks (from beads)
- SWARM-42: [open] Implement user authentication endpoint
- SWARM-43: [open] Add input validation to signup form
- SWARM-44: [in_progress] Write integration tests for login flow
This allows agents to autonomously pick up and work on tracked issues.
Interrupt Context
When an agent is interrupted (due to an urgent message), the interrupt context is included in the rebuilt prompt:
## Interrupt Context
You were interrupted by an urgent message. Your previous session was cancelled
so you could process this message. Review the messages section above and respond
to the urgent request.
Related
- Agent Lifecycle — When prompts are built in the state machine
- Messaging — How messages are consumed into the prompt
- Configuration — Agent prompt configuration
- Skills — How skills inject into the prompt context