Loop Engineering

The engineering discipline of systems that self-improve through feedback.

Not prompt tricks. Not single agents. Closed loops — observe, act, evaluate, update, repeat — made structured, measurable, comparable, and engineerable.

Read the Manifesto · Explore Patterns · Run the Stack · Onboarding Paths

---

The Paradigm Shift

Era	Focus	Optimized Unit	Cognitive Ceiling
2020–2023	Prompt Engineering	Single turn, in-context cues	No closure, state loss
2023–2024	Context Engineering	Static retrieval-augmented memory	Unchanged parameters, no iteration
2024–2025	Agent Engineering	Autonomous delegation & tools	No systemic evaluation, feedback-blind
2025+	Loop Engineering	Closed dynamical feedback loops	Unbounded, self-directed systems

The Hierarchy of Optimization:

• Prompt engineering optimizes a single interaction.
• Agent engineering optimizes an autonomous actor.
• Loop engineering optimizes the entire closed system to get better over time through feedback.

North Star: Loop Engineering provides the default, interoperable stack to declare, run, score, and integrate feedback loops across Claude Code, Codex, LangGraph, CrewAI, Cursor, and more. → contributions/NORTH_STAR.md

Quick Install:

pip install "le-loop-stack>=0.1.0"

---

Core Ecosystem Pillars

Pillar	Focus Area	Key Artifacts
Theory	Foundational conceptual rigor	13 Fundamentals · 6-Level Taxonomy · 14 Design Patterns
Method	Closed-loop lifecycle governance	D-D-M-I-S Framework (Design, Diagnose, Measure, Improve, Scale)
Standards	Interoperable specification models	LSS 1.0 (Loop Specification Schema) · LES 1.0 (Loop Effectiveness Score)
Evidence	Real-world validation & history	Case Studies (AlphaGo, Toyota TPS, PR pipelines, coding agents)
Runtime	Execution, scoring, and benchmarks	Dataset registries, replay sandboxes, and the public scorecard

This repository serves as the narrative and theoretical home for the loop engineering movement. Machine-readable specifications and governance rules live in the canonical Loop Core Engineering repository.

---

The Published Stack

Everything below is live, synchronized, and published across GitHub and PyPI. Version registry: ECOSYSTEM_VERSIONS.md.

flowchart TD
  classDef primary fill:#18181b,stroke:#27272a,stroke-width:2px,color:#ffffff;
  classDef highlight fill:#f4f4f5,stroke:#18181b,stroke-width:2px,color:#18181b;
  classDef standard fill:#ffffff,stroke:#e4e4e7,stroke-width:1.5px,color:#18181b;

  DOCS[["◆ Loop Engineering <br/>(You are here)<br/>Manifesto · Patterns · Case Studies"]]:::primary
  FORGE["⚙ LoopForge<br/>pip install le-loopforge"]:::standard
  CTL["loopctl CLI<br/>pip install le-loopctl"]:::standard
  CORE[["◆ Loop Core Engineering<br/>LSS Spec · LES Spec · Validators"]]:::highlight
  NET[("■ LoopNet v0.2<br/>545 trajectories")]:::standard
  GYM["◆ LoopGym<br/>pip install loopgym"]:::standard
  BENCH["▲ LoopBench<br/>pip install loopbench"]:::standard

  DOCS --> FORGE
  FORGE --> CTL
  FORGE --> CORE
  CORE --> NET
  CORE --> GYM
  NET --> GYM
  GYM --> BENCH
  CORE --> BENCH
  FORGE --> GYM

Loading

Repository	Focus	Purpose & Links
LoopForge	Creation	Scaffold valid LSS specs from patterns · loopforge/ · pip install le-loopforge · loopctl · Golden Path
Loop Core Engineering	Specs & Governance	The constitutional foundation, schemas, and validators · GitHub →
LoopNet	Dataset	Ground truth loop executions and trajectories · GitHub → · Hugging Face →
LoopGym	Runtime	Sandboxed simulation environment to run and replay loops · GitHub → · pip install loopgym
LoopBench	Benchmarks	Continuous, public community scoreboard · GitHub → · pip install loopbench

• ◆ Complete Install Map: ECOSYSTEM.md
• ◆ Ecosystem Governance: CANONICAL-SOURCE.md
• ◆ PyPI Registry Naming Rules: PYPI_NAMING.md

---

The Loop, Formally

Every loop is structured as a closed dynamical system:

       Observe
          │
          ▼
        Decide
          │
          ▼
         Act
          │
          ▼
       Evaluate
          │
          ▼
     Update State
          │
          └───────────(repeat)───────────► [Observe]

Mathematically formalized as: $$\mathcal{L} = (S, A, O, T, E, M, \tau)$$

Where:

• $\mathbf{S}$ : State space of the system
• $\mathbf{A}$ : Action space of the loop workers
• $\mathbf{O}$ : Observation space (feedback signals)
• $\mathbf{T}$ : Transition functions ($S \times A \to S$)
• $\mathbf{E}$ : Evaluator models (generates scores & rewards)
• $\mathbf{M}$ : Memory representation (episodic & parameter state)
• $\mathbf{\tau}$ : Termination conditions & criteria

