Loop Engineering Series (1): From Prompt to System

When AI stops answering one-off questions and starts running a workflow continuously, observably, and reversibly — that’s Loop Engineering. This is the first post in the octo-agent official technical series.

What is octo-agent

octo-agent is a local AI agent platform for engineering practice. It is not meant to be a smarter chatbot; its goal is to let AI execute repetitive engineering tasks in a stable, observable, and reversible way.

Unlike general-purpose ChatGPT clients or one-shot code-generation tools, octo-agent emphasizes:

  • Local-first: it runs on your machine, with code and state kept in the local repository.
  • Workflow-driven: complex tasks are orchestrated via workflow scripts, not left to the luck of a single prompt.
  • Repeatable: the same workflow can be run again and again, with predictable behavior.
  • Observable: .octo/ holds all loop state, logs, and execution history in one place.
  • Progressive: through L1 / L2 / L3 phases, automation graduates from “read-only” to “act”.

It also provides a skill system for capturing best practices, MCP for connecting external tools, and sub_agent for multi-agent collaboration. Loop Engineering is a working pattern built on top of these capabilities.

What is Loop Engineering

The traditional way: you type → AI replies → you check → you type again. Every task requires you to initiate, follow up, and close it manually.

Loop Engineering is different: you design a system that discovers tasks, delegates them to sub-agents, verifies results, records state, runs on a schedule, and only calls a human at key decision points.

Google engineer Addy Osmani captured it best:

“Loop engineering is replacing yourself as the person who prompts the agent. You design the system that does it instead.”

Anthropic Claude Code lead Boris Cherny put it closer to engineering reality:

“I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”

Loop Engineering is not about AI generating an answer once; it is about AI running a stateful, feedback-driven, reversible working system.

Why Loop Engineering is becoming mainstream

Driver Why it matters
Mature tooling The six primitives needed for loops are now first-class citizens in modern coding agents.
Practitioner testimony The people building the tools say, “I don’t write prompts; I write loops.”
Natural evolution From prompt engineering → context engineering → harness engineering → loop engineering.
Repeatability Design once, run repeatedly for CI failures, issue triage, dependency updates, and other maintenance tasks.
Economics Free humans from initiating and following up; let them focus on actual judgment calls.

The rise of Loop Engineering reflects a broader trend: AI is moving from single interactions to continuously running systems.

The six building blocks of Loop Engineering

The industry has settled on six primitives (five modules + one memory layer):

Module Purpose Typical implementation
Automations / Scheduling Trigger on a schedule, discover tasks, classify them cron, hooks, GitHub Actions
Worktrees Parallel agents do not step on each other’s files git worktree, isolated directories
Skills Codify project knowledge into reusable instructions SKILL.md, reusable prompts
Plugins / Connectors (MCP) Connect to external tools (issue trackers, Slack, APIs) MCP servers
Sub-agents Separate maker and checker independent agent acting as verifier
Memory / State Persist across conversations state files, databases, task records

octo-agent provides all of these primitives as a unified Loop Engineering platform, rather than a loose collection of tools.

How octo-agent maps to the six primitives

Loop primitive octo-agent capability How to invoke it
Goal / run until condition /goal <objective> or create_goal keep the agent running until the objective is met
Scheduling / Automations cron-task-creator skill, /api/tasks persistent cron tasks that survive session restarts
In-session loops loop skill + schedule_wakeup octo /loop 1h check CI
Worktree isolation worktree-isolate skill, workflow isolation: "worktree" writes code in an isolated worktree
Sub-agents sub_agent tool, agent() in workflows implementer + verifier separation
Skills SKILL.md + skill tool load best-practice guides
Memory / State MEMORY.md, .octo/STATE.md, task state persist across conversations
Connectors mcp tool + MCP servers connect to issue trackers, Slack, staging APIs
Workflow orchestration workflow tool multi-agent, staged, parallel, pipelined execution

octo-agent’s unique strength is that these capabilities are not isolated plugins; they are a coordinated system designed around Loop Engineering. workflow orchestrates, cron-task-creator schedules, worktree-isolate isolates, sub_agent divides labor, skill encodes practice, and MEMORY.md / .octo/ hold state.

L1 / L2 / L3: three gears of progressive automation

Loop Engineering is not a binary “manual or fully automatic” choice. octo-agent splits it into three gears:

Gear Behavior Use when Risk
L1: Read-only report Discovers, classifies, generates reports; makes no external changes First 1–3 runs of a new loop Very low
L2: Draft assistant Proposes fixes, draft comments, PR descriptions; waits for human confirmation before publishing Loop classification quality is stable Low
L3: Auto-execute Executes safe actions automatically (labels, reminders, worktrees, draft PRs); irreversible actions still require human gate Loop is validated and safety boundaries are clear Controllable

The value of this progressive model is that automation starts from “observation” and gradually earns “action”. This is the key to preventing loops from running out of control.

How to implement a loop in octo-agent

Step 1: Write a LOOP.md

Before writing any loop, write a LOOP.md that locks down purpose, trigger, scope, done condition, safety boundaries, and rollout plan:

# Loop: dependency-sweeper

## Purpose
Automatically upgrade patch/minor dependencies every week.

