Design-Control-Loop Skill: The Eight-Phase Sequence and Handoff Criteria Explained

The design-control-loop skill guides users through an eight-phase sequence (A–H) where each phase has measurable handoff criteria—from understanding repository architecture to validating CI workflows—that must be satisfied before advancing.

The design-control-loop skill in the humanlayer/skills repository provides a structured framework for implementing agentic control loops that autonomously manage codebases. Organized into eight sequential phases, this methodology ensures that every control loop component is observable, bounded, and reviewable through concrete, verifiable handoff criteria defined in the skill's source documentation.

The Eight-Phase Sequence (A–H)

The plugins/design-control-loop/skills/design-control-loop/SKILL.md file defines the complete eight-phase journey. Each phase must satisfy specific completion criteria before the skill proceeds to the next phase.

Phase A – Understand the System

In this initial phase, you gather comprehensive repository context including CI setup, package managers, existing validation scripts, current agent loops, and overall system architecture.

Handoff criterion: You can name the repository’s package manager, install command, likely validation commands, CI platform, and any existing loop conventions. You understand the packages, services, and applications at a high level.

Phase B – Design the Loop with the User

This phase involves conducting a structured interview to define the five core control-loop components: the set point, sensor, controller, actuator, and disturbances/dampener. The design must be recorded in writing.

Handoff criterion: A short written design document naming the set point, sensor, controller, actuator (agent + skill + validation), and disturbances/dampener—each component must be runnable locally.

Phase C – Build the Actuator Skill

Create a repository-local skill (SKILL.md) that instructs the coding agent how to act. This skill embeds golden patterns and includes a response template for consistent execution.

Handoff criterion: The skill explains the job clearly enough that the agent can operate unattended, including explicit instructions for formatting its final response.

Phase D – Make Each Component Runnable Locally

Deliver the sensor, controller, and actuator as independent commands or scripts. Verify they function correctly through manual execution before any CI orchestration attempt.

Handoff criterion: The user can run sensor, controller, and actuator locally and independently without errors.

Phase E – Wire the Loop into CI

Assemble a recurring workflow—typically using GitHub Actions—that orchestrates the sequence: sensor → controller → actuator. Configure the cadence and inject memory persistence.

According to the references/workflow-template.yml, the workflow should support both scheduled runs and manual triggers:

name: Design-Control-Loop
on:
  workflow_dispatch:
  schedule:
    - cron: '0 2 * * *'   # daily at 02:00 UTC

jobs:
  loop:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Run sensor
        run: ./scripts/sensor.sh
      - name: Run controller
        run: ./scripts/controller.sh
      - name: Run actuator
        run: ./scripts/actuator.sh

Handoff criterion: The workflow can run from workflow_dispatch without relying on files that do not exist.

Phase F – Put a Human on the Loop

Add persistent feedback mechanisms through a memory file and implement an optional /iterate PR command. This allows human reviewers to steer future autonomous runs by providing standing feedback that survives between executions.

Handoff criterion: Standing feedback survives between runs, and /iterate (if enabled) updates the existing PR rather than creating duplicates.

Phase G – Flow Control

Enforce PR-bounding to limit the number of open pull requests the loop can generate at any time. This prevents unbounded resource consumption and review backlog.

Handoff criterion: Scheduled runs no-op when the open-PR bound for this loop is already met.

Phase H – Validate, Dry-Run, and Iterate Faster

Validate the workflow YAML structure, perform a dry-run execution, and then iterate by increasing cadence or batch size once the loop demonstrates stability.

Handoff criterion: The workflow YAML parses successfully, all referenced files exist, and the loop has produced at least one reviewed PR.

Implementation Artifacts and Source Files

The humanlayer/skills repository contains several reference materials that implement these phases:

Skill Definition and Phase Guide

The complete eight-phase layout and handoff criteria are documented in plugins/design-control-loop/skills/design-control-loop/SKILL.md. This file serves as the primary interface for the skill, defining what must be accomplished at each stage.

Control-Loop Taxonomy Reference

The plugins/design-control-loop/skills/design-control-loop/references/control-loop-taxonomy.md file explains the theoretical foundation of the four core components (set point, sensor, controller, actuator) and provides design questions for Phase B.

Example Implementation

For a concrete walkthrough, see plugins/design-control-loop/skills/design-control-loop/references/example-control-loop.md, which demonstrates the eight phases applied to a real-world scenario.

CI Workflow Template

The plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml provides the skeleton YAML structure used in Phase E, showing how to orchestrate the sensor, controller, and actuator within GitHub Actions.

Summary

• The design-control-loop skill divides control-loop implementation into eight sequential phases (A–H) with concrete, measurable handoff criteria.
• Phase A requires understanding the repository's package management and CI setup, while Phase B mandates a written design document naming all five control-loop components.
• Phase C focuses on creating the actuator skill (SKILL.md), and Phase D ensures all components run locally before CI integration.
• Phase E wires the loop into CI (typically GitHub Actions), Phase F adds human feedback mechanisms, and Phase G enforces PR-bounding to prevent resource exhaustion.
• Phase H requires YAML validation, dry-run success, and at least one reviewed PR before increasing operational cadence.

Frequently Asked Questions

What are the five core components defined in Phase B of the design-control-loop skill?

The five core components are the set point (target state), sensor (measures current state), controller (decides actions), actuator (agent + skill that executes changes), and disturbances/dampener (external factors or safety controls). According to the control-loop-taxonomy.md reference, each component must be runnable locally before proceeding to Phase C.

How does the handoff criterion for Phase E differ from Phase D?

Phase D requires that the sensor, controller, and actuator run locally and independently as standalone scripts or commands. Phase E requires integrating these components into a CI workflow (typically via workflow_dispatch in GitHub Actions) where the orchestration logic must execute without referencing non-existent files.

Where can I find the concrete YAML template for implementing Phase E?

The workflow skeleton resides in plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml within the humanlayer/skills repository. This template demonstrates the sensor → controller → actuator orchestration pattern and includes both workflow_dispatch for manual triggers and schedule for automated cadence.

What prevents the design-control-loop from creating too many pull requests?

Phase G (Flow Control) implements PR-bounding, where the handoff criterion requires that scheduled runs no-op when the open-PR bound for the specific loop is already met. This ensures the loop remains bounded and does not overwhelm reviewers with unlimited concurrent pull requests.

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