Control-Theory Mental Model Documentation in the Design-Control-Loop Skill

The control-theory mental model for the design-control-loop skill is documented in control-loop-taxonomy.md and SKILL.md, located in the humanlayer/skills repository under the plugins/design-control-loop/skills/design-control-loop/ path.

The design-control-loop skill in the HumanLayer skills repository treats software repositories as dynamic systems governed by feedback loops. By applying classic control-theory concepts, the skill creates an agentic control loop that continuously measures, compares, and adjusts codebase states. The complete mental-model description spans two primary reference files that map control-theory terminology to software engineering workflows.

Primary Documentation Files

The control-theory mental model is split between the skill definition and the detailed taxonomy.

SKILL.md: The Entry Point

Located at plugins/design-control-loop/skills/design-control-loop/SKILL.md, this file introduces the mental model in the "The mental model" section. It provides a high-level workflow overview and directs practitioners to the taxonomy file for deeper architectural study. This document serves as the primary entry point for understanding how the skill conceptualizes autonomous code maintenance.

control-loop-taxonomy.md: The Deep Reference

The complete technical specification lives in plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md. This file defines the five core components of the feedback system and includes a Mermaid diagram illustrating the feedback flow between them. Lines 66-76 of this file contain specific design questions that ensure the resulting loop remains observable, bounded, and reviewable.

The Five Components of the Control Loop

The taxonomy treats the codebase as a dynamic system with five interacting components:

• Set point: The desired target state (e.g., "test coverage ≥ 80%").
• Sensor: Measures the current state and quantifies the gap between reality and the set point.
• Controller: Transforms the measurement into a concrete, executable next step.
• Actuator: A coding agent (such as Claude or Codex) that applies the change and opens a pull request.
• Disturbance: External factors—such as team commits, dependency updates, or previously generated code—that push the system away from the set point.

Together, these components create a closed-loop system where the sensor continuously feeds the controller information about the gap, and the actuator works to minimize that gap despite ongoing disturbances.

Implementing the Mental Model

The taxonomy provides theoretical grounding, but the skill includes concrete implementation patterns for each component.

Visualizing the Feedback Loop

The control-loop-taxonomy.md file contains the following Mermaid diagram that illustrates how signals flow through the system:

flowchart LR
  SetPoint[Set point] --> Compare((Compare))
  Measured[Measured output] --> Compare
  Compare --> Error[Measured error]
  Error --> Controller[Controller]
  Controller --> Actuator[Actuator]
  Actuator --> System[System / Repository]
  Disturbance[Disturbance] --> System
  System --> Output[System output]
  Output --> Sensor[Sensor]
  Sensor --> Measured

Sensor Implementation

The sensor acts as the measurement device. An illustrative sensor script might use static analysis tools to report the current state:

#!/usr/bin/env node

# sensor.js – example placeholder for a static-analysis sensor

npx eslint . --format json | jq '.[] | {file:.filePath, errors:.messages|length}'

This script outputs structured data that the controller can consume to determine the next action.

Controller Logic

The controller processes sensor output to select targets. A minimal TypeScript controller demonstrates deterministic selection:

// controller.ts – deterministic controller example
import { readFileSync } from "fs";

type Finding = { file: string; errors: number };
const findings: Finding[] = JSON.parse(readFileSync("sensor-output.json", "utf8"));
const target = findings.find(f => f.errors > 0);
if (target) console.log(`Patch ${target.file}`); else console.log("No work");

This component bridges the gap between raw measurement and actionable work items.

Actuator Configuration

The actuator executes the actual work. A GitHub Actions workflow excerpt shows how to invoke a coding agent as an actuator:

# .github/workflows/control-loop.yml (excerpt)

jobs:
  act:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run Claude Code
        run: |
          claude-code apply --target ${{ steps.select.outputs.file }} \
            --prompt "@./references/prompt-template.md" \
            --output /tmp/pr-body.md

This pattern demonstrates how the control loop integrates with CI/CD infrastructure to create autonomous pull requests.

Complete Reference File Structure

Beyond the primary taxonomy and skill definition, the humanlayer/skills repository contains several supporting reference files:

File	Purpose	Link
SKILL.md	Skill definition, workflow overview, and mental model entry point.	SKILL.md
control-loop-taxonomy.md	Full control-theory taxonomy, component definitions, design questions, and feedback diagram.	control-loop-taxonomy.md
example-control-loop.md	Worked example of a complete production-ready loop.	example-control-loop.md
agent-runner-templates.md	Templates for invoking various coding agents (Claude, Codex, GPT-4).	agent-runner-templates.md
workflow-template.yml	Skeleton GitHub Actions workflow connecting all components.	workflow-template.yml

Summary

• The control-theory mental model for the design-control-loop skill is defined in SKILL.md and detailed in control-loop-taxonomy.md within the humanlayer/skills repository.
• The model consists of five components: set point, sensor, controller, actuator, and disturbance.
• Design questions in the taxonomy file (lines 66-76) ensure loops are observable, bounded, and reviewable.
• The Mermaid diagram in control-loop-taxonomy.md provides a visual reference for signal flow.
• Supporting files include implementation templates for sensors, controllers, and actuators that transform theory into autonomous workflows.

Frequently Asked Questions

Where exactly is the control-theory mental model documented in the repository?

The documentation is split between two locations in the humanlayer/skills repository. The high-level introduction resides in plugins/design-control-loop/skills/design-control-loop/SKILL.md, while the complete technical specification—including component definitions and design questions—is located at plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md.

What distinguishes the sensor from the actuator in this mental model?

The sensor is a read-only component that measures the current state of the system (such as test coverage or lint errors) and reports the gap between reality and the set point. The actuator is a write-capable agent that modifies the system state, typically by generating code changes and opening pull requests. The sensor observes; the actuator alters.

Can this control loop work with AI agents other than Claude?

Yes. While the examples reference Claude Code, the agent-runner-templates.md file provides adapter patterns for various coding agents including OpenAI Codex and GPT-4. The control-theory mental model is agent-agnostic; the actuator component can invoke any tool capable of applying patches to the repository.

Why does the taxonomy include a "disturbance" component?

The disturbance component acknowledges that software repositories are not closed systems. External factors—such as human commits, dependency updates, or infrastructure changes—continuously push the codebase away from the desired set point. Explicitly modeling disturbances ensures the control loop accounts for environmental chaos rather than assuming static conditions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}