## Trigger
Every Monday at 9 AM (cron: `0 9 * * 1`).

## Discovery
Run `go list -u -m all` / `npm outdated` / `pip list --outdated`.

## Done condition
All safe patch/minor dependencies are upgraded and tested; major dependencies are listed for human handling.

## Safety
- Only upgrade patch/minor; never touch major.
- Run tests in an isolated worktree; do not pollute main.
- Do not auto-merge / deploy / close issues.

## State file
`.octo/dependency-sweeper-state.md`

Step 2: Choose a trigger

Scenario Recommended way Example
One-shot, repeated within a session schedule_wakeup (/loop skill) octo /loop 30m check for unmerged PRs
Long-running, across sessions cron-task-creator create a cron task with a prompt and directory
Complex multi-agent flow workflow tool octo workflow daily-triage '{"since": "1d"}'

Step 3: Use the built-in loop-engineering skill

octo /loop-engineering design a daily triage loop for my Go backend

This skill will:

  1. Map out the full chain: trigger → discovery → state → worktree → implementer → verifier → human gate.
  2. Generate LOOP.md and STATE.md templates.
  3. Remind you to choose an L1 → L2 → L3 rollout strategy.

Step 4: Orchestrate with workflow

workflow scripts run in an IO-free mruby sandbox: the script itself cannot touch the filesystem or network; all real IO must be delegated to a child agent via agent():

# ✅ Correct: let a child agent write the file
agent("Write a report to .octo/STATE.md with this content: ...", { "read_only" => false })

# ❌ Wrong: File.write inside the script
File.write(".octo/STATE.md", "...")

This design forces every loop step through LLM reasoning, while keeping the script itself safe.

A typical loop lifecycle

Scheduled trigger (cron or /loop)
  → Discover tasks (issues / PRs / CI / commits)
  → Classify and prioritize
  → Write to STATE.md / update state
  → For low-risk tasks: spin up an implementer sub-agent in an isolated worktree
  → verifier sub-agent independently checks patch + tests
  → Within safety / allowlist: auto-open PR / update ticket / add label
  → Risky / ambiguous: escalate to human gate
  → Next run resumes from STATE.md

This is a recursive goal: define the objective, and AI iterates until it is complete or escalated. STATE.md and processed.json give the loop memory so it does not lose progress when conversation context resets.

Four safety red lines

The stronger the automation, the more important the safety boundaries. octo-agent recommends these four red lines:

  1. Maker and checker must be separated: use sub_agent or agent() to designate implementer and verifier.
  2. File writes must be worktree-isolated: pass isolation: "worktree" to avoid polluting main.
  3. Irreversible actions must have a human gate: merge, deploy, close issues, delete tags, post to public channels — loops may propose, but not execute.
  4. Start from L1: the first version is always report-only; never auto-edit code on day one.

Where Loop Engineering applies

Loop Engineering is not limited to coding. Any task that meets four conditions — regular inputs, clear judgment criteria, iterative improvement, and irreversible actions that need a human gate — can use it.

Role Tasks to turn into loops How to run
Backend engineer Dependency upgrades, issue triage, CI failure classification, post-merge cleanup workflow + cron
Content creator Daily trend scan → topic selection → first draft → human review workflow + scheduler
Freelancer Weekly client-email sorting → classification → draft replies MCP + email + agent
Account manager Daily CRM review → flag follow-ups → prepare talking points connect to Salesforce/HubSpot
Lawyer / legal Contract pre-screening: extract key clauses → flag risks → human review read-only loop, L1
Personal productivity Weekly note/bill/todo consolidation → categorize → generate next-week priorities local files + memory

Development has natural advantages: version control, tests, and type systems provide objective validation; git worktree and CI provide reversible sandboxes; issues, PRs, and CI produce structured data that agents can read. Non-code scenarios are usually better suited to L1 reports and L2 drafts with human confirmation, with only a few low-risk tasks reaching L3.

Common risks and mitigations

Risk Why it happens Mitigation
Token cost explosion Sub-agents + long loops + high-frequency scheduling burn tokens fast Limit batch size, lower frequency, start from L1.
Verification debt Nobody reviews the loop’s output Every run writes to STATE.md; review it regularly.
Comprehension debt The loop writes code faster than you can understand it Start with low-risk tasks; keep a human gate.
Cognitive surrender Shifting from “using loops to accelerate work I understand” to “letting loops think for me” Reserve loops for repetitive tasks; keep judgment for humans.

Addy Osmani’s warning is worth repeating:

“Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.”

Where to start

If you are new to Loop Engineering, start with repetitive maintenance tasks rather than core business-logic refactoring. Recommended priority:

  1. Daily Triage: every morning scan issues / PRs / CI and save the “what happened today?” context switch.
  2. Dependency Sweeper: upgrade patch/minor dependencies weekly, especially in Go where API compatibility is usually reliable.
  3. Post-Merge Cleanup: auto-delete merged branches and remind people to close linked issues. Low blast radius, high annoyance value.

The biggest value of Loop Engineering is not reducing time spent writing code; it is reducing context switching and accumulated busywork, so human energy goes to design, architecture, and genuinely complex bugs.

Next in the series

References

This is the first post in the octo-agent official technical series.