Forem: Otoniel Rojas

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

Otoniel Rojas — Fri, 03 Apr 2026 21:15:38 +0000

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.

7. Getting Started (2–5 minutes)

Clone https://github.com/otonielrojas/iraf-demo
Add hero.jpg to the root (or use your own).
Open in Windsurf, Cursor, or Claude Code.
Paste the bootstrap prompt from the README.
Approve file/Git prompts and watch recursion happen.

The future of software isn’t just written — it is iteratively refined inside your next Git repository.

Try the Demo → https://iraf-demo.netlify.app

Fork & Contribute → https://github.com/otonielrojas/iraf-demo

Drop a comment below if you run the bootstrap prompt — I’d love to see how your agents evolve their own domains!

The Sacrilegious Coder

Otoniel Rojas — Sat, 22 Nov 2025 23:06:48 +0000

Why AI is not a cheat code, but the natural evolution of language.

In the strict, cathedral-like structures of traditional software development, I have always been something of a sacrilegious agent. While the high priests of code worship at the altars of strict procedure, linting rules, and design patterns, I have existed in the experimental fringe—exploring, breaking, and rebuilding.

For years, the divide was clear. To build, you had to submit to the dogma: learn the syntax, memorize the boilerplate, and respect the hierarchy of abstraction.

But the arrival of Artificial Intelligence has shattered the stained glass. It has exposed a truth that many traditionalists are desperate to ignore:

Code was never the destination; it was merely a friction-heavy translator for human reason.

The Boilerplate Blindfold

Traditional developers often pride themselves on "doing things the right way." This usually implies a rigorous adherence to specific frameworks, architectural patterns (MVC, MVVM, Clean Architecture), and syntax rules. There is a comfort in this rigidity. It feels scientific. It feels engineered.

However, looking at it through the lens of this new era, much of this "engineering" looks suspiciously like ritual.

A vast majority of modern coding is the management of boilerplate—repetitive sections of code that are necessary to satisfy the compiler or framework but contribute nothing to the unique logic of the application. We have spent decades convincing ourselves that writing CRUD (Create, Read, Update, Delete) operations by hand is a skill.

It is not. It is a tax.

The traditional developer is often unaware of their dependence on these patterns. They have mistaken the map for the territory, believing that the act of typing code is where the value lies, rather than the logic governing the system.

AI: The Natural Extension of Reason

To me, AI is not a "cheat code" or a shortcut; it is the ultimate compiler.

The history of computing is a history of rising language levels. We moved from binary to Assembly, from Assembly to C, from C to Python. Each step distanced us from the metal and brought us closer to human thought.

AI is the final leap in this evolution. It allows us to bypass the "mixed bag" of APIs, documentation lookups, and syntax errors, and engage directly with the highest goal of language communication.

When I prompt an AI, I am not "coding" in the traditional sense; I am structuring logic using the universal language of reason. If I can articulate a complex system—its inputs, its transformations, its desired outputs—with clarity and logic, the AI handles the implementation details.

This shifts the primary skill of the creator from Syntax Retention to Systemic Reasoning.

The Inevitable Resistance

We are already seeing the antibodies of the traditional world attacking this new organism. "It’s not real code," they say. "It’s hallucinations." "It’s unmaintainable."

This resistance is natural. It is the reaction of a guild that realizes its gatekeeping power is dissolving.

They will stick to their old practices not because those practices are superior, but because those practices are their identity.

For a developer who has spent twenty years learning the idiosyncrasies of memory management or the specific quirks of a JavaScript build pipeline, the idea that a "common" person could achieve the same result using plain English is terrifying. It feels like a violation of the rules of engagement.

They will cling to the difficulty of the process as proof of its value.

The Independence of the Common Creator

We are standing at the precipice of a new era of independence. For the first time, the barrier to creation is not technical literacy, but conceptual clarity.

This is the beginning of the independence of the common man and woman. The "impossible" ideas—the apps, the tools, the digital art—that were previously locked behind the paywall of a $150,000 education or years of tedious study are now accessible to anyone with the right idea and the reason to articulate it.

The future belongs not to those who can write the most lines of flawless code, but to those who can think the most clearly.

The tools of the trade have changed. The new IDE is the human mind, and the new programming language is truth.

Originally published on Medium.