How to Build a Robust AI Loop: The Six‑Component Toolkit and Common Pitfalls

Loop Engineering Overview

Loop engineering is the design of a system that executes five sequential stages—discover, handoff, verify, persist, schedule—each supported by dedicated tooling. Omission of any stage causes the loop to stall or fail.

Six Core Components

Automations – provides the heartbeat and scheduling.

Skills – supplies persistent context (memory).

Sub‑agents – performs independent verification.

State – records progress and stable rules.

Worktrees – isolates concurrent agents.

Connectors – extends the loop beyond the filesystem.

1. Automations (Heartbeat)

Four heartbeat modes are supported:

In‑session loop – runs until the task completes. Example: /loop 5m check deployment finished Goal‑driven – stops when a clear success condition is met. Example: /goal test/auth all passed and lint clean Scheduled trigger – runs on a cron schedule (e.g., 0 9 * * 1-5 for weekdays at 9 AM).

Event‑driven – triggered by repository events such as PR open or CI failure. Example GitHub Action snippet: on: pull_request Brake design requires at least two of the following limits: success condition, iteration count, time limit, or cost limit. Without limits, token costs compound as contexts are repeatedly resent.

A common pitfall is a “half‑finished loop” where an agent declares success prematurely, causing wasted token spend. The fix is to enforce an objective gate rather than a subjective “looks good” check.

2. Worktrees (Isolation)

Problem: Concurrent agents editing the same file cause merge conflicts, analogous to two engineers editing the same line of code.

Solution: Use git worktree to create independent working directories with separate branches while sharing repository history.

# Claude Code
--worktree flag to launch sub‑agent
# Or set in sub‑agent configuration
isolation: worktree

Worktrees eliminate mechanical conflicts, but the practical limit is the reviewer’s bandwidth—how many agents you can safely review while asleep.

3. Skills (Memory)

Purpose: Avoid re‑explaining project context on every session. Intent is stored externally for compounding effect.

Structure: a folder containing SKILL.md, metadata, scripts/, and references/.

skill/
├── SKILL.md      # documentation
├── metadata      # trigger conditions
├── scripts/      # tool scripts
└── references/   # reference docs

Invocation examples:

Claude Code may auto‑invoke when the skill description matches.

Codex: use $ or /skills to call.

Key tip: Concise, concrete descriptions are far more useful than vague, clever ones. Example of a bad description: “trigger when the user mentions design needs.” Example of a good description: “trigger when the user mentions ‘make cover’, ‘generate illustration’, ‘cover image’, ‘Xiaohongshu cover’, or ‘public account header’.”

4. Sub‑agents (Check Separation)

Core principle: An agent that scores its own output tends to be overly friendly. Solution: Introduce a second, independent agent with different instructions (or a different model) to audit the first. Typical modes:

Maker‑Checker – first agent writes code, second agent performs an independent review.

Explorer‑Implementer – first agent finds problems, second agent writes fixes.

Spec‑Verifier – first agent writes to spec, second agent checks against the spec.

Cost: Sub‑agents consume additional tokens because each runs its own model and tools; use when a “second opinion” adds measurable value. Three recommendations:

Never let the code‑writing agent score itself; require an independent checker.

Give the checker different instructions or perspective.

For high‑risk decisions, place a human gate before the checker finalizes.

5. Connectors (Hands‑Feet)

Problem: A loop that can only see the filesystem is severely limited. Solution: Use MCP‑based connectors so agents can read issue trackers, query databases, call staging APIs, and post to Slack. Contrast:

Without connector – you copy‑paste a fix; with connector – the loop opens a PR, links a Linear ticket, and pings a channel after CI passes.

Without connector – you manually run a database migration; with connector – the loop reads the current schema, writes a migration, runs tests, and submits.

Without connector – you type a Slack notification; with connector – the loop sends the message directly to the designated channel.

Distribution: Plugins package connectors and skills together, allowing teammates to install with a single setup step.

6. State / Memory (Backbone)

Problem: Models forget after each run; memory must be stored outside the model, on disk. Two‑layer structure:

Rule files (CLAUDE.md, AGENTS.md)  # stable habits, keep short
Progress file (progress.md)        # what was tried, what passed, what remains open

Habit: Read the state file at the start of each run and update it at the end. Example progress.md :

## 2026-06-27 Morning Triage Loop

### Completed
- `#1234` CI failure: auth timeout, fixed
- `#1235` Dependency upgrade: axios 0.27→1.0, tests passed

### Failures (needs human)
- `#1236` Database migration plan pending (production data)

### Next Steps
- `#1237` Performance optimization review pending

Missing a state file results in a “memory‑less loop” that repeats work and burns tokens.

Putting It All Together: A Morning Maintenance Loop

Schedule: trigger at 9 AM on weekdays (Automations – heartbeat)
 ↓
Discover: read progress.md, find last night’s CI failures and new issues (Skills + State)
 ↓
Handoff: for each item, create a fix in an isolated checkout (Worktrees + Connectors)
 ↓
Verify: independent reviewer scores (Sub‑agents)
 ↓
Persist: on PASS open PR; write risky items to progress.md for human review (State)

The loop is designed once; subsequent runs require no manual prompts.

Correct Assembly Order

1. Run the process manually until it stabilizes.
2. Encapsulate the stable parts into a Skill.
3. Package the Skill into a loop.
4. Add scheduling only after the loop runs stably three times.

Skipping any step leads to specific failure modes: without manual stabilization the loop’s behavior is opaque; without Skills the loop must re‑explain context each run; without verification the loop can crash silently; adding scheduling too early burns tokens while you sleep.

Maturity Ladder

Level 1 – Read‑only reporting : Summarize and report for a few days; output is reference‑only.

Level 2 – Draft generation + human review : Sign off each output; proceed only with test coverage.

Level 3 – Checker auto‑submits low‑risk changes : Run with a checker guard; lint fixes run automatically.

Level 4 – Human gate reviews only risky items : Most changes pass automatically; critical actions (deletes, production deployments) require confirmation.

Level 5 – Full autonomy : Intervene only on exceptions; failure cost is low, tests are present, and diagnosis is fast.

Actionable Guidance for Different Audiences

First‑time Loop Builder

Select a task with a clear success condition (e.g., tests pass, lint clean).

Run the full process manually once.

Encapsulate the stable parts into a Skill.

Wrap the Skill in a /goal loop and monitor it.

Do not add scheduling until the loop runs stably three times.

Existing Loops Checklist

Ensure each loop has an independent checker.

Confirm each loop maintains a State file.

Verify each loop defines at least two brake limits (success condition, count, time, or cost).

Check that Worktrees provide sufficient isolation for parallel agents.

Identify which of the six components is missing.

Preparing for Level 5 (Full Autonomy)

Define the failure cost (production outage, monetary loss, data leak).

Confirm comprehensive test coverage.

Ensure rapid diagnosis of loop failures.

Place a human gate at the most critical decision point.

Validate that you can safely review the output of all agents while asleep.

If any answer is not a clear “yes,” do not jump to Level 5; progress one level at a time.