Prism

Prism splits every push into specialist perspectives — security, architecture, code quality and more — then reassembles them into one verdict. Like a prism does with light.

Comment

Inspiration

Code review is one of the most important moments in software development — and one of the most consistently under-resourced. A single reviewer is asked to hold security, architecture, readability, performance, and domain logic in their head at once, across files they may have never seen, in minutes. The result is reviews that are either too shallow (rubber-stamp approvals) or too narrow (one person's specialty dominates).

We kept thinking about how a prism works: white light enters, and the glass splits it into every wavelength at once — then you see the full spectrum. That's what code review should do. Not one person seeing one slice. Every dimension, simultaneously, then recombined into a single picture. GitLab's Transcend Hackathon gave us the moment to build it.

What it does

Prism is a GitLab-native, multi-specialist code-review orchestrator. The moment a change is pushed, Prism:

Orients itself — reads the README, architecture notes, key config files, and recent commit history before judging a single line. Queries GitLab Orbit — pulls live operational context: pipeline status, open issues, known vulnerabilities, SAST/DAST findings. Every specialist reviews the code and the operational state of the project. Casts the right specialists — deterministically, from the diff. Security, architecture, and code-style always run. Frontend, backend, database, devops, and performance are cast only when the files in the change call for them. Runs specialists in parallel — each is its own model call with its own single-domain prompt. The security reviewer is not distracted by CSS. The frontend reviewer is not guessing at SQL safety. Coordinates the results — a lead reviewer reconciles agreements, surfaces conflicts (who disagreed, and the decision with reasoning), and fills gaps no specialist covered alone. Writes one unified review — three formats (analysis.json, analysis.md, analysis.txt) committed to a protected prism-reviews branch. The branch is archive-only, locked against merging, and grows as a permanent project memory. The review includes pinpoint findings (file · line · severity · confidence), a per-branch health dashboard, and a memory ledger of issues that keep recurring or stay unaddressed across runs. When done, Prism posts a commit note on the reviewed commit — GitLab's own notification system fires for every project watcher automatically. Prism ships in two forms with identical output: GitLab Catalog Agent — uses GitLab Duo natively. Open Duo Chat, select Prism, type check this repo. No external key needed. Self-hosted Python engine — for CI pipelines and CLI use, powered by Claude, OpenAI, or Gemini.

How we built it

The architecture is a pipeline of composable modules, each with a single responsibility: providers.py → one API key → Claude / OpenAI / Gemini (prefix-detected) intake.py → commit message + issue → structured intent analyzer.py → diff → deterministic specialist cast (no LLM, fast and auditable) specialist.py → one domain · one call · one DomainReport coordinator.py → reconcile all reports → CoordinatorReview synthesis.py → one review · three formats (JSON + MD + TXT) memory.py → recurring & ignored issues across runs orbit.py → GitLab REST → pipeline · issues · vulns · SAST context notifier.py → GitLab commit note + optional SMTP email gitlab_io.py → git read · orphan branch write · branch protection · source purge runner.py → end-to-end pipeline (clone → review → publish) app.py + web/ → FastAPI + SSE streaming demo UI Specialists run in a ThreadPoolExecutor because the provider SDKs are synchronous. Results land back at their correct index regardless of completion order, so the coordinator always sees a stable, ordered list. The prism-reviews branch is an orphan — it shares no history with the project's source branches, contains only review/, _repo-status/, and _memory/, and is immediately protected via the GitLab API after the first push (push: Maintainers, merge: No one). The Catalog Agent was built by translating the entire engine design into an 8-step system prompt — with explicit Orbit query instructions, a full review tree layout, and a hard barrier against creating merge requests from prism-reviews.

Challenges we ran into

The orphan branch problem. GitLab's create_commit API forks new branches from an existing one by default, copying all source files into prism-reviews. Making the agent understand "this branch must contain only review artifacts, created from nothing" required an explicit warning block in the system prompt and a purge step in the Python engine that strips any non-review file before every push.

  • Agents vs. flows. The hackathon's aiCatalogFlowCreate mutation is gated behind an experimental tier we didn't have access to. We pivoted to aiCatalogAgentUpdate on an agent we owned, rewrote the entire prompt to match the engine's exact behavior, and discovered that an agent with the right system prompt is more capable than a flow anyway — it reasons about which step to run next rather than following a fixed graph.
  • Keeping one review, not 25. Early versions produced one report per specialist per file — noise, not signal. The coordinator pattern (one reconciliation pass over all domain reports, explicit conflict surfacing, a single overall_status) was the architectural insight that made the output actionable.
  • Provider parity. Gemini's OpenAI-compatible endpoint rejects response_format: json_object silently. Claude's JSON mode requires a repair retry for some responses. Building a provider abstraction that handles all three reliably — with graceful degradation — was more work than expected.

Accomplishments that we're proud of

The coordinator pattern — surfacing conflicts between specialists (not just findings) is something human review teams rarely make explicit. Prism names who disagreed, what they each said, and why the decision went one way. GitLab Orbit integration — every specialist sees the live operational state of the project before reviewing a single line. A change that touches a file with an open critical vulnerability gets flagged differently than the same change on a clean project. Memory across reviews — Prism remembers what a branch keeps tripping over. A finding that appears in three consecutive reviews and stays unaddressed is a different kind of signal than a new finding. A published Catalog agent that uses GitLab Duo natively, responds to natural-language shorthand (check this repo, repo health, what keeps coming up?), and produces the same structured output as the self-hosted engine. Zero merge risk — prism-reviews is protected the moment it's created. Review artifacts are physically blocked from ever landing in source branches.

What we learned

The hardest part of multi-agent systems is not the agents — it is the contract between them. Once we defined exactly what a DomainReport looks like (status · summary · findings with file/line/severity/confidence), everything else — the parallel execution, the coordinator, the synthesis — fell into place cleanly. We also learned that a system prompt is architecture. The Catalog agent's prompt is not documentation of what Prism does; it is Prism, for the Duo runtime. Every ambiguity in the prompt became a behavior bug in the agent. Writing it with the same discipline as production code — explicit schemas, explicit failure modes, explicit barriers — was the difference between an agent that drifts and one that ships reviews.

What's next for Prism

MR-level diff reviews triggered by webhooks — Prism already handles MR context; the next step is a GitLab webhook integration that fires automatically on MR open/update. Cross-project memory — today memory is per-repository. An organization-level memory of recurring security patterns or architectural anti-patterns across all their projects would make Prism's signal much richer. Native GitLab Duo API key support — if GitLab opens a Duo API surface for external integrations, the self-hosted engine drops the provider abstraction and calls Duo directly, unifying both forms of Prism. Review diffing — show what changed between two reviews of the same branch: issues fixed, issues introduced, issues that persisted. A changelog for code quality. Confidence calibration — track specialist confidence scores over time against whether developers actually fixed the flagged issues. Use that signal to tune which specialists get cast for which change types.

Built With

Share this project:

Updates