Home

🔁 Loop Engineering: Systems Architecture & Knowledge Base

Welcome to the Loop Engineering documentation and systems portal.

• Repository: sololys/loop-engineering
• Interactive Showcase: Explore the Showcase
• Core Doctrine: Stop prompting. Design the loop. Get a score.
• Ecosystem Role: Operational Harness for Autonomous Code Agents, Strict Evaluation Frameworks, and Deterministic Local-First CLI Utilities.

---

🏛️ Foundational Manifesto: From Conversational Persuasion to Deterministic Regulation

The prevailing paradigm of human-machine interaction relies on a critical structural flaw: the ad-hoc prompt. This high-entropy method assumes that continuous, manual intervention can reliably steer an autonomous computational agent, but in practice, it merely introduces cognitive fatigue, context degradation, and operational drift. To arrest this decay, the architecture must transition from conversational persuasion to deterministic regulation. Loop Engineering eliminates the fragility of human prompting by replacing it with a closed, autonomous control system—a rigorous operational harness where execution is dictated not by improvisation, but by pre-configured, immutable design.

Within this paradigm, computational agency is no longer an open-ended dialogue but a formalized geometric trajectory. An operational loop is initiated by a defined trigger, drawing upon strict contextual boundaries before generating an action internally. This execution is immediately subjected to a harsh verification gate, enacted through an adversarial separation between the subagent that generates and the subagent that validates. Only when this internal admissibility test is satisfied does the system update its state memory and proceed. By confining this entire sequence within isolated worktrees and enforcing explicit constraints, the system achieves true autonomy: the capacity to execute continuously without the liability of human babysitting.

Autonomy, however, is inherently volatile unless bound by unforgiving limits. The architecture secures itself through fail-closed circuit breakers, strict path denylists, and rigid cost ceilings, ensuring that any deviation from the operational contract results in immediate termination rather than compounding error. This structural integrity is never left to assumption; it is quantified through a definitive readiness evaluation. Before any loop is permitted to operate in a production environment, it must prove its transition from an unsafe script into a hardened asset, measured against a strict metric that demands explicit memory contracts, continuous state synchronization, and absolute zero drift.

Ultimately, this operational tooling functions as the mechanical execution of a broader epistemic philosophy. The localized utilities and automated triage patterns are not merely development conveniences; they are the physical manifestation of the realization gate, demanding that developers stop prompting and instead architect the loop itself. By enforcing this strict separation between generative noise and validated consequence, the system ensures that every automated action is anchored in deterministic law. It is an architecture that survives and scales not by expanding the freedom of the agent, but by perfecting the precision of its constraints.

---

⚡ The Loop Engineering Paradigm

Conventional AI-assisted development relies on human-driven prompting—an ad-hoc, high-entropy process that suffers from fatigue, context loss, and operational drift.

Loop Engineering replaces manual prompting by designing closed, autonomous control systems that prompt, supervise, and verify agents deterministically:

TRIGGER ───► CONTEXT ───► PROMPT ───► ACTION ───► VERIFICATION ───► STATE UPDATE
   ▲                                                                        │
   └─────────────────────── NEXT ITERATION / HALT ◄─────────────────────────┘

By enforcing strict boundaries, isolated git worktrees, explicit budget ceilings, and an adversarial Maker/Checker split, loops run continuously or on demand without human babysitting.

---

🧭 Core Documentation & Navigation

1. Core Primitives & Memory
   The Five Primitives (Scheduling, Worktrees, Skills, MCP Connectors, Maker/Checker Subagents) and the stateful memory contracts (STATE.md, LOOP.md, loop-budget.md, loop-constraints.md).

2. Production Patterns
   The 7 battle-tested operational loop patterns: ci-sweeper, daily-triage, dependency-sweeper, issue-triage, pr-babysitter, changelog-drafter, and post-merge-cleanup.

3. CLI Tooling Suite
   Reference and usage for local-first CLI tools: loop-audit, loop-init, loop-cost, loop-sync, loop-context, and loop-mcp-server.

4. Safety & Circuit Breakers
   Guardrails, path denylists (.env, secrets, prod k8s/auth), token/cost ceilings, drift traps, and fail-closed termination.

5. Multi-Loop Orchestration
   Concurrent execution across worktrees, shared state synchronization, lock management, and escalation paths.

6. Ecosystem Integration
   Mapping Loop Engineering into Epistemic Architectures ($\Phi \to \Pi_k \to \Omega \to W$) and deterministic verification gates.

---

📊 The Loop Readiness Score

Before running any autonomous loop in production, evaluate its structural readiness using loop-audit:

npx @cobusgreyling/loop-audit . --suggest

Score Tier	Status	Readiness Level
0 – 39	🔴 Unsafe	Ad-hoc prompt script. Missing memory contracts, budget limits, or verification gates.
40 – 69	🟡 Partial	Has basic prompt & state, but lacks isolated worktrees, cost ceiling, or path denylists.
70 – 89	🟢 Production	Fully scaffolded: explicit budget, constraints, state sync, and maker/checker separation.
90 – 100	💎 Hardened	Full evaluation suite, MCP least-privilege scoping, automated circuit breakers, and zero drift.

---

🛠️ Quickstart (5 Minutes)

# 1. Initialize a new production loop (e.g. daily triage with Grok or Claude)
npx @cobusgreyling/loop-init . --pattern daily-triage --tool grok

# 2. Check token spend and cost boundaries
npx @cobusgreyling/loop-cost

# 3. Audit structural loop readiness
npx @cobusgreyling/loop-audit . --badge

# 4. Verify state synchronization
npx @cobusgreyling/loop-sync .