Docs › Universal Loop

Universal Self-Improvement Loop

A config-driven audit engine and self-improvement loop that works in any project, any stack, any agent client. v3.0.0

Overview

This page proves that the self-improvement loop works in any project, any stack, any agent client. The loop detects code quality issues automatically, diagnoses them against known patterns, proposes fixes, and executes them — all within a single, config-driven pipeline that adapts to the project's language, framework, and agent environment.

Architecture

Two components power the loop: universal-audit.sh — a config-driven audit engine that scans code against project-specific rules — and the self-improvement skill — an orchestrator that interprets audit results and drives the fix pipeline.

init-agents → scaffolding → audit detects → skill diagnoses
       ↓
agent proposes → human approves → fix → verify → commit

Execution Flow

init-agents — bootstraps the project with audit config, scripts, and skill directory
scaffolding — creates PATTERNS.md, ANTI-PATTERNS.md, ADR skeleton
audit detects — universal-audit.sh scans codebase and emits JSON report
skill diagnoses — the self-improvement skill matches findings to patterns
agent proposes — agent presents a fix plan with rationale
human approves — user reviews and approves or rejects the proposal
fix → verify → commit — approved fix is applied, re-audited, and committed

Key Files

The init-agents command creates 7 artifacts that form the loop's infrastructure:

File	Purpose
`.audit-config.json`	Configuration for the audit engine: excludes, severity levels, language-specific rules
`scripts/audit-project.sh`	The audit script that runs checks and outputs structured JSON
`skills/self-improvement/`	Skill directory containing the orchestrator and pattern definitions
`PATTERNS.md`	Catalog of recognized improvement patterns with severity and fix strategies
`ANTI-PATTERNS.md`	Catalog of anti-patterns to detect and avoid
`ADRs/`	Architecture Decision Records directory for documenting audit-driven decisions
`scripts/generate-adr.sh`	Automated ADR generator for documenting fixed issues

Stack Awareness

The loop auto-detects the project's language and configures excludes and check presets accordingly. Supported stacks and their auto-detection markers:

Node.js — detects package.json, excludes node_modules/, uses ESLint/Prettier presets
Python — detects pyproject.toml or requirements.txt, excludes __pycache__ and .venv
Rust — detects Cargo.toml, excludes target/
Go — detects go.mod, excludes vendor directory

The auto-detected configuration is written to .audit-config.json:

{
  "version": "3.0.0",
  "stack": "node",
  "excludes": ["node_modules", "dist", ".next"],
  "checks": {
    "patterns": true,
    "anti-patterns": true,
    "adr-gap": true,
    "skill-gap": true
  },
  "severity": {
    "P0": "blocking",
    "P1": "high",
    "P2": "medium",
    "P3": "low"
  }
}

Agent Client Support

The loop uses a detect_target mechanism to adapt its output format and invocation style to the agent client in use:

Client	Detection	Format
OpenCode	`OPENCODE_HOME` env var	Standard skill invocation via `skill()` tool
Claude Code	`CLAUDE_CODE` env var	CLAUDE.md + `.claude/skills/` convention
Cursor	`cursor` in `TERM_PROGRAM`	`.cursorrules` injection
Devin	`DEVIN` env var	Devin-compatible instruction format
Gemini CLI	`GEMINI_CLI` env var	Gemini-compatible prompt template

Cross-Platform

On Unix systems, the init command creates symlinks for the skill and script directories. On Windows, where symlinks may require elevated privileges, the loop falls back to copying the files instead. The init-agents.sh script detects the platform automatically and selects the appropriate strategy — no manual flags needed.

Quick Start

Initialize the loop in any project with a single command, then run the audit:

bash init-agents.sh
bash scripts/audit-project.sh --json
# Review the output, then run the self-improvement loop:
# "run self-improvement loop"