AI Engineering: Agents and Applications › AI Coding Agents › Day 308

Hands-on lab — Day 308: Shipping a Feature with an Agent

Commands

Setup

pip install -r requirements/requirements.txt

Run

python examples/feature_orchestrator.py

Test

bash tests/run_tests.sh

File tree

examples/feature_orchestrator.py
expected-output/examples-run.txt
expected-output/FIELDS.md
expected-output/measured-values.txt
expected-output/run-output.txt
expected-output/starter-run.txt
expected-output/test-output.txt
expected-output/test-run.txt
metadata.yml
README.md
requirements/requirements.txt
security.md
starter/feature_orchestrator.py
tests/run_tests.sh
tests/test_feature_orchestrator.py
troubleshooting.md

Lab README

Day 308 Lab: Shipping a Feature with an Agent

Lesson

Purpose

Build an End-to-End Feature Orchestrator in Python that executes automated verification quality gates and compiles comprehensive Walkthrough artifacts for peer review.

Learning objectives

  • Execute verification commands and evaluate exit codes.
  • Synthesize structured Walkthrough markdown artifacts.
  • Format modified file lists and test execution evidence.
  • Manage end-to-end feature delivery telemetry.

Prerequisites

  • Python 3.10+ installed
  • pytest installed

Supported operating systems

  • macOS, Linux, Windows WSL2

Hardware requirements

  • Standard CPU, 512MB RAM

Required software

  • Python 3.10+, pytest

Free and open-source options

  • Python Standard Library, Pytest

Installation

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements/requirements.txt

File structure

  • starter/feature_orchestrator.py: Starter implementation skeleton
  • examples/feature_orchestrator.py: Verified reference implementation
  • tests/test_feature_orchestrator.py: Test suite
  • expected-output/: Captured execution logs

How to run

python3 examples/feature_orchestrator.py

What the commands do

  • Executes test command, captures output, and compiles Walkthrough markdown summary.

Expected output

## Feature Walkthrough: Demo Feature

### Summary of Changes
The feature was implemented following the 6-stage agentic shipping playbook.

### Modified Files
- `a.py`

### Verification Evidence
- Test Exe

Validation steps

Run test runner:

bash tests/run_tests.sh

Tests

The test suite validates:

  • Passing and failing quality gate execution
  • Walkthrough formatting with feature name, modified files, and test output
  • Evidence attachment and review note generation

Cleanup

rm -rf .pytest_cache __pycache__ .venv

Troubleshooting

Verify test command paths and string formatting.

Security notes

Runs completely offline on local CPU.

Extension exercises

Add code coverage percentage extraction.

Day number: 308 of 365

Expected output

FIELDS.md

# Measured Values
- `features_orchestrated`: 1
- `walkthroughs_generated`: 1

examples-run.txt

# Feature Walkthrough: Demo Feature

## Summary of Changes
The feature was implemented following the 6-stage agentic shipping playbook.

## Modified Files
- `a.py`

## Verification Evidence
- Test Exe

measured-values.txt

features_orchestrated=1
walkthroughs_generated=1

run-output.txt

# Feature Walkthrough: Demo Feature

## Summary of Changes
The feature was implemented following the 6-stage agentic shipping playbook.

## Modified Files
- `a.py`

## Verification Evidence
- Test Exe

starter-run.txt

An untouched starter fails the suite. Captured from a real run:


self = <examples.feature_orchestrator.FeatureOrchestrator object at 0x10aaa7d90>
feature_name = 'Multi-Tenancy Middleware'
files_modified = ['models.py', 'schemas.py', 'routes.py', 'tests/test_api.py']
test_results = {'passed': True, 'exit_code': 0, 'stdout': '5 passed in 0.02s', 'stderr': ''}

    def generate_walkthrough_artifact(self, feature_name: str, files_modified: List[str], test_results: Dict[str, Any]) -> str:
>       raise NotImplementedError('TASK 2: implement generate_walkthrough_artifact.')
E       NotImplementedError: TASK 2: implement generate_walkthrough_artifact.

examples/feature_orchestrator.py:21: NotImplementedError
=========================== short test summary info ============================
FAILED tests/test_feature_orchestrator.py::test_execute_quality_gates_passed
FAILED tests/test_feature_orchestrator.py::test_execute_quality_gates_failed
FAILED tests/test_feature_orchestrator.py::test_generate_walkthrough_artifact
============================== 3 failed in 0.03s ===============================

Implement each TASK in starter/, copy it over examples/, and the same
suite goes green.

test-output.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-308-shipping-a-feature-with-an-agent
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 3 items

tests/test_feature_orchestrator.py::test_execute_quality_gates_passed PASSED [ 33%]
tests/test_feature_orchestrator.py::test_execute_quality_gates_failed PASSED [ 66%]
tests/test_feature_orchestrator.py::test_generate_walkthrough_artifact PASSED [100%]

============================== 3 passed in 0.08s ===============================

test-run.txt

============================= test session starts ==============================
platform darwin -- Python 3.14.0, pytest-9.1.1, pluggy-1.6.0 -- <repo>/.venv-tools/bin/python3.14
cachedir: .pytest_cache
rootdir: <repo>/labs/sections/ai-engineering/day-308-shipping-a-feature-with-an-agent
plugins: cov-7.1.0, anyio-4.14.2
collecting ... collected 3 items

tests/test_feature_orchestrator.py::test_execute_quality_gates_passed PASSED [ 33%]
tests/test_feature_orchestrator.py::test_execute_quality_gates_failed PASSED [ 66%]
tests/test_feature_orchestrator.py::test_generate_walkthrough_artifact PASSED [100%]

============================== 3 passed in 0.08s ===============================

Source files

