cdovaz/agent-loop-architect

Agent Loop Architect (Loop Engineering)

Overview

Agent Loop Architect is an execution standard and design pattern for orchestrating complex, multi-stage agent workflows through closed-loop iterations with persistent memory and state tracking.

Instead of treating agent executions as one-shot prompts or linear pipelines, the Agent Loop enforces an iterative lifecycle where subagents specialize, verify their work through objective gates, and systematically learn across runs.

The Two Golden Rules of the Loop

1. No Execution Without Prior Learning: Before proposing or implementing any solution, agents must execute the Learn phase by consulting existing positive and negative patterns in memory.
2. No Completion Without Compression: A cycle is not finished when code or content is written; it concludes only after the Compress phase distills the outcome into memory and updates state.

flowchart TD
    Start([Task Initiated]) --> Learn[1. LEARN: Ingest .loop-memory/]
    Learn --> Plan[2. PLAN: Stage Decomposition & etapas.json]
    Plan --> Exec[3. EXECUTE: Dispatched Specialized Subagents]
    Exec --> Verify{4. VERIFY: Objective Gates Passed?}
    Verify -- No: Regress / Pivot --> Learn
    Verify -- Yes --> Compress[5. COMPRESS: Distill Memory & Update State]
    Compress --> Done([Loop Completed])

---

The 5 Phases of the Loop

Every loop cycle strictly advances through five phases:

Phase 1: Learn (Pre-flight Ingestion)

• Mandatory check: Subagents must read:
  • .loop-memory/positive-cases/ (winning patterns, validated fixes, high-converting copy angles, optimal prompt templates).
  • .loop-memory/negative-cases/ (anti-patterns, failed hypotheses, edge-case regressions, banned approaches).
• Goal: Prevent agents from repeating previously documented mistakes and force reuse of proven patterns.

Phase 2: Plan & Orchestrate (State Initialization)

• Decompose the objective into discrete, ordered stages.
• Initialize or update etapas.json with stage status, assigned subagents, inputs, outputs, and acceptance criteria.
• Assign dedicated subagent roles matching domain requirements.

Phase 3: Execute (Specialized Subagent Dispatch)

• Run subagents sequentially or in parallel based on stage dependencies.
• Subagents work in isolated context, passing concise artifacts or diffs rather than full conversational baggage.

Phase 4: Verify & Evaluate (Objective Acceptance Gates)

• Validate execution output against explicit, automated or deterministic criteria (e.g., unit/integration test results, linting, fact-checking citations, tone compliance).
• If verification fails:
  • Document the failure as an intermediate negative pattern.
  • Return to Learn/Plan with the failure feedback.
• If verification passes: proceed to Compress.

Phase 5: Compress (Post-Flight Memory Distillation)

• Positive Distillation: Extract the exact pattern, template, prompt fragment, or code fix that succeeded and write it to .loop-memory/positive-cases/CASE-<ID>.md.
• Negative Distillation: Document dead ends, rejected hypotheses, and regressions in .loop-memory/negative-cases/CASE-<ID>.md.
• State Finalization: Update etapas.json with completed timestamps, final artifacts, and execution metrics.

---

Directory Structure and Memory Architecture

Every project operating with the Loop pattern adheres to the following root or workspace structure:

<project-root>/
├── .loop-memory/
│   ├── positive-cases/
│   │   ├── CASE-001-fix-auth-race-condition.md
│   │   └── CASE-002-high-conversion-cold-hook.md
│   └── negative-cases/
│       ├── CASE-001-failed-jwt-in-localstorage.md
│       └── CASE-002-clickbait-hook-bounce.md
├── etapas.json
├── references/
│   └── domain-examples.md
└── SKILL.md

