🏭 Background Coding Agents for Industrial Manufacturing

Applying Spotify's proven approach (1,500+ PRs, 60-90% time savings) to industrial PLC/SCADA systems

📊 Quick Stats

Metric	Spotify (Software)	Manufacturing (This Example)
Scale	Thousands of repos	50+ production sites
Results	1,500+ PRs merged	Potential for similar scale
Time Savings	60-90%	70-75% estimated
Success Rate	High	90%+ with safety verifications

🎯 What Is This?

This repository demonstrates how to apply Spotify's background coding agent concepts to industrial manufacturing environments, based on their three-part blog series.

Spotify's Achievement

1,500+ PRs merged via AI agents
60-90% time savings on migrations
50% of all PRs now automated
Complex migrations: language upgrades, framework changes, config updates

Manufacturing Application

Automate PLC code updates across multiple sites
Safety-critical verification with human oversight
75% time savings on fleet-wide changes
Zero safety incidents with proper safeguards

Key Concepts from Spotify

Fleet Management Architecture: Automated code transformations across thousands of repositories
Context Engineering: Crafting effective prompts with examples, preconditions, and desired end states
Verification Loops: Strong feedback mechanisms with deterministic verifiers and LLM judges

Manufacturing Use Cases

1. Legacy PLC Code Migration

Migrate Ladder Logic to Structured Text
Update Siemens TIA Portal versions
Modernize Allen-Bradley RSLogix to Studio 5000

2. Safety System Updates

Update safety interlocks across production lines
Standardize emergency stop procedures
Implement new regulatory compliance requirements

3. Configuration Management

Update HMI/SCADA configurations
Standardize alarm priorities and descriptions
Update tag databases across multiple sites

4. Production Line Modernization

Migrate from proprietary protocols to OPC UA
Update communication drivers
Standardize data logging configurations

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    Fleet Manager CLI                        │
│  (Orchestrates migrations across manufacturing sites)       │
└────────────────────┬────────────────────────────────────────┘
                     │
                     ▼
┌─────────────────────────────────────────────────────────────┐
│              Background Coding Agent                        │
│  • Claude Code / Custom Agent                               │
│  • Natural Language Prompts                                 │
│  • MCP Tools for PLC/SCADA systems                          │
└────────────────────┬────────────────────────────────────────┘
                     │
        ┌────────────┼────────────┐
        ▼            ▼            ▼
   ┌─────────┐ ┌─────────┐ ┌─────────┐
   │ Site A  │ │ Site B  │ │ Site C  │
   │ PLC     │ │ PLC     │ │ PLC     │
   │ Config  │ │ Config  │ │ Config  │
   └─────────┘ └─────────┘ └─────────┘

Repository Structure

background-coding-agents/
├── README.md                          # This file
├── pyproject.toml                     # Modern Python packaging config
├── .pre-commit-config.yaml            # Quality automation
├── .env.example                       # Environment variable template
├── verify_setup.sh                    # Setup verification script
│
├── src/background_coding_agents/      # Main package (installable)
│   ├── __init__.py
│   ├── agents/                        # Agent implementations
│   │   ├── __init__.py
│   │   └── plc_agent.py              # PLC code transformation agent
│   ├── verifiers/                     # Verification loops
│   │   ├── __init__.py
│   │   ├── plc_compiler_verifier.py  # Compile PLC code
│   │   └── safety_verifier.py        # Safety checks (CRITICAL)
│   ├── fleet_manager/                 # Fleet Management orchestration
│   │   ├── __init__.py
│   │   ├── cli.py                    # Main CLI tool
│   │   └── config.yaml               # Fleet configuration
│   ├── models/                        # Pydantic data models (Phase 1, Week 2)
│   ├── config/                        # Configuration management
│   ├── logging/                       # Structured logging (Phase 2)
│   ├── utils/                         # Utility functions
│   ├── mocks/                         # Production-quality mocks (Phase 5)
│   └── telemetry/                     # MLflow integration (Phase 5)
│
├── tests/                             # Test suite (Phase 3)
│   ├── unit/                          # Unit tests
│   ├── integration/                   # Integration tests
│   └── e2e/                           # End-to-end tests
│
├── prompts/                           # Migration prompts (Spotify-style)
│   ├── safety_interlock_update.md
│   └── protocol_migration.md
│
├── examples/                          # Example implementations
│   └── safety_interlock_update/
│
└── docs/                              # Comprehensive documentation
    ├── spotify-insights.md            # Lessons from Spotify's blogs
    ├── comparison-spotify-vs-manufacturing.md
    ├── implementation-roadmap.md      # Phased rollout plan
    └── diagrams.md                    # Visual architecture

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/mitkox/background-coding-agents.git
cd background-coding-agents

