Code Execution Agent

Purpose

This page documents the development workflow used when building or modifying software through the Orchestration Agent and Code Execution Agent. The workflow defines the sequence of steps, the responsibilities of each component, and the rules that govern implementation.

Status: Implemented (workflow is established and used in active development)

Responsibilities

The Code Execution Agent is responsible for:

• Code generation
• Code modification
• Technical implementation tasks
• Research or code inspection under explicit instructions

Important: The Code Execution Agent does not perform git operations directly. Git operations remain under direct user (or Orchestration Agent) control.

Workflow diagram

Loading diagram…

Step-by-step procedure

1. Verify context and write permissions

Before any implementation work begins, the Orchestration Agent confirms:

• The correct project directory is active
• Write permissions to the relevant files exist
• The current state of the codebase is understood (recent changes, open issues)
• No conflicting work is in progress

2. Design the solution

The Orchestration Agent designs the solution before writing any prompt. This includes:

• Identifying the affected files and components
• Defining the expected behavior and output
• Identifying constraints, edge cases, and risk areas
• Confirming the approach with the user if there is meaningful ambiguity

3. Prepare an implementation prompt

The Orchestration Agent writes an explicit, scoped implementation prompt. The prompt describes:

• What to build, not how to build it in detail
• The relevant context (file paths, existing patterns, constraints)
• The expected output format
• Explicit boundaries (what not to change)

Prompts describe the goal and leave implementation decisions to the Code Execution Agent within the specified constraints. They are not prewritten code to copy.

4. Code Execution Agent writes or modifies code

The Code Execution Agent executes the prompt and returns the generated implementation. This step is isolated: the Code Execution Agent does not read session history, does not have access to git, and does not push changes anywhere.

5. Review, integrate, and test

The Orchestration Agent reviews the returned code for:

• Correctness against the original design
• Consistency with existing patterns and style
• Security issues or unsafe patterns
• Missing edge case handling

The code is then integrated into the project and tested as appropriate. If the output is not acceptable, the workflow loops back to step 3 with a reduced scope or more explicit constraints.

6. Manual git commit and push

Git operations remain under direct user control. The Code Execution Agent does not interact with git under any circumstances. The user (or Orchestration Agent with explicit user authorization) performs the commit and push after reviewing the integrated changes.

7. Report the result

The Orchestration Agent reports the outcome: what was built, what was changed, and any open issues or follow-up tasks. Relevant documentation is updated.

Key rules

• The Code Execution Agent does not interact with git under any circumstances
• Prompts describe what to build, not prewritten code to paste
• Tasks should be split into small sequential units rather than one large prompt
• If the Code Execution Agent fails or the output is incorrect, retry with a smaller, more explicit scope
• If recovery is not possible, stop and ask the user before continuing
• Do not proceed with integration if the review step identifies a significant issue

Error handling

There is currently no automated retry mechanism. If a prompt produces incorrect output, the recovery path is:

1. Identify what went wrong (scope too broad, ambiguous instruction, context missing)
2. Write a more explicit prompt with reduced scope
3. Retry from step 3

If multiple retries fail, the Orchestration Agent stops and reports the issue to the user rather than continuing with a partially correct result.

Related pages

→ Orchestration Agent — planning and coordination agent → Data Flow — how development results move through the system → System Overview — full architecture context