/review

description: >-
  Turn an implementation plan, tech spec, or existing codebase into an interactive
  architecture diagram the developer can edit directly — drag, reconnect edges, draw
  new edges, comment on nodes with @mentions — then feed those structured edits back
  as revision instructions. Use when the user asks to "diagram this plan", "review the
  architecture visually", "show me the architecture", "visualize current architecture",
  or wants to review a plan-mode plan on a canvas instead of in prose.

ArchEyes — bidirectional plan diagrams

ArchEyes makes the diagram an **input device**. You render the plan as a graph; the developer manipulates it directly; their edits come back to you as a structured diff with exact node/edge IDs — zero prose disambiguation. You revise and re-render. Loop until they approve.

**You are the parser.** ArchEyes' code never reads a plan. You author `plan-graph.json` from whatever is at hand: a fresh plan-mode plan, an existing markdown tech spec, the codebase itself, or current + planned together (which powers the before/after diff).

**Don't interview the developer first.** The graph is the question — render your best guess and let them fix it on the canvas. That's faster and more precise than terminal Q&A. The one thing the canvas *can't* express as an edit is a framing choice: **altitude** (system vs service vs class level) and **before/after diff vs single-state graph**. Pick one, state which you picked in your terminal message, and ask up front only when you're genuinely torn — fixing altitude visually means the developer deleting and merging a dozen nodes by hand.

The loop

1. **Author the graph.** Write `plan-graph.json` (schema below). Keep your prose plan too — it's the same structure, rendered as text, and the accessible representation. 2. **Run the review.** `npx archeyes review plan-graph.json` (or `archeyes review …` if installed). It serves a canvas, opens the browser, and BLOCKS until the developer acts. 3. **Read the feedback.** The command prints ONE JSON envelope to stdout and exits.

• exit `0` → an envelope was printed (`revise` | `approve` | `cancel`). Act on it.
• exit non-zero → no feedback (idle timeout / error). If it says the server is still

up, run `archeyes review --resume` to re-attach. Otherwise start a new round. 4. **Interpret + revise** (guide below). Rewrite `plan-graph.json` AND your prose plan. 5. **Re-render.** Run `archeyes review plan-graph.json` again. Loop.

• `action: "approve"` → the current graph + plan are final. Stop.
• `action: "cancel"` → stop the loop, keep the plan as-is, ask the developer in the

terminal how they want to proceed.

**Reuse node IDs across rounds.** Positions and comments are keyed to node `id`. If you rename a node's `id` when revising, the developer's saved layout resets and any comment that referenced it loses its anchor. The CLI prints a `WARN` to stderr when the graph you just authored dropped an `id` the previous round referenced — if you see that, you renamed something you shouldn't have; reconcile before re-rendering.

Authoring `plan-graph.json`

{
  "version": 1,
  "title": "Split payment flow out of OrderService",
  "groups": [{ "id": "domain", "label": "Domain layer" }, { "id": "infra", "label": "Infrastructure" }],
  "nodes": [
    { "id": "OrderService", "label": "OrderService", "kind": "service", "group": "domain",
      "status": "modify", "files": ["src/services/order.ts"], "description": "payment logic moving out" },
    { "id": "PaymentService", "label": "PaymentService", "kind": "service", "group": "domain",
      "status": "new", "files": ["src/services/payment.ts"] }
  ],
  "edges": [
    { "id": "e1", "from": "OrderService", "to": "DB", "kind": "reads / writes", "status": "existing",
      "description": "Reads and writes order rows through the shared Postgres pool.",
      "calls": ["store.query<Order>(sql, params)", "store.tx(fn)"] }
  ]
}

• `kind` ∈ `service | repository | datastore | adapter | external | module | component | other`

(drives the node icon).

• `status` ∈ `existing | new | modify | delete` on **both** nodes and edges — this is the

whole before/after diff. For a plain plan (no "before"), most things are `new`. For a refactor, mark what's already there `existing`, what you're adding `new`, what you're changing `modify`, what you're removing `delete`.

• Every `edge.from`/`edge.to` must be a real node `id`; every `node.group` a real group `id`.

The CLI validates this and refuses an inconsistent graph.

• On an edge, `kind` is the short "used for" verb (rendered on the arrow); `description` is the

free-text "what the source uses the target for"; `calls[]` lists the specific methods/functions the source invokes on the target (the edge-analog of `node.files[]`). The dev sees all three by clicking the arrow. Author them — a bare arrow with no `description`/`calls` is a weaker diagram.

**Granularity.** Class/module-level for a feature plan. Aim for ~30 nodes or fewer; beyond that, collapse detail into groups. Go higher only when the plan genuinely can't be expressed with fewer moving parts. A graph you can read at a glance beats a complete-but-dense one.

**Labels are short identifiers** — `PaymentService`, not "the service that handles payments". Node boxes are fixed-width and truncate long labels. Put the sentence in `description`, the paths in `files`, the methods in `calls`.

Interpreting the feedback envelope

{
  "action": "revise",
  "comments":     [{ "nodeId": "OrderService", "text": "move token refresh into @PaymentService" }],
  "edgeComments": [{ "edgeId": "e1", "text": "this read/write should go through @OrderRepo, not the DB directly" }],
  "reconnected":  [{ "edgeId": "e1", "end": "target", "was": "DB", "now": "OrderRepo" }],
  "added":       {
    "nodes": [{ "tempId": "new:1", "label": "PricingService", "kind": "service", "group": "domain", "description":