loop-harness

Workflow-memory-first orchestration harness for long-running AI coding tasks.

loop-harness wraps AdaL CLI to enable multi-phase, recoverable workflows with persistent memory via OpenBrain MCP server.

The Idea

Coding agents are great at single turns. They degrade on long tasks (50–500 tool calls) because they lose context, repeat mistakes, and can't recover from bad paths.

loop-harness adds what's missing:

• Job decomposition into phases (Plan → Execute → Verify → Report)
• Workflow memory that survives compaction (stored in OpenBrain)
• Checkpoint + rollback when strategies fail
• Recovery logic with retry budgets and escalation
• Ratchet rules that prevent repeating past mistakes
• Dynamic AGENTS.md injection to steer AdaL per phase

Architecture

You → loop-harness (orchestrator) → AdaL CLI (LLM brain) ← OpenBrain (MCP memory)

• loop-harness: The foreman — plans, tracks progress, handles recovery
• AdaL CLI: The skilled worker — does the actual coding
• OpenBrain: The institutional memory — remembers everything across sessions

All integration is non-invasive. We don't modify AdaL internals.

Install

# Requires Python 3.12+
pip install -e .

# Also need AdaL CLI
npm install -g @sylphai/adal-cli

# Optional: OpenBrain MCP server for persistent memory
npm install -g @adamrdrew/agent-memory-mcp

Usage

# Run a bug fix workflow
loop run "Fix issue #123: API returns 500 on empty payload"

# Resume a paused/failed job
loop resume <job-id>

# Check job status
loop status
loop status <job-id>

How It Works

1. You give loop-harness a task
2. It queries OpenBrain for relevant past context
3. For each phase (PLAN → EXECUTE → VERIFY → REPORT):
   • Generates a dynamic AGENTS.md with phase-specific instructions
   • Invokes AdaL CLI with a crafted prompt
   • Parses the result, logs to memory
   • Checkpoints progress
4. If a phase fails: retry, rollback, or escalate
5. On completion: codify lessons learned (ratchet)

Project Status

v0.1.0 — MVP in progress

• Core engine (outer + middle loop)
• Workflow state machine with persistence
• AdaL CLI subprocess driver
• Dynamic AGENTS.md generation
• OpenBrain MCP client (with local fallback)
• Checkpoint/rollback via git
• Ratchet rules system
• CLI (loop run / loop resume / loop status)
• End-to-end integration test
• Multiple workflow templates
• Full MCP protocol support for OpenBrain

License

MIT