The Iterative Refinement Agentic Framework (IRAF): A Git-Native Architecture for Autonomous, Self-Improving AI Systems

#ai #automation #promptengineering #agentskills

Originally published on Medium: Read the original post

A Git-native system where AI agents plan, build, evaluate, and refine their own landing page — in real time.

This framework originated from a collaborative ideation process between human and AI. The core vision — blending agency, delegation, and self-evolving Markdown blueprints to overcome developer resistance — was driven by human insight into organizational psychology and real-world adoption barriers. The architecture, repository prototypes, and this write-up were iteratively refined together. Full credit to Otoniel’s original concept and direction.

In 2026, AI agents are technically mature, yet enterprise adoption lags due to a deeply human barrier: lack of trust, fear of lost control, and reluctance to abandon legacy workflows. Traditional frameworks rely on opaque external orchestration, requiring constant human babysitting.

IRAF (Iterative Refinement Agentic Framework) is a novel, platform-agnostic pattern that embeds a closed-loop feedback system directly into a Git repository. Using only three structured Markdown blueprint files (agents.md, skills.md, clauses.md), agents autonomously plan, delegate, execute, self-evaluate, and — crucially — rewrite their own definitions. Git becomes the single source of truth: every decision and improvement is versioned, auditable, and reversible. The human shifts from micromanager to evolutionary architect.

Live Demo

GitHub repo: https://github.com/otonielrojas/iraf-demo
Deployed site: https://iraf-demo.netlify.app

1. The Core Problem: The Trust Gap in the Agentic Era

Decades of engineering culture prized explicit human control. Modern AI offers genuine agency, yet it triggers resistance: developers treat models as fancy autocomplete, avoid deep orchestration, and default to “black-box” skepticism of tools like Auto-GPT or LangGraph.

What’s missing is a system that proves its safety and value through visible, Git-native evolution.

2. The Vision: Iterative Refinement as the Operating Principle

IRAF operates on a fractal closed loop:

Agency — Agents make autonomous decisions within strict bounds.
Delegation — Tasks are decomposed and routed to specialized sub-agents.
Self-Evaluation — Independent LLM-as-judge scoring against explicit criteria.
Refinement — Agents update the blueprint files themselves.

The entire state lives in the repo. No proprietary servers. Every change is a Git commit.

3. Architecture: The Repository as the Brain

All intelligence lives in lightweight Markdown files at the root.

agents.md — Agent Registry (defines personas, responsibilities, triggers, and delegation rules)
skills.md — Modular Capabilities (Tailwind CDN + Mermaid visualization)
clauses.md — Governance Constitution (strict safety rules, commit format, and weighted evaluation criteria: 40% technical correctness, 40% trust/clarity, 20% visual polish — minimum passing score 90)

4. Proof in Action: The Live Demo

I ran the bootstrap prompt in Windsurf with Claude Opus 4.6. After just 2 iterations the system reached a score of 92/100 and produced the polished landing page you see below.

The agents:

Added the hero image and modern Tailwind styling
Wrote the trust narrative and governance principles
Embedded and rendered the Mermaid recursion diagram
Added scoring transparency and feature grid
Updated the footer with live iteration/score data
Committed everything with the exact standardized format

Watch the Full Recursion Happen Live (6 minutes, raw)

https://youtu.be/h0OIUTcCtGM

5. Why This Architecture Breaks Down Resistance

Psychological Safety — Git history makes every improvement transparent; git revert undoes any hallucination.
Zero Vendor Lock-in — Pure Markdown + Git works with any LLM backend.
Measurability — Built-in evaluator scores deliver clear ROI.

6. The Road to Autonomy: From Local to Cloud

IRAF is designed for a frictionless transition. Run locally in your AI IDE to build trust, then promote to GitHub Actions / Netlify for 24/7 operation while keeping the developer as final authority.