How to Use Composite GitHub Actions in build‑iterated‑agentic‑loop and design‑control‑loop for Reusable YAML

Both plugins implement a three‑stage reusable workflow pattern—gating, environment setup, and PR management—that enables deterministic, context‑aware agentic automation across repositories.

The humanlayer/skills repository provides two powerful plugins—build‑iterated‑agentic‑loop and design‑control‑loop—that automate code generation and system design through AI agents. Instead of duplicating CI logic, both plugins follow an identical composite GitHub Actions pattern that packages the entire agent lifecycle into a single reusable workflow file. This architecture allows downstream repositories to invoke complex agentic pipelines with just a few lines of YAML.

The Three‑Stage Composite Pattern

Both build‑iterated‑agentic‑loop and design‑control‑loop rely on the same architectural recipe expressed in their respective workflow‑template.yml files. The pattern divides execution into three discrete stages that handle routing, runtime, and artifact management.

Stage 1: Gate and Routing

The workflow begins by determining whether the run should proceed. In plugins/build‑iterated‑agentic‑loop/skills/build‑iterated‑agentic‑loop/references/workflow‑template.yml (lines 44‑84), the "Check iterate marker" step inspects github.event_name to distinguish between scheduled runs, manual triggers, and PR comments beginning with /iterate.

• For schedule or workflow_dispatch events, the gate immediately returns run_agent=true.
• For issue_comment events, the step verifies the comment starts with /iterate, checks the author permissions, and queries the PR body via gh api to locate the hidden marker <!-- codelayer-agent:workflow=… -->.
• The step writes run_agent=true|false to the job output, which subsequent steps use as a conditional guard.

This gating logic is identically implemented in plugins/design‑control‑loop/skills/design‑control‑loop/references/workflow‑template.yml (lines 45‑84), ensuring consistent behavior across both plugins.

Stage 2: Execution Environment

All setup steps are guarded by if: steps.agent_gate.outputs.run_agent == 'true', preventing unnecessary compute when the gate fails. This stage (lines 85‑105 in both templates) performs the following:

1. Code checkout using actions/checkout@v5 with a dynamic ref parameter for iterations.
2. Git configuration to set user identity and switch to the correct branch.
3. Runtime installation of bun and Node.js, caching ~/.bun/install/cache between runs.
4. Dependency installation via bun install --frozen-lockfile.
5. Agent invocation using bunx @humanlayer/cli@latest codelayer to execute the coding or design task.

By standardizing the environment inside the composite action, downstream repositories do not need to manage bun or Node versions themselves.

Stage 3: Post‑Processing and PR Management

The final stage (lines 107‑159) transforms the agent’s raw output into repository changes. The workflow strips ANSI escape codes and writes the cleaned output to /tmp/pr‑body.md.

• New runs create a dedicated branch, append the hidden workflow marker via .github/scripts/agent‑iteration.ts, push the branch, and open a labeled PR.
• Iterate runs detect the existing PR via the marker, commit changes directly to that branch, and post a follow‑up comment summarizing the new output.
• Artifact upload uses actions/upload‑artifact@v4 to persist the raw agent log for debugging.

The hidden HTML comment marker guarantees that a /iterate command on a PR reaches the exact workflow instance that created it, even when multiple agents run concurrently in the same repository.

Key Implementation Files

The composite pattern is defined across these specific files in the humanlayer/skills repository:

Plugin	File Path	Purpose
build‑iterated‑agentic‑loop	plugins/build‑iterated‑agentic‑loop/skills/build‑iterated‑agentic‑loop/references/workflow‑template.yml	Reusable workflow implementing the gated agent loop for code generation.
design‑control‑loop	plugins/design‑control‑loop/skills/design‑control‑loop/references/workflow‑template.yml	Reusable workflow for sense‑control‑actuation loops, adaptable to sensor and controller steps.
Shared helper	.github/scripts/agent‑iteration.ts	TypeScript utility that constructs iteration prompts and injects the hidden <!-- codelayer-agent:workflow=… --> marker into PR bodies.

