aide-architect-editor-pattern

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architect → Editor Pattern

Born 2026-08-28 from rival gap analysis (Cursor, VS Code, Claude Code,
Cline, Aider, Windsurf, Replit all converge on this pattern in some
form). The two-call decomposition is the single highest-leverage
**architectural** improvement AIDE can ship — it lets the small
house model (cipher 4B) reach planning quality that only much larger
cloud models can do directly, because the **editor** is just a
syntax-aware translator, not a planner.

## Research base (verified 2026-08-28)

1. **Aider architect/editor mode** (aider.chat/docs/usage/modes.html):
   architect proposes, editor edits. Two model calls. Default editor
   is auto-selected per architect (e.g. o1 architect + Sonnet editor).
   "Certain LLMs aren't able to propose coding solutions and specify
   detailed file edits all in one go. For these models, architect
   mode can produce better results." Article: "Aider's
   architect/editor mode for detailing changes."
2. **Cursor, Claude Code, VS Code, Cline, Replit**: every rival
   internally has a "think then do" two-phase pattern. Some
   surface it (Plan/Act), some hide it. The principle is the same:
   separate reasoning from mechanical action.
3. **AIDE audit 2026-08-28**: we always do one model call. The agent
   loop calls the model with system + transcript, gets back tool
   calls, runs them. For small models this means the same
   "reasoning budget" is split between (a) deciding WHAT to do and
   (b) producing the exact `<tool>...</tool>` syntax. (b) is
   trivially mechanical; (a) is the hard part. We can use a small

### Concrete rules

1. **Architect and editor CAN be the same model.** Aider explicitly
   says "architect mode can also be helpful when you use the same
   model as both the architect and the editor." The two-call gives
   the model two shots at the problem; the second shot sees the
   first shot's plan and only has to translate, not re-reason.
2. **Architect output is a fenced `## Plan` block.** No tool calls
   in the architect stage. A parser extracts the block from prose.
3. **Editor output is the same XML tool call format we already use.**
   No schema change. The plan becomes a system-prompt prefix: "You
   are the editor. Translate this plan into AIDE tool calls..."
4. **If the architect emits tool calls anyway**, we treat the whole
   thing as editor output and skip the second call. Don't waste
   tokens.
5. **If the plan is empty or unparseable**, fall through to the
   current one-call path. The pattern is opt-in, not a hard cut.
6. **The architect prompt includes the credo and harness scaffold.**
   Same content, different framing. "Read first, plan second, never
   edit" is the only behavioural change.
7. **The editor prompt is the current agent prompt + the plan.**
   The model sees the plan as a contract to fulfill, not as a
   suggestion to re-reason about.
8. **Telemetry records both calls.** The `agent:message` and

## Why it's done this way

- **Quality**: a small model given a clear plan will produce correct
  tool calls more reliably than the same model asked to both
  reason AND emit XML. We remove the cognitive load of XML
  formatting during reasoning.
- **Auditability**: the operator sees the plan BEFORE the editor
  runs. This is the same pattern Cursor + Replit + Aider ship.
  Reviewing a plan is faster than reviewing diffs.
- **Cost**: when architect and editor are the same model, we pay
  for 1 extra call. When the editor is a smaller model, we save
  cost. Same wiring, both modes win.
- **All-local**: the architect and editor are both served from the
  in-house engine. No cloud, no telemetry. The two-call happens
  inside AIDE.
- **Backwards compatible**: the one-call path stays. The pattern
  is opt-in. No existing user workflow breaks.

## Dependencies / issues / bugs

- **Depends on**: agent-loop.mjs (where the chat function is wired),
  harness/scaffold.mjs (the editor uses the same scaffold tier),
  model-runtime (model selection per role). All present and shipped.
- **Existing approval flow**: the editor's first mutating tool call

## Threat matrix

| Threat | Signature | Defense |
|---|---|---|
| Plan is too vague for editor | Editor fabricates details not in plan | Editor's tool calls go through approval; operator can reject + ask for re-plan |
| Plan is wrong (model hallucinated) | Editor executes hallucinated plan | Approval flow: operator reviews plan + diffs together |
| Two-call latency | User waits 2x longer | Editor is a fast/small model by default; opt-in for the use case |
| Plan contains forbidden content (e.g. credential type) | Editor executes | Same input sanitization as the one-call path; the architect prompt forbids credential field targeting per aide-desktop-agent-model-spec |
| Architect and editor are DIFFERENT models with different permissions | Editor does more than architect planned | Editor is constrained to the same agent-policy as architect; no new permissions |
| Cost spike | 2x model calls in a loop | Per-session cap (8 cycles) + 1-call fallback |
| Editor cannot find a path the plan referenced | Tool fails | Existing consecutive-mistake limit + call_user escape |

## Pitfalls

- **Do NOT collapse architect + editor into one call** even if
  they share a model. The two-call structure is the entire value
  prop. Aider's docs are explicit: "Allowing the model two
  requests to solve the problem and edit the files can sometimes
  provide better results."
- **Do NOT add new tool types** for the editor. Same `<tool>` XML.
- **Do NOT cache plans across sessions.** The plan is a contract
  with the transcript; if either changes, the plan is stale.
  Re-derive each turn.
- **Do NOT skip the approval flow** on the editor's tool calls
  just because the architect "already approved." They are
  different models (or at least different calls); the operator
  must see and approve the actual edits.
- **Do NOT surface the plan in the chat reply.** It belongs in the
  pending_approval event so the cockpit renders it as a card,
  not in the transcript the model re-sees next turn.

## Verification

End-to-end test (build before the integration): the test takes a
prompt that on a 4B model usually fails direct editing (large
multi-file refactor) and proves that with architect/editor the
success rate goes up. Measure: edit-shape correctness + the
operator-rejection rate (lower is better).

From AnonymousNomad/covert-coder, Apache-2.0.

More from AnonymousNomad/covert-coder