Wire the spoken loop into the screen, then re-skin toward the mockups — built as the reference template for many custom Companions.
Version. v0.2 Date. 2026-06-26 For. The Operator. Two decisions settled (unified open; template framing — branding + language, ready-not-active). Reading level. Plain English. The change request that follows carries the file names, component paths, and line-level grounding. Changed from v0.1. Added the template framing — this is the reference Companion, customizable along branding and language, ready-not-active — and a template-cleanliness build gate.
The whole thing in a paragraph
The Engine now has the full spoken loop — say "open Goosey," your unqualified commands land in Goosey, say "close" to leave. It works at the Engine and API level (merged, tested, green). But the screen you look at uses none of it. This note scopes making that loop visible and usable on the Companion surface, and moving that surface toward the mockups you've drawn.
The honest finding: you called this "a completely new Companion." The live frontend isn't bare ground — three working conversation surfaces already exist, on a clean foundation that already uses the mockup's colors and fonts. It's a sound frame missing the focus layer. So the lower-risk path is to wire focus into what's there and re-skin it, with a clean fallback to rebuild if it comes out wrong. Because it's all about the Engine and the API — and the Engine is untouched either way — trying the cheaper path first costs little.
The one settled decision
Open is unified
When you open an engagement — by clicking it or saying "open Goosey" — it both takes you to that engagement's surface and sets your command-focus there, as one act. "Where I'm looking is where my commands land." Today these are two disconnected things: the screen navigates one way, the Engine's focus is set another, and the frontend never sets it at all. Unifying them is the heart of this work.
Decided — unified
Navigate and set-focus happen together. The existing click-to-open gains a focus-set call beside it; the two "opens" become one.
Template framing — this is the reference Companion, not the only one
The core commitment
This Companion surface is the reference template from which many custom Companions are created — not a one-off. That changes how every piece is built: each must be customizable from the start, or it gets built twice.
Decided — two axes, ready-not-activeBranding (palette, fonts, Companion name, voice register) and language (full string translatability) are the two axes — the complete set, no third. Built ready, not active: parameterized and swappable seams, shipping with the one Loomworks brand and English. The runtime brand/language switcher is built when a second Companion gives real requirements, not speculatively now.
Why the seams are cheap to build clean — the machinery already exists. Template-cleanliness is not new architecture; it is using what's there correctly. Branding rides the existing design tokens (the swap point; the standing rule is already "tokens, never ad-hoc colors") — so the build touches zero hardcoded colors. Language rides the existing brand-string registry (strings as functions, already grouped) — so every label, confirmation, and disambiguation becomes a registered string, never an inline literal; the registry is the seam a translation layer plugs into later. The Companion's name already arrives from data, so the name axis is already swap-ready. This mirrors the Engine's white-label commitment (brand-free outcomes the host translates) on the consumer side.
The template-cleanliness gate (every build step)
No hardcoded color (tokens only). No inline user-facing string (registry only). Companion name and identity from data (never literal "Companion"/"Goosey"). Voice-register strings isolated so tone is swappable. Because the repo already guards its wire boundary, the change request adds a lightweight test that fails if the new focus components introduce a raw color or an inline string — the template rule guaranteed in code, not requested in the prompt.
What the inspection found
A read-only inspection of the live frontend and the mockups established the ground this builds on:
The mockups (the design target). A dual-pane chat surface — conversation on the left, a four-room workspace on the right — with a top-bar focus chip reading "here: 7 · Goosey · E0007" (number, name, E-label; never the hidden UUID). Open and close are spoken; the picker also opens by click.
The live frontend (the build truth). The mockup's colors and fonts are already the live design tokens, so a build can match the mockups natively. Three conversation surfaces already work and already talk to the Engine. There's a clean API client, an established pattern for "me"-style endpoints, a shared-state pattern, a voice hook, and a vocabulary guard that already keeps engine jargon off the screen.
The gap (verified, not assumed). The frontend calls none of the focus endpoints the Engine gained. No focus chip. And the existing "open" is screen navigation only — it jumps you to an engagement's page but never tells the Engine that's where your commands go. Two unconnected "opens" — the build reconciles them into the one unified open.
The build shape — wire first, re-skin second, judge in between
The work splits into two phases with a deliberate judge-seam between them, so the moment of judgment — sound frame or patchwork? — comes before the expensive cosmetic work, not after.
Phase 1 — Wire the focus capability
Make the Engine's focus loop visible and working on the existing surfaces, changing as little of the look as possible.
A focus adapter — the frontend reads "where am I" and sets/clears focus against the Engine endpoints the spine built.
A focus context — a small shared "where you are" state, so the chip can show it on any surface (matches the existing pattern; not a new architecture).
The focus chip — the "here: 7 · Goosey · E0007" indicator in the top bar. Number, name, E-label; never the UUID.
Unified open — the click-to-open gains a focus-set call; navigation and focus become one act.
Spoken open/close wired — the composer/voice path carries open/close to the Engine, completing the visible spoken loop.
The judge-seam
At the end of Phase 1 the focus loop works and you can use it. You look at it and decide: sound frame worth re-skinning, or patchwork to rebuild? Phase 2 proceeds only on a sound frame. This is the cheap-failure point — if wiring focus reveals the surfaces fight it, you learn that here, before investing in the re-skin.
Phase 2 — Re-skin toward the mockups
Only if Phase 1's frame is judged sound. Move the surface's look and layout toward the mockups — the dual-pane conversation-plus-four-room-workspace, the composer with command chips, the voice surfacing, the picker home — on the working focus foundation. Scoped in its own change request after the seam, its shape informed by what Phase 1 reveals and which mockups you prioritize. Named here so the arc is visible, not drafted in detail yet.
The patchwork question, answered
You raised the real risk: modifying an existing solution can produce a patchwork product. Honestly read against the inspection:
Patchwork happens when new behavior is bolted onto a foundation built on different assumptions — when the old structure fights the new thing. The inspection found the opposite: a clean foundation missing the focus layer, not a wrong-built one resisting it. The focus work adds an absent layer; it doesn't carve into a mis-built one.
The patchwork risk is actually higher in a from-scratch rebuild — a new surface still talks to the same Engine, renders the same conversation, uses the same tokens, obeys the same vocabulary wall. Rebuilding means reusing those (which is "modify what exists" with extra steps) or duplicating them (two of everything, drifting apart — patchwork, self-inflicted and doubled).
The fallback is cheap because it's all about the Engine and the API. The frontend is a consumer of a substrate that's built and green. If the wired-and-reskinned surface comes out wrong, you rebuild the surface and the Engine is untouched. Trying the cheaper path first is bounded: at worst you fall back to rebuild, having lost a surface, never the substrate.
Seed alignment — checked against v0.12
A Companion surface is the most seed-governed thing in the product. Checked against the seed (v0.12) and the architecture specification (v0.6); the build conforms on every surface-governing commitment:
Plain-terms discipline — methodology words appear in plain language, never engine shorthand. The frontend already enforces this with a vocabulary guard; the build keeps it.
Only show what is available — no disabled buttons, no grayed-out options. The chip and open/close affordances appear only when they apply.
Identity is cryptographic, not email — the chip shows number + name + E-label; the UUID stays invisible; nothing keys on email. The mockups already honor this.
The Companion is the user-facing entity; the AI is invisible — the surface speaks as the Companion, discloses no model.
Operator-authority over state transitions — open/close set focus (where commands land), not artifact state, so this commitment is untouched; existing card actions still route state changes through Operator approval.
No conflict with the seed or the architecture specification is visible.
What the first change request covers (Phase 1)
The change request drafted from this note covers Phase 1 only — wire the focus capability — in disciplined steps, each its own commit, the test suite green at each, halting before any push for your authorization. In plain terms: the focus adapter; the focus context; the focus chip; unified open; spoken open/close wired; and tests plus an end-to-end walk (open by click and by voice → chip updates → unqualified command lands in focus → close → chip clears → next command asks). Phase 2 (the re-skin) is a separate change request drafted after the judge-seam.
What this does NOT do
It does not rebuild the conversation surfaces from scratch — it wires focus in and (Phase 2) re-skins. Rebuild stays the fallback if the frame is judged unsound.
It does not change the Engine — the spine, resolver, intents, and endpoints are merged; this consumes them.
It does not touch artifact state authority — open/close set focus, not artifact validity.
It does not commit Phase 2's detailed shape — that waits for the judge-seam.