The Orchestration Strategy

In the previous lesson, we spent our time planning. We built the "brain" of our app using a Product Requirements Document (PRD) and a Technical Specification. Now, it is time to build the actual application.

Building a production-ready app involves dozens of small tasks. If you did this manually, you would spend hours writing boilerplate code, setting up databases, and fixing small bugs. Instead, we use an Orchestration Strategy.

Orchestration means you act as the manager. You will oversee a Main Session that coordinates 23 different tasks across 6 development phases. To do this, you will delegate work to specialized agents:

• task-executor: This is your primary builder. It writes the code and the initial tests.
• test-enhancer: This agent reviews existing tests and adds edge cases to ensure the app doesn't break.
• recipe-validator: This agent checks if the complex business logic (such as ingredient scaling) matches our specific rules.
• doc-updater: This keeps your documentation, such as the API map (OpenAPI), in sync with your code.

In this lesson, you will learn how to guide these agents to build the RecipeBox app.

Before we start the engines, let's remember how Spec-Driven Development (SDD) works. Everything the agents build is based on the files we created earlier:

1. The Specification: This is the source of truth. If the agent needs to know what fields a Recipe has, it looks at @specs/recipebox/specification.md.
2. The Constitution: This is a file (named AGENTS.md) that contains your "rules of the house." It tells the agents to use specific styles, such as using type hints in Python or following certain security patterns.
3. The Task List: We have a clear list of tasks (T001 through T023). We never guess what to do next; we simply follow the list.

By keeping these specs in the agent's context, we ensure that the code stays consistent even as the project grows.

One important note before we begin building: in Unit 1, you created a PRD, domain model, and technical plan. These have been consolidated into a single specification.md file that lives in the specs/recipebox/ directory. This is the file our agents reference as their source of truth. Additionally, the hands-on practice exercises use SQLite instead of PostgreSQL to keep the environment simple and avoid complex server setup. Because we use SQLAlchemy as our ORM, every pattern you write — models, relationships, queries — works identically with PostgreSQL. Switching databases in production requires only changing the connection string. The architecture and code quality remain the same.

The first phase of our build is the Foundation. This involves creating the database models. We use an Atomic Loop for every task: Delegate -> Validate -> Commit.

Let's look at how you would handle Task T001: Create the Recipe Model.

First, you ask Codex to spawn a task-executor agent with a clear instruction. You tell it exactly what to build and which spec to follow.

Spawn a task-executor agent: "Execute T001 from @specs/recipebox/tasks.md: 
Create Recipe model with fields (name, description, prep_time, cook_time, servings), 
relationships (one-to-many RecipeIngredients), and unit tests."

The agent will then create the files. Once it has finished, it provides a report. Your job is not to rewrite the code, but to validate it quickly. You do this by running the tests the agent produced. First, let's confirm the model can be imported and instantiated:

from src.recipebox.models.recipe import Recipe

def test_recipe_model_exists():
    recipe = Recipe(name="Pasta", servings=4)
    assert recipe.name == "Pasta"

This test confirms that the Recipe class was created in the expected module and can be instantiated. Next, we check that all requested fields are present:

def test_recipe_fields():
    recipe = Recipe(
        name="Pasta",
        description="Delicious Italian pasta",
        servings=4
    )
    assert recipe.name == "Pasta"
    assert recipe.description == "Delicious Italian pasta"
    assert recipe.servings == 4

Running pytest against these two tests confirms the agent followed the Recipe definition from your spec. The output should look like this:

2 passed in 0.12s

Once you are satisfied, you perform an Atomic Commit. This means you save only the files related to this specific task to your version control (Git). This keeps your project history clean and easy to track.

One of the biggest benefits of orchestration is the ability to do two things at once. In a traditional workflow, you might build the Recipe API, finish it, and then start the Meal Planning feature.

With orchestration, because we have a solid foundation, these two features can be built in parallel tracks.

• Track A: Focuses on the Recipe API (CRUD operations such as creating, reading, updating, and deleting recipes).
• Track B: Focuses on the Meal Planning logic (scheduling recipes for certain dates).

Since both tracks use the Foundation models we built in Phase 1, they do not interfere with each other. You can have one agent session working on Track A while you (or another agent session) work on Track B.

When both tracks are finished, you perform an Integration Checkpoint. This is where you ensure that the two features interact correctly. For example, you might verify that a recipe (from Track A) can be successfully linked to a meal plan (from Track B):

def test_add_recipe_to_meal_plan():
    # Call the endpoint that links a recipe to a meal plan
    response = client.post("/meal-plans/plan_456/recipes/recipe_123")
    assert response.status_code == 200
    assert response.json()["recipe_id"] == "recipe_123"

1 passed in 0.18s

By working this way, you can cut the total "calendar time" it takes to build the app by nearly 50%.

Once the features are built, we do not simply hope they work; we use a Quality Pipeline. This is Phase 6 of our plan.

Instead of writing every single test case yourself, you delegate this to the test-enhancer. This agent looks at your code and identifies "holes" in your testing.

For example, if you have a service that scales recipe ingredients, the test-enhancer might suggest testing what happens if a user enters 0 servings.

Spawn a test-enhancer agent: "Enhance RecipeService test coverage. 
Focus on edge cases like 0 servings or very large numbers."

After the agent runs, you check the coverage report. In a production app, we usually aim for 95% coverage or higher. This means 95% of your code lines are exercised by a test.

Finally, we use the doc-updater. In modern development, your API documentation (OpenAPI/Swagger) should never be written by hand. The agent reads your code and updates the documentation automatically so that other developers know how to use your API.

A professional developer doesn't just build; they measure. To prove that orchestration is superior to manual coding, we track our metrics.

You should keep a log of two things:

1. Agent Execution Time: How long the AI took to write the code.
2. Your Validation Time: How long you took to review and approve it.

Look at this comparison for a typical foundation phase:

In this example, the orchestrated approach took about 42 minutes, while performing the tasks manually would have taken over 3 hours. This represents an efficiency gain of 79%.

By keeping these metrics, you can show your team or your clients exactly how much faster you are delivering high-quality code.

In this lesson, you learned the Orchestration Strategy for building a production app. We moved from the planning phase into implementation by delegating 23 tasks to specialized agents.

Here is what we covered:

• The Atomic Loop: How to Delegate, Validate, and Commit code for every task.
• Parallel Tracks: Using orchestration to build multiple features (Recipe API and Meal Planning) simultaneously.
• Quality Automation: Using the test-enhancer and doc-updater to ensure the app is robust and well-documented.
• Efficiency Metrics: Tracking time to prove the speed and quality gains of this methodology.

In the upcoming practice exercises, you will enter the CodeSignal IDE and begin Phase 1: Foundation. You will be responsible for starting the orchestration sessions and validating the models created by the agents. Note that the practices will have you manually implement the code that agents would generate in a real orchestration session. Working through this foundation by hand gives you a deep understanding of the models and services, so you can confidently guide and validate agent output when you orchestrate at scale. Get ready to build!