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

> Learn how agent-iteration.ts streamlines PR feedback with footer and prompt modes. It injects metadata and generates execution contexts for iterative coding workflows.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: api-reference
- Published: 2026-09-13

---

**The [`agent-iteration.ts`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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:

```bash
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:

```bash
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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/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`](https://github.com/humanlayer/skills/blob/main/agent-iteration.ts) with `--command prompt` to generate the execution context for the agent.