What is the Purpose of /iterate PR Comments in Loop Skills?

The /iterate comment serves as a control signal that routes maintainer feedback to the specific workflow instance that created a pull request, enabling continuous refinement of code without spawning new PRs.

The humanlayer/skills repository implements loop skills—agentic coding workflows that generate pull requests and iteratively improve them based on human direction. These workflows, documented in plugins/build-iterated-agentic-loop/skills/build-iterated-agentic-loop/SKILL.md and plugins/design-control-loop/skills/design-control-loop/SKILL.md, rely on /iterate PR comments to transform static pull requests into living conversation threads. When a maintainer posts a comment beginning with /iterate, the system triggers a new execution cycle that gathers the full PR context, invokes the LLM agent, and commits updates directly to the existing branch.

Control Signal Routing Through Hidden Markers

When a loop skill such as design-control-loop or build-iterated-agentic-loop creates a PR, it embeds a hidden marker in the PR body that ties the artifact to its originating workflow instance. This marker enables the system to route subsequent comments to the correct workflow even when multiple agents operate simultaneously in the same repository.

The Hidden Marker System

According to the humanlayer/skills source code, the PR body contains an HTML comment marker with the exact format:

<!-- codelayer-agent:workflow=<id>;memory=<path>;… -->

This hidden marker persists in the PR description and contains the workflow identifier and path to the persistent memory file. The marker ensures that when a maintainer subsequently comments on the PR, the system can extract the workflow ID and memory location necessary to reconstruct the agent's context.

Workflow Identification Logic

In plugins/design-control-loop/skills/design-control-loop/references/workflow-template.yml, the workflow filters incoming issue_comment events using a strict prefix check:

startsWith(github.event.comment.body, '/iterate')

Only comments beginning with /iterate trigger the iteration steps. This prefix requirement prevents accidental triggering while allowing maintainers to write normal comments without interrupting the agent workflow. Upon detecting the command, the workflow extracts the hidden marker from the PR body before proceeding to the checkout step.

The Iteration Pipeline: Building Context and Applying Changes

Once the system identifies an /iterate command, it executes a structured pipeline defined in agent-iteration.ts. This script operates in two distinct modes: footer generation when creating the PR, and prompt generation when processing feedback.

Generating the Footer with agent-iteration.ts

When initially creating a PR, the workflow invokes the script with the --command footer flag:

bun .github/scripts/agent-iteration.ts \
  --command footer \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json

As implemented in plugins/design-control-loop/skills/design-control-loop/references/agent-iteration.ts (lines 45-53), the footer mode appends both visible instructions (the /iterate <feedback> hint) and the hidden marker to the PR body. This ensures future maintainers understand how to interact with the agent while preserving the technical metadata required for workflow routing.

Building the Full Context Prompt

When processing an actual /iterate comment, the workflow switches to --command prompt mode:

bun .github/scripts/agent-iteration.ts \
  --command prompt \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json \
  --repo humanlayer/skills \
  --pr-number 42 \
  --comment-body "/iterate Fix the naming ..."

In this mode, the script gathers the PR title, body, complete comment threads, the current diff, and the persistent memory file. As defined in lines 65-71 of agent-iteration.ts, it constructs a comprehensive prompt that provides the LLM agent with full historical context, enabling it to generate changes that account for previous iterations and accumulated feedback.

Applying Changes and Persistent Memory

After the LLM generates suggested modifications, the agent applies these changes to the PR branch, commits them, and pushes the updates. Simultaneously, the system distills any durable guidance—such as coding standards or architectural decisions—into the memory file specified in the hidden marker. This file, typically located at .github/agent-memory.json, remains human-readable and ensures the agent retains critical context across workflow runs without ballooning the prompt size with redundant historical data.

Practical Implementation Examples

The complete interaction follows a three-phase pattern. First, when creating the PR, the workflow generates the footer:

# Add the iteration footer when the workflow creates the PR

bun .github/scripts/agent-iteration.ts \
  --command footer \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json

# → prints the markdown snippet that the workflow appends to the PR body

Second, the maintainer triggers refinement by commenting directly on the PR:

# Trigger an iteration from a maintainer comment

#    (write this as a comment on the PR)

/iterate Fix the naming of the utility function and add a unit test

Third, the workflow detects the comment and executes the iteration cycle:

# The same workflow, when it receives the comment, runs:

bun .github/scripts/agent-iteration.ts \
  --command prompt \
  --workflow $WORKFLOW_ID \
  --memory .github/agent-memory.json \
  --repo humanlayer/skills \
  --pr-number 42 \
  --comment-body "/iterate Fix the naming ..."

# → prints a full prompt that is sent to the LLM agent; the agent then

#   commits changes, updates the memory file, and posts a summary comment.

Summary

• The /iterate comment serves as a specialized control signal that converts standard PR comments into agentic workflow triggers, filtered by the startsWith check in the GitHub Actions workflow template.
• Hidden HTML markers embedded in PR bodies store workflow IDs and memory file paths, enabling precise routing of comments to their originating workflow instances without cross-contamination.
• The agent-iteration.ts script operates in dual modes: footer mode initializes PRs with interaction instructions and metadata (lines 45-53), while prompt mode constructs comprehensive LLM prompts from PR diffs, comments, and persistent memory (lines 65-71).
• Persistent memory files store distilled knowledge across iterations, allowing the agent to maintain context and improve continuously while keeping individual prompts concise and relevant.

Frequently Asked Questions

How does the system prevent accidental triggering of agent iterations?

The workflow explicitly checks that the comment body begins with the /iterate string using the condition startsWith(github.event.comment.body, '/iterate') in workflow-template.yml. This prefix requirement ensures that only intentionally formatted commands trigger the agent, while regular discussion comments on the PR are ignored by the automation.

What information is included in the hidden PR marker?

The hidden marker follows the format <!-- codelayer-agent:workflow=<id>;memory=<path>;… --> and contains the unique workflow identifier, the path to the agent memory file (typically .github/agent-memory.json), and additional metadata required to reconstruct the agent's context. This marker resides in the PR body as an HTML comment, remaining invisible to human readers while providing machine-readable routing data.

Can multiple loop skills operate on the same repository simultaneously?

Yes, because each workflow instance writes its own unique hidden marker containing a distinct workflow ID. When an /iterate comment arrives, the system extracts the marker and routes the signal only to the specific workflow that created that particular PR, allowing multiple design-control-loop and build-iterated-agentic-loop instances to coexist without interference.

What happens to feedback across multiple /iterate cycles?

Durable feedback gets distilled into the persistent memory file specified in the hidden marker. According to the implementation in agent-iteration.ts, the system updates this memory file after each successful iteration, ensuring that guidance such as naming conventions, architectural decisions, and debugging fixes accumulates across runs. This approach maintains a concise, human-readable knowledge base that the agent references in subsequent iterations without requiring full replay of comment history.

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