System Prompts & Dialects
Relevant source files
The following files were used as context for generating this wiki page:
- packages/coding-agent/src/system-prompt.ts
- packages/coding-agent/src/prompts/system/system-prompt.md
- packages/coding-agent/src/prompts/system/project-prompt.md
- packages/coding-agent/src/prompts/system/custom-system-prompt.md
- packages/coding-agent/src/prompts/system/agent-creation-architect.md
- packages/coding-agent/test/system-prompt-dedup.test.ts
- packages/coding-agent/scripts/format-prompts.ts
The System Prompts & Dialects module is responsible for the dynamic construction and orchestration of instructions that govern AI agent behavior within the Oh My Pi harness. It assembles multifaceted prompts by synthesizing core engineering principles, tool inventories, project-specific context, and specialized "skills" or "rules." This system ensures that agents operate with high technical accuracy, follow repository-specific conventions, and maintain a consistent persona while interacting with the codebase.
The architecture relies on a hierarchical resolution of prompt files (e.g., SYSTEM.md), where project-level configurations typically override user-level defaults. This modularity allows the system to adapt to different task domains, such as code review, UI design, or architectural planning, by injecting specific templates and guidelines based on the active agent's role.
Prompt Assembly Architecture
The assembly process is centralized in the buildSystemPrompt function. This function coordinates the retrieval of environmental data, tool metadata, and context files to produce a final set of system messages.
Core Components and Logic
The system uses a prioritized resolution strategy for prompt content:
- Custom/Resolved Prompts: Explicitly provided CLI prompts or resolved file paths take top priority.
- Capability-based Discovery: The system walks up the directory tree to find
SYSTEM.mdfiles at the project or user level. - Context and Rules: Discovered rules (with
alwaysApply: true) and project context files are injected and deduplicated to prevent instruction bloat. - Environmental Context: Information such as the current date, working directory, and system specifications (CPU/GPU) is appended to provide the model with a "worldview."
The diagram above illustrates the sequential flow of prompt construction, from initial input resolution to the final rendering of concatenated markdown blocks.
Sources: packages/coding-agent/src/system-prompt.ts:404-517, packages/coding-agent/test/system-prompt-dedup.test.ts:167-175
Specialized Prompt Dialects
The system supports multiple "dialects" or specialized instruction sets tailored for specific personas. These are often defined in specialized .md files that include metadata for agent configuration.
Agent Persona Definitions
Agents are defined with specific traits, including:
- Thinking Level: Controls the depth of reasoning (e.g.,
minimal,medium,high,xhigh). - Domain Expertise: Specialized personas like the
designer(UI/UX),librarian(external research), orreviewer(security/quality). - Operational Parameters: Defines success criteria, forbidden patterns (e.g., "AI Slop Patterns" for designers), and specific implementation procedures.
Summary of Key Agent Dialects
| Agent Type | Responsibility | Thinking Level | Primary Source |
|---|---|---|---|
| Architect | Translates requirements into agent configurations. | High | agent-creation-architect.md |
| Designer | UI/UX implementation and visual consistency. | High | designer.md |
| Librarian | External library research and API verification. | Minimal | librarian.md |
| Oracle | Senior engineer for debugging and architecture. | Extra High | oracle.md |
| Reviewer | Quality and security analysis of patches. | High | reviewer.md |
Sources: packages/coding-agent/src/prompts/agents/designer.md:1-10, packages/coding-agent/src/prompts/agents/oracle.md:1-10, packages/coding-agent/src/prompts/system/agent-creation-architect.md:1-10
Context Resolution and Deduplication
To prevent the model's context window from being cluttered with redundant information, the system implements strict deduplication logic.
Deduplication Strategy
- Content-Based Dedupe: Files with identical content are filtered, keeping only the version closest to the current working directory.
- Instruction Overlap: The system compares blocks of text within
AGENTS.mdand rules. If a rule's content is already present in a loaded context file via an@import, the redundant rule is dropped. - Recursive Expansion: The system expands
@pathimports within context files using the file's own directory as a base.
This sequence diagram shows how the system ensures only unique and relevant instructions are passed to the AI model.
Sources: packages/coding-agent/src/system-prompt.ts:333-358, packages/coding-agent/test/system-prompt-dedup.test.ts:182-200
Internal URL Handlers & Resource Mapping
The system prompts define a set of internal URI schemes that allow agents to reference project resources efficiently. These URLs often auto-resolve to filesystem paths for bash tools.
| Protocol | Resource Type | Description |
|---|---|---|
skill:// | Specialized Knowledge | Points to skill instructions and associated files. |
rule:// | Domain Constraints | Details regarding local project rules. |
agent:// | Output Artifacts | References output from previous agent turns. |
local:// | Shared Plans | Plan artifacts or content shared between subagents. |
vault:// | Obsidian Vault | Interface for reading/editing Obsidian notes. |
issue:// | GitHub Issues | Disk-cached access to repository issues. |
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:46-64
Tooling Policy and Constraints
System prompts explicitly define how and when an agent should use specific tools. This prevents agents from using generic shell commands when specialized, more accurate tools are available.
Specialized Tool Preferences
Agents are instructed to use specialized tools over bash equivalents:
- Reads/Writes: Use
read,write, andedit(surgical edits) instead ofcatorsed. - Search: Use
grepandglobspecialized tools instead of systemrgorfind. - Intelligence: Use
lspfor definition/reference lookups instead of text search. - Compute: Use
evalfor complex logic or scripts; usebashonly for single binary calls or short pipelines.
Execution Workflow
- Scope: Read relevant skills and rules before acting.
- Research: Plan multi-file work and reuse existing patterns.
- Implement: Fix problems at the source and remove obsolete code.
- Verify: Prove work via tests or E2E scenarios before yielding.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:92-125, packages/coding-agent/src/prompts/system/system-prompt.md:160-190
Conclusion
The System Prompts & Dialects module serves as the "operating manual" for AI agents within the repository. By combining static templates with dynamic context discovery and rigorous deduplication, it provides agents with the necessary constraints and information to perform complex engineering tasks safely and accurately. The use of specialized dialects further allows the system to deploy expert-level agents for diverse domains like UI design, code review, and architectural planning.