Autonomous Iteration Engine

The /iterate command turns Claude Code into an autonomous agent that continuously improves any codebase you point it at — exploring, analyzing, and implementing improvements in rounds, using Cortexa's encrypted vault as the institutional memory that carries lessons from one round into the next.

Cortexa isn't only its own dogfood. The engine is project-agnostic: the vault, the Deep Think gating, and the self-improving loop work the same whether the target is a Rust desktop app, a Next.js frontend, a Python service, or a monorepo. The only project-specific part is a short command file you tailor to your repo's layout and build commands.

Mental model

Cortexa is the memory. /iterate is the loop. Each round, agents load what was learned before (cortexa_context), do one focused piece of work, and write back what they found (cortexa_capture). Across many rounds the vault accumulates a complete, searchable history of your project's bugs, decisions, and dead-ends — so the engine stops repeating itself and starts compounding.

Prerequisites

• Claude Code open on the target repository.
• The Cortexa app running with its MCP server connected to Claude Code (run /mcp to verify). The vault is what makes the loop self-improving — without it, each round starts blank. See MCP Setup.
• An iterate command file in the repo (see Set it up on your project).

Quick Start

# Run a single iteration
/iterate

# Run continuously (Claude self-paces the interval)
/loop /iterate

# Fixed 20-minute interval
/loop 20m /iterate

How It Works

Each iteration is one tight explore → analyze → decide → implement → record cycle:

1. Load context — cortexa_context pulls prior decisions, patterns, and known bugs for the area in play, so the agent never redoes past work or contradicts a settled decision.
2. Explore — Grep/Glob/Read the focus area for the single highest-impact open item (a correctness bug, a UX/a11y gap, a missing feature, a cleanup).
3. Analyze — cortexa_think (Deep Think) runs the finding through Expand → Critique → Synthesize, returning a confidence level, readiness gates, and risks.
4. Decide — small, well-researched, gate-closed changes auto-approve; anything bigger or riskier is proposed to you.
5. Implement & verify — make the change, then run the project's verify command (e.g. cargo check, npm test, tsc --noEmit, go build, pytest). Verify gates the commit — never commit code that doesn't build.
6. Record — cortexa_capture writes the decision/finding back to the vault for the next round, then the engine reports what it did and what to focus on next.

The engine can run in two shapes:

• Parallel mode — dispatch several worktree-isolated agents at once, each on a different focus area, then collect and rank their findings by Deep Think confidence and scope. Best for broad sweeps.
• Sequential mode — one focused agent goes deep on a specific area or a follow-up identified in a previous round. Best for finishing a thread.

Define your focus areas

Focus areas are the one genuinely project-specific ingredient — they're the rotation of subsystems the engine sweeps so coverage stays even instead of fixating on one corner. Define them in your command file as a list the engine cycles through (e.g. picking 3 per round).

A generic starting rotation for a typical app:

#	Area	What it looks at
1	Core domain logic	The central business rules / engine of the app
2	Data layer	Schema, queries, migrations, indexing, integrity
3	API / interface	HTTP/RPC routes, contracts, request validation
4	UI / frontend	Components, views, accessibility, UX states
5	Auth & security	Authn/z, secrets handling, input sanitization
6	Background jobs	Queues, schedulers, workers, retries
7	CLI / tooling	Commands, output formatting, developer ergonomics
8	Config & settings	Unused settings, missing controls, defaults
9	Tests & CI	Coverage gaps, flaky tests, pipeline health
10	Docs	Stale, missing, or contradictory documentation

Trim, rename, and reorder these to match your repo. The Cortexa project's own rotation — Agent pipeline · Search · MCP tooling · Storage · UI · Hive/Sync · CLI · Settings — is just this idea specialized to its subsystems.

Auto-Approve Criteria

A change is implemented automatically only when all of these hold:

• Deep Think confidence is "well-researched",
• ALL gates have status: "closed" (none open or deferred),
• estimated scope is small (≤ ~30 lines changed),
• it touches no security-sensitive files (auth, crypto, key/secret management — list yours explicitly in the command file),
• it is not a file deletion or a large refactor.

Otherwise the finding is proposed to you with: what was found, the Deep Think verdict (confidence, gates, risks), an implementation plan and scope estimate, and a prompt to approve / redirect / skip / stop. Tighten or loosen these thresholds in your command file to match how much autonomy you want to grant.

Self-Improving Loop

This is the whole point: each iteration makes the next one smarter.

