Loop Engine

Step 0 — before anything: adopt the principal-mind skill. It sets how you decide (no hedging), debug (root cause), secure (reflexes), and speak (outcome-first). Every phase below runs inside that mindset, on every model tier.

Every task is recursion with a base case: if (done) return;. You may not claim "done" while any done-criterion is unmet.

The loop

Understand → Clarify → Plan → Execute → Review → Compare vs Done-State
     ▲                                                    │
     └────────────── criteria unmet? loop ────────────────┘
                     all criteria met? STOP

1. Understand (always first, never skipped)

Read BEFORE asking: the repo, applicable host instructions (AGENTS.md on Codex, CLAUDE.md on Claude), workspace/project.md, the store (python <plugin>/db/store.py rules <domain>), code-review-graph if present, and the web when facts are missing. Don't hunt for framework files — query the map: python <plugin>/db/store.py map <topic> returns exactly which skill/tool/agent to load for a topic (one query instead of directory reads). Then write down: assumptions (things you'll take as true) and unknowns (things only the user can settle).

2. Clarify (once, batched, only unknowns)

Ask only questions that change what you build — stack choice, auth mode, repo layout, product intent. Never re-ask what intake already answered (clarifications table). One batch, not a drip. If a default is industrial standard, state it and proceed unless overridden.

3. Plan (architect tier)

Complex/ambiguous/architectural work → the architect role produces: the plan, the file map, risks, and a done-state contract — concrete, checkable criteria written to plans + done_criteria. Planning respects the host's configured reasoning settings. The architect NEVER writes production code.

4. Execute (builder tier)

The builder role implements plan tasks one at a time, obeying design-law, clean-code-law, structure-law, auth-law, security-law. Independent small tasks may fan out to parallel builders. Trivial mechanical edits and digests go to the summarizer role.

Host routing

Read the runtime contract. Claude agent wrappers retain their model pins. Codex uses the selected model for architect, builder, summarizer, learner and design-scout responsibilities, delegating only where supported and permitted; otherwise run sequentially. The parent coordinates state writes. Never change the user's model configuration.

5. Review (gates, not opinions)

Atelier review: ponytail pass, code-review-graph impact, lint/typecheck, file-size law, design-token compliance for UI, a11y/perf where relevant. Update done_criteria.passed with evidence.

6. Compare & terminate

SELECT criterion FROM done_criteria WHERE plan_id=? AND passed=0. Rows remain → loop (fix, don't restart). Zero rows → report done, with evidence. A manual criterion passes only when the user says so — log their words as evidence.

Session hygiene

• Use the host's configured model and reasoning effort.
• After a milestone or before a long build: use host compaction only when available and appropriate — persist state to the store first so nothing is lost (plans and criteria live in SQLite, not in chat history).
• Never poll anything, anywhere. Event-driven or one-shot timers only. User instructions and host permissions take precedence. Unmet criteria prevent a completion claim, but do not authorize ignoring a stop or retrying an external blocker indefinitely.