Loop Engineering

The PR Babysitter loop includes built-in safety measures:

• No auto-merge: The loop is configured to propose changes rather than merging them automatically.
• Denylist: Sensitive areas such as auth, payments, and secrets are denylisted to prevent automated interference with critical logic.

When designing agentic systems, distinguish between the environment of a single agent and the orchestration of multiple runs:

• Agent Harness Engineering: Focuses on the environment for a single agent, including its tools, context, permissions, and rules (the sandbox).
• Loop Engineering: Focuses on the scheduling and orchestration of harness runs over time, including state management and verification chains.

Formula: Harness = single session setup Loop = harness + schedule + state + verification chain

Loop Engineering is a concept focused on designing autonomous loops rather than direct prompting. The framework is synthesized from several key sources:

• Core Definition: Based on work by Cobus Greyling and Addy Osmani, involving the 'five primitives + memory' model.
• Anthropic / Claude Code Perspective: Emphasizes turning workflows into skills and loops. In Claude Code, /loop, /goal, and /schedule are treated as first-class primitives.
• Related Concepts: To design effective loops, consider concepts like Agent Harness Engineering, The Factory Model, Intent Debt, Comprehension Debt, Cognitive Surrender, and Orchestration Tax.

This repository aims to transform these abstract frameworks into practical, copyable patterns, templates, and tool-specific guidance.

The KY Cut Surface Philosophy v0.1 is a public philosophical artifact that posits a core thesis: candidate generation is not consequence realization.

This philosophy serves as a conceptual bridge to Loop Engineering. For a technical deep dive into how this relates to generation versus consequence, refer to the documentation at stories/ky-cut-surface-generation-vs-consequence.md within the repository.

The stories/ directory contains documented real-world implementations and failures categorized by their engineering pattern. Key patterns include:

• Daily Triage: Moving from L1 (report only) to L2 (auto-fix) after calibration.
• CI Sweeper: Automated maintenance within CI pipelines (requires budget controls and kill switches).
• PR Babysitter: Managing PR state with attempt limits and verifiers.
• Multi-loop: Handling collisions between concurrent loops using branch locks and priority locks.
• Dependency Sweeper: Automating dependency updates (requires verifiers to match CI install paths).
• Quant research: Using numerical checkers as verifiers for backtests.
• Post-Merge Cleanup: Off-peak maintenance tasks.
• Changelog Drafter: Low-risk, high-ROI automation.

@cobusgreyling/readiness-core provides core types and utilities used by loop-audit and goal-audit. It is primarily intended for internal use within the loop-engineering monorepo to ensure consistent auditing logic across different packages.

Key features include:

• Shared types such as BaseAuditResult and Finding.
• Core heuristics for auditing file existence.
• Core heuristics for auditing skill directories.

Loop Engineering is part of a layered ecosystem designed to scale from single prompts to entire populations of agents. Use the following layers to address specific needs:

• Memory Layer: Manages tiers and recall budgets (memory-engineering).
• Design Layer (This Repo): Provides patterns, starters, and the Loop Ready score (loop-engineering).
• Runtime Layer: Provides versioned harnesses and traces (harness-foundry).
• Governance Layer: Provides evidence and verdicts (outerloop).
• Fleet Layer: Governs populations of agents with registries and kill switches (fleet-engineering).

Loop engineering is built upon five core primitives plus a durable memory layer:

• Automations / Scheduling: Handles discovery and triage on a set cadence.
• Worktrees: Provides safe, parallel execution environments.
• Skills: Maintains persistent project knowledge.
• Plugins & Connectors: Enables interaction with real tools (e.g., via MCP).
• Sub-agents: Implements the maker/checker split.
• Memory / State: Acts as a durable spine outside of any specific conversation.

When running npx @cobusgreyling/loop init, you can specify a --pattern to address specific workflow pain points:

If you prefer not to use loop-init, you can manually copy the required files from the starter template into your project root:

cp -r starters/pr-babysitter-opencode/skills .
cp starters/pr-babysitter-opencode/AGENTS.md .
cp starters/pr-babysitter-opencode/LOOP.md .
cp starters/pr-babysitter-opencode/pr-babysitter-state.md.example pr-babysitter-state.md
cp starters/pr-babysitter-opencode/opencode.json.example opencode.json

If you prefer not to use the scaffold command, you can manually copy the required files from the starter directory into your project root:

cp -r starters/minimal-loop-opencode/skills .
cp starters/minimal-loop-opencode/AGENTS.md .
cp starters/minimal-loop-opencode/LOOP.md .
cp starters/minimal-loop-opencode/STATE.md.example STATE.md
cp starters/minimal-loop-opencode/opencode.json.example opencode.json