aide-architect-editor-implementation

Files (1)

• SKILL.md

SKILL.md (first lines)

# Architect → Editor — Implementation

The doctrine lives in `aide-architect-editor-pattern`. This skill
is the **engineering playbook** for that doctrine: the concrete
files, the exact insertion points, the test cases, the rollout
order, and the failure modes.

## Architecture (recap)

Two model calls per "complex" agent turn:

1. **Architect**: same system prompt + transcript + a framing
   suffix that says "read first, plan second, never emit tool
   calls. Output a `## Plan` block." Returns text with a
   fenced plan block.
2. **Editor**: same system prompt + transcript + the architect's
   plan as a system-prompt prefix. Returns the same XML tool
   calls we already parse.

The agent loop decides "architect then editor" per turn, not
per session. A session can have some turns be architect/editor
and other turns be the one-call path.

## Files to touch

### 1. `node/src/services/agent-loop.mjs`

Add a new option on `start(task, mode, chatFnOverride, options)`:

```ts
type AgentOptions = {
  architectEditor?: boolean;  // opt-in to the two-call pattern
  architectMaxRetries?: number; // default 1
}
```

Modify `runSession` so that, when `architectEditor` is on AND
the model emits no tool calls AND the response contains a
`## Plan` block, the loop:

### 2. `common/contracts/agent.ts`

Add a new event type:

```ts
export const AgentPlanEvent = z.object({
  event: z.literal('plan'),
  session_id: z.string().min(1),
  plan: z.string().max(8192),
  model: z.string().optional(),
  created_at: z.number().int()
}).strict();
```

Add to the `AgentStreamEvent` discriminated union.

### 3. `node/src/routes/agent.ts`

Extend `AgentStartRequest` to accept `architect_editor?: boolean`.

Extend the start handler to read the new field and pass it
through to `service.start()`.

### 4. `daemon/model-manager.mjs` + `node/src/services/model-runtime.ts`

Add a `role: 'architect' | 'editor' | 'chat'` parameter on
the chat function. When set, the runtime resolves the
preferred model for that role (smaller/faster for editor,
stronger/slower for architect). If the role model isn't
allowlisted, fall through to the chat-default model.

This is OPTIONAL for v1 — both architect and editor can use
the same chat-default model. The role is a hint, not a hard
selector.

### 5. `harness/scaffold.mjs`

Add a new scaffold tier `architect` (~400 tokens) with the
framing "read first, plan second, never edit." Used as the
system-prompt prefix when `architectEditor: true`.

Add a new scaffold tier `editor` (~300 tokens) with the
framing "you are the editor. The architect produced this plan.
Translate it into AIDE tool calls. Do not re-reason."

## Rollout

Ship in 2 PRs:

### PR A — architect/editor core (this session, smaller)

- architect/editor option on agent loop
- `agent:plan` event
- plan parser
- 6 arch tests
- skill `aide-architect-editor-pattern` (already done)
- skill `aide-architect-editor-implementation` (this skill)

### PR B — scaffold tiers + role selector (next session)

- `architect` and `editor` scaffold tiers in `harness/scaffold.mjs`
- `role: 'architect' | 'editor'` on the chat function
- `daemon/model-manager.mjs` role-aware resolution
- `/architect` slash command

## Pitfalls

- **Do NOT add a "needs approval for architect" prompt** in
  the agent loop. The architect is reasoning; it's free.
- **Do NOT cache the plan between turns.** Re-derive every
  turn; the transcript may have grown.
- **Do NOT surface the plan as a chat reply.** It goes on the
  `agent:plan` event, not in the assistant message.
- **DO limit the architect output to a single `## Plan`
  block.** Multi-block plans are a parser anti-pattern.
- **DO honour the existing approval flow on the editor's
  tool calls.** The architect did not approve; the operator
  must see the actual tool calls.
- **DO keep the architect loop budget visible** to the

From AnonymousNomad/covert-coder, Apache-2.0.

More from AnonymousNomad/covert-coder