Round 1: finds bug X, captures it in Cortexa
Round 2: cortexa_context surfaces bug X, avoids related issues
Round 3: captures pattern Y, builds on the decisions from rounds 1–2
...
Round N: the vault holds a complete institutional memory of every fix

The vault compounds. After a few dozen rounds the engine has a working understanding of every subsystem's quirks, every architectural decision and why it was made, and every approach that did and didn't work — on your project, in your encrypted vault. Scope each capture with project: "<your-project>" so context and search stay cleanly partitioned per repo.

Set it up on your project

1. Connect Cortexa's MCP server to Claude Code (/mcp to verify).
2. Create .claude/commands/iterate.md in your repo. Claude Code auto-registers project commands from this directory. Tailor the lanes, focus areas, verify command, security-sensitive paths, and project name to your codebase.
3. Run /iterate for a single round, or /loop /iterate to run continuously.

A portable starting template — copy it in and edit the bracketed parts:

---
description: One autonomous explore/analyze/fix iteration for [PROJECT].
---

You are running **ONE iteration** of the [PROJECT] improvement loop. Do exactly
one focused, high-value change, verify it, and commit. Keep iterations small.

## Project config
- Repo layout: [e.g. `src/` app, `tests/`, `docs/`]
- Verify command: [e.g. `npm test && npx tsc --noEmit`]
- Security-sensitive files (never auto-approve): [e.g. `auth/`, `crypto/`, `.env*`]
- Focus-area rotation (pick the least-recently-explored each round):
  1. Core domain logic
  2. Data layer
  3. API / interface
  4. UI / frontend
  5. Auth & security
  6. Tests & CI
  7. Docs

## Steps — do all, in order
1. **Load context.** `cortexa_context(context: "<what you're about to work on>", project: "[PROJECT]")`
   — pull prior decisions so you don't redo work or contradict a decision.
2. **Pick ONE item — severity first.** Survey the chosen focus area for the single
   highest-impact open item (bug > valuable feature > polish). Small enough to finish
   and verify this round.
3. **Analyze.** `cortexa_think` on the finding. Read its confidence, gates, and risks.
4. **Decide.** Auto-approve only if: confidence "well-researched", all gates closed,
   ≤30 lines, no security-sensitive files, not a deletion/large refactor. Otherwise
   propose to the human and wait.
5. **Implement** the one change.
6. **Verify** with the project's verify command. If it fails, fix or revert. Never
   commit code that doesn't build/test.
7. **Commit** (and push if that's your workflow).
8. **Record continuity.** `cortexa_capture(thought_type: ..., project: "[PROJECT]",
   content: "<short: what you did and why>")` so the next iteration has memory.

## Rules
- One focused change per iteration.
- Verify gates the commit. Never push broken code.
- Keep `cortexa_capture` content short (≤ ~300 chars) — long tool-call args get truncated.

Two-machine variant (NRTMF)

For larger efforts you can run the engine on two machines at once — e.g. a frontend lane on one and a backend lane on the other — coordinating in real time over the NRTMF live feed so neither side stomps the other's interface changes. Each agent reads the shared channel first, announces intent before touching the seam (a shared type, an API route, an event name), and broadcasts cross-cutting results. Cortexa's own iterate command is exactly this two-lane setup; see Multi-Agent Workflows for the pattern.

Troubleshooting

/loop /iterate fails with "Unknown skill": Some Claude Code versions can't invoke project commands from /loop. Workarounds:

• Type /iterate directly (always works).
• Use /loop explore and fix bugs (a plain prompt, no skill reference).
• Set up a cron with a descriptive prompt instead of a slash command.

Agents can't reach the Cortexa MCP server: The loop is only self-improving when the vault is connected. Run /mcp to verify, or start the Cortexa app if it isn't running. Without it the engine still works, but each round starts without memory of the last.

Case study: Cortexa building itself

Cortexa was largely built by pointing this engine at its own repo. Across the sessions that produced v0.8.0 → v0.13.1, the iteration engine autonomously delivered:

• 180+ fixes and features across 50+ autonomous rounds,
• multiple shipped releases,
• the HNSW embedding index (O(log N) search at 100K+ items),
• Hive security hardening (20+ vulnerabilities fixed across audits),
• first-class projects with Principles,
• the 7-layer collective cognition stack, wired end-to-end,
• and a complete VitePress documentation site.

Every finding, decision, and implementation was captured in the vault — institutional memory that made each subsequent round sharper. The same loop works on your project; only the focus areas and verify command change.