references/workflow-template.yml
GitHub# Agent <Task Title> - iterated control loop
#
# This workflow has two modes:
# 1. scheduled/manual mode: run one sense -> control -> actuate iteration on a fresh agent
# branch and open a PR. When sensor/controller/actuator are fused, collapse them to one step.
# 2. /iterate mode: when a maintainer comments on an agent-created PR, update that PR
# and optionally update .github/agent-memory/<task-slug>.md for future runs.
#
# The /iterate path intentionally checks the PR body marker BEFORE checkout/setup so
# every agent workflow can listen for /iterate while non-matching workflows no-op cheaply.
name: "Agent: <Task Title>"
on:
schedule:
- cron: "0 13 * * *" # Update me based on user preferences
workflow_dispatch:
issue_comment:
types: [created] # for iteration!
permissions:
contents: write
pull-requests: write
issues: write
concurrency:
group: agent-<task-slug>
cancel-in-progress: true
jobs:
agent-task:
# Run all non-comment events. For issue comments, only authorized PR comments
# starting with /iterate are allowed to reach the marker preflight below.
if: |
github.event_name != 'issue_comment' ||
(
github.event.issue.pull_request &&
startsWith(github.event.comment.body, '/iterate') &&
(github.event.comment.author_association == 'OWNER' ||
github.event.comment.author_association == 'MEMBER' ||
github.event.comment.author_association == 'COLLABORATOR')
)
runs-on: ubuntu-latest
steps:
- name: Check iterate marker to bound work-in-progress
id: agent_gate
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
EVENT_NAME: ${{ github.event_name }}
GITHUB_REPOSITORY: ${{ github.repository }}
PR_URL: ${{ github.event.issue.pull_request.url }}
WORKFLOW_ID: agent-<task-slug>
AGENT_LABEL: agent-<task-slug>
run: |
# Scheduled runs no-op when an open PR already exists for this agent (flow control).
if [ "$EVENT_NAME" = "schedule" ] || [ "$EVENT_NAME" = "workflow_call" ]; then
EXISTING_PR=$(gh pr list --repo "$GITHUB_REPOSITORY" --state open --label "$AGENT_LABEL" --json number,url --limit 1)
if [ "$(echo "$EXISTING_PR" | jq 'length')" -gt 0 ]; then
echo "run_agent=false" >> "$GITHUB_OUTPUT"
echo "Open PR already exists for $AGENT_LABEL; no-op."
exit 0
fi
fi
# Manual runs are normal agent runs, so allow the rest of the job.
if [ "$EVENT_NAME" != "issue_comment" ]; then
echo "run_agent=true" >> "$GITHUB_OUTPUT"
exit 0
fi
# /iterate comments are shared by all recurring agent workflows. The hidden
# PR body marker deterministically routes the comment to the workflow that
# originally opened the PR. Non-matching workflows exit before checkout/setup.
PR_DATA=$(gh api "$PR_URL")
BODY=$(echo "$PR_DATA" | jq -r '.body // ""')
if grep -Fq "<!-- codelayer-agent:workflow=$WORKFLOW_ID;" <<< "$BODY"; then
echo "run_agent=true" >> "$GITHUB_OUTPUT"
echo "number=$(echo "$PR_DATA" | jq -r '.number')" >> "$GITHUB_OUTPUT"
echo "head_ref=$(echo "$PR_DATA" | jq -r '.head.ref')" >> "$GITHUB_OUTPUT"
echo "head_sha=$(echo "$PR_DATA" | jq -r '.head.sha')" >> "$GITHUB_OUTPUT"
else
echo "run_agent=false" >> "$GITHUB_OUTPUT"
echo "PR was not created by $WORKFLOW_ID; no-op."
fi
- uses: actions/checkout@v5
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
with:
fetch-depth: 0
- uses: actions/checkout@v5
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name == 'issue_comment'
with:
# Iteration updates the existing agent PR branch rather than creating a new one.
ref: ${{ steps.agent_gate.outputs.head_ref }}
fetch-depth: 0
- name: Configure git user & branch
if: steps.agent_gate.outputs.run_agent == 'true'
shell: bash
run: |
if [ "${{ github.event_name }}" != "issue_comment" ]; then
BRANCH="<branch-prefix>/$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
echo "BRANCH=$BRANCH" >> "$GITHUB_ENV"
git checkout -b "$BRANCH"
fi
git config user.name "github-actions[bot]"
git config user.email "github-actions[bot]@users.noreply.github.com"
# NOTE: setup below assumes a bun/Node repo. Replace with this repo's runtime + install.
- name: Install bun
if: steps.agent_gate.outputs.run_agent == 'true'
uses: oven-sh/setup-bun@v2
with:
bun-version: 1.3.14
- name: Install Node.js
if: steps.agent_gate.outputs.run_agent == 'true'
uses: actions/setup-node@v4
with:
node-version: 24
- name: Cache bun dependencies
if: steps.agent_gate.outputs.run_agent == 'true'
uses: actions/cache@v4
with:
path: ~/.bun/install/cache
key: bun-${{ runner.os }}-${{ hashFiles('**/bun.lock') }}
restore-keys: |
bun-${{ runner.os }}-
- name: Install dependencies
if: steps.agent_gate.outputs.run_agent == 'true'
run: bun install --frozen-lockfile
# --- Iteration path: a /iterate comment refines the existing PR ---
# Iteration is one actuator pass over reviewer feedback, not a fresh sense->control->actuate cycle.
- name: Actuator — iterate on feedback
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name == 'issue_comment'
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FORCE_COLOR: "3"
GITHUB_REPOSITORY: ${{ github.repository }}
PR_NUMBER: ${{ steps.agent_gate.outputs.number }}
COMMENT_BODY: ${{ github.event.comment.body }}
run: |
set -o pipefail
# Build an iteration prompt from the PR body, comments, the /iterate feedback, and memory.
# NOTE: update the agent-iteration.ts path to where you installed it (.github/scripts/, ci-scripts/, scripts/).
bun .github/scripts/agent-iteration.ts \
--command prompt \
--workflow agent-<task-slug> \
--memory .github/agent-memory/<task-slug>.md \
--repo "$GITHUB_REPOSITORY" \
--pr-number "$PR_NUMBER" \
--comment-body "$COMMENT_BODY" > /tmp/agent-prompt.md
# NOTE: replace with your agent runner from references/agent-runner-templates.md
bunx @humanlayer/cli@latest codelayer \
--provider anthropic --model claude-sonnet-4-6 --thinking high \
--prompt "$(cat /tmp/agent-prompt.md)" \
2>&1 | tee /tmp/agent-output.txt
# NOTE: replace with agent-specific extraction from references/agent-runner-templates.md
cat /tmp/agent-output.txt | sed 's/\x1b\[[0-9;]*m//g' > /tmp/pr-body.md
# --- Scheduled / manual path: one sense -> control -> actuate iteration ---
# If your sensor and controller are fused into the agent (or into one tool), collapse
# the next three steps into a single Actuator step — do not invent separation you don't have.
- name: Sensor — measure current state
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
run: |
# Run the sensor you designed and write a stable, normalized measurement.
# Replace with your sensor (lint / AST search / type-check / tests / telemetry / script / agent).
# Example shape:
# <sensor command> > /tmp/sensor-output.json
echo "TODO: run the sensor and write /tmp/sensor-output.json"
- name: Controller — select the next increment
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
run: |
# Consume /tmp/sensor-output.json and choose what to change this run, within scope
# and batch size. Deterministic example: sort findings and take the top N.
# If the agent itself is the controller, delete this step.
# Example shape:
# <controller command> /tmp/sensor-output.json > /tmp/controller-output.md
echo "TODO: select target(s) and write /tmp/controller-output.md"
- name: Actuator — run the coding agent
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
FORCE_COLOR: "3"
run: |
set -o pipefail
MEMORY_CONTENT="$(cat .github/agent-memory/<task-slug>.md)"
CONTROLLER_OUTPUT="$(cat /tmp/controller-output.md 2>/dev/null || true)"
PROMPT="$(cat <<EOF
<paste prompt-template.md here and replace placeholders>
## Selected work (controller output)
$CONTROLLER_OUTPUT
## Agent Memory
$MEMORY_CONTENT
EOF
)"
# NOTE: replace this block with your agent runner from references/agent-runner-templates.md.
# Each agent has different output formats — see that file for extraction steps.
bunx @humanlayer/cli@latest codelayer \
--provider anthropic --model claude-opus-4-8 --thinking high \
--prompt "$PROMPT" \
2>&1 | tee /tmp/agent-output.txt
# NOTE: response extraction is agent-specific — see references/agent-runner-templates.md.
- name: Extract PR body
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
run: |
# CodeLayer example — strip ANSI codes. Replace with your agent's extraction.
cat /tmp/agent-output.txt | sed 's/\x1b\[[0-9;]*m//g' > /tmp/pr-body.md
- name: Push and create PR
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name != 'issue_comment'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
AGENT_LABEL: agent-<task-slug>
WORKFLOW_ID: agent-<task-slug>
run: |
if git diff --quiet origin/main...HEAD; then
echo "No commits were created by the agent; skipping PR creation."
exit 0
fi
git push --set-upstream origin "${{ env.BRANCH }}"
# Add the hidden workflow marker to the PR body for /iterate routing.
# NOTE: Update the path to agent-iteration.ts based on where you installed it
bun .github/scripts/agent-iteration.ts \
--command footer \
--workflow "$WORKFLOW_ID" \
--memory .github/agent-memory/<task-slug>.md >> /tmp/pr-body.md
gh label create "$AGENT_LABEL" --description "Recurring <Task Title> agent PR" --color "0E8A16" || true
PR_URL=$(gh pr create --title "[$(date +%m/%d)] <Task Title>" --body-file /tmp/pr-body.md)
gh pr edit "$PR_URL" --add-label "$AGENT_LABEL"
- name: Push iteration changes and comment
if: steps.agent_gate.outputs.run_agent == 'true' && github.event_name == 'issue_comment'
env:
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
run: |
if ! git diff --quiet HEAD; then
git add -A
git commit -m "chore: iterate <task-slug> agent feedback"
git push origin HEAD:${{ steps.agent_gate.outputs.head_ref }}
fi
gh pr comment ${{ steps.agent_gate.outputs.number }} --body-file /tmp/pr-body.md
- name: Upload agent output
if: always() && steps.agent_gate.outputs.run_agent == 'true'
uses: actions/upload-artifact@v4
with:
name: agent-output
path: /tmp/agent-output.txt