How rjmad1/rajajeevanloopengineering works
1. Repository role
- This repo is not just an application; it is a framework + runtime + content pack for executing structured AI-agent “loops.”
- It combines human-readable loop specifications, governance standards, templates, and a small Java execution engine that validates and tracks phase transitions.
2. Primary architecture boundary: content vs runtime
- The repository splits cleanly into two layers:
- Specification/content layer: shared/, loops/, templates/, examples/, recipes/, and docs/
- Execution/runtime layer: code/ plus container/bootstrap tooling
- That boundary matters: the markdown/schema assets define what a loop is, while the Java code enforces how loop state changes are accepted or rejected.
3. Loop specification and governance layer
- shared/ contains cross-cutting contracts, standards, naming, metrics, versioning, and schemas.
- loops/ contains the actual loop catalogs grouped by purpose:
- core/ for discovery/planning/implementation/verification/reflection
- engineering/ for bug fixing, refactoring, test generation, docs, code review
- platform/ for validation and contract checks
- governance/ for ADRs, compliance, release readiness
- This layer is the source of truth for workflow design and auditability.
4. Runtime Java engine
- code/ is a standalone Java 21+ Gradle project.
- The runtime classes are organized around a state-machine model:
- LoopDefinition and LoopSpecCompiler in spec/
- LoopPhase, LoopInstance, LoopStateMachine, TransitRequest, TransitResponse in engine/
- TelemetryService in telemetry/
- The runtime’s job is to load/compile loop definitions and enforce valid lifecycle transitions.
5. State machine and transition enforcement
- The central execution boundary is LoopStateMachine.
- It appears to validate transitions between phases such as implementation, verification, reflection, etc., and to track whether a loop instance is in a valid state.
- TransitRequest/TransitResponse are the main data-transfer objects for submitting and evaluating a requested state transition.
6. API/server boundary
- LoopEngineServer exposes the runtime as a language-neutral REST API.
- The README identifies the key endpoints:
- POST /api/v1/loops/transit
- GET /api/v1/loops/{loopId}/status
- GET /health
- This is the integration boundary for external agents, CI/CD jobs, or shell clients.
7. Telemetry and observability
- TelemetryService is a distinct subsystem for recording engine activity.
- In architecture terms, this sits beside the state machine rather than inside the loop spec layer, so metrics/trace data can be gathered without changing loop definitions.
- The repo’s shared metrics docs suggest telemetry is part of the governance and validation model, not an afterthought.
8. Bootstrapping and portability tools
- The repository includes scripts for porting the loop framework into another repo:
- bootstrap.py
- interactive-bootstrap.ps1
- port-loops.ps1
- loop-control.sh
- These tools are operational scaffolding: they copy specs, templates, container config, and the Java engine into a target project.
9. Container and local-dev environment
- .devcontainer/ and Dockerfile indicate first-class containerized development/runtime support.
- The README says the container runs the loop engine on port 8080 and is designed with reduced privileges.
- This makes deployment and local verification part of the architecture, not separate tooling.
10. Build and test boundary
- code/build.gradle, gradlew, and the test tree under code/src/test/java/... show the runtime is built and validated independently.
- Tests are organized per subsystem:
- engine tests
- spec compiler tests
- telemetry tests
- That mirrors the production boundaries and supports diagramming the verification flow around each component.
11. Documentation and operational knowledge
- docs/ contains architecture, compatibility, traceability, validation, migration, and troubleshooting material.
- This is unusually important in this repo: the docs are part of the framework’s operating model because the loops are intended to be auditable, governed workflows.
- examples/ provides sample run artifacts that demonstrate expected outputs and lifecycle traces.
12. End-to-end data flow
- Authoring flow: loop definitions and standards are written in markdown/schema files.
- Compilation flow: LoopSpecCompiler converts those definitions into runtime-ready LoopDefinition structures.
- Execution flow: clients send transition requests to the REST API.
- Enforcement flow: LoopStateMachine validates the transition and returns a response/status.
- Observability flow: TelemetryService records engine activity.
- Packaging flow: Docker/devcontainer/bootstrap scripts make the same framework portable to other repositories.
13. How to draw the architecture
- A good diagram would show three main zones:
- Authoring/knowledge zone: shared, loops, templates, docs, examples
- Execution zone: Java engine (spec, engine, telemetry)
- Integration/deployment zone: REST API, shell client, bootstrap scripts, Docker/devcontainer
- The key arrows are from loop specs into the compiler/state machine, and from external clients into the REST API.
Main entry points: LoopStateMachine.java State Machine · LoopEngineServer.java Loop API · loop Runtime Tests · shared Shared Contracts
Components 20
Authoring & Knowledge
Human-readable loop specs, governance standards, templates, examples, and documentation.
- Shared Contracts · Cross-cutting contracts, naming, metrics, governance, and schemas for the loop framework.
shared - Loop Catalog · Core, engineering, platform, governance, and release loop definitions.
loops - Templates · Reusable markdown templates for loops, checklists, reviews, skills, and status artifacts.
templates - Docs · Reference and operating documentation for concepts, validation, migration, and traceability.
docs - Examples · Sample artifacts showing expected loop outputs and lifecycle traces.
examples - Recipes · Scenario-oriented guidance for applying the framework in different contexts.
recipes
Execution Runtime
Java engine that compiles loop specs, enforces phase transitions, and records telemetry.
- Spec Compiler · Compiles loop definitions into runtime-ready LoopDefinition objects.
code/src/main/java/com/rajajeevan/loop/spec/LoopSpecCompiler.java - Loop Definition · Compiled representation of a loop used by the execution engine.
code/src/main/java/com/rajajeevan/loop/spec/LoopDefinition.java - State Machine · Validates phase transitions and enforces loop lifecycle rules.
code/src/main/java/com/rajajeevan/loop/engine/LoopStateMachine.java - Loop Instance · In-memory/runtime state for an active loop instance.
code/src/main/java/com/rajajeevan/loop/engine/LoopInstance.java - Loop API · Language-neutral REST boundary for transit requests, status queries, and health checks.
code/src/main/java/com/rajajeevan/loop/engine/LoopEngineServer.java - Transit Request · Client-submitted transition request evaluated by the engine.
code/src/main/java/com/rajajeevan/loop/engine/TransitRequest.java - Transit Response · Result returned after transition validation and execution.
code/src/main/java/com/rajajeevan/loop/engine/TransitResponse.java - Telemetry · Records engine activity and supports metrics-oriented governance.
code/src/main/java/com/rajajeevan/loop/telemetry/TelemetryService.java
Integration & Portability
Bootstrap, container, and portability tooling that package the framework for local or external use.
- Bootstrap CLI · Java command-line entry point for bootstrapping loop assets into another project.
code/src/main/java/com/rajajeevan/loop/bootstrap/BootstrapCli.java - Gradle Build · Standalone Java 21+ build and test configuration for the runtime.
code/build.gradle - Runtime Tests · Tests for the state machine, compiler, telemetry, and server behavior.
code/src/test/java/com/rajajeevan/loop - Dev Container · Containerized development environment and startup scripts for the engine.
.devcontainer/devcontainer.json - Docker Image · Container image definition for running the loop engine with reduced privileges.
Dockerfile - Porting Tools · Scripts for copying loop specs, templates, and runtime scaffolding into another repository.
bootstrap.py
Connections 25
- Shared Contracts → Loop Catalog: standards inform · Shared contracts and governance standards shape the loop catalog.
- Shared Contracts → Spec Compiler: schemas guide · Schemas and contract docs define what the compiler accepts.
- Loop Catalog → Spec Compiler: definitions compile to · Loop markdown specifications are compiled into runtime definitions.
- Templates → Loop Catalog: authoring support · Templates help create consistent loop specifications and artifacts.
- Docs → Shared Contracts: documents · Documentation explains contracts, governance, and validation practices.
- Examples → Docs: illustrate · Examples demonstrate expected outputs described by the documentation.
- Recipes → Templates: reuse · Recipes reuse templates and show common ways to apply the framework.
- Spec Compiler → Loop Definition: produces · The compiler emits runtime-ready loop definitions.
- Loop Definition → State Machine: drives · Compiled definitions are the basis for state validation.
- Loop Instance → State Machine: managed by · The state machine governs the lifecycle of each loop instance.
- Transit Request → Loop API: submitted to · External clients send transition requests to the REST server.
- Loop API → State Machine: delegates to · The server forwards requests to the state machine for enforcement.
- State Machine → Transit Response: returns · The state machine produces a transition response after validation.
- State Machine → Telemetry: emits events · Transition activity is recorded for observability and governance.
- Loop API → Telemetry: observes · API operations are tracked for health and usage visibility.
- Gradle Build → Runtime Tests: runs · The Gradle build compiles and executes the runtime test suite.
- Runtime Tests → State Machine: verifies · Tests exercise transition rules and state-machine behavior.
- Runtime Tests → Spec Compiler: verifies · Tests exercise spec compilation behavior.
- Runtime Tests → Telemetry: verifies · Tests cover telemetry behavior.
- Dev Container → Docker Image: uses · Containerized development depends on the Docker image definition.
- Docker Image → Loop API: runs · The container is configured to run the engine API.
- Porting Tools → Shared Contracts: copies · Bootstrap tooling ports shared contracts and schemas into target repos.
- Porting Tools → Templates: copies · Bootstrap tooling ports templates into target repos.
- Porting Tools → Bootstrap CLI: invokes · Scripts coordinate with the Java bootstrap CLI for packaging work.
- Bootstrap CLI → Loop API: bootstraps · The CLI helps initialize or operationalize the runtime environment.