Memory Case Schema (.loop-memory/*/CASE-*.md)

Each case file must follow this standardized markdown template:

# Case: [Short Descriptive Title]
- **Date:** YYYY-MM-DD
- **Domain:** [Engineering | Copywriting | Sales | Research]
- **Type:** [Positive | Negative]
- **Trigger / Context:** [Exact situation, error message, or prompt goal]

## Pattern / Technique
[Detailed description of what worked or why it failed]

## Concrete Artifact / Code Snippet / Prompt
```[language]
[Paste the concrete snippet, template, or diff here]

Takeaway & Heuristic

• Do: [Actionable rule for future agents]
• Don't: [What must be avoided]

### `etapas.json` Schema

The `etapas.json` file tracks current lifecycle progression:

```json
{
  "project": "agent-loop-project",
  "loop_version": "2.0.0",
  "updated_at": "2026-11-06T21:00:00Z",
  "current_stage": "fix",
  "stages": [
    {
      "id": "reproduce",
      "role": "QA Reproducer Subagent",
      "status": "completed",
      "input": "Bug report #402",
      "output": "tests/repro_spec.ts",
      "memory_consulted": ["CASE-001-fix-auth-race-condition.md"]
    },
    {
      "id": "fix",
      "role": "Core Fix Engineer Subagent",
      "status": "in_progress",
      "input": "tests/repro_spec.ts",
      "output": null,
      "memory_consulted": []
    }
  ],
  "metrics": {
    "total_cycles": 1,
    "positive_patterns_harvested": 0,
    "negative_patterns_avoided": 1
  }
}

---

Integrated Domain Archetypes

Agent Loop Architect includes 4 battle-tested domain pipelines. For complete step-by-step instructions and prompts for each archetype, see domain-examples.md.

1. Bug Fixing & Engineering

• Pipeline: Reproduce -> Root Cause -> Fix -> Test -> Document
• Learn Check: Ingest prior fixes for related subsystems; avoid past regressions.
• Verification Gate: Reproduction test changes from RED to GREEN; no collateral test breaks.
• Compress: Store the root cause explanation and minimal fix diff in .loop-memory/positive-cases/.

2. Content & Copywriting

• Pipeline: Audience & Angle Research -> Hook & Narrative Draft -> Critique & Tone Polish -> Proof & Fact-Check -> Distribution Packaging
• Learn Check: Read top-performing hooks and banned buzzwords/clichés.
• Verification Gate: Target reading level, brand voice rubric score $\ge 8.5/10$, verified factual claims.
• Compress: Harvest high-performing angles and hook formulas into memory.

3. Sales Outreach

• Pipeline: ICP Intelligence -> Value Hypothesis -> Personalized Sequencing -> Objection Countering -> Dispatch Prep
• Learn Check: Query response rates on value propositions, objection patterns, and invalid assumptions.
• Verification Gate: Specificity checklist (no generic mail-merge lines), compliance with spam guidelines.
• Compress: Save successful personalization hooks and record low-response angles in negative cases.

4. Research, Financial & Legal Analysis

• Pipeline: Discovery & Source Ingestion -> Fact-Checking & Risk Matrix -> Quantitative / Legal Synthesis -> Scenario Stress-Testing -> Executive Briefing
• Learn Check: Ingest precedent cases, past analysis oversights, and data validity standards.
• Verification Gate: 100% cited source tracing; risk matrices tested against stress scenarios.
• Compress: Save synthesis templates, source reliability ratings, and risk assessment heuristics.

---

Subagent Dispatch Guidelines

When dispatching subagents inside a loop:

1. Role Specificity: Never prompt a generalist agent. Prefix prompts with domain role instructions (e.g., You are the QA Reproducer Subagent...).
2. Memory Injection: Always supply the paths or summary of relevant .loop-memory/ cases in the initial subagent prompt.
3. Discrete Handoffs: Subagents should communicate through explicit files (e.g., reproduction scripts, draft files, evaluation rubrics) rather than conversational history.
4. Autonomous Step Gate: A subagent is NOT allowed to advance etapas.json status to "completed" without verifiable proof (logs, test outputs, validation scores).

---

Common Mistakes & Anti-Patterns

Anti-Pattern	Why It Breaks the Loop	The Correct Practice
Skipping the Learn phase	Agents reinvent known bugs or use rejected copy angles.	Enforce reading .loop-memory/ as step 0 in every prompt.
Omitting the Compress phase	Lessons are lost as soon as the session context resets.	Never conclude a task without distilling winning/failing cases into files.
Monolithic agent execution	A single agent gets confused trying to plan, code, verify, and document at once.	Dispatch specialized subagents for each discrete stage.
Soft verification ("looks good")	Hallucinations slip into production.	Use deterministic gates: test suites, linter output, fact citations.
Unbounded retry loops	Agent loops infinitely on an unfixable defect.	Limit loop retries to 3 iterations before triggering a human escalation gate.