Skip to content

Commit 4e98421

Browse files
KhaiTrang1995KhaiTrang1995
authored
docs: add deeper architecture diagrams (#288)
Adds docs/architecture-diagrams.md with sequence, lifecycle, autonomy, and stack Mermaid diagrams. Thanks @KhaiTrang1995.
1 parent 91bbfc4 commit 4e98421

5 files changed

Lines changed: 345 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,8 @@ flowchart LR
164164

165165
</details>
166166

167+
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).
168+
167169
**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.
168170

169171
## Patterns

‎docs/architecture-diagrams.md‎

Lines changed: 142 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,142 @@
1+
# Architecture Diagrams
2+
3+
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.
4+
5+
All diagrams are [Mermaid](https://mermaid.js.org/), rendered natively by GitHub when viewing this file.
6+
7+
## One loop cycle (sequence)
8+
9+
Who talks to whom, in order, within a single run — including the fork between the safe auto-path and the human escalation path.
10+
11+
```mermaid
12+
sequenceDiagram
13+
actor Eng as Engineer
14+
participant Sched as Scheduler
15+
participant Skill as Triage Skill
16+
participant State as STATE.md / Memory
17+
participant WT as Worktree
18+
participant Maker as Implementer Agent
19+
participant Check as Verifier Agent
20+
participant MCP as MCP / Git / Tickets
21+
participant Gate as Human Gate
22+
23+
Sched->>Skill: Fire pattern (e.g. daily-triage)
24+
Skill->>State: Read goals + last run + budget
25+
State-->>Skill: Context snapshot
26+
Skill->>WT: Create isolated worktree
27+
WT-->>Skill: worktree path
28+
Skill->>Maker: Task with skills + constraints
29+
Maker->>Maker: Implement change in worktree
30+
Maker->>Check: Hand off patch
31+
Check->>Check: Run tests + policy gates
32+
33+
alt Verify pass and budget OK
34+
Check->>MCP: Open PR or update ticket
35+
MCP-->>Gate: PR link + summary
36+
Gate->>Gate: Safe and allowlisted?
37+
alt Safe auto-path
38+
Gate->>MCP: Approve merge or leave L1 report
39+
MCP->>State: Write run outcome
40+
else Risky or ambiguous
41+
Gate->>Eng: Escalate with full context
42+
Eng->>MCP: Decide / override
43+
MCP->>State: Write decision + outcome
44+
end
45+
else Verify fail or budget exceeded
46+
Check->>State: Log failure mode
47+
Check->>Eng: Report only, no auto-merge
48+
end
49+
```
50+
51+
## Run lifecycle (state)
52+
53+
The states one scheduled run moves through, from cadence fire to the final durable log entry.
54+
55+
```mermaid
56+
stateDiagram-v2
57+
[*] --> Scheduled
58+
Scheduled --> LoadingContext: cadence fire
59+
LoadingContext --> BlockedBudget: budget exceeded
60+
LoadingContext --> RunningTriage: context OK
61+
RunningTriage --> WorkingInWorktree: task selected
62+
RunningTriage --> IdleNoop: nothing to do
63+
WorkingInWorktree --> Verifying: implementer done
64+
Verifying --> AwaitingHumanGate: verify pass + risky
65+
Verifying --> Failed: verify fail
66+
AwaitingHumanGate --> Applied: human or allowlist approve
67+
AwaitingHumanGate --> Rejected: human reject
68+
Applied --> Logged
69+
Failed --> Logged
70+
Rejected --> Logged
71+
BlockedBudget --> Logged
72+
IdleNoop --> Logged
73+
Logged --> [*]
74+
```
75+
76+
## Autonomy levels L1-L3
77+
78+
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.
79+
80+
```mermaid
81+
stateDiagram-v2
82+
[*] --> L1_ReportOnly
83+
L1_ReportOnly --> L2_Assisted: audit score up + human OK
84+
L2_Assisted --> L3_Unattended: denylist + budget + gates proven
85+
L3_Unattended --> L2_Assisted: incident or cost spike
86+
L2_Assisted --> L1_ReportOnly: kill switch
87+
L3_Unattended --> L1_ReportOnly: kill switch
88+
```
89+
90+
## Stack: primitives + tools
91+
92+
The [Five Building Blocks + Memory](primitives.md) model made concrete: which package in `tools/` implements which primitive, and how they connect.
93+
94+
```mermaid
95+
flowchart TB
96+
subgraph Human["Engineer / Owner"]
97+
Design[Design LOOP.md patterns]
98+
Gate[Human gate + kill switch]
99+
Review[Read PRs + reports]
100+
end
101+
102+
subgraph Control["Control plane"]
103+
Sched[Automations / Scheduling]
104+
Patterns[patterns/registry.yaml]
105+
Cost[loop-cost: estimate spend]
106+
end
107+
108+
subgraph Memory["Durable memory"]
109+
State[STATE.md]
110+
LoopDoc[LOOP.md]
111+
Context[loop-context: prune, inject, circuit breaker]
112+
Sync[loop-sync]
113+
end
114+
115+
subgraph Execution["Execution plane"]
116+
WT[loop-worktree: isolated attempts + locks]
117+
Maker[Implementer sub-agent]
118+
Verifier[Verifier sub-agent]
119+
end
120+
121+
subgraph Tooling["CLIs + connectors"]
122+
Init[loop-init: scaffold]
123+
Audit[loop-audit: readiness score]
124+
MCP[MCP server: read-only policy + tools]
125+
end
126+
127+
Design --> Patterns
128+
Init --> State
129+
Init --> LoopDoc
130+
Sched --> Patterns
131+
Patterns --> Cost
132+
Cost --> Context
133+
Patterns --> WT
134+
State <--> Sync
135+
WT --> Maker
136+
Maker --> Verifier
137+
Verifier --> Context
138+
Context --> Gate
139+
Verifier --> MCP
140+
Gate --> Review
141+
Audit --> Design
142+
```

‎docs/assets/css/showcase.css‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -380,6 +380,38 @@ section {
380380
box-shadow: 0 8px 32px rgba(0, 0, 0, 0.3);
381381
}
382382

383+
/* Architecture diagrams */
384+
.diagram-list {
385+
display: flex;
386+
flex-direction: column;
387+
gap: 24px;
388+
}
389+
390+
.diagram-card {
391+
overflow-x: auto;
392+
}
393+
394+
.diagram-card .tag {
395+
font-size: 0.7rem;
396+
font-weight: 700;
397+
letter-spacing: 0.08em;
398+
text-transform: uppercase;
399+
color: var(--accent-2);
400+
margin-bottom: 12px;
401+
}
402+
403+
.diagram-card h3 {
404+
font-size: 1.15rem;
405+
font-weight: 700;
406+
margin-bottom: 16px;
407+
}
408+
409+
.diagram-card .mermaid {
410+
display: flex;
411+
justify-content: center;
412+
min-width: 480px;
413+
}
414+
383415
.pattern-card .tag {
384416
font-size: 0.7rem;
385417
font-weight: 700;

‎docs/index.html‎

Lines changed: 167 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -14,6 +14,28 @@
1414
<meta property="og:image" content="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-social-banner.jpg">
1515
<link rel="stylesheet" href="{{ site.baseurl }}/assets/css/showcase.css">
1616
<link rel="icon" href="https://raw.githubusercontent.com/cobusgreyling/loop-engineering/main/assets/visuals/loop-engineering-logo.svg">
17+
<script type="module">
18+
import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
19+
mermaid.initialize({
20+
startOnLoad: true,
21+
theme: "dark",
22+
securityLevel: "loose",
23+
themeVariables: {
24+
background: "#111a28",
25+
primaryColor: "#132235",
26+
primaryTextColor: "#e8edf5",
27+
primaryBorderColor: "#3ee8c5",
28+
lineColor: "#5b9dff",
29+
secondaryColor: "#0d1420",
30+
tertiaryColor: "#111a28",
31+
textColor: "#e8edf5",
32+
clusterBkg: "#0d1420",
33+
clusterBorder: "#2a3b52",
34+
edgeLabelBackground: "#111a28",
35+
fontFamily: "SF Pro Display, -apple-system, BlinkMacSystemFont, Segoe UI, Roboto, sans-serif",
36+
},
37+
});
38+
</script>
1739
</head>
1840
<body>
1941

@@ -38,6 +60,7 @@
3860
<ul class="nav-links">
3961
<li><a href="#patterns">Patterns</a></li>
4062
<li><a href="#primitives">Primitives</a></li>
63+
<li><a href="#architecture">Architecture</a></li>
4164
<li><a href="#interactive">Picker</a></li>
4265
<li><a href="#start">Get Started</a></li>
4366
<li><a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/QUICKSTART.md">Quickstart</a></li>
@@ -173,6 +196,150 @@ <h3>State</h3>
173196
</p>
174197
</section>
175198

199+
<section id="architecture" class="wrap">
200+
<p class="section-label">Deeper architecture</p>
201+
<h2 class="section-title">How one run actually moves</h2>
202+
<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>
203+
<div class="diagram-list">
204+
<div class="pattern-card diagram-card">
205+
<div class="tag">Sequence</div>
206+
<h3>One loop cycle</h3>
207+
<pre class="mermaid">
208+
sequenceDiagram
209+
actor Eng as Engineer
210+
participant Sched as Scheduler
211+
participant Skill as Triage Skill
212+
participant State as STATE.md / Memory
213+
participant WT as Worktree
214+
participant Maker as Implementer Agent
215+
participant Check as Verifier Agent
216+
participant MCP as MCP / Git / Tickets
217+
participant Gate as Human Gate
218+
219+
Sched->>Skill: Fire pattern (e.g. daily-triage)
220+
Skill->>State: Read goals + last run + budget
221+
State-->>Skill: Context snapshot
222+
Skill->>WT: Create isolated worktree
223+
WT-->>Skill: worktree path
224+
Skill->>Maker: Task with skills + constraints
225+
Maker->>Maker: Implement change in worktree
226+
Maker->>Check: Hand off patch
227+
Check->>Check: Run tests + policy gates
228+
229+
alt Verify pass and budget OK
230+
Check->>MCP: Open PR or update ticket
231+
MCP-->>Gate: PR link + summary
232+
Gate->>Gate: Safe and allowlisted?
233+
alt Safe auto-path
234+
Gate->>MCP: Approve merge or leave L1 report
235+
MCP->>State: Write run outcome
236+
else Risky or ambiguous
237+
Gate->>Eng: Escalate with full context
238+
Eng->>MCP: Decide / override
239+
MCP->>State: Write decision + outcome
240+
end
241+
else Verify fail or budget exceeded
242+
Check->>State: Log failure mode
243+
Check->>Eng: Report only, no auto-merge
244+
end
245+
</pre>
246+
</div>
247+
<div class="pattern-card diagram-card">
248+
<div class="tag">State</div>
249+
<h3>Run lifecycle</h3>
250+
<pre class="mermaid">
251+
stateDiagram-v2
252+
[*] --> Scheduled
253+
Scheduled --> LoadingContext: cadence fire
254+
LoadingContext --> BlockedBudget: budget exceeded
255+
LoadingContext --> RunningTriage: context OK
256+
RunningTriage --> WorkingInWorktree: task selected
257+
RunningTriage --> IdleNoop: nothing to do
258+
WorkingInWorktree --> Verifying: implementer done
259+
Verifying --> AwaitingHumanGate: verify pass + risky
260+
Verifying --> Failed: verify fail
261+
AwaitingHumanGate --> Applied: human or allowlist approve
262+
AwaitingHumanGate --> Rejected: human reject
263+
Applied --> Logged
264+
Failed --> Logged
265+
Rejected --> Logged
266+
BlockedBudget --> Logged
267+
IdleNoop --> Logged
268+
Logged --> [*]
269+
</pre>
270+
</div>
271+
<div class="pattern-card diagram-card">
272+
<div class="tag">State</div>
273+
<h3>Autonomy levels L1-L3</h3>
274+
<pre class="mermaid">
275+
stateDiagram-v2
276+
[*] --> L1_ReportOnly
277+
L1_ReportOnly --> L2_Assisted: audit score up + human OK
278+
L2_Assisted --> L3_Unattended: denylist + budget + gates proven
279+
L3_Unattended --> L2_Assisted: incident or cost spike
280+
L2_Assisted --> L1_ReportOnly: kill switch
281+
L3_Unattended --> L1_ReportOnly: kill switch
282+
</pre>
283+
</div>
284+
<div class="pattern-card diagram-card">
285+
<div class="tag">Architecture</div>
286+
<h3>Stack: primitives + tools</h3>
287+
<pre class="mermaid">
288+
flowchart TB
289+
subgraph Human["Engineer / Owner"]
290+
Design[Design LOOP.md patterns]
291+
Gate[Human gate + kill switch]
292+
Review[Read PRs + reports]
293+
end
294+
295+
subgraph Control["Control plane"]
296+
Sched[Automations / Scheduling]
297+
Patterns[patterns/registry.yaml]
298+
Cost[loop-cost: estimate spend]
299+
end
300+
301+
subgraph Memory["Durable memory"]
302+
State[STATE.md]
303+
LoopDoc[LOOP.md]
304+
Context[loop-context: prune, inject, circuit breaker]
305+
Sync[loop-sync]
306+
end
307+
308+
subgraph Execution["Execution plane"]
309+
WT[loop-worktree: isolated attempts + locks]
310+
Maker[Implementer sub-agent]
311+
Verifier[Verifier sub-agent]
312+
end
313+
314+
subgraph Tooling["CLIs + connectors"]
315+
Init[loop-init: scaffold]
316+
Audit[loop-audit: readiness score]
317+
MCP[MCP server: read-only policy + tools]
318+
end
319+
320+
Design --> Patterns
321+
Init --> State
322+
Init --> LoopDoc
323+
Sched --> Patterns
324+
Patterns --> Cost
325+
Cost --> Context
326+
Patterns --> WT
327+
State <--> Sync
328+
WT --> Maker
329+
Maker --> Verifier
330+
Verifier --> Context
331+
Context --> Gate
332+
Verifier --> MCP
333+
Gate --> Review
334+
Audit --> Design
335+
</pre>
336+
</div>
337+
</div>
338+
<p style="text-align: center; margin-top: 24px;">
339+
<a href="https://github.com/cobusgreyling/loop-engineering/blob/main/docs/architecture-diagrams.md">Copy-friendly Mermaid source →</a>
340+
</p>
341+
</section>
342+
176343
<section id="patterns" class="wrap">
177344
<p class="section-label">Copy & run</p>
178345
<h2 class="section-title">Production patterns</h2>

‎docs/primitives.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -95,3 +95,5 @@ You then add:
9595
- Connectors when you want it to drive tickets and PRs instead of just suggesting
9696

9797
The best loops are the ones where each new primitive is added only when the previous version has proven its value (and its failure modes).
98+
99+
See [architecture-diagrams.md](architecture-diagrams.md) for how these primitives map onto the actual `tools/` packages, plus the run-lifecycle and sequence diagrams.

0 commit comments

Comments
 (0)