The Agent Loop
Relevant source files
The following files were used as context for generating this wiki page:
- packages/coding-agent/src/prompts/system/system-prompt.md
- packages/coding-agent/src/prompts/system/orchestrate-notice.md
- packages/coding-agent/src/prompts/system/plan-mode-active.md
- packages/coding-agent/src/prompts/tools/task.md
- packages/coding-agent/DEVELOPMENT.md
- packages/coding-agent/src/prompts/system/subagent-system-prompt.md
The Agent Loop is the core operational cycle of the Oh My Pi (OMP) coding harness. It governs how autonomous agents interact with the codebase, utilize specialized tools, and manage complex tasks through a structured sequence of execution phases. The loop is designed to optimize for correctness and maintainability, ensuring that every action is grounded in actual repository context rather than model training data.
At its highest level, the loop transitions through six primary stages: Scope, Research, Decompose, Implement, Verify, and Cleanup. This systematic approach ensures that agents do not just execute commands, but instead reason about the environment, plan changes, and verify results before yielding.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:144-184, packages/coding-agent/DEVELOPMENT.md:31-45
Execution Workflow Phases
The standard agent loop follows a strict six-step process to ensure reliable code changes and task completion.
| Phase | Responsibility | Key Actions |
|---|---|---|
| 1. Scope | Requirement Analysis | Read relevant skills/rules; plan multi-file work before touching files. |
| 2. Research | Context Grounding | Read code sections (not just snippets); check exports via LSP; reuse existing patterns. |
| 3. Decompose | Task Breakdown | Update TODOs; delegate complex changes via parallel task subagents. |
| 4. Implement | Code Modification | Fix problems at source; prefer updating existing files; avoid destructive commands. |
| 5. Verify | Quality Assurance | Run unit or E2E tests; assert logical behavior; avoid mocks. |
| 6. Cleanup | Finalization | Update changelogs, docs, and remove scaffolding only after smoke tests pass. |
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:144-184
Research and Grounding
Agents are prohibited from "hoping" or guessing. Every claim must be grounded in observed facts using tools like grep, glob, read, or lsp. This research phase ensures that the agent understands the architecture and data flow before attempting any modifications.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:104-114, packages/coding-agent/src/prompts/system/plan-mode-active.md:46-55
Orchestration and Delegation
For substantial or parallelizable work, the agent loop employs an Orchestrator role. Instead of performing every edit itself, the primary agent decomposes the goal into discrete units and dispatches them to specialized subagents using the task tool.
Parallelization Strategy
The orchestrator must parallelize work maximally. It identifies disjoint file scopes or independent refactors and batches them into a single parallel task call. Serial execution is only permitted when a strict dependency exists (e.g., one task produces a schema that another consumes).
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:12-23, packages/coding-agent/src/prompts/tools/task.md:5-15
The Orchestration Workflow
The following diagram illustrates the flow of an orchestration-heavy agent loop:
The orchestrator manages the lifecycle, while subagents (spawned in isolated worktrees if required) perform the specific edits.
Sources: packages/coding-agent/src/prompts/system/orchestrate-notice.md:44-53, packages/coding-agent/src/prompts/tools/task.md:28-35
Plan Mode and Execution Specs
In complex scenarios, the agent loop enters Plan Mode. This is a read-only state where the agent acts as a software architect to produce an "execution spec."
Execution Spec Requirements
A plan is not a high-level design document; it is a deterministic set of instructions. It must be detailed enough that a "fresh" agent (with no prior conversation context) could execute it from top to bottom without making any additional design decisions.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:1-12
Transitioning to Implementation
To exit Plan Mode and begin implementation, the agent must call the resolve tool with an apply action. This requires the user's approval, at which point the session may be cleared or compacted, and the write-access implementation loop begins.
Sources: packages/coding-agent/src/prompts/system/plan-mode-active.md:5-10, packages/coding-agent/src/prompts/system/plan-mode-active.md:131-140
Subagent Lifecycle and Coordination
Subagents are specialized workers spawned for specific assignments. They follow a truncated version of the agent loop focused on execution and reporting.
Subagent Properties
- Isolation: Can be run in dedicated worktrees to return patches without affecting the main tree directly.
- Context: Start with a blank conversation history; they rely on the
assignmentand sharedlocal://files for context. - Communication: Use the
irctool for quick coordination with peers to avoid overlapping edits on the same files.
Summary
The Agent Loop in Oh My Pi transforms a standard LLM interaction into a disciplined engineering process. By enforcing research-first planning, maximizing parallel delegation through subagents, and gating every phase behind technical verification tools, the system ensures that autonomous agents produce code that is correct, idiomatic, and verifiably functional.