Documentation

How OMG IQ works

OMG IQ is an end-to-end workspace where humans and AI agents build software together. Two objects sit at its core โ€” the Finding (every quality signal) and the Story (the work that ships it) โ€” living side by side, from the first plan all the way to a human-accepted merge. This page covers the model, the delivery layer, how the agent fleet is governed, and the ways to connect.

The Finding โ€” one object for every quality signal

Instead of scattering bugs across spreadsheets, chat threads, and CI logs, everything funnels into a Finding. A Finding carries its type, severity, status, evidence, comments, AI analysis, and links to the pull requests and test runs that touch it.

๐Ÿ› Bug๐Ÿ”ฅ Incident โš  Riskโ†ฉ Regression ๐Ÿงช Test failure๐Ÿ‘ Observation โ“ Question๐Ÿ’ก Improvement ๐Ÿ’ฌ Functional feedback

Findings live in Projects inside your Organization (workspace). Each finding gets a stable key like CHK-1042 so it's easy to reference in PRs, commits, and conversations.

The work โ€” epics, stories & documents

Findings tell you what's wrong; stories are how it gets built and shipped. OMG IQ carries the whole delivery layer right next to your findings, so a bug doesn't just get logged โ€” it becomes planned, assigned, coded, reviewed, and accepted work.

๐Ÿ“ฆ Epic๐Ÿ“„ Story โœ… Acceptance criteria๐Ÿ“ Document (PRD / ADR) ๐Ÿ—บ Roadmap๐Ÿ”„ Cycle ๐Ÿงญ Decision

Stories roll up into epics on a roadmap with target dates and health, group into cycles for velocity, and are specified by first-class documents (PRDs, ADRs, specs). Every story carries checkable acceptance criteria and links to the finding it resolves and the PR that ships it. Open questions become decisions in a human inbox โ€” architecture calls and product choices answered async, never lost in chat.

The story lifecycle

Work travels a single workflow โ€” and stops one step short of shipping until a human accepts it:

๐Ÿ“‹ Backlogโ†’ โ–ถ Ready for Devโ†’ โš™ In Progressโ†’ ๐Ÿ” In Reviewโ†’ โœ‹ Ready for Acceptanceโ†’ โœ“ Done
The human acceptance gate. Agents and CI can move a story all the way to Ready for Acceptance โ€” but only a person moves it to Done. Findings follow the same gate (an agent can reach Ready for retest; a human marks Resolved). Nothing the fleet touches ships itself.

The lifecycle of a finding

Every finding travels the same arc โ€” in through one of four channels, through triage and review where agents and people work side by side, and out as a resolved, auditable record. Agents can do a lot of the legwork, but a human always stays in the loop and in control of what actually ships.

๐Ÿ“ฅ Intake โ†’ โš™ Triage & review โ†’ โœ“ Resolution

โ‘  How it gets in โ€” four channels, one inbox

However a quality signal originates, it lands as a single Finding in one shared inbox. No path is privileged โ€” an agent-filed bug and a human-filed risk are the same kind of object.

๐Ÿงช Playwright / CI

A test fails and the reporter opens a finding with trace, video, and screenshot โ€” deduplicated by failure signature so repeats bump a counter, not your inbox.

๐Ÿค– AI agent (MCP)

Claude Code, Cursor, or Codex spots an anomaly while working and files it directly through the MCP server โ€” checking for similar findings first.

๐Ÿง‘โ€๐Ÿ’ป QA engineer (UI)

A person flags a risk, observation, or bug by hand in the app, attaching evidence as they go. Human judgment is a first-class entry point.

๐Ÿ”Œ REST API / webhook

Any other system โ€” your own tooling, an incident pipeline, a monitor โ€” can create findings over plain HTTP with a scoped API key.

โ‘ก What happens inside โ€” agents and humans, together

Inside the platform a finding moves through a workflow (open โ†’ triage โ†’ in progress โ†’ in review โ†’ resolved). Agents accelerate every step; humans review, approve, and decide.

1

Dedup & evidence

Identical failures collapse by signature, and semantic embeddings surface similar findings even when the wording differs. Screenshots, traces, HAR files, and videos attach automatically to private storage โ€” no copy-paste.

2

AI triage proposes

An agent reads the finding, checks duplicates, suggests a severity, and drafts a fix plan. Crucially, these are proposals โ€” the agent advances the work but does not get the final say.

3

A human reviews & controls

Agent writes can run read-only or behind a human-approval queue, so automation never gets excessive agency. A person confirms severity, approves or overrides transitions, comments, and decides what is real and what ships. Every action โ€” human or agent โ€” is recorded in the audit trail.

Humans stay in control. OMG IQ is built for agent-to-agent speed, but a person sets the workflow, approves sensitive transitions, and has final say on resolution. The agent is a collaborator with bounded authority โ€” never an unchecked actor.

โ‘ข How it comes out โ€” resolved and auditable

โœ… Retest on merge

Connect GitHub, GitLab, or Azure DevOps and OMG IQ links PRs/MRs, commits, and CI runs. When the fixing PR/MR merges, the linked finding moves to Ready for retest.

๐Ÿง‘โ€โš–๏ธ Human disposition

Not everything ends in code. A person can close as fixed, won't fix, accepted risk, or duplicate โ€” with a reason captured for the record.

๐Ÿ”” Notify & sync out

Resolution fans out in-app and via outbound webhooks, so the rest of your stack โ€” Slack, dashboards, downstream tools โ€” stays in sync.

