Agent Loops

agent-loops is the implementation discipline skill for Cortex. It is the workflow you use when an agent is expected to make real code changes, verify them, and leave behind reviewable evidence instead of “looks good to me” confidence.

What It Is

The skill-backed command is:

/ctx:agent-loops

Use it when the work involves:

  • writing or changing production code
  • adding or updating tests
  • running review and remediation cycles
  • deciding what should be committed now versus filed for later

The core promise is simple: implementation work moves through explicit loops, not vague “done” states.

The Three Loops

agent-loops organizes implementation into three sequential gates:

Code Change Loop -> Test Writing Loop -> Lint Gate

Each loop has a clear exit condition:

  • Code Change Loop exits only when all P0 and P1 review findings are resolved.
  • Test Writing Loop exits only when all P0 and P1 test gaps are resolved and the tests are not low-quality or misleading.
  • Lint Gate exits only when lint passes cleanly.

If a loop cannot converge after the allowed remediation cycles, the skill says to stop and escalate rather than thrash.

The Non-Negotiables

These are the parts of the skill that matter most in practice:

  • Atomic commits, not feature blobs. Each loop works on the next smallest complete, reviewable change.
  • Independent review only. The implementer does not review their own diff or self-audit their own tests.
  • committer, not ad hoc git commit. The skill explicitly requires committer for the loop commit step.
  • Evidence before completion. Review artifacts, audit artifacts, tests, and lint results are the exit criteria.

Review Routing

The code-review and test-audit flow is stricter than the old “ask another model if convenient” approach.

Code review order

  1. Provider-aware review script first
  2. Fresh-context Codex fallback reviewer if needed
  3. Escalate if no independent reviewer is available

Test audit order

  1. Provider-aware test-audit script first
  2. Fresh-context Codex fallback auditor if needed
  3. Escalate if no independent auditor is available

The important behavioral rule is that the implementer never “grades their own homework.”

Severity Model

The skill uses review severities to decide what blocks loop exit:

Severity Meaning Loop behavior
P0 Security or correctness critical Must fix before exit
P1 Reliability, validation, or edge-case issue Must fix before exit
P2 Important but non-blocking improvement File follow-up issue
P3 Nice-to-have cleanup or preference File follow-up issue

That means agent-loops is opinionated about what gets fixed now versus what gets tracked for later.

Atomic Commit Model

The unit of work is the next atomic commit, not “the feature.”

An atomic commit should:

  • do one logical thing
  • be reviewable in isolation
  • keep related logic, types, and tests together
  • leave the tree in a state where existing checks still make sense

The skill explicitly recommends using committer at the end of each loop exit:

committer "fix(parser): reject CONNECT requests with missing port" src/parser.rs tests/test_parser.rs

If your change needs multiple independent design decisions, it probably needs multiple loop passes and multiple commits.

Code Change Loop

This is the first loop: implement, review, remediate, re-review.

High-level flow:

Implement -> specialist-review -> remediate P0/P1 -> specialist-review -> commit

What it enforces:

  • review happens on a scoped diff
  • only cited P0 and P1 findings block exit
  • P2 and P3 findings become tracked follow-up work
  • repeated failure triggers a circuit breaker instead of endless retries

The skill’s circuit breaker is three review cycles. If P0 or P1 findings still remain, the agent should stop and escalate with the latest artifact.

Test Writing Loop

This loop is not just “write some tests.” It requires an independent audit for coverage gaps and bad-test patterns.

High-level flow:

Audit -> write tests -> verify -> re-audit -> commit

What the audit is looking for:

  • missing contract coverage
  • missing error-path or edge-case tests
  • mirror tests
  • flaky assertions
  • tests that would still pass if the implementation were broken

This is one of the best parts of the skill: it treats false confidence as a real failure mode, not a minor testing preference.

Lint Gate

The lint gate is the final cleanup loop:

Discover linter -> auto-fix what is safe -> re-check -> commit

Unlike review and test audit, lint is binary. The skill’s stance is that team lint policy is not something the agent negotiates around. If a rule seems wrong, escalate rather than silently bypassing it.

Issue Filing

agent-loops also defines what happens to non-blocking findings.

  • P2 and P3 issues should be filed rather than silently dropped.
  • The filed issue should include enough context to be actionable later.
  • Backlog-first tracking is preferred when a project already has a backlog flow.

So the skill is not just “fix things now”; it is also “leave the work in a cleanly trackable state.”

How To Use It Well

The shortest practical pattern is:

  1. Run /ctx:agent-loops when starting implementation.
  2. Decompose the work into the next atomic commit.
  3. Finish the code loop.
  4. Finish the test loop.
  5. Finish the lint gate.
  6. Commit with committer.

The review and audit steps inside agent-loops are part of the skill workflow itself. They are not the same thing as cortex review, which is a separate standalone recommendation surface for loading review-relevant skills.

What This Guide Is Not

This guide is intentionally high-level. The underlying skill contains the full operator contract, including:

  • exact reviewer and auditor fallback rules
  • script invocation details
  • review artifact shape
  • audit artifact shape
  • circuit-breaker behavior

If you are editing the skill itself or implementing review tooling around it, read skills/agent-loops/SKILL.md in the repo directly.