cobusgreyling/loop-engineering

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.