# Run setup script
./setup.sh

# Or manual setup:
python3 -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate
pip install -e ".[dev]"

# Configure for local vLLM (recommended)
cp .env.example .env
# Edit .env - no API keys needed for local deployment!

# Verify installation
./verify_setup.sh
fleet-manager --help

1.5 Start Local LLM (Recommended)

# Install vLLM (if not already installed)
pip install vllm

# Start local inference server
vllm serve minimax-m2.1 --port 8000
# Or: vllm serve THUDM/glm-4.7-chat --port 8000

# Test the fleet manager (dry run)
fleet-manager safety_interlock_update --dry-run

No API keys required! The default configuration uses local vLLM.

2. Understand the Concepts (30 minutes)

# Read the complete guide
cat GUIDE.md

# Or start with the summary
cat PROJECT_SUMMARY.md

# Review Agents Code integration guide
cat AGENTS.md

3. Review Spotify's Approach (20 minutes)

4. Explore the Implementation (30 minutes)

# See the architecture
cat docs/diagrams.md

# Review a migration prompt (Spotify-style)
cat prompts/safety_interlock_update.md

# Understand safety verification
cat src/background_coding_agents/verifiers/safety_verifier.py

# Walk through complete example
cat examples/safety_interlock_update/README.md

5. Development Workflow

# Run linters
ruff check src/
black src/ --check
mypy src/

# Auto-fix linting issues
ruff check src/ --fix
black src/

# Run tests (when implemented)
pytest

# Run pre-commit on all files
pre-commit run --all-files

📁 What's Inside

📚 Documentation (~3,500 lines)

GUIDE.md - Complete implementation guide
docs/spotify-insights.md - All lessons from Spotify's blogs
docs/comparison-spotify-vs-manufacturing.md - Detailed comparison
docs/implementation-roadmap.md - Year 1 phased plan
docs/diagrams.md - Visual architecture

🖥️ Local LLM Deployment (Air-Gapped Ready)

This project prioritizes local LLM deployment for industrial environments:

Why Local First?

✅ Air-gapped environments: No internet required
✅ Data privacy: PLC code stays on-premises
✅ Cost predictability: No per-token API charges
✅ Low latency: Faster than cloud APIs
✅ Compliance: Meets industrial security standards

Supported Providers

Local (Recommended):

vLLM: High-performance inference (minimax-m2.1, GLM-4.7)
llama.cpp: Edge deployment on industrial PCs
No API keys required!

Cloud (Optional):

Anthropic Claude (requires ANTHROPIC_API_KEY)
OpenAI GPT (requires OPENAI_API_KEY)
MiniMax Cloud (requires API key)

Quick Setup

# 1. Install vLLM
pip install vllm

# 2. Start server
vllm serve minimax-m2.1 --port 8000

# 3. Configure (already default in .env.example)
LLM_PROVIDER=vllm
LLM_MODEL=minimax-m2.1
LLM_BASE_URL=http://localhost:8000

# 4. Run fleet manager
fleet-manager safety_interlock_update --dry-run

See AGENTS.md for complete local deployment guide.

🏗️ Architecture

Fleet Manager
    ↓
Background Coding Agent (Claude Code)
    ↓
Verification Loops:
├── 1. PLC Compiler Verifier
├── 2. Safety Verifier ⚠️ (CRITICAL)
├── 3. Simulation Verifier
└── 4. LLM Judge
    ↓
Change Request → Safety Review → Deploy

See docs/diagrams.md for detailed flows.

