background-coding-agents: Instructions file for Codex

AGENTS.md

This file provides guidance to Coding Agents when working with code in this repository.

Project Overview

This is a demonstration repository showing how to apply Spotify's background coding agent concepts to industrial manufacturing environments. It's based on Spotify's 3-part engineering blog series on their journey merging 1,500+ AI-generated PRs with 60-90% time savings.

The codebase demonstrates automated PLC/SCADA code transformations across multiple manufacturing sites with safety-critical verification layers.

Key Commands

Setup

# Initial setup
./setup.sh

# Manual setup
python3 -m venv venv
source venv/bin/activate  # or . venv/Scripts/activate on Windows
pip install -r requirements.txt

Running the Fleet Manager

# From root directory (using installed entry point)
fleet-manager --help

# Example: Dry-run migration
fleet-manager safety_interlock_update --dry-run

# Example: List configured sites
fleet-manager list-sites

# View migration status
fleet-manager status

Development

# Run tests (if implemented)
pytest

# Format code
black .

# Type checking
mypy agents/ verifiers/ fleet-manager/

Architecture Overview

This project implements a Fleet Management Architecture for automated code changes across manufacturing sites, analogous to Spotify's repository fleet management:

Core Components

1. Fleet Manager (fleet-manager/cli.py)

   • Orchestrates migrations across multiple sites
   • Targets sites based on filters (PLC type, firmware version, etc.)
   • Manages verification loops and change requests
   • Configuration in fleet-manager/config.yaml

2. Background Coding Agent (src/background_coding_agents/agents/plc_agent.py)

   • Transforms PLC code based on natural language prompts
   • Uses iterative change-verify loops (max 10 turns)
   • Supports local LLMs (vLLM, llama.cpp) for air-gapped deployments
   • Cloud LLMs optional (Anthropic, OpenAI, MiniMax)
   • Limited tool access (verify, git diff, ripgrep)