AI agents, checked by the engine¶

AI authors. The graph judges.

Your requirements are typed needs in your own reStructuredText or MyST files, so an AI assistant can draft them while you review. Whether the work is complete is not the assistant’s call: ubc agent gaps computes it from the links your [workflow] declares, with the same answer on your laptop and in CI. A stage you mark for review stays held until each of its needs has a current review whose scores clear the floors you set: the model supplies the scores, the engine applies the floors. In VS Code, each file is checked as you type, and the whole project each time you save, which is also as you type with auto-save after a delay. The checks are formal: they prove that a link exists, a field is valid and a review is current, not that a requirement is right. That judgement stays with your reviewers.

        flowchart LR
    ai["AI assistant"] -- "writes needs" --> src["your .rst and .md files"]
    src --> eng["ubc engine"]
    eng -- "next step" --> ai
    rev["reviewer"] -- "scores" --> eng
    eng -- "diagnostics" --> ide["VS Code"]
    eng -- "exit code" --> ci["CI"]

Why each stage is checked¶

Each step an agent takes succeeds only with some probability, and over a change of many steps the probabilities multiply. As illustrative arithmetic, not a measured accuracy: at 92% per step, all 20 steps are right about 19% of the time, and all 50 about 1.5%. So Pharaoh’s loop does not wait for the end: it checks each stage before the next one starts. The drive-workflow skill, which the Pharaoh Agent panel and Claude Code use, and Copilot’s @workflow-author agent work one stage, run ubc agent gaps, then ubc agent next again, and stop; next holds a stage you mark for review until its review is current and passes. The headless ubc agent run rebuilds the project after its runner writes, and reports the next step and how many gaps the project has left. A trace link your [workflow] asks for and the stage left out shows up at that stage, not first at release; whether the content is right is still for your reviewers (see below).

What runs when¶

Every check below is deterministic: no model takes part in any of them.

When	What is checked
As you type, in each open file (VS Code and any LSP editor)	Syntax and markup, and a quick check of each need’s own field and link values against their schemas (types, patterns and formats are checked with the whole project).
When you open a file, and each time you save (`index_on_save` in the [server] settings, on by default), so also as you type when VS Code’s `files.autoSave` is `afterDelay`	The whole project: references and need links across files and the `schemas.json` rules (in the Diagnostics view), and, when the project declares a `[workflow]`, the workflow gaps (in the Problems panel). VS Code only: other editors show the per-file checks, and leave the project-wide ones to `ubc check` and the workflow gaps to `ubc agent gaps`.
`ubc check`	The whole project’s links, schemas and required fields, with a non-zero exit on findings. It does not read `[workflow]`, so it reports no workflow gaps.
`ubc agent gaps` and `release-check` (`trace` shows the trace links as a matrix)	The obligations your `[workflow]` declares: trace links in both directions, required links, orphans, code traces, lifecycle status, every `[NEEDS CLARIFICATION: …]` marker an agent left because it could not decide, and the needs still waiting for a review. `release-check --baseline` fails on gaps that are not in your baseline, and on baselined gaps that have got worse.
`ubc agent verdict-check` and `release-check --with-verdicts`	For a stage you mark for review: each need has a review verdict, neither the need, the needs it traces to, nor its rubric changed since, and every axis you set a floor for meets it.

Gate AI-written work runs the last two rows in CI.

What no check covers:

whether a requirement is right, or whether a test really verifies it;
whether the reviewer is independent of the author: the engine asks for it and cannot observe it, so score with a different model than the one that wrote the needs (Reviews and quality analysis);
the reviewing agent and model, which a verdict records but nothing gates on;
how accurate the scores are, which is unmeasured for any agent.

When an agent writes files outside VS Code, VS Code sees the changed .rst and .md files and re-indexes after the same debounce as a save, so its diagnostics lag a moment behind; the ubc agent commands read the files afresh on every run, so the command line is the authority.

Pick your setup¶

Three ways in, from most to least structured. They combine: an assistant driving Pharaoh’s loop in VS Code also gets the MCP tools.

Drive Pharaoh’s loop¶

CLI VS Code Experimental

Your assistant asks ubc agent next for the one next step, authors it, and the gates above decide whether it is done.

You need the ubc CLI and a [workflow]: ubc agent install writes the V-model profile, and ubc agent install --detect derives one from the needs you already have.
And an assistant that reads the installed skills (GitHub Copilot, Claude Code, Mistral Vibe, OpenCode or another), or an [agent.runner] for the headless ubc agent run.
Without a license, the ubc agent commands that read your needs work on up to 100 needs (What works without a license).

Start with the quick start; Pharaoh Agentic Engineer explains the model.

Give any assistant your graph over MCP¶

MCP Beta

The MCP server lets an assistant query your needs graph, search and resolve references, and read the product documentation. It does not run the ubc agent commands: an assistant drives Pharaoh’s loop through the command line and the installed skills.

In VS Code it is automatic: the extension registers the server for Copilot Chat, and the Pharaoh Agent panel hands it to every Claude Code, Mistral Vibe or OpenCode session it starts.
Claude Code in a terminal: ubc agent install --register-mcp claude-code-cli registers the server for the project (Setup and health), and ubc agent doctor checks the registration.
Without a license, only the two documentation tools answer (The MCP server).

Setting it up for other assistants is not covered here yet. The MCP tools reference lists every tool.

Ask `@pharaoh` in Copilot Chat¶

VS Code Experimental

@pharaoh answers questions about Sphinx-Needs and ubCode from their documentation, and @pharaoh /pharaoh-intent captures a feature’s intent as the root needs your [workflow] defines.

You need VS Code with GitHub Copilot Chat.

See Chat participant.

What it writes and what it sends¶

What it writes. ubc agent install writes a ubproject.toml with the [workflow] and its need types when the project has none (--detect adds a derived [workflow] to the one you have), the skills under .claude/, .agents/ and .github/agents/, the review rubrics under quality/, and a record of what it wrote under .pharaoh/, where review verdicts are kept too. Commit all of it, .pharaoh/ included. The quick start lists every file and skill.

What it sends. ubc itself never calls a language model. The model that writes and scores is the one you run: your assistant, the runner ubc agent run starts, the agent in the Pharaoh Agent panel, or the model Run Quality Analysis scores with (by default the agent you drive with, or VS Code’s own language model when that agent runs outside the editor; Copilot out of the box; ubcode.qualityAnalysis.agentId picks another), which receives the needs it scores and the needs they link to. The documentation tools fetch public documentation pages and send no project data. Network use and data lists every network request ubCode makes.