→ Detailed breakdown: What is a loop?

Declaring Loops in LSS (Loop Specification Schema)

LSS provides a declarative, machine-readable format to define the architecture, inputs, and constraints of any loop.

loop_name: code-repair-loop
version: "1.0"
objective: "Fix failing tests with minimal diff"
workers:
  - role: implementer
evaluators:
  - type: test_suite
termination_conditions:
  - type: all_tests_pass
  - type: max_iterations
    value: 10

→ LSS 1.0 Specification

---

Building with Agent Harnesses

You do not need to replace your existing agent stack. Map your existing agent loop, monitor its trajectories, and benchmark its performance in minutes.

Harness / Platform	Integration Guide	Target Framework
Claude Code	integrate/CLAUDE_CODE.md	Anthropic CLI agent
OpenAI Codex	integrate/CODEX.md	Codex code models
LangGraph	examples/integrate-langgraph/	LangChain Graphs
CrewAI	examples/integrate-crewai/	Role-playing Multi-agent swarms
Cursor	integrate/CURSOR.md	Cursor IDE Composer & Agent
OpenAI Agents SDK	integrate/OPENAI_AGENTS.md	OpenAI Swarm/Agents
Aider	integrate/AIDER.md	CLI git-integrated coding agent
Gemini CLI	integrate/GEMINI_CLI.md	Google Generative AI

→ View Full Integration Hub

Run your first scored loop:

# Install the complete stack
pip install "le-loop-stack>=0.1.0"

# Scaffold a loop spec from an English description
loopforge intent "Create a code-repair loop with a test-runner evaluator" -o mapped.yaml --suggest-level

# Score your loop spec on the 8 LES dimensions
loopctl score --spec mapped.yaml --json

---

Onboarding Paths

Profile	Recommended Onboarding Path	Expected Time
The Theorist	Manifesto → Fundamentals	~2 hours
The Builder	Golden Path v3 → pip install le-loop-stack → Integration Hub	~15 min
The Practitioner	Loop Playground → Live Leaderboard	~30 min
The Researcher	Paper Series → LoopNet v0.2 → Case Studies	~1 day
The Architect	D-D-M-I-S Framework → LES scoring	~2 hours

---

Repository Architecture

Path	Purpose	Key Artifacts
manifesto/	Founding Principles	The philosophy and paradigm of loop engineering
fundamentals/	Core Theory	13-topic detailed theoretical foundation of self-improving systems
taxonomy/	Classification	Six-level loop classification taxonomy
patterns/	Design Patterns	14 engineering patterns described as reusable LSS specs
framework/	Methodology	D-D-M-I-S procedural guide for building and deploying loops
case-studies/	Historical Evidence	Analyses of AlphaGo, Toyota TPS, GitHub PR engines, and coding loops
loop-library/	Spec Library	Production-grade reference loop YAML files
loopforge/	Creation Tools	Interactive scaffolding tools to map intents to LSS specs
implementations/	Code Examples	Minimal reference implementations in Python, LangGraph, and CrewAI
research/	Research Frontier	Active open problems, roadmaps, and paper series

---

Reference Loop Library

A preview of pre-declared loops available in loop-library/:

Reference Spec	Level	Intent / Target Use Case
Research Agent	Level 2	Literature review & multi-source synthesis
Coding Agent	Level 3	Autonomous software feature implementation
Autonomous Debugger	Level 3	Test-driven localized software repair
Code → Debug (nested)	Level 4	Coding loop with nested recursive debugging
Scenario Swarm (parallel)	Level 4	SWARM decision rehearsal: 3 parallel perspectives with a unified merged forecast
Startup Validator	Level 2	PMF hypothesis verification and fast lean iterations

→ Browse the Full Spec Library · Master Checklist · Next Steps

---

Ecosystem Toolchain

Unified tools to speed up loop design, execution, validation, and benchmarking.

Tool	Purpose	Source / Usage
loopctl	Unified CLI tool	tools/loopctl.py · Validate, score, level, and diagram LSS specs
loopforge	Spec generator	loopforge/ · Scaffold complete LSS YAML files from text-based intents
loop_validator	Schema validator	tools/loop_validator.py · Local LSS schema verification
daily_checkin	Automated reporter	scripts/daily_checkin.py · Continuous deployment checks
loop_diagram_generator	Visualizer	tools/loop_diagram_generator.py · Auto-generate clean Mermaid diagrams from LSS YAML

---

Join the Community

We welcome contributions to LSS specs, new agent harnesses, case studies, benchmarks, and core tooling.

• ◆ Loop Playground — Create and test your first loop in the sandbox.
• ◆ Community Spotlight — Highlighted community loops and implementations.
• ◆ Reproduction Challenge — Replicate verified benchmark scores.
• ◆ Contributor Guidelines · Governance Model · Reproduction Manual

---

Citation

@misc{loop-engineering-2026,
  title={Loop Engineering: The Discipline of Self-Improving Systems},
  author={Loop Engineering Community},
  year={2026},
  url={https://github.com/KanakMalpani/Loop-Engineering}
}

Feedback is the fundamental unit of intelligence.
Loop Engineering makes it engineerable.

_{MIT License}