The Problem

Developers spend most of their time writing and maintaining prompts that drive AI coding agents. The repetitive “prompt‑then‑run” loop is noisy, hard to version, and offers no systematic way to measure effectiveness or cost.

What This Does

loop-engineering supplies a library of patterns, starters, and CLI tools that let teams treat an AI‑agent workflow as a first‑class software component. The core packages—@cobusgreyling/loop‑audit, @cobusgreyling/loop‑init, @cobusgreyling/loop‑cost, and @cobusgreyling/loop‑context—are located under tools/ and expose a TypeScript CLI (tools/*/src/cli.ts). Scaffolding (loop-init) creates a skills/ directory, a state/ file and a budget manifest, then prints a “Loop Ready” score (see README.md and docs/QUICKSTART.md). The pattern catalog (patterns/) and example projects (examples/) show ready‑made loops for Claude, Codex, Cursor, and others.

How It Is Wired

  1. Entry point – Running npx @cobusgreyling/loop‑init . executes the compiled CLI at tools/loop‑init/dist/cli.js, which loads tools/loop‑init/src/cli.ts.
  2. CLI bootstrap – cli.ts parses command‑line flags, resolves the target directory, and calls auditor.ts (e.g., tools/goal‑audit/src/auditor.ts or tools/loop‑audit/src/auditor.ts) to validate the generated loop configuration.
  3. Auditor – The auditor reads the generated skills/, state/, and budget/ files, runs a series of rule checks (see tools/*/src/reporter.ts for output formatting) and returns an exit code. It is the most‑connected module in both audit tools (Ca = 2, Ce = 0).
  4. Reporter – Formats results for the console and, when invoked via CI, writes a JSON artifact.
  5. Context manager – tools/loop‑context/src/context-manager.ts (Ca = 1, Ce = 0) holds runtime metadata (e.g., token budgets) that the CLI can query.
  6. Publish workflows – GitHub Actions in .github/workflows/ call the audit CLIs (publish-goal-audit-bootstrap.yml, release-loop-audit.yml, etc.) to validate loops before publishing the npm packages.

No circular imports are present; the import graph consists of 28 internal modules with 10 edges, keeping the dependency surface small and predictable.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/loop-engineering
cd loop-engineering

# Install the CLI tools (npm is the package manager)
npm install

# Scaffold a new loop in the current directory
npx @cobusgreyling/loop-init .

# Run an audit on the generated loop
npx @cobusgreyling/loop-audit .

Configuration – The scaffold creates skills/, state/, and budget/ JSON/TOML files. No external environment variables are required for a local run; CI workflows inject a GitHub token only when publishing (publish-goal-audit-bootstrap.yml).

Running examples – Pick an example, cd examples/claude-code, then invoke the same CLI commands against that folder.

Real‑World Use

A CI pipeline can treat the audit CLI as a gate: on every PR, tools/loop-audit validates that the loop’s budget stays within limits and that required skills are present. If the audit passes, the pipeline proceeds to npm publish the corresponding @cobusgreyling/* package, guaranteeing that any downstream service consumes a vetted loop definition.

Code Health & Issues

  • Measured findings (static analysis)
  • HIGH – duplicated code blocks in tools/goal-audit/src/auditor.ts, tools/loop-audit/src/auditor.ts, tools/mcp-server/src/resolver.ts, tools/mcp-server/src/index.ts (≈20 repeated 6‑line fragments). Fix: extract shared helpers into a common module.
  • MEDIUM – high branching density in tools/loop-audit/src/auditor.ts, scripts/ci-validate-gates.sh, scripts/validate-registry.mjs (147 branch points over 485 lines). Fix: refactor into smaller, strategy‑based functions or tables.
  • Repository hygiene (CI, tests, licence, lockfile) – all present.
  • Code‑health audit (GitHub Actions)
  • MEDIUM – No dependency‑vulnerability scan. Add dependency-review-action or osv-scanner.
  • MEDIUM – Checkout step keeps the token (persist-credentials: false needed).
  • LOW – Jobs lack timeout-minutes; set realistic limits.
  • LOW – Missing convention files (.editorconfig, .gitattributes, formatter config).

No critical or high‑severity CI issues were found.

The Bottom Line

loop-engineering provides a concrete, CLI‑driven framework for turning AI‑agent prompts into versioned, auditable loops. The codebase is well‑structured with minimal coupling, but duplicated auditor logic and dense branching raise maintenance overhead. Adding dependency scanning and a few CI hardening steps would make the repo production‑ready for teams that want reproducible AI‑agent pipelines.