# Build‑Iterated‑Agentic‑Loop Workflow Phases Explained

> Understand the four workflow phases of build-iterated-agentic-loop: Planning, Execution, Reflection, and Iteration. Learn how this skill optimizes AI agent development.

- Repository: [HumanLayer/skills](https://github.com/humanlayer/skills)
- Tags: deep-dive
- Published: 2026-09-07

---

**The build‑iterated‑agentic‑loop skill follows four sequential workflow phases: Planning, Execution, Reflection, and Iteration, defined in the `workflow‑template.yml` file.**

The **build‑iterated‑agentic‑loop** is an agentic workflow skill from the **humanlayer/skills** repository that implements a closed‑loop system for repeatedly improving an agent's behavior. This pattern is widely used to create self‑correcting AI agents that plan actions, execute them, evaluate results, and refine their approach—mirroring the classic *observe‑think‑act* control loop but staged for observability and debugging.

## The Four Build‑Iterated‑Agentic‑Loop Phases

The workflow is explicitly broken into four distinct phases as defined in `plugins/build‑iterated‑agentic‑loop/skills/build‑iterated‑agentic‑loop/references/workflow‑template.yml`. Each phase has dedicated responsibilities and outputs that feed into the next stage.

### Phase 1: Planning

The **Planning** phase generates a high‑level plan for the current iteration. The LLM is prompted to outline objectives, identify required sub‑tasks, and allocate necessary resources. This phase establishes the *intention* for the cycle before any code runs.

Key activities include:
- Prompting the LLM to articulate clear objectives
- Decomposing complex goals into manageable sub‑tasks
- Identifying dependencies and required tools

### Phase 2: Execution

The **Execution** phase carries out the plan's sub‑tasks. The agent performs concrete actions—such as code generation, API calls, file operations, or tool invocations—and captures all outputs and side effects.

Key activities include:
- Running agent actions according to the plan
- Capturing stdout, stderr, return codes, and artifacts
- Recording execution traces for downstream analysis

### Phase 3: Reflection

The **Reflection** phase evaluates actual results against expected outcomes. This critical feedback stage compares achievements against the original goals, recording successes, failures, edge cases, and unexpected behavior.

Key activities include:
- Computing metrics and success criteria
- Performing delta analysis between expected and actual results
- Documenting learnings in a structured format

### Phase 4: Iteration

The **Iteration** phase closes the loop by feeding reflection insights back into the planning stage. The agent updates its knowledge base or memory and constructs an improved plan for the next cycle, continuing until termination conditions are met.

Key activities include:
- Updating persistent memory or context stores
- Adjusting prompts or parameters based on learnings
- Checking termination conditions (max iterations, target metrics, or convergence)

## Source Files and Implementation Details

| File Path | Purpose |
|-----------|---------|
| `references/workflow‑template.yml` | Defines the four workflow phases and their sequencing |
| `references/skill‑template.md` | Boilerplate for creating new skills that use the loop |
| `references/response‑template.md` | Standardized LLM response format for each phase |
| `references/agent‑iteration.ts` | TypeScript implementation of the iteration controller |
| [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) | Human‑readable documentation summarising the loop workflow |

As implemented in **humanlayer/skills**, the loop terminates when a configurable condition is satisfied—typically a target metric threshold, convergence detection, or a maximum iteration limit.

## Code Example: Running the Build‑Iterated‑Agentic‑Loop

The Python wrapper exposes a clean interface for invoking the complete four‑phase cycle:

```python
from build_iterated_agentic_loop import AgentLoop

# Initialise with custom prompt and termination criteria

loop = AgentLoop(
    initial_prompt="Design a Python CLI that lists GitHub repos.",
    max_iterations=5,
    stop_condition=lambda state: state["score"] > 0.9,
)

# Run through all four phases internally

final_state = loop.run()

print("Final artifacts:", final_state["artifacts"])

```

## Code Example: Hooking Into Individual Phases

For debugging or custom orchestration, the loop exposes lifecycle callbacks:

```python
def on_plan(state):
    print("Planning:", state["plan"])

def on_execute(state):
    print("Executing:", state["action_log"])

def on_reflect(state):
    print("Reflection metrics:", state["metrics"])

loop = AgentLoop(...)
loop.on_plan = on_plan
loop.on_execute = on_execute
loop.on_reflect = on_reflect
loop.run()

```

These hooks allow external systems to observe or intervene at phase boundaries without modifying the core loop logic defined in `agent‑iteration.ts`.

## Summary

- The **build‑iterated‑agentic‑loop** implements a four‑phase cycle: **Planning → Execution → Reflection → Iteration**
- Phase definitions reside in `references/workflow‑template.yml` within the skill directory
- The loop repeats until termination conditions are satisfied, enabling self‑improving agent behavior
- Implementation spans TypeScript (`agent‑iteration.ts`) and Python wrappers with optional phase‑level callbacks
- Reference templates (`skill‑template.md`, `response‑template.md`) standardize adoption across new skills

## Frequently Asked Questions

### What triggers the transition between phases in the build‑iterated‑agentic‑loop?

Phase transitions are governed by completion signals in `workflow‑template.yml`. Each phase emits a structured output that becomes the input for the subsequent phase. The loop controller in `agent‑iteration.ts` manages state handoff and error handling between stages.

### How does the Reflection phase feed back into Planning?

The Reflection phase produces a structured evaluation—stored in the loop state—that the Iteration phase uses to update the agent's memory or context. This modified state is then passed to the next Planning invocation, creating a continuous learning cycle without manual intervention.

### Can I customize the termination condition for the loop?

Yes. The `AgentLoop` constructor accepts a `stop_condition` callable that receives the current state dictionary. Common conditions include score thresholds, iteration caps, or convergence detectors. The default behavior uses `max_iterations` as a safety limit.

### Where is the canonical documentation for this skill?

Primary documentation lives in [`SKILL.md`](https://github.com/humanlayer/skills/blob/main/SKILL.md) at the skill root, with implementation details in `references/workflow‑template.yml` and `references/agent‑iteration.ts`. These files together constitute the authoritative specification for the build‑iterated‑agentic‑loop workflow phases.