Loops
Execution runs that take a scoped artifact, run through gated phases, and return reviewable output.
Lifecycle
The orchestrator prompt at plugins/code/prompts/prompt.md drives the phased workflow; state persists entirely in files under the work directory.
Phases
| # | Phase | Primary agent or skill |
|---|---|---|
| 0.9 | Pre-exploration | @code:pre-explorer |
| 1 | Plan draft | @code:plan-draft-writer or @code:plan-importer |
| 1.1 | Plan review checkpoint (hard stop) | human |
| 1.2 | Process answered questions | @code:answered-questions-subagent |
| 1.2a | Process addressed gaps | @code:plan-writer (gap mode) |
| 1.3 | Simple-mode evaluation | judges:eval-cache then @code:plan-evaluator |
| 1.4.x | Cross-repo discovery and PRDs | cross-repo-coordinator, generic-discovery, cross-repo-prd-writer |
| 2.5 | Critic validation | parallel critics (gated by critic-cache) |
| 2.6 | Plan refinement | @code:plan-writer (merge mode) |
| 2.7 | Plan finalization | @code:plan-writer (finalize mode) |
| 3 | Implementation | per-task verification-subagent → implementation-subagent |
| 4 | Code simplification | @code-simplifier:code-simplifier |
| 5 | Testing and validation | @test-engineer and @code:build-validator |
| 6 | Visual QA | @code:visual-qa-subagent (Playwright) |
| 7 | Logging and completion | orchestrator writes log.md and exits |
The orchestrator is read-only: it never touches project files directly. It uses Bash, Task, TodoWrite, AskUserQuestion, and SendMessage and delegates every file operation.
Bounded retries
Loop agents exit a phase by emitting a promise token such as <promise>PLAN_VALIDATED</promise>. A SubagentStop hook verifies the promise with a deterministic validation script; if validation fails, the iteration counter increments and the agent is forced to retry up to its configured budget. See Loop until correct.
Outputs
plan.jsonandplan.mdreviews/*.review.jsonrequirements-extract.json,code-map.json,investigation-log.mdstate.json(polled by UIs),log.md,perf.jsonl- diffs, commits, and usually a PR via the
git_properations - judge reports (
plan-judges.json,code-judges.json) when thejudgesplugin is invoked .learnings/pending and processed learnings
Concurrency and locking
The desktop client's cloud command executor serializes commands by lock key. The default lock key is derived from the operation ID and the scoped path from the request body (repoPath | worktreePath | workDir | runDir | path).
Amend
/code:amend-planlets you inject directives, answer questions, or confirm changes without restarting the loop.
Where the code lives
The orchestrator is plugins/code/prompts/prompt.md. Phase-level contracts are encoded in the orchestrator prompt and enforced by the hooks in plugins/code/hooks/hooks.json.