examples/feature_orchestrator.py (1812 bytes)
import subprocess
import os
from typing import Dict, Any, List

class FeatureOrchestrator:
    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)
        
    def execute_quality_gates(self, test_cmd: str = "python3 -m unittest") -> Dict[str, Any]:
        res = subprocess.run(
            test_cmd,
            shell=True,
            cwd=self.workspace_root,
            capture_output=True,
            text=True
        )
        return {
            "exit_code": res.returncode,
            "passed": res.returncode == 0,
            "stdout": res.stdout,
            "stderr": res.stderr
        }
        
    def generate_walkthrough_artifact(
        self,
        feature_name: str,
        files_modified: List[str],
        test_results: Dict[str, Any]
    ) -> str:
        file_table = "\n".join([f"- `{f}`" for f in files_modified])
        status = "PASSED (100%)" if test_results.get("passed") else "FAILED"
        return (
            f"# Feature Walkthrough: {feature_name}\n\n"
            f"## Summary of Changes\n"
            f"The feature was implemented following the 6-stage agentic shipping playbook.\n\n"
            f"## Modified Files\n{file_table}\n\n"
            f"## Verification Evidence\n"
            f"- Test Execution Status: `{status}`\n"
            f"- Exit Code: `{test_results.get('exit_code')}`\n\n"
            f"### Test Output\n```text\n{test_results.get('stdout', '').strip()}\n```\n\n"
            f"> *Ready for human architectural review and merge.*"
        )

if __name__ == "__main__":
    orchestrator = FeatureOrchestrator(".")
    res = orchestrator.execute_quality_gates("python3 -c 'print(\"Tests OK\")'")
    print(orchestrator.generate_walkthrough_artifact("Demo Feature", ["a.py"], res)[:200])
metadata.yml (407 bytes)
lesson_id: D308
day: 308
kind: python
languages:
- python
setup_commands:
- pip install -r requirements/requirements.txt
run_commands:
- python examples/feature_orchestrator.py
test_commands:
- bash tests/run_tests.sh
cleanup_commands:
- rm -rf __pycache__ .pytest_cache
requires_network: false
requires_api_key: false
estimated_minutes: 45
last_executed: '2026-08-30'
executed_on: macOS 15.0 Apple Silicon
requirements/requirements.txt (14 bytes)
pytest>=7.0.0
starter/feature_orchestrator.py (1106 bytes)
"""STARTER -- implement each TASK below, then run the tests.

Every function that raises NotImplementedError is yours to write. The
imports, constants and data structures are given; the logic is not.
Run `bash tests/run_tests.sh` to see which tasks are still outstanding.
"""

import subprocess
import os
from typing import Dict, Any, List

class FeatureOrchestrator:

    def __init__(self, workspace_root: str):
        self.workspace_root = os.path.realpath(workspace_root)

    def execute_quality_gates(self, test_cmd: str='python3 -m unittest') -> Dict[str, Any]:
        raise NotImplementedError('TASK 1: implement execute_quality_gates.')

    def generate_walkthrough_artifact(self, feature_name: str, files_modified: List[str], test_results: Dict[str, Any]) -> str:
        raise NotImplementedError('TASK 2: implement generate_walkthrough_artifact.')
if __name__ == '__main__':
    orchestrator = FeatureOrchestrator('.')
    res = orchestrator.execute_quality_gates('python3 -c \'print("Tests OK")\'')
    print(orchestrator.generate_walkthrough_artifact('Demo Feature', ['a.py'], res)[:200])
tests/run_tests.sh (253 bytes)
#!/usr/bin/env bash
set -e
export PYTHONPATH=examples:.
if [ -n "$PYTEST" ]; then
    $PYTEST tests/test_*.py -v
elif command -v pytest &> /dev/null; then
    pytest tests/test_*.py -v
else
    python3 -m unittest discover -s tests -p 'test_*.py' -v
fi
tests/test_feature_orchestrator.py (1458 bytes)
import pytest
import tempfile
from examples.feature_orchestrator import FeatureOrchestrator

def test_execute_quality_gates_passed():
    with tempfile.TemporaryDirectory() as tmpdir:
        orchestrator = FeatureOrchestrator(tmpdir)
        res = orchestrator.execute_quality_gates("python3 -c 'print(\"Gate Passed\")'")
        assert res["exit_code"] == 0
        assert res["passed"] is True
        assert "Gate Passed" in res["stdout"]

def test_execute_quality_gates_failed():
    with tempfile.TemporaryDirectory() as tmpdir:
        orchestrator = FeatureOrchestrator(tmpdir)
        res = orchestrator.execute_quality_gates("python3 -c 'exit(1)'")
        assert res["exit_code"] == 1
        assert res["passed"] is False

def test_generate_walkthrough_artifact():
    orchestrator = FeatureOrchestrator(".")
    test_res = {
        "passed": True,
        "exit_code": 0,
        "stdout": "5 passed in 0.02s",
        "stderr": ""
    }
    walkthrough = orchestrator.generate_walkthrough_artifact(
        feature_name="Multi-Tenancy Middleware",
        files_modified=["models.py", "schemas.py", "routes.py", "tests/test_api.py"],
        test_results=test_res
    )
    assert "# Feature Walkthrough: Multi-Tenancy Middleware" in walkthrough
    assert "- `models.py`" in walkthrough
    assert "- `routes.py`" in walkthrough
    assert "Test Execution Status: `PASSED (100%)`" in walkthrough
    assert "5 passed in 0.02s" in walkthrough

Troubleshooting

Troubleshooting - Day 308

Verify test commands return clean exit code 0 on success.

Security notes

Security - Day 308

Ensure walkthrough artifacts contain no production secrets or access tokens.