How to Invoke the Reusable Workflow

Downstream repositories consume these composite actions using the workflow_call syntax. Reference the specific plugin workflow in your caller file:

# .github/workflows/agent.yml

name: Run Build Iterated Agent

on:
  workflow_dispatch:
  schedule:
    - cron: "0 13 * * *"

jobs:
  agent:
    uses: humanlayer/skills/.github/workflows/build-iterated-agentic-loop.yml@main
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

To pass custom inputs—such as a target path for the design control sensor—expose them in the caller and forward them to the composite action:

# .github/workflows/custom-design-agent.yml

name: Custom Design Loop

on:
  workflow_dispatch:
    inputs:
      target_path:
        description: "Path or package to focus on"
        required: false

jobs:
  agent:
    uses: humanlayer/skills/.github/workflows/design-control-loop.yml@main
    with:
      target_path: ${{ github.event.inputs.target_path }}
    secrets:
      ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

For manual iteration, comment on an existing agent‑created PR:

/iterate please improve the error handling and add unit tests

The composite workflow detects the comment, validates the hidden marker, and executes only the iteration branch—updating the existing PR rather than spawning a new one.

Why This Pattern Works

Single source of truth – All heavy lifting lives in one file per plugin; consumers inherit updates automatically by pinning to a tag or branch.

Explicit gating – The early exit in Stage 1 prevents wasteful checkout and build minutes when a comment does not belong to the specific agent workflow.

Deterministic routing – The hidden HTML marker embedded by agent‑iteration.ts creates an unambiguous link between a PR and its parent workflow, eliminating collisions in multi‑agent environments.

Environment agnostic – By provisioning bun and Node.js internally, the composite action imposes no runtime requirements on the calling repository beyond a standard GitHub Actions runner.

Summary

• Both build‑iterated‑agentic‑loop and design‑control‑loop expose a reusable workflow defined in references/workflow‑template.yml.
• The pattern separates concerns into gate/routing, execution environment, and PR management stages.
• The gate step outputs a boolean condition that guards all expensive operations, saving CI resources.
• Hidden HTML markers in PR bodies enable reliable round‑tripping between agent runs and human /iterate commands.
• Downstream repositories invoke the logic via uses: humanlayer/skills/.github/workflows/{plugin}.yml@main without duplicating setup steps.

Frequently Asked Questions

What is the purpose of the hidden marker comment?

The hidden HTML comment—formatted as <!-- codelayer-agent:workflow=… -->—is injected into PR bodies by .github/scripts/agent‑iteration.ts. It stores metadata identifying which workflow file created the PR, ensuring that when a maintainer writes /iterate, the gate step can route the command back to the correct reusable workflow instance even if multiple agents are active.

How does the gate step prevent unnecessary CI runs?

The "Check iterate marker" step runs first and sets an output variable run_agent to 'false' whenever the triggering event is an irrelevant comment or lacks the proper authorization. All subsequent steps include if: steps.agent_gate.outputs.run_agent == 'true', causing the workflow to skip checkout, dependency installation, and agent execution. This design minimizes compute usage for non‑agent comments.

Can I customize the agent environment or inputs?

Yes. The reusable workflows accept inputs defined in their workflow_call interfaces. You can pass repository‑specific variables—such as target paths, model selections, or feature flags—when invoking the workflow with the with: keyword. The templates consume these inputs during the codelayer CLI invocation.

Which file contains the actual reusable workflow definition?

The composite action logic resides in the references/workflow‑template.yml file within each plugin directory. For build‑iterated‑agentic‑loop, the path is plugins/build‑iterated‑agentic‑loop/skills/build‑iterated‑agentic‑loop/references/workflow‑template.yml. For design‑control‑loop, use plugins/design‑control‑loop/skills/design‑control‑loop/references/workflow‑template.yml. These files are referenced by the caller workflows in the .github/workflows/ directory of the humanlayer/skills repository.

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