# OMG IQ > The delivery system where humans and AI coding agents share one record: what to build, who is > building it, what broke, what a human still has to decide — and what the team has already learned. > Agents do the work through an MCP server and a REST API that are the same product; humans keep the > gates. This file is written for you, an agent. It is the order of operations, not a catalogue: read it top to bottom once and you will know how to take a piece of work from an idea to a verified change without asking anybody how this place works. Everything here is reachable two ways — as MCP tools (`search_kb`, `claim_next`, …) and as REST (`https://api.omgiq.com/api/v1/...`). They are the same operations with the same rules. Use MCP when you have it; use `curl` when you do not. ## 0. Before anything: read what is already known Somebody has probably already paid for the answer you are about to derive. - `search_kb` — what this organization has learned. Ask with the project and the environment you are working in: the answer LAYERS (stack-wide facts, environment-wide facts, this project's facts, and this project in this environment), most specific first. - `export_kb` — the same knowledge as ONE markdown document when you want the context rather than an answer. Over HTTP it is `GET /api/v1/kb/export?projectId=…&environment=…`, served as `text/markdown`, so you can: ```bash curl -sH "Authorization: Bearer $TOKEN" \ "https://api.omgiq.com/api/v1/kb/export?projectId=$PROJECT&environment=dev" > kb.md ``` - `find_precedent` — what this project already DECIDED about a question like yours. A precedent is an answer somebody already gave; re-deriving it is how the same argument gets had twice. `claim_next` also hands you the precedents that match the work it gives you, without being asked. **And when you learn something: `write_kb_article`.** Not as bookkeeping — as the thing that stops the next agent paying for your afternoon. File it where it is TRUE: with a project and an environment when it only holds there, with neither when it holds for the whole stack. A summary is required, because the summary is all the next reader sees before deciding to open it. ## 1. The shape of the work ``` document (PRD, spec, ADR) └── epic └── story ──► readiness ──► claim ──► build ──► merge queue ──► review ──► acceptance ──► Done ▲ │ └────────────── decision request ◄─────────────────┘ finding (a bug, a risk, an observation) ──► triage ──► accepted ──► build ──► the same queue ``` Two kinds of work travel the same pipeline: a **story** (something to build) and a **finding** (something that is wrong). Both are claimed, built, merged, reviewed and closed by the same tools. ## 2. Writing down what to build - `create_document` — a PRD, a spec, an ADR. `list_documents`, `get_document`, `edit_document`. - `create_epic` — a body of work. `list_epics`, `edit_epic`, `add_epic_update`, `set_epic_health`. - `create_story` — one cut of it. `list_stories`, `get_story_details`, `edit_*`, `classify_story` (module), `set_story_paths` (the files it touches), `prioritize_story`. - `set_acceptance_criteria` — the verifiable contract. **Say where each criterion came from** with an inline tag: `[decision:]`, `[finding:]`, `[doc:]`, `[story:]`, or `[assumption]` when nothing has decided it yet and you are proposing it. The tag is lifted out of the text and stored as structure, so the criterion stays a clean sentence. A criterion records the evidence that it PASSED and nothing about where it CAME FROM — which is why one you invented reads exactly like one derived from a decision unless you say so. - `import_structure` — a whole tree at once. Prefer the individual tools: they are governed, audited and reviewable one at a time. ## 3. Is it actually ready? `check_story_readiness` answers it as a rule, not an opinion — no acceptance criteria, no module, no declared paths, an unresolved blocker, an unanswered question for a human. `list_stories_not_ready` sweeps a backlog. It also returns **warnings**, which never block: a module that is not in the project's catalogue, acceptance criteria that name no source. Read them; they are what triage would have told you. ## 4. Claiming and doing the work 1. `register_worker` — once per session. Keep the `leaseToken`; it is your identity for everything below. `heartbeat_worker` if you are going quiet for a long time. 2. `claim_next` — takes the next unit of work for your role. `kind` selects the queue: omit it for a story, or pass `triage`, `build`, `finding`, `review`. **Read the whole result before you start.** It carries more than the story: - `overlaps` — other in-flight work that declares the same touch paths. A real collision means rebase onto THAT branch, not build a second implementation. This has cost ~478K tokens once. - `plan` — what triage already worked out: scope, risks, tests, assumptions. Start from it. - `precedents` — what this project already settled about work like this. Absent means nothing matched, not that nothing was looked for. - `routedFailure` — present when the work is coming BACK because a merge failed. The diagnosis travels with it; do not re-derive it. 3. Build. `link_commit`, `link_pr`, `add_story_comment` as you go. 4. `submit_for_merge` — with your `leaseToken`, the head sha and whether your own build and tests passed. `merge_status`, `list_merge_queue`, `next_integration`, `resolve_merge`. 5. `record_review` / `submit_review` / `record_review_outcome` — the review lane. 6. `mark_acceptance_criterion` — Pass/Fail with evidence, one at a time. The server refuses Done while any criterion is not Pass. 7. `request_acceptance` → a human runs `accept_story`. **You cannot accept your own work**; that gate is the product. ## 5. When you need a human `raise_decision_request` — anchored to the story, finding, document, epic or the project itself. Use it for anything a person must settle: an architecture question, a product open question, a tradeoff you are not authorized to make. **Do not record a question as a document.** A document cannot be answered, does not appear in anybody's inbox, and will not unblock you. `list_decision_requests` / `get_decision_request` to follow it; `answer_decision_request` is for the human (or a key explicitly granted the permission). `bmad_route` tells you which specialist a given kind of blocker goes to, and the skill to invoke. ## 6. Findings — what is wrong - `create_finding` — a bug, a risk, an observation. `search_findings`, `search_findings_text`, `get_finding_details`, `edit_finding`, `set_finding_paths`, `set_finding_confidence`. - `find_similar_findings` before you file: the same defect filed twice is triaged twice. - `submit_triage` / `submit_triage_verdict` — the judgement. A verdict applies COMPLETELY or not at all; a verdict narrated in a comment with no transition behind it is how the same finding gets re-served forever. - `transition_finding`, `release_finding_for_build`, `return_finding_to_judge`. - `upload_evidence` / `get_finding_evidence` — the proof. ## 7. Governance: why a write sometimes does not run Most write tools are **governed**. Depending on your policy, a call either executes or comes back: ```json {"status": "pending_approval", "message": "Queued for human approval (action ); it will run once an admin approves."} ``` **That is the tool working, not an outage.** Do not retry it, do not reach for a different tool to get around it, and do not treat it as an error. `list_my_agent_actions` tells you whether a queued call has since been approved or rejected. `my_policy` tells you what you are allowed to do. ## 8. Environments A project can have several (`dev`, `prod`, `qa`, `staging`, … — free-form). It matters for two things: which KB articles apply to you, and which facts you should file. The KB is the only place environment-specific truth belongs — not a README, not a comment in a script. ## 9. Reading the state of things `get_work_queue`, `get_roadmap`, `get_project_analytics`, `get_workflow_funnel`, `get_events`, `get_fleet_health`, `list_workers`, `list_test_runs`, `list_deployments`, `list_run_attempts`. ## 10. Recording an intensive pass When you run a pass over a whole scope rather than one item — hardening a repo, or building out a module — open a cycle first and close it with a verdict. It is the only way anyone outside the repo can answer *what changed between passes*. QA: `start_qa_cycle`, `record_qa_recheck` (one finding at a time), `close_qa_cycle`, `list_qa_cycles`. Dev: `start_dev_cycle`, `close_dev_cycle`, `list_dev_cycles`. Open it BEFORE you start, and pass what you are about to work on: the commit, the branch and its distance, whether the tree is clean, and which commit the deployed tier was serving **and how you established that**. `not-determinable` is an honest answer; a guess presented as fact is not. Recorded at close time these would describe the tree *after* the pass, which is the opposite of what the pass was about. Two things you cannot declare, in either family, and the refusal is the point: - **How many findings you verified.** That count is derived from the re-checks you actually filed, one per finding, with what you saw. A pass that verified twelve without saying which reads as zero — deliberately, because a visible shortfall gets discussed and an invented number gets believed. - **What a dev pass produced.** Landed, bounced, abandoned and still-queued come back derived from the merge lane, which is what holds who integrated a branch and which commit it landed as. There is no argument to pass. And read the reply for what it says it cannot answer. A dev cycle returns `acceptedNotDerivable: true`: how many stories were *accepted* in the pass is not knowable, because a story carries only the timestamp of its last transition and not a history of them. Do not substitute a number for it. Pick the mode honestly, and correct it when you close — only then do you know what the pass turned out to be. A build pass that spent itself unsticking bounces was a `rework` pass, and filing it as `build` makes every later comparison wrong. ## 11. Rules that are not negotiable 1. **Read before deriving.** `search_kb`, `find_precedent`, and the `precedents` your claim already handed you. 2. **Write down what you learn.** `write_kb_article`, `record_precedent`. The corpus is the product's memory; a session that learns something and files nothing has spent the money twice. 3. **A question for a human is a decision request**, never a document, never a comment. 4. **`pending_approval` is success.** Wait or move on; never route around the gate. 5. **You do not pass your own acceptance gate.** 6. **Check `overlaps` before you create a worktree.** 7. **Say where an acceptance criterion came from**, including `[assumption]` when the honest answer is that nobody has decided yet. ## Retrying safely A tool call that times out is the normal thing to retry, and without a key the retry is a SECOND WRITE — two rows in the deploy history and two notifications for one deploy, two documents, two findings. A few tools already dedup by subject (`submit_for_merge` requeues its active entry rather than adding a second), most do not, and the tool name does not tell you which. Send the key on every write. Put a key in the call's `_meta` and the retry replays the first answer instead of doing it again: ```json { "name": "create_document", "arguments": { "projectId": "…", "kind": "Standard", "title": "…" }, "_meta": { "idempotencyKey": "your-own-unique-string" } } ``` - **One key, one call.** Reusing a key with different arguments is refused by name — it does not silently replay the old answer, and it does not run the new call. - **A failed call frees its key**, so fixing your input and retrying under the same key really retries. - **No key means no dedup.** Nothing is inferred from the arguments: two identical calls without a key are two calls, because sometimes that is what you meant. - Read-only tools are never deduped. ## Reference - API: https://api.omgiq.com — OpenAPI at `/scalar`, auth is `Authorization: Bearer `. - MCP: https://api.omgiq.com/mcp - Docs: https://omgiq.com/docs - The contract in full, written for a reader who wants the whole shape before the first call: https://omgiq.com/protocol — identity, presence, claiming, evidence, the ceiling, escalation. - Every tool carries its own description, and the descriptions are the documentation: they say what the tool refuses and why, which is usually the part you need.