💡 Key Concepts from Spotify

Part 1: The Journey

Fleet Management for automated code changes
Natural language prompts replace complex scripts
1,500+ PRs merged, 60-90% time savings

Part 2: Context Engineering

6 Prompt Engineering Principles:

Tailor prompts to agent type
State preconditions clearly
Use concrete examples
Define success criteria
Do one change at a time
Keep tools limited

Part 3: Verification Loops

Inner Loop: Fast feedback during execution
Outer Loop: Comprehensive checks before PR
LLM Judge: Catches scope creep
Result: Reliable, predictable output

See docs/spotify-insights.md for complete breakdown.

🔐 Manufacturing Adaptations

Critical Differences

Spotify (Software)	Manufacturing
Failed PR = annoying	Failed safety = catastrophic
Easy rollback	Requires shutdown
Automated testing	Simulation + human review

Safety-First Approach

Automated Verification:

✅ Emergency stop integrity
✅ Safety interlock validation
✅ Guard circuit checks
✅ Dangerous pattern detection
✅ SIL compliance

Human Oversight:

✅ Safety engineer review (mandatory)
✅ Test environment validation
✅ Production approval process

See docs/comparison-spotify-vs-manufacturing.md for details.

📈 Use Cases & ROI

Example 1: Safety Interlock Update

Task:     Update 50 sites to ISO 13849-1:2023
Manual:   400 hours ($40K)
Agent:    102 hours ($15K)
Savings:  75% time, 63% cost
Quality:  100% consistency (vs ~80% manual)

Example 2: Protocol Migration

Task:     Modbus TCP → OPC UA (30 sites)
Manual:   300 hours ($30K)
Agent:    90 hours ($14K)
Savings:  70% time, 53% cost
Benefit:  Security, Industry 4.0 ready

Example 3: Configuration Standardization

Task:     Alarm priorities fleet-wide
Manual:   50 hours
Agent:    10 hours
Savings:  80%
Risk:     Low, immediate value

See GUIDE.md for detailed ROI calculator.

📋 Implementation Roadmap

Year 1 Phased Approach

Phase	Duration	Investment	ROI	Description
Phase 0	1 month	$75K	-	Prerequisites, infrastructure
Phase 1	2 months	$20K	-25%	Proof of concept (5 sites)
Phase 2	3 months	$80K	38%	Foundation (20 sites)
Phase 3	3 months	$100K	40%	Safety-critical (10 sites)
Phase 4	3 months	$150K	133%	Fleet-wide (50+ sites)
Total	12 months	$425K	65%	Full implementation

Year 2 Projection: $100K investment → 500% ROI

See docs/implementation-roadmap.md for complete plan.

🎓 Learning Paths

For Decision Makers (1 hour)

PROJECT_SUMMARY.md - Overview
GUIDE.md - ROI sections
docs/implementation-roadmap.md - Budget & timeline

For Engineers (3 hours)

GUIDE.md - Complete guide
docs/spotify-insights.md - All Spotify lessons
examples/safety_interlock_update/README.md - Walkthrough

For Safety Engineers (2 hours)

verifiers/safety_verifier.py - What's checked
docs/comparison-spotify-vs-manufacturing.md - Safety focus
examples/safety_interlock_update/README.md - Review process

See FILE_INDEX.md for complete navigation guide.

🔍 Key Files

Must Read

GUIDE.md - Start here for complete understanding
PROJECT_SUMMARY.md - Quick overview
FILE_INDEX.md - Navigation by role/topic

Deep Dives

docs/spotify-insights.md - Every lesson from Spotify
docs/comparison-spotify-vs-manufacturing.md - Detailed comparison
docs/implementation-roadmap.md - Execution plan

Examples

prompts/safety_interlock_update.md - Spotify-style prompt
examples/safety_interlock_update/README.md - Complete walkthrough
verifiers/safety_verifier.py - Safety implementation

⚠️ Safety & Compliance

Non-Negotiable Requirements

Mandatory Safety Verifier - Always runs, never skipped
Human Safety Review - Required for all safety-critical changes
Simulation Testing - Before any hardware deployment
Staged Rollouts - Test → Validate → Deploy
Audit Trail - Complete documentation of all changes

