# cobusgreyling/loop-engineering architecture

> Architecture diagram of the GitHub repository cobusgreyling/loop-engineering, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/cobusgreyling/loop-engineering
- Repository: https://github.com/cobusgreyling/loop-engineering
- Video tour (about a minute): https://gitdiagram.com/cobusgreyling/loop-engineering/video

## Overview

1. **What this repo is**
   - This is not a single application; it is a **reference monorepo for “loop engineering”**: a system of reusable agent workflows, starter kits, docs, and CLI tools for designing and operating AI agent loops.
   - The repo’s architecture splits cleanly into **reference content**, **starter scaffolds**, **runtime-specific examples**, **shared templates/skills**, and **published Node-based tools**.

2. **Core domain model**
   - The central concepts are **patterns** and **loops**.
   - Patterns live in `patterns/` as the canonical catalog of loop types (daily triage, PR babysitter, CI sweeper, dependency sweeper, changelog drafter, post-merge cleanup, issue triage).
   - Each pattern is described in prose plus a machine-readable registry (`patterns/registry.yaml`, schema in `patterns/registry.schema.json`), which downstream tooling and starters can consume.

3. **Documentation and conceptual layer**
   - `docs/`, `README.md`, `LOOP.md`, `STATE.md`, and `resources/` form the human-facing architecture guide.
   - These files explain the primitives, safety model, failure modes, operating rules, and pattern selection process.
   - The docs site is also published via GitHub Pages, so the repository doubles as both source code and a static knowledge base.

4. **Starter-kit layer**
   - `starters/` contains cloneable project blueprints for different AI runtimes: Claude Code, Codex, Grok, Opencode, and minimal loop variants.
   - A starter is the boundary where abstract pattern guidance becomes a concrete repo layout: it packages loop instructions, state files, skills, and sometimes verifier agents.
   - There are tool-specific variants because each agent runtime expects different config and file conventions.

5. **Shared instruction assets**
   - `templates/` provides reusable file templates for loop state, skill definitions, constraints, and budgets.
   - `skills/` contains shared skill bundles used by the generated loops.
   - `scripts/issue-bodies/` holds canonical issue/PR body fragments used by the repo’s workflow automation and issue templates.
   - This layer is the repository’s “instruction vocabulary” that gets copied or referenced by starters and tools.

6. **Executable tooling layer**
   - `tools/` contains the operational CLIs, each published as its own npm package:
     - `loop-init`: scaffolds a loop into a target project.
     - `loop-audit`: scores readiness and flags missing loop components.
     - `loop-cost`: estimates token/cadence cost.
     - `loop-sync`: detects drift between `LOOP.md` and `STATE.md`.
     - `mcp-server`: exposes pattern/skill/state lookup over MCP.
     - `goal-audit` and `loop-audit` are related audit tools for readiness and goal/project validation.
   - These tools are the repo’s execution boundary: they transform the static reference model into actionable checks, generated files, and runtime lookups.

7. **Data flow from pattern to running loop**
   - The usual flow is: **pattern selection → starter scaffold → state/skills creation → runtime execution → state updates → audit/sync checks**.
   - `loop-init` seeds a project with the files needed to run a loop.
   - The loop then writes durable state into files like `STATE.md` or pattern-specific state docs.
   - `loop-sync` and `loop-audit` consume those files to detect drift and score readiness over time.

8. **Runtime and integration boundaries**
   - The repo explicitly supports multiple agent runtimes rather than a single implementation.
   - `examples/` shows how the same loop concepts map into Claude, Codex, Grok, OpenClaw, Opencode, GitHub Actions, and MCP-based setups.
   - `examples/mcp/` is the connector boundary: it demonstrates read-only and write-safe integrations with external systems such as GitHub, Linear, and Slack via MCP config.

9. **Automation and governance**
   - `.github/workflows/` is a major architectural subsystem: it runs validation, auditing, releases, and contributor triage.
   - The repo self-hosts its own checks on push/PR, including pattern validation and audit workflows.
   - This makes the repo a dogfooded control system: the repo maintains the quality of its own loop patterns and shipped artifacts.