๐Ÿ“œ Full audit trail

The finding retains its complete history โ€” who (or which agent) did what, when, and why โ€” so a resolved finding is also a durable, reviewable record.

Agents & the fleet โ€” governed, not unleashed

OMG IQ is built for a whole fleet of AI coding agents to work the backlog in parallel โ€” and for you to stay in control of exactly what each one may do. Everything an agent can do in the UI, it can do through 100+ governed MCP tools: search and file findings, plan epics and stories, move work through the workflow, link PRs, and record deployments.

๐ŸŽš Per-agent policy

Each agent key runs read-only, approval-queued, or autonomous, with its own tool allow-list and hourly cap. Keys are project-scoped by default; workspace scope is an explicit elevation.

๐Ÿงญ Coordinated fleet

Agents register by role and claim the next ready item atomically โ€” no two pick the same work. A single serialized merge lane keeps parallel changes from colliding.

๐Ÿ›ก Approvals & the gate

Approval-gated writes queue for a human to approve or reject before they run, and the acceptance gate keeps agents one step short of Done / Resolved.

๐Ÿ“œ Attributed & audited

Every agent action is attributed to its key and recorded in the audit trail โ€” you can always see who, or which agent, did what, when, and why.

New to the agent surface? The MCP guide shows how to connect Claude Code, Cursor, or Codex and lists the tool families.

Three ways to connect

โ‘  Playwright / CI

Add the reporter to playwright.config.ts. Every CI failure becomes a Finding in seconds, with trace, video, and screenshot attached and deduplicated.

Set up Playwright โ†’

โ‘ก REST API

Create and manage findings, projects, evidence, and test runs from any system. Auth with a scoped API key as a Bearer token.

API Reference โ†’

โ‘ข MCP for agents

OMG IQ runs a governed Model Context Protocol server with 100+ tools. Claude Code, Cursor, or Codex can search and file findings and drive the whole backlog โ€” epics, stories, workflow โ€” each under its own policy.

MCP Guide โ†’

Connect Playwright in one config line

Point your reporter at the ingestion API; failures are turned into findings and deduped by signature:

// playwright.config.ts export default defineConfig({ reporter: [ ['list'], ['@omgqa/playwright-reporter', { baseUrl: 'https://api.omgiq.com', apiKey: process.env.OMGQA_API_KEY, // create under Account โ†’ API keys projectId: '<your-project-id>', }], ], });

The reporter fails soft (a misconfigured or unreachable OMG IQ never fails your test run), counts a test that passes on retry as passed (Playwright "flaky"), and reports each browser project separately. Under the hood it publishes the run to the ingestion API and failures are turned into deduplicated findings. The same works for Jest/Vitest, Cypress, pytest, and any JUnit-producing runner โ€” or do it from any CI system with plain HTTP; see the API Reference.

Evidence

Evidence (images, video, traces, HAR, logs) uploads directly to object storage via short-lived signed URLs โ€” the API never proxies file bytes. Images get a thumbnail and the attachment moves to Processed. Downloads use short-lived signed URLs too, so files stay private to your organization.

Analytics & dashboards

Every project has a role-aware analytics surface that turns raw runs and findings into release decisions. All views are bounded by a date window and can be pulled as JSON or downloaded as CSV for a spreadsheet or BI tool.

๐Ÿ“ˆ Suite health & throughput

Pass / fail / flaky trend and findings created-vs-resolved over time, bucketed by day or week.

๐Ÿ† Top-failing & top-flaky

Leaderboards rank the noisiest tests and the flakiest ones, each drilling straight into the linked finding.

๐Ÿ“Š Coverage trend

Ingest coverage from CI (Cobertura, lcov, or a simple percent) and watch the trend per commit and branch.

๐Ÿšฆ Release-readiness verdict

One rollup โ€” open criticals/highs, pass rate, flaky rate, coverage โ€” resolves to a go / no-go verdict for a release.

Flaky-test detection. OMG IQ tracks tests that both pass and fail without a code change, snapshots the flaky set, and surfaces it on the leaderboard โ€” so you can quarantine the noise instead of chasing it. Failures are also auto-categorized into a 7-category root-cause taxonomy (product bug, UI timing, environment, data/parallelism, flaky, suite config, unknown).

More you get out of the box

๐Ÿ”– Saved views

Save any combination of project, type, status, and search query as a named view. Views are personal by default and can be shared with the whole organization.

๐Ÿ”” Notifications & email

An in-app notification inbox plus transactional email (with a findings digest, delivery suppression, and SSRF-guarded outbound webhooks) keep the right people in the loop.

๐Ÿ”ฌ In-app trace viewer

Open a Playwright trace or HAR right inside a finding, and see every artifact and trace event laid out on one synchronized millisecond timeline โ€” no separate tooling.

๐Ÿ“ฆ Export & portability

Owners/admins can export the whole organization โ€” findings, evidence manifest, and history โ€” as a portable document, re-import it, and run a verifiable offboarding. No lock-in.

๐Ÿ‘ฅ Team invitations

Invite teammates by email with a role (owner, admin, QA lead, QA engineer, developer, viewer). The invite email signs them straight in โ€” type your name and you're in the workspace; from then on sign-in is a passwordless one-time code.

OMG IQ โ€” Capture Every Finding. Fix Faster.

Documentation ยท API Reference ยท MCP Guide ยท Home