agent-iteration.ts Reference: Footer and Prompt Modes for /iterate PR Comments

The agent-iteration.ts reference implements a dual-mode helper script in the humanlayer/skills repository that enables coding-agent workflows to handle iterative pull-request feedback, using footer mode to inject persistent workflow metadata into PR descriptions and prompt mode to generate comprehensive execution contexts when processing /iterate commands.

The agent-iteration.ts utility serves as the central coordination point for stateful agentic workflows on GitHub. This TypeScript file provides the infrastructure necessary to maintain context across multiple iterations of code review, allowing agents to respond to /iterate comments with full awareness of previous interactions, memory files, and complete PR history.

What Is agent-iteration.ts?

agent-iteration.ts is a shared helper script located in the repository’s workflow automation suite. Its primary responsibility is bridging the gap between static PR metadata and dynamic agent execution by providing two distinct rendering functions: renderFooter and renderIterationPrompt. These functions support the /iterate command pattern, where maintainers can trigger subsequent agent actions by commenting on pull requests.

Footer Mode: Embedding Workflow Identity

The footer mode generates a static markdown block that establishes a persistent link between the PR and its originating workflow instance.

How renderFooter Works

When invoked with --command footer, the script executes the renderFooter function (lines 41‑55) to produce a markdown footer containing two critical components:

• Visible instructions for maintainers explaining how to use /iterate <feedback> to request changes
• A hidden HTML comment marker (<!-- codelayer-agent:workflow=…;memory=…;version=1 -->) that stores the workflow ID and memory file path

This hidden marker is the sole mechanism that allows other workflow instances to identify which agent should process future /iterate commands on this PR.

When to Use Footer Mode

Use footer mode when the workflow initially opens the PR. The generated footer must be appended to the PR body during creation, ensuring that subsequent /iterate comments can be routed back to the correct workflow instance and memory file.

Prompt Mode: Generating Execution Context

The prompt mode generates a full iteration prompt that prepares the coding agent to act on specific feedback.

How renderIterationPrompt Builds Context

When invoked with --command prompt, the script executes renderIterationPrompt (lines 65‑109), which performs several data-gathering steps:

1. Reads the memory file using readTextIfExists to retrieve durable guidance from previous iterations
2. Fetches PR metadata and all issue/review comments via ghJson calls to the GitHub API
3. Strips the command token using stripIterateCommand to isolate the actual feedback from the /iterate prefix
4. Assembles a comprehensive markdown prompt containing:
   • The current iteration request
   • Workflow identity and explicit agent instructions
   • The complete memory file content
   • PR summary (number, title, state, base/head refs)
   • Full PR body and formatted conversation history

When to Use Prompt Mode

Use prompt mode when a maintainer posts a /iterate comment on an existing PR. The script expects parameters including --repo, --pr-number, and --comment-body, and outputs a complete prompt ready for the agent’s execution step. The agent uses this context to update the PR and optionally write condensed guidance back to the memory file.

Operational Differences Between Footer and Prompt Modes

While both modes support the same /iterate workflow, they operate at different lifecycle stages with distinct outputs:

• Execution Timing: Footer mode runs once during PR creation, while prompt mode activates every time a maintainer posts /iterate feedback
• Output Type: Footer mode generates static markdown with embedded metadata, whereas prompt mode produces a dynamic, context-rich instruction set for the agent
• Data Scope: Footer mode contains only workflow identifiers (ID and memory path), while prompt mode includes the full conversation history, PR metadata, and current memory state
• Function Targets: renderFooter constructs the hidden HTML comment marker, while renderIterationPrompt orchestrates data collection via ghJson and readTextIfExists

Implementation Examples

Injecting a Workflow Footer

Run this command when creating the PR to generate the footer markdown:

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

The script outputs a markdown block that should be appended to the PR description, containing both visible /iterate instructions and the hidden workflow marker.

Processing an /iterate Comment

Run this command when a maintainer posts feedback to generate the agent prompt:

bun .github/scripts/agent-iteration.ts \
  --command prompt \
  --workflow myWorkflowId \
  --memory .github/agent-memory.json \
  --repo humanlayer/skills \
  --pr-number 123 \
  --comment-body "/iterate Please update the README to include usage examples."

The script aggregates PR context, strips the /iterate token, and emits a complete prompt for the coding agent.

Integration with Control Loop Plugins

The agent-iteration.ts script integrates with higher-level workflow orchestration provided by:

• design-control-loop plugin: Provides the primary control-loop logic that invokes agent-iteration.ts during PR workflows
• build-iterated-agentic-loop reference: Offers an alternative implementation pattern for projects with different directory layouts

Both plugins rely on the footer marker to maintain workflow continuity across multiple agent iterations.

Summary

• agent-iteration.ts provides two essential functions—renderFooter and renderIterationPrompt—to support stateful /iterate workflows on GitHub pull requests
• Footer mode establishes workflow identity by injecting a hidden HTML comment (<!-- codelayer-agent:workflow=…;memory=…;version=1 -->) into the PR body during creation
• Prompt mode aggregates comprehensive context—including memory files, PR metadata, and conversation history—to generate actionable instructions for the coding agent
• The script uses helper functions readTextIfExists, ghJson, and stripIterateCommand to gather and sanitize data before prompt assembly
• Implementation requires the bun runtime and integrates with control-loop plugins like design-control-loop for complete workflow orchestration

Frequently Asked Questions

What is the hidden HTML comment in footer mode?

The hidden HTML comment is a machine-readable marker generated by renderFooter at lines 41‑55 that contains the workflow ID and memory file path. This marker allows the system to route subsequent /iterate commands back to the originating workflow instance while remaining invisible to human readers in the rendered PR description.

How does the agent access previous iteration context?

The agent accesses previous context through the memory file specified in the footer marker. When prompt mode executes, renderIterationPrompt calls readTextIfExists to load this file, which contains condensed guidance from prior iterations, and embeds its contents into the generated prompt alongside the current PR conversation history.

Can I use agent-iteration.ts with workflows other than design-control-loop?

Yes, agent-iteration.ts is a standalone utility that any workflow can invoke via CLI. While the design-control-loop plugin provides a reference implementation, the build-iterated-agentic-loop plugin demonstrates an alternative integration pattern, and custom workflows can call the script directly provided they supply the required --workflow, --memory, and mode-specific parameters.

What triggers the transition from footer to prompt mode?

The transition occurs when a maintainer posts a comment containing the /iterate command on a PR that contains the footer marker. The workflow detects this comment, validates that the marker’s workflow ID matches the current instance, and then invokes agent-iteration.ts with --command prompt to generate the execution context for the agent.

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