10. **Publishing and release path**
   - The tools under `tools/` are packaged and released independently, while the root repo serves as the reference source.
   - Release notes, changelogs, and GitHub Actions workflows coordinate the publishing pipeline.
   - GitHub Pages is the documentation delivery boundary; npm is the CLI delivery boundary.

11. **Examples, stories, and validation artifacts**
   - `stories/` captures real-world outcomes and failure cases, which act as architectural evidence for the patterns.
   - `tools/*/test` and fixture directories validate the tooling against known-good loop projects.
   - This is important structurally: the repo uses narrative evidence, fixture projects, and automated tests as separate proof layers for the loop system.

12. **Overall architecture in one sentence**
   - The repo is a **reference platform** where **pattern definitions** feed **starter kits and skills**, which are operationalized by **CLI tools and MCP services**, verified by **CI workflows**, and documented through **static docs, examples, and stories**.

Main entry points: [`patterns/README.md`](https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/README.md) (Pattern catalog), [`patterns/registry.yaml`](https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/registry.yaml) (Registry), [`examples/README.md`](https://github.com/cobusgreyling/loop-engineering/blob/main/examples/README.md) (Runtime examples), [`tools/mcp-server`](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/mcp-server) (MCP server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_docs["Docs & reference"]
  node_root_readme["README<br/>entry docs<br/>[README.md]"]
  node_loop_md["LOOP<br/>[LOOP.md]"]
  node_state_md["STATE<br/>[STATE.md]"]
  node_docs_site["Docs site<br/>published docs<br/>[index.html]"]
end

subgraph group_group_patterns["Patterns"]
  node_pattern_catalog["Pattern catalog<br/>loop patterns<br/>[README.md]"]
  node_pattern_registry["Registry<br/>pattern metadata<br/>[registry.yaml]"]
  node_pattern_schema["Schema"]
end

subgraph group_group_starters["Starters"]
  node_starter_claude["Claude starter<br/>runtime scaffold"]
  node_starter_codex["Codex starter<br/>runtime scaffold"]
  node_starter_grok["Grok starter<br/>runtime scaffold"]
  node_starter_opencode["Opencode starter<br/>runtime scaffold"]
  node_starter_minimal["Minimal loop<br/>starter baseline"]
end

subgraph group_group_shared["Shared assets"]
  node_templates["Templates"]
  node_skills["Shared skills<br/>skill bundles"]
  node_issue_bodies["Issue bodies<br/>workflow snippets"]
end

subgraph group_group_tools["Tools & services"]
  node_loop_init["loop-init<br/>scaffold CLI"]
  node_loop_audit["loop-audit<br/>audit CLI"]
  node_loop_cost["loop-cost<br/>cost CLI"]
  node_loop_sync["loop-sync<br/>drift CLI"]
  node_mcp_server["MCP server<br/>lookup service"]
end

subgraph group_group_examples["Examples & evidence"]
  node_examples_runtime["Runtime examples<br/>runtime mappings<br/>[README.md]"]
  node_examples_mcp["MCP examples<br/>integration examples<br/>[README.md]"]
  node_stories["Stories<br/>field evidence<br/>[README.md]"]
end

subgraph group_group_automation["Automation"]
  node_github_workflows["Workflows<br/>ci governance"]
  node_repo_scripts["Scripts<br/>repo automation"]
end

node_root_readme -->|"introduces"| node_pattern_catalog
node_root_readme -->|"documents"| node_docs_site
node_loop_md -->|"pairs with"| node_state_md
node_docs_site -->|"explains"| node_pattern_catalog
node_docs_site -->|"references"| node_templates
node_pattern_catalog -->|"indexed by"| node_pattern_registry
node_pattern_registry -->|"validated by"| node_pattern_schema
node_pattern_catalog -->|"materialized in"| node_starter_claude
node_pattern_catalog -->|"materialized in"| node_starter_codex
node_pattern_catalog -->|"materialized in"| node_starter_grok
node_pattern_catalog -->|"materialized in"| node_starter_opencode
node_pattern_catalog -->|"materialized in"| node_starter_minimal
node_templates -->|"feeds"| node_starter_claude
node_skills -->|"feeds"| node_starter_claude
node_issue_bodies -->|"supports"| node_github_workflows
node_loop_init -->|"generates"| node_templates
node_loop_init -->|"installs"| node_skills
node_loop_audit -->|"checks"| node_pattern_registry
node_loop_sync -->|"reads"| node_state_md
node_loop_sync -->|"compares"| node_loop_md
node_mcp_server -->|"serves"| node_pattern_catalog
node_mcp_server -->|"serves"| node_skills
node_mcp_server -->|"serves"| node_state_md
node_examples_runtime -->|"shows"| node_starter_claude
node_examples_runtime -->|"shows"| node_starter_codex
node_examples_runtime -->|"shows"| node_starter_grok
node_examples_runtime -->|"shows"| node_starter_opencode
node_examples_mcp -->|"integrates"| node_mcp_server
node_stories -->|"evidence for"| node_pattern_catalog
node_github_workflows -->|"validates"| node_pattern_registry
node_github_workflows -->|"runs"| node_loop_audit
node_repo_scripts -->|"checks"| node_pattern_registry
node_repo_scripts -->|"supports"| node_github_workflows

click node_root_readme "https://github.com/cobusgreyling/loop-engineering/blob/main/README.md"
click node_loop_md "https://github.com/cobusgreyling/loop-engineering/blob/main/LOOP.md"
click node_state_md "https://github.com/cobusgreyling/loop-engineering/blob/main/STATE.md"
click node_docs_site "https://github.com/cobusgreyling/loop-engineering/blob/main/docs/index.html"
click node_pattern_catalog "https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/README.md"
click node_pattern_registry "https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/registry.yaml"
click node_pattern_schema "https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/registry.schema.json"
click node_starter_claude "https://github.com/cobusgreyling/loop-engineering/tree/main/starters/pr-babysitter"
click node_starter_codex "https://github.com/cobusgreyling/loop-engineering/tree/main/starters/ci-sweeper"
click node_starter_grok "https://github.com/cobusgreyling/loop-engineering/tree/main/starters/issue-triage"
click node_starter_opencode "https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop-opencode"
click node_starter_minimal "https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop"
click node_templates "https://github.com/cobusgreyling/loop-engineering/tree/main/templates"
click node_skills "https://github.com/cobusgreyling/loop-engineering/tree/main/skills"
click node_issue_bodies "https://github.com/cobusgreyling/loop-engineering/tree/main/scripts/issue-bodies"
click node_loop_init "https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-init"
click node_loop_audit "https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-audit"
click node_loop_cost "https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-cost"
click node_loop_sync "https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-sync"
click node_mcp_server "https://github.com/cobusgreyling/loop-engineering/tree/main/tools/mcp-server"
click node_examples_runtime "https://github.com/cobusgreyling/loop-engineering/blob/main/examples/README.md"
click node_examples_mcp "https://github.com/cobusgreyling/loop-engineering/blob/main/examples/mcp/README.md"
click node_stories "https://github.com/cobusgreyling/loop-engineering/blob/main/stories/README.md"
click node_github_workflows "https://github.com/cobusgreyling/loop-engineering/blob/main/.github/workflows/validate-patterns.yml"
click node_repo_scripts "https://github.com/cobusgreyling/loop-engineering/blob/main/scripts/validate-registry.mjs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_root_readme,node_loop_md,node_state_md,node_docs_site,node_github_workflows,node_repo_scripts toneBlue
class node_pattern_catalog,node_pattern_registry,node_pattern_schema toneAmber
class node_starter_claude,node_starter_codex,node_starter_grok,node_starter_opencode,node_starter_minimal toneMint
class node_templates,node_skills,node_issue_bodies toneRose
class node_loop_init,node_loop_audit,node_loop_cost,node_loop_sync,node_mcp_server toneIndigo
class node_examples_runtime,node_examples_mcp,node_stories toneTeal
```

## Components

### Docs & reference

Human-facing architecture, concepts, and published guidance.

- [README](https://github.com/cobusgreyling/loop-engineering/blob/main/README.md): entry docs · Top-level orientation and repo overview. · `README.md`
- [LOOP](https://github.com/cobusgreyling/loop-engineering/blob/main/LOOP.md): loop contract · Operational loop instructions and repo-level loop contract. · `LOOP.md`
- [STATE](https://github.com/cobusgreyling/loop-engineering/blob/main/STATE.md): loop state · Repository-level durable state for the reference loop. · `STATE.md`
- [Docs site](https://github.com/cobusgreyling/loop-engineering/blob/main/docs/index.html): published docs · Static documentation and conceptual guide published via GitHub Pages. · `docs/index.html`

### Patterns

Canonical loop catalog and machine-readable registry.

- [Pattern catalog](https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/README.md): loop patterns · Canonical prose descriptions of supported loop archetypes. · `patterns/README.md`
- [Registry](https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/registry.yaml): pattern metadata · Machine-readable registry of patterns and their schema. · `patterns/registry.yaml`
- [Schema](https://github.com/cobusgreyling/loop-engineering/blob/main/patterns/registry.schema.json): registry schema · Validation schema for the pattern registry. · `patterns/registry.schema.json`

### Starters

Cloneable runtime-specific blueprints for running loops.

- [Claude starter](https://github.com/cobusgreyling/loop-engineering/tree/main/starters/pr-babysitter): runtime scaffold · Claude Code starter layout for loop projects. · `starters/pr-babysitter`
- [Codex starter](https://github.com/cobusgreyling/loop-engineering/tree/main/starters/ci-sweeper): runtime scaffold · Codex starter layout for loop projects. · `starters/ci-sweeper`
- [Grok starter](https://github.com/cobusgreyling/loop-engineering/tree/main/starters/issue-triage): runtime scaffold · Grok starter layout for loop projects. · `starters/issue-triage`
- [Opencode starter](https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop-opencode): runtime scaffold · Opencode starter layout for loop projects. · `starters/minimal-loop-opencode`
- [Minimal loop](https://github.com/cobusgreyling/loop-engineering/tree/main/starters/minimal-loop): starter baseline · Minimal loop variant for lightweight setups. · `starters/minimal-loop`

### Shared assets

Reusable templates, skills, and workflow fragments consumed by starters and tools.

- [Templates](https://github.com/cobusgreyling/loop-engineering/tree/main/templates): file templates · Reusable markdown templates for state, constraints, and skills. · `templates`
- [Shared skills](https://github.com/cobusgreyling/loop-engineering/tree/main/skills): skill bundles · Common skills reused across generated loops and starters. · `skills`
- [Issue bodies](https://github.com/cobusgreyling/loop-engineering/tree/main/scripts/issue-bodies): workflow snippets · Canonical issue and PR body fragments used by automation. · `scripts/issue-bodies`

### Tools & services

Executable CLIs and MCP service boundaries.

- [loop-init](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-init): scaffold CLI · Seeds a target project with loop files and starter assets. · `tools/loop-init`
- [loop-audit](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-audit): audit CLI · Scores loop readiness and flags missing components. · `tools/loop-audit`
- [loop-cost](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-cost): cost CLI · Estimates token and cadence cost for a loop. · `tools/loop-cost`
- [loop-sync](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/loop-sync): drift CLI · Detects drift between loop instructions and durable state. · `tools/loop-sync`
- [MCP server](https://github.com/cobusgreyling/loop-engineering/tree/main/tools/mcp-server): lookup service · Exposes pattern, skill, and state lookup over MCP. · `tools/mcp-server`

### Examples & evidence

Runtime mappings, integrations, stories, and validation fixtures.

- [Runtime examples](https://github.com/cobusgreyling/loop-engineering/blob/main/examples/README.md): runtime mappings · Examples showing how patterns map onto different agent runtimes. · `examples/README.md`
- [MCP examples](https://github.com/cobusgreyling/loop-engineering/blob/main/examples/mcp/README.md): integration examples · Read-only and safe-write connector examples for external systems. · `examples/mcp/README.md`
- [Stories](https://github.com/cobusgreyling/loop-engineering/blob/main/stories/README.md): field evidence · Narrative evidence of successes, failures, and architectural tradeoffs. · `stories/README.md`

### Automation

Repository governance, CI, releases, and contributor workflows.

- [Workflows](https://github.com/cobusgreyling/loop-engineering/blob/main/.github/workflows/validate-patterns.yml): ci governance · Validation, release, and contributor automation on GitHub Actions. · `.github/workflows/validate-patterns.yml`
- [Scripts](https://github.com/cobusgreyling/loop-engineering/blob/main/scripts/validate-registry.mjs): repo automation · Utility scripts for validation, publishing, and demo generation. · `scripts/validate-registry.mjs`

## Connections

- README → Pattern catalog: introduces · The top-level README points to the pattern catalog as the core domain model.
- README → Docs site: documents · Repository documentation is also served as a static site.
- LOOP → STATE: pairs with · The loop contract and durable state define the operational boundary.
- Docs site → Pattern catalog: explains · Docs describe how to select and operate patterns.
- Docs site → Templates: references · Conceptual docs reference shared templates and primitives.
- Pattern catalog → Registry: indexed by · Pattern prose is mirrored in a machine-readable registry.
- Registry → Schema: validated by · The registry is checked against the schema.
- Pattern catalog → Claude starter: materialized in · Patterns are instantiated into runtime-specific starters.
- Pattern catalog → Codex starter: materialized in · Patterns are instantiated into runtime-specific starters.
- Pattern catalog → Grok starter: materialized in · Patterns are instantiated into runtime-specific starters.
- Pattern catalog → Opencode starter: materialized in · Patterns are instantiated into runtime-specific starters.
- Pattern catalog → Minimal loop: materialized in · Patterns are instantiated into a minimal starter variant.
- Templates → Claude starter: feeds · Starter repos copy shared templates into concrete layouts.
- Shared skills → Claude starter: feeds · Starter repos include shared and runtime-specific skills.
- Issue bodies → Workflows: supports · Workflow automation uses canonical issue and PR body fragments.
- loop-init → Templates: generates · Scaffolding uses templates to create loop files.
- loop-init → Shared skills: installs · Scaffolding installs the appropriate skills bundle.
- loop-audit → Registry: checks · Audit tooling consumes the registry to score readiness.
- loop-sync → STATE: reads · Sync compares live instructions against durable state.
- loop-sync → LOOP: compares · Sync detects drift between the loop contract and current state.
- MCP server → Pattern catalog: serves · The MCP service exposes pattern lookup.
- MCP server → Shared skills: serves · The MCP service exposes skill lookup.
- MCP server → STATE: serves · The MCP service exposes state lookup.
- Runtime examples → Claude starter: shows · Examples demonstrate the Claude runtime mapping.
- Runtime examples → Codex starter: shows · Examples demonstrate the Codex runtime mapping.
- Runtime examples → Grok starter: shows · Examples demonstrate the Grok runtime mapping.
- Runtime examples → Opencode starter: shows · Examples demonstrate the Opencode runtime mapping.
- MCP examples → MCP server: integrates · MCP examples demonstrate the lookup and connector boundary.
- Stories → Pattern catalog: evidence for · Stories provide real-world validation and failure cases for patterns.
- Workflows → Registry: validates · CI validates the registry and pattern definitions.
- Workflows → loop-audit: runs · Release and audit workflows execute the audit tooling.
- Scripts → Registry: checks · Repository scripts validate the registry before release.
- Scripts → Workflows: supports · Scripts provide CI and release plumbing for workflows.