How Mazora works

Why this exists

Coding agents have no memory of your product. Every session starts from nothing, so you re-explain the same things — who the users are, which rules must hold, what the flows do. When you leave something out, the agent does not stop and ask. It fills the gap with something plausible, and plausible is the problem: the code looks right and quietly contradicts a rule you never thought to mention.

Pasting a long prompt helps for one session. It is not reviewed, not versioned, and nobody notices when it stops matching the product. Mazora makes that description a thing you keep: written once, corrected as you go, and handed to the agent the same way every time.

The loop

There is one path through Mazora, not a choice of modes:

create a project
  ↓
describe the product        ← you can scan your repo to fill some of this in
  ↓
deliver work in Guardrails  ← each ticket reviewed stage by stage
  ↓
hand the agent a compiled brief
  ↓
keep the context true       ← Mazora tells you when a ticket outgrew it

You spend a little time at the top of that loop and most of your time at the bottom of it. The context is not a document you write and abandon — it is the thing every ticket is checked against.

1. Create a project

A name and a one-line description. One project per codebase — the context describes a product, so two products mean two projects.

2. Describe the product

Five sections, each answering a question an agent will otherwise guess at:

• MVP Basics — what it is, who it is for, what problem it solves, and what success looks like. Everything else is read in this light.
• Tech Stack — language, framework, data layer, and the libraries that matter. First, because it decides which files are worth reading later.
• Actors — who and what interacts with the product. People, roles, and external systems. The distinctions matter most: what a provider can see that a customer cannot.
• Policies — the rules that must keep holding. "Refunds return to the original payment method." "Only owners can invite teammates." These are what an agent breaks when it has not been told.
• Workflows — journeys in prose: what starts them, what happens, how they end, and what happens when they fail.

Write plainly. This is read by a model and by you, not parsed by a schema — full sentences work better than bullet fragments.

3. Connect your repository

Optional, and it saves the most typing. On the Tech Stack section, install the Mazora GitHub App. You choose which repositories it can see, and GitHub brings you back with the connection recorded.

Mazora never clones your repository. It reads the file listing over GitHub's API, and then only specific files — see what gets sent below.

4. Scan it

Tech Stack is read from your dependency manifests — package.json, *.csproj, go.mod and similar. Which technologies you use is worked out by matching against a fixed list, with no AI involved; turning that into readable prose is done by a model.

Actors, Policies and Workflows are read from your source. Mazora picks files by name — controllers, routes, services, validators — and you can see exactly which files it would read before running anything.

A scan never overwrites text you wrote. If you have edited a section, the scan result is offered beside your version and you choose. That rule holds for rescans too: if the repository has not changed since the last scan, Mazora says so instead of regenerating an answer it already has.

5. Deliver with Guardrails

Guardrails is where you spend your time once the context exists. You describe a piece of work in one input, and it is drafted in three stages:

• Product — user story, business goal, acceptance criteria, business rules.
• QA — test scenarios, happy path, failure paths, edge cases. Drafted adversarially against your approved acceptance criteria, hunting for what they did not say. Where something has no defined behaviour, it raises an open question rather than inventing an answer.
• Developer — technical notes, affected areas, known risks.

Each stage lands unapproved. You read it, edit it, and approve it — and only then does the next stage unlock. Content existing is never enough; approval is a decision you make.

A final pass runs with no model involved, flagging anything one stage introduced that the others never mention. It is the cheapest way to catch a developer note that quietly assumes a rule nobody wrote down.

6. Hand off to the agent

Once all three stages are approved, Mazora compiles a single handoff document: what to build, what must be true, what to test, and where the boundaries are. It is assembled from a template, not generated — the same inputs always produce the same document.

Edit an approved section afterwards and the handoff keeps serving the last approved version until you approve again. You are never handed a brief that has quietly changed underneath a review.

7. Keep the context true

This is the step that makes the rest hold. Every ticket that names a role, a rule, or a journey your context never mentioned makes the context slightly less true — and the context is what briefs your agent. Left alone it rots quietly, which is worse than being obviously empty, because you keep trusting it.

So Mazora checks. When you open a work item, it compares what the ticket says about the product against what your four context sections describe, and tells you what is missing: the term, how often the ticket used it, the sentence it came from, and which section should record it. That check is deterministic — no AI, no repository read, no cost — so it runs every time.

You have three options on each one. Dismiss it, and it never comes back for that project. Go write the section yourself. Or ask Mazora to suggest how that section should read with the new fact folded in — that part uses a model, and only when you click. The suggestion arrives as editable text beside what the section says now, and Mazora flags anything you had written that the suggestion no longer says. Nothing is saved until you accept it.

It only reads the product side of a ticket — the title and the POPM section. Test scenarios and technical notes deliberately do not count, because they name test fixtures and database tables, and flagging those as missing product facts on every ticket would make the whole thing noise you learn to ignore.

Connect your agent directly

Instead of copying documents around, your agent can read Mazora itself. Mazora runs an MCP server with nine read-only tools covering projects, work items, readiness, and the compiled handoff.

Create a token under Agent access, then point your MCP client at it:

{
  "mcpServers": {
    "mazora": {
      "url": "https://your-mazora-mcp-url",
      "headers": { "Authorization": "Bearer mzr_your-token" }
    }
  }
}

Tokens do not expire by default, which is the point — you paste it once. They are stored hashed, shown to you exactly once, and can be revoked at any time, which takes effect on the agent's very next call. The tools are read-only: an agent can read your context, and cannot change it.

What Mazora sends to OpenAI

Four things use a model, and each only runs when you ask for it:

• Generating a report — your product basics, the four context sections, and your work items.
• Drafting a work item — the description you wrote and the relevant approved sections.
• Summarising a scan — for the tech stack, your repository name and the technologies detected from your manifests. For the other sections, excerpts of the source files that were selected.
• Suggesting context wording — the term a work item introduced, the sentences it appeared in, and the current text of the section it belongs in. Finding the gap is deterministic and free; only the suggested wording uses a model, and only when you click to ask for it.

Your manifest file contents are never sent, and neither is any file outside the selection. Mazora does not send your account email, payment details, or GitHub credentials. The Privacy Policy has the full description, including the limits on how much is read.

What it does not do

• Scanning is a guess. Detection matches file names and dependency lists. It can read the wrong files and miss the ones that matter. Treat a scan as a first draft to correct.
• A scan describes a sample, not your repository. It reads a selection, so "the code does not appear to do X" is a statement about the files it read.
• AI output is never final. Every draft lands unapproved, and nothing auto-approves. That is deliberate: the review is the product, not an obstacle in front of it.
• Mazora does not write code and does not connect to your agent's editor. It produces the context your agent works from.

Getting started

Create a project, fill in the basics, connect your repository, and scan. From there you are in Guardrails, and the context comes with you.

Start free