How Loop Engineer works

Loop Engineer runs a state machine, not a conversation. Each phase has one role, one provider, and one narrow contract.

The controlled loop

ANALYZE → PLAN → IMPLEMENT → TEST → REVIEW → DECIDE
                      ↑                    |
                      └──────── FIX ←──────┘

A run starts from the current commit of your repository. The analyst and planner inspect the code with read-only access. The implementer writes changes into an isolated Git worktree. The tester runs your configured commands — build, test, lint, typecheck — without a shell. The reviewer inspects the diff, and the final judge decides whether the quality gates are satisfied. If tests fail or the review finds blocking issues, the fixer gets a bounded number of correction cycles.

Roles and access

Validated handoffs

Roles exchange structured JSON that is validated with Zod schemas before it becomes workflow state. Raw chat transcripts never drive the loop. Repository content enters prompts inside untrusted-data fences, so file contents are treated as data rather than instructions.

Stop conditions

The orchestrator stops when one of the following happens:

• All quality gates pass (tests green, no blocking review findings).
• The configured cycle or runtime limit expires.
• Progress stalls between cycles.
• A provider becomes unavailable, for example a session limit.
• You cancel the run.

What you get at the end

.loop-engineer/
├── runs/<run-id>/
│   ├── report.md
│   ├── report.json
│   ├── task.md
│   ├── config.snapshot.yml
│   └── validated handoffs and provider events
└── worktrees/<run-id>/
    └── generated changes for human review

Nothing is committed and nothing is pushed. You inspect the worktree, take what you want, and discard the rest with loopeng clean. Continue with the security model or the comparison with plain agent sessions.