Core Primitives

🧱 Core Primitives and Memory Architecture

Loop engineering is built on five core primitives combined with an explicit, file-based memory architecture. Together, they transform unstructured LLM sessions into robust, repeatable, autonomous software processes.

---

1. The Five Primitives

┌────────────────────────────────────────────────────────────────────────┐
│                        1. SCHEDULING / TRIGGER                         │
│             (Cron, Systemd, GitHub Actions, /loop, /goal)              │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                         2. ISOLATED WORKTREE                           │
│             (Git worktree: clean branch, zero file conflict)           │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                              3. SKILLS                                 │
│        (Persistent intent, conventions, build & test commands)         │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                    4. CONNECTORS / MCP SUBSTRATE                       │
│     (External API access: GitHub PRs, Linear tickets, Slack alerts)    │
└───────────────────────────────────┬────────────────────────────────────┘
                                    │
                                    ▼
┌────────────────────────────────────────────────────────────────────────┐
│                    5. SUB-AGENTS (MAKER / CHECKER)                     │
│      Maker proposes code ──► Checker evaluates against strict rubric   │
└────────────────────────────────────────────────────────────────────────┘

1. Automations / Scheduling (The Heartbeat)

Without a durable trigger, an agent is merely an interactive chatbot.

• Interval-based: Runs every $N$ hours or days (e.g., daily dependency audit).
• Event-based: Triggered by webhook, repository dispatch, or CI failure.
• Goal-directed: Iterates continuously until a concrete, verifiable condition evaluates to true (/goal).

2. Worktrees (Parallelism Without Chaos)

When multiple agents or loops touch the same repository files simultaneously, conflicts and race conditions are inevitable.

• Every loop invocation creates or checks out an isolated git worktree.
• History is shared, but the active working tree is strictly isolated.
• Worktrees are automatically purged upon task completion or escalation.

3. Skills (Persistent Intent)

Without skills, an agent suffers from intent debt—it must rediscover project architecture, lint standards, and build rules on every single run.

• Encoded in SKILL.md documents containing instructions, reference scripts, and edge-case lessons.
• Units of modular reuse packaged across repositories.

4. Connectors & MCP (Least-Privilege External Interfaces)

The Model Context Protocol (MCP) provides standard interfaces for reading and modifying external issue trackers, chat channels, and pull requests:

• GitHub MCP: Read issues/PRs, open draft PRs, add labels (no auto-merge by default).
• Linear / Jira MCP: Read tickets, update workflow status.
• Slack / Discord MCP: Send alerts exclusively to dedicated escalation channels.

5. Maker / Checker Split

The agent that writes code must never be the sole judge of its correctness.

• The Maker: High-creativity agent tasked with solving the problem, writing diffs, and generating candidate solutions.
• The Checker: Independent agent (often running a different model or system prompt) tasked with running tests, inspecting security invariants, and verifying against strict acceptance criteria.

---

2. Stateful Memory Architecture

Loops preserve state and context across disjoint invocations through standardized markdown files:

.
├── STATE.md               # Dynamic status: active task, blocker, last commit
├── LOOP.md                # System contract: mission, input, output, cadence
├── loop-budget.md         # Hard financial & token limits (per run / day)
├── loop-constraints.md    # Path denylist, forbidden patterns, human gates
└── loop-run-log.md        # Append-only audit history of previous iterations

Memory Contract	Lifespan	Purpose
STATE.md	Ephemeral / Mutable	Tracks what the loop is currently doing, what was just finished, and what is next.
LOOP.md	Static / Governed	The operational contract defining the loop's exact scope, inputs, outputs, and cadence.
loop-budget.md	Enforced Boundary	Defines max token spend, API call limits, and maximum runtime minutes.
loop-constraints.md	Immutable Guardrail	Specifies forbidden paths (.env, secrets, prod terraform), forbidden commands, and required checks.
loop-run-log.md	Append-Only Ledger	Historical log of every execution, diff generated, and checker verdict.