Brightmark

When we hand a client their new website, we need their feedback — and the usual ways of getting it are lossy. Brightmark fixes that at the source: the client opens a share link, sees their own live site, and clicks the thing they mean. Every comment is pinned to the exact element, and — this is the part that matters — it comes out the other side as a work order an AI coding agent can pick up and fix. It is Brightwork's own product, and it is how we work with website clients.

"The button on the about page"

Website feedback usually arrives as a guessing game. A long email. A screenshot with a red arrow. A message that says "the button on the about page looks off" — and there are three buttons on the about page. The developer has to reconstruct what the client meant before they can even start, and something always gets lost in the translation.

Brightmark removes the ambiguity by binding every comment to the exact spot in the page. There is nothing to describe, because the client didn't describe it — they pointed at it. The note and the element travel together from the moment it's left, so the person (or agent) doing the fix never has to guess which thing was meant.

brightmark · dashboard

Point at anything. No login.

The client's side is deliberately frictionless. They get a share link — a clean /r/{host}/{code} URL, no account, no password — and land on their own live site inside the review screen. In Comment mode, hovering highlights whatever element is under the cursor; a click opens a small composer to leave feedback pinned to that exact spot.

It isn't only for buttons and boxes. A client can select a specific run of text and comment on the wording itself, or ask for a whole new page. Whatever they touch, the comment is anchored to it — not to a coordinate that drifts the next time the layout moves.

brightmark · leaving a comment

brightmark · comment rail

Left: click an element and a composer opens with a preview of exactly what's pinned. Right: every note lands in the comment rail with an "anchored" badge — a small promise that it still points at the right thing.

The comment that survives a redeploy

A pin is only useful if it keeps pointing at the right element after the site changes. A raw x/y coordinate doesn't — move a section, add a paragraph, ship a redesign, and the arrow now points at empty space. So Brightmark doesn't store a coordinate. It stores a three-layer anchor: a CSS selector, a hybrid XPath, and a text snippet — three independent ways to find the same element again.

On load, the in-page agent re-resolves every pin — selector first, then XPath, then a fuzzy text match — and reports honest status: anchored, fuzzy, or lost. It re-anchors on device-toggle, on resize, and across Astro view-transition swaps. A comment keeps its meaning even after the underlying site has moved on.

brightmark · comment detail

The agency's cockpit

Where the client sees a clean review screen, the operator gets a cockpit. The review canvas can preview the site at mobile, tablet, laptop and desktop widths — a layout preview, stated honestly: it resizes the frame, it is not true device emulation. There is zoom, fullscreen, an address bar to navigate the preview, and an Inspect mode that overlays spacing, typography and WCAG contrast checks.

Alongside sits the comment rail and a Kanban triage board — Open, In review, In progress, Resolved — with severity, filters and drag-and-drop. It's where a pile of client notes becomes an ordered queue of work.

brightmark · triage board

Straight into the dev workflow

A comment doesn't have to stay inside Brightmark. When a project is wired to a repository, comments can auto-raise GitHub issues — each tagged source:brightmark and a severity:* label, so the work lands where the developers already live. The whole integration is opt-in and completely inert unless a repo and token are configured.

And it stays in sync both ways. Close the GitHub issue and the comment flips to resolved and disappears from the client's link; delete the comment and its issue is withdrawn or closed. One truth, mirrored — nobody has to remember to update the other side.

Hand the fix to an AI agent

This is the part that makes Brightmark Brightmark. A pinned comment is already precise about where — but a fix also needs to know what was happening. So the in-page agent instruments the page and captures, per comment, the reproduction context a developer would otherwise have to reconstruct: console output and errors, failed or slow network requests, the environment (browser, OS, viewport, locale), and a breadcrumb trail of what the client did.

Crucially, that context is redacted in the browser before anything leaves the page — passwords, tokens and PII are scrubbed at the source, then re-scrubbed server-side and size-capped. The agent gets what it needs to reproduce the problem, and nothing it shouldn't have.

The loop

A client's click at one end comes out as a resolved issue at the other — and the client, who never saw any of the machinery, just sees the thing they pointed at get fixed. The tool that hands feedback to an AI agent closes its own loop.

The work order, over MCP

The bridge to the agent is a Model Context Protocol server (built on FastMCP, over stdio) that exposes each comment as a work order through four tools. A coding agent like Claude Code connects, sees the queue, pulls the exact anchor and context for one item, does the work, and marks it done:

• project_summary project name, repo, counts and open work-order totals
• list_work_orders the comments as work orders, filterable by status and severity
• get_work_order the three-layer anchor + source_file hint + redacted repro context
• update_work_order sets status — mirrored back onto the linked GitHub issue

Prefer not to plug an agent in live? Work orders also export as a WORKORDER.md bundle — one section per comment, screenshots included — written straight into a folder you open in Claude Code.

Built the way we build

There's a pleasing symmetry here: the tool that hands feedback to AI agents was itself built by AI agents. Brightmark came together through Brightwork's orchestration system — Loom on GitHub — where every task is an issue, built on its own branch, reviewed as a pull request, and auto-merged when it's clean.

The assembly line

Across roughly five weeks that produced about 182 commits and 185 merged pull requests spanning issues #7 through #420 — every decision auditable in a pull request you can still read. And in the same spirit: this very case study was built the same way, as a tracked GitHub issue run through a Loom cycle.

What's underneath

To read a client's live site well enough to highlight its elements and screenshot them, Brightmark renders the target through a same-origin proxy: it fetches every asset and rewrites its URLs so the whole page loads from Brightmark's own origin — which is what makes the target's DOM readable and its element captures clean. A proxy that fetches arbitrary URLs is also a security surface, so it is wrapped tightly.

Honest about scope: this approach is excellent on static and server-rendered sites — the Astro, WordPress and Squarespace sites we typically build — and heavy, client-rendered single-page apps are out of scope for v1. Brightmark is also desktop-only by design; it's an operator tool, and we haven't pretended otherwise.

How this shows up for clients

Strip away the machinery and here's what a website client actually gets. Giving feedback is effortless — no login, no account, just click the thing you mean. Nothing gets lost or misunderstood, because the exact element and the context travel with every note. And fixes happen fast, because that precise code location and reproduction context go straight to the people — and the agents — doing the work.

The full stack