Verification Layers

Change Request
    ↓
① Compiler Check (syntax, structure)
    ↓
② Safety Check (emergency stops, interlocks, guards)
    ↓
③ Simulation Test (runtime behavior)
    ↓
④ LLM Judge (scope + safety compliance)
    ↓
⑤ Human Safety Review (mandatory approval)
    ↓
Production Deployment

Result: Zero safety incidents with proper process

📚 Based On

Spotify Engineering Blogs

Technologies

Local LLMs - vLLM, llama.cpp for air-gapped deployment (recommended)
Cloud LLMs - Anthropic Claude, OpenAI GPT, MiniMax (optional)
Model Context Protocol (MCP) - Tool interface for agents
Pydantic - Type-safe configuration with .env support
structlog - Structured JSON logging

Standards

ISO 13849-1 - Safety of machinery
IEC 61508 - Functional safety
IEC 62443 - Industrial cybersecurity

🚦 Getting Started

Immediate (Today)

# Clone repository
git clone [this-repo]
cd background-coding-agents

# Read overview
cat PROJECT_SUMMARY.md

# Review architecture
cat docs/diagrams.md

This Week

# Complete guide
cat GUIDE.md

# Spotify lessons
cat docs/spotify-insights.md

# Example walkthrough
cat examples/safety_interlock_update/README.md

This Month

# Implementation planning
cat docs/implementation-roadmap.md

# Adapt to your environment
# - List your PLC types
# - Identify pain points  
# - Calculate ROI
# - Prepare pilot proposal

� Recent Updates

December 2025

✨ Local vLLM Integration (v0.2.0)

Switched to local vLLM as primary deployment target
No API keys required for default configuration
Air-gapped deployment ready out of the box
Cloud providers now optional

🐛 Agent Reliability Fixes

Fixed NoneType iteration errors in LLM response handling
Added graceful fallbacks for empty/None responses
Improved error handling in discovery and planning phases

⚙️ Configuration Improvements

Environment variables properly override YAML config
.env file support via pydantic-settings
Fixed fleet-manager entry point async/sync issues

See AGENTS.md for complete technical documentation.

�💬 Summary

This repository demonstrates how Spotify's proven approach (1,500+ PRs, 60-90% time savings) can be adapted for industrial manufacturing with appropriate safety and compliance layers.

Key Takeaways

✅ Proven at scale - Spotify shows it works (1,500+ PRs)
✅ High ROI - 65% Year 1, 500% Year 2
✅ Safety first - Multiple verification layers
✅ Phased adoption - Start small, scale gradually
✅ Zero compromise - Full safety and compliance maintained

Expected Results

Time Savings: 70-75% on fleet-wide migrations
Consistency: 100% identical implementation
Testing: Comprehensive before deployment
Safety: Zero incidents with proper safeguards

📧 Next Steps

Choose your path:

👔 Decision Maker? → PROJECT_SUMMARY.md → docs/implementation-roadmap.md

👨‍💻 Engineer? → GUIDE.md → docs/spotify-insights.md

⚠️ Safety Engineer? → verifiers/safety_verifier.py → docs/comparison-spotify-vs-manufacturing.md

📋 Project Manager? → docs/implementation-roadmap.md → examples/safety_interlock_update/README.md

Ready to transform your manufacturing maintenance?

Start with GUIDE.md for the complete picture, or jump to FILE_INDEX.md for navigation by role.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
agents		agents
docs		docs
examples/safety_interlock_update		examples/safety_interlock_update
fleet-manager		fleet-manager
prompts		prompts
src/background_coding_agents		src/background_coding_agents
verifiers		verifiers
.env.example		.env.example
.gitignore		.gitignore
.pre-commit-config.yaml		.pre-commit-config.yaml
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
fleet-manager-cli		fleet-manager-cli
pyproject.toml		pyproject.toml
requirements.txt		requirements.txt
setup.sh		setup.sh
verify_setup.sh		verify_setup.sh

License

mitkox/background-coding-agents

Folders and files

Latest commit

History

Repository files navigation