Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.
TypeScript agentic-aiai-agentsai-codinganthropicautomationclaudeclaude-codecodexcoding-agentsdevops-automationdevtoolsgithub-actionsgrokllmloop-engineeringmcpprompt-engineering
docs: add deeper architecture diagrams (#288)
JonyT Agentic4e9842117abd
diff --git a/README.md b/README.mdindex 8e4dcf6..6ef60f0 100644--- a/README.md+++ b/README.md@@ -164,6 +164,8 @@ flowchart LR</details>+Deeper diagrams — the actor-level sequence within one run, the run lifecycle's states, autonomy levels L1-L3, and how `tools/` maps onto the primitives — live in [docs/architecture-diagrams.md](docs/architecture-diagrams.md).+**This reference repo now runs its own `validate-patterns` + `audit` workflows on every push/PR** (see `.github/workflows/`). We also added `LOOP.md` describing the loops that will maintain it.## Patternsdiff --git a/docs/architecture-diagrams.md b/docs/architecture-diagrams.mdnew file mode 100644index 0000000..3798543--- /dev/null+++ b/docs/architecture-diagrams.md@@ -0,0 +1,142 @@+# Architecture Diagrams++Deeper, more detailed companions to the [Anatomy of a Loop](../README.md#anatomy-of-a-loop) diagram in the README. Where that one shows the linear shape of a single loop, these show: the actor-level sequence within one run, the states a run moves through, how the three autonomy levels relate, and how the actual tools in `tools/` map onto the [Five Building Blocks + Memory](primitives.md) model.++All diagrams are [Mermaid](https://mermaid.js.org/), rendered natively by GitHub when viewing this file.++## One loop cycle (sequence)++Who talks to whom, in order, within a single run — including the fork between the safe auto-path and the human escalation path.++```mermaid+sequenceDiagram+ actor Eng as Engineer+ participant Sched as Scheduler+ participant Skill as Triage Skill+ participant State as STATE.md / Memory+ participant WT as Worktree+ participant Maker as Implementer Agent+ participant Check as Verifier Agent+ participant MCP as MCP / Git / Tickets+ participant Gate as Human Gate++ Sched->>Skill: Fire pattern (e.g. daily-triage)+ Skill->>State: Read goals + last run + budget+ State-->>Skill: Context snapshot+ Skill->>WT: Create isolated worktree+ WT-->>Skill: worktree path+ Skill->>Maker: Task with skills + constraints+ Maker->>Maker: Implement change in worktree+ Maker->>Check: Hand off patch+ Check->>Check: Run tests + policy gates++ alt Verify pass and budget OK+ Check->>MCP: Open PR or update ticket+ MCP-->>Gate: PR link + summary+ Gate->>Gate: Safe and allowlisted?+ alt Safe auto-path+ Gate->>MCP: Approve merge or leave L1 report+ MCP->>State: Write run outcome+ else Risky or ambiguous+ Gate->>Eng: Escalate with full context+ Eng->>MCP: Decide / override+ MCP->>State: Write decision + outcome+ end+ else Verify fail or budget exceeded+ Check->>State: Log failure mode+ Check->>Eng: Report only, no auto-merge+ end+```++## Run lifecycle (state)++The states one scheduled run moves through, from cadence fire to the final durable log entry.++```mermaid+stateDiagram-v2+ [*] --> Scheduled+ Scheduled --> LoadingContext: cadence fire+ LoadingContext --> BlockedBudget: budget exceeded+ LoadingContext --> RunningTriage: context OK+ RunningTriage --> WorkingInWorktree: task selected+ RunningTriage --> IdleNoop: nothing to do+ WorkingInWorktree --> Verifying: implementer done+ Verifying --> AwaitingHumanGate: verify pass + risky+ Verifying --> Failed: verify fail+ AwaitingHumanGate --> Applied: human or allowlist approve+ AwaitingHumanGate --> Rejected: human reject+ Applied --> Logged+ Failed --> Logged+ Rejected --> Logged+ BlockedBudget --> Logged+ IdleNoop --> Logged+ Logged --> [*]+```++## Autonomy levels L1-L3++How a pattern moves between report-only, assisted, and unattended operation — see [primitives-matrix.md](primitives-matrix.md) for the readiness criteria behind each transition.++```mermaid+stateDiagram-v2+ [*] --> L1_ReportOnly+ L1_ReportOnly --> L2_Assisted: audit score up + human OK+ L2_Assisted --> L3_Unattended: denylist + budget + gates proven+ L3_Unattended --> L2_Assisted: incident or cost spike+ L2_Assisted --> L1_ReportOnly: kill switch+ L3_Unattended --> L1_ReportOnly: kill switch+```++## Stack: primitives + tools++The [Five Building Blocks + Memory](primitives.md) model made concrete: which package in `tools/` implements which primitive, and how they connect.++```mermaid+flowchart TB+ subgraph Human["Engineer / Owner"]+ Design[Design LOOP.md patterns]+ Gate[Human gate + kill switch]+ Review[Read PRs + reports]+ end++ subgraph Control["Control plane"]+ Sched[Automations / Scheduling]+ Patterns[patterns/registry.yaml]+ Cost[loop-cost: estimate spend]+ end++ subgraph Memory["Durable memory"]+ State[STATE.md]+ LoopDoc[LOOP.md]+ Context[loop-context: prune, inject, circuit breaker]+ Sync[loop-sync]+ end++ subgraph Execution["Execution plane"]+ WT[loop-worktree: isolated attempts + locks]+ Maker[Implementer sub-agent]+ Verifier[Verifier sub-agent]+ end++ subgraph Tooling["CLIs + connectors"]+ Init[loop-init: scaffold]+ Audit[loop-audit: readiness score]+ MCP[MCP server: read-only policy + tools]+ end++ Design --> Patterns+ Init --> State+ Init --> LoopDoc+ Sched --> Patterns+ Patterns --> Cost+ Cost --> Context+ Patterns --> WT+ State <--> Sync+ WT --> Maker+ Maker --> Verifier+ Verifier --> Context+ Context --> Gate+ Verifier --> MCP+ Gate --> Review+ Audit --> Design+```diff --git a/docs/assets/css/showcase.css b/docs/assets/css/showcase.cssindex 5cda479..c2fa44f 100644--- a/docs/assets/css/showcase.css+++ b/docs/assets/css/showcase.css@@ -380,6 +380,38 @@ section {box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);}+/* Architecture diagrams */+.diagram-list {+ display: flex;+ flex-direction: column;+ gap: 24px;+}++.diagram-card {+ overflow-x: auto;+}++.diagram-card .tag {+ font-size: 0.7rem;+ font-weight: 700;+ letter-spacing: 0.08em;+ text-transform: uppercase;+ color: var(--accent-2);+ margin-bottom: 12px;+}++.diagram-card h3 {+ font-size: 1.15rem;+ font-weight: 700;+ margin-bottom: 16px;+}++.diagram-card .mermaid {+ display: flex;+ justify-content: center;+ min-width: 480px;+}+.pattern-card .tag {font-size: 0.7rem;font-weight: 700;diff --git a/docs/index.html b/docs/index.htmlindex 151f811..0ab126b 100644--- a/docs/index.html+++ b/docs/index.html@@ -14,6 +14,28 @@ title: Loop Engineering — Showcase<meta property="og:image" content="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-social-banner.jpg"><link rel="stylesheet" href="{{ site.baseurl }}/assets/css/showcase.css"><link rel="icon" href="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-logo.svg">+ <script type="module">+ import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";+ mermaid.initialize({+ startOnLoad: true,+ theme: "dark",+ securityLevel: "loose",+ themeVariables: {+ background: "#111a28",+ primaryColor: "#132235",+ primaryTextColor: "#e8edf5",+ primaryBorderColor: "#3ee8c5",+ lineColor: "#5b9dff",+ secondaryColor: "#0d1420",+ tertiaryColor: "#111a28",+ textColor: "#e8edf5",+ clusterBkg: "#0d1420",+ clusterBorder: "#2a3b52",+ edgeLabelBackground: "#111a28",+ fontFamily: "SF Pro Display, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",+ },+ });+ </script></head><body>@@ -38,6 +60,7 @@ title: Loop Engineering — Showcase<ul class="nav-links"><li><a href="#patterns">Patterns</a></li><li><a href="#primitives">Primitives</a></li>+ <li><a href="#architecture">Architecture</a></li><li><a href="#interactive">Picker</a></li><li><a href="#start">Get Started</a></li><li><a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md">Quickstart</a></li>@@ -173,6 +196,150 @@ title: Loop Engineering — Showcase</p></section>+<section id="architecture" class="wrap">+ <p class="section-label">Deeper architecture</p>+ <h2 class="section-title">How one run actually moves</h2>+ <p class="section-desc">The actor-level sequence within a run, the states it passes through, how the three autonomy levels relate, and how the tools in this repo map onto the primitives above.</p>+ <div class="diagram-list">+ <div class="pattern-card diagram-card">+ <div class="tag">Sequence</div>+ <h3>One loop cycle</h3>+ <pre class="mermaid">+sequenceDiagram+ actor Eng as Engineer+ participant Sched as Scheduler+ participant Skill as Triage Skill+ participant State as STATE.md / Memory+ participant WT as Worktree+ participant Maker as Implementer Agent+ participant Check as Verifier Agent+ participant MCP as MCP / Git / Tickets+ participant Gate as Human Gate++ Sched->>Skill: Fire pattern (e.g. daily-triage)+ Skill->>State: Read goals + last run + budget+ State-->>Skill: Context snapshot+ Skill->>WT: Create isolated worktree+ WT-->>Skill: worktree path+ Skill->>Maker: Task with skills + constraints+ Maker->>Maker: Implement change in worktree+ Maker->>Check: Hand off patch+ Check->>Check: Run tests + policy gates++ alt Verify pass and budget OK+ Check->>MCP: Open PR or update ticket+ MCP-->>Gate: PR link + summary+ Gate->>Gate: Safe and allowlisted?+ alt Safe auto-path+ Gate->>MCP: Approve merge or leave L1 report+ MCP->>State: Write run outcome+ else Risky or ambiguous+ Gate->>Eng: Escalate with full context+ Eng->>MCP: Decide / override+ MCP->>State: Write decision + outcome+ end+ else Verify fail or budget exceeded+ Check->>State: Log failure mode+ Check->>Eng: Report only, no auto-merge+ end+ </pre>+ </div>+ <div class="pattern-card diagram-card">+ <div class="tag">State</div>+ <h3>Run lifecycle</h3>+ <pre class="mermaid">+stateDiagram-v2+ [*] --> Scheduled+ Scheduled --> LoadingContext: cadence fire+ LoadingContext --> BlockedBudget: budget exceeded+ LoadingContext --> RunningTriage: context OK+ RunningTriage --> WorkingInWorktree: task selected+ RunningTriage --> IdleNoop: nothing to do+ WorkingInWorktree --> Verifying: implementer done+ Verifying --> AwaitingHumanGate: verify pass + risky+ Verifying --> Failed: verify fail+ AwaitingHumanGate --> Applied: human or allowlist approve+ AwaitingHumanGate --> Rejected: human reject+ Applied --> Logged+ Failed --> Logged+ Rejected --> Logged+ BlockedBudget --> Logged+ IdleNoop --> Logged+ Logged --> [*]+ </pre>+ </div>+ <div class="pattern-card diagram-card">+ <div class="tag">State</div>+ <h3>Autonomy levels L1-L3</h3>+ <pre class="mermaid">+stateDiagram-v2+ [*] --> L1_ReportOnly+ L1_ReportOnly --> L2_Assisted: audit score up + human OK+ L2_Assisted --> L3_Unattended: denylist + budget + gates proven+ L3_Unattended --> L2_Assisted: incident or cost spike+ L2_Assisted --> L1_ReportOnly: kill switch+ L3_Unattended --> L1_ReportOnly: kill switch+ </pre>+ </div>+ <div class="pattern-card diagram-card">+ <div class="tag">Architecture</div>+ <h3>Stack: primitives + tools</h3>+ <pre class="mermaid">+flowchart TB+ subgraph Human["Engineer / Owner"]+ Design[Design LOOP.md patterns]+ Gate[Human gate + kill switch]+ Review[Read PRs + reports]+ end++ subgraph Control["Control plane"]+ Sched[Automations / Scheduling]+ Patterns[patterns/registry.yaml]+ Cost[loop-cost: estimate spend]+ end++ subgraph Memory["Durable memory"]+ State[STATE.md]+ LoopDoc[LOOP.md]+ Context[loop-context: prune, inject, circuit breaker]+ Sync[loop-sync]+ end++ subgraph Execution["Execution plane"]+ WT[loop-worktree: isolated attempts + locks]+ Maker[Implementer sub-agent]+ Verifier[Verifier sub-agent]+ end++ subgraph Tooling["CLIs + connectors"]+ Init[loop-init: scaffold]+ Audit[loop-audit: readiness score]+ MCP[MCP server: read-only policy + tools]+ end++ Design --> Patterns+ Init --> State+ Init --> LoopDoc+ Sched --> Patterns+ Patterns --> Cost+ Cost --> Context+ Patterns --> WT+ State <--> Sync+ WT --> Maker+ Maker --> Verifier+ Verifier --> Context+ Context --> Gate+ Verifier --> MCP+ Gate --> Review+ Audit --> Design+ </pre>+ </div>+ </div>+ <p style="text-align: center; margin-top: 24px;">+ <a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/architecture-diagrams.md">Copy-friendly Mermaid source →</a>+ </p>+</section>+<section id="patterns" class="wrap"><p class="section-label">Copy & run</p><h2 class="section-title">Production patterns</h2>diff --git a/docs/primitives.md b/docs/primitives.mdindex d743d85..b6c4dad 100644--- a/docs/primitives.md+++ b/docs/primitives.md@@ -95,3 +95,5 @@ You then add:- Connectors when you want it to drive tickets and PRs instead of just suggestingThe best loops are the ones where each new primitive is added only when the previous version has proven its value (and its failure modes).++See [architecture-diagrams.md](architecture-diagrams.md) for how these primitives map onto the actual `tools/` packages, plus the run-lifecycle and sequence diagrams.