Pharaoh Agentic Engineer¶
Added in version 0.31.0.
Caution
This is an experimental feature.
Pharaoh — ubCode’s agentic engineer — is under active development.
The concepts and configuration below are stable enough to try on a real project,
but the ubc agent command is still hidden from ubc --help,
its output shapes may change, and the VS Code surfaces are evolving.
Pin your ubc version and expect breaking changes between releases.
We would love your feedback.
Pharaoh is ubCode’s agentic engineer. You describe your engineering process once — the stages a requirement passes through, and the evidence each stage needs. From then on, AI does the writing and the engine does the judging: it computes what is done, what is missing, and what to do next — the same answer every time, on your laptop or in CI — and holds any step that has not passed an independent review.
The AI never grades its own homework, and nothing enters your history without your approval. And your requirements are not a list in a Markdown file: they are typed needs in your real reStructuredText or MyST documents, parsed 100% standards-compliant and re-validated by a millisecond-fast Rust engine as you type.
AI authors. The graph judges — AI speed, with audit-grade traceability.
What’s in the name?
Pharaoh is a nod to our lineage: ubCode mirrors Sphinx and Sphinx-Needs, and just as the pharaohs ruled the land the Great Sphinx keeps watch over, Pharaoh oversees and commands the needs your docs describe.
Every Sphinx needs a Pharaoh.
The mental model¶
If you have used make, you already have it: ubc agent next is make for your
requirements. It looks at what exists and names the single next thing to build. You
— or your AI assistant — build exactly that one step; the engine re-checks the graph and
names the next. Repeat until nothing is left.
flowchart LR
next["🎯 <b>1 · ask</b><br/>ubc agent next"]
author["🤖 <b>2 · author</b><br/>you or your AI build one step"]
check["🚦 <b>3 · confirm</b><br/>ubc agent gaps"]
done(["🏁 <b>done</b><br/>release-check"])
next --> author
author --> check
check -- "still gaps" --> next
check -- "all covered" --> done
Ask for the next step¶
Point the engine at the feature you are working on and ask what to do next:
$ ubc agent next --id US_LOGIN
It returns at most one stage — the first actionable step in your declared order — as JSON built for an agent to read:
{
"ok": true,
"stage": {
"id": "reqs",
"produces": "req",
"skill": "draft-requirement",
"review": "review-requirement",
"route": {
"scope": "stream",
"granularity": "per-root",
"path": "specs/{stream}/requirements.rst",
"feature": "login",
"id_prefix": "REQ_",
"resolved_path": "specs/login/requirements.rst"
},
"gates_to_pass": ["trace"],
"gate": {
"link": "traces_to",
"up_type": "user_story",
"min": 1,
"direction": "both"
},
"id_prefix": "REQ_",
"verdicts_dir": "/work/acme/.pharaoh/verdicts"
}
}
In plain words: the next step is to author req needs (ids prefixed REQ_) with
the draft-requirement skill, writing them to specs/login/requirements.rst — the
route resolved for this stream — and the gate still to satisfy is the trace
edge spelled out under gate: at least one traces_to link up to a user_story,
covered in both directions. verdicts_dir is where this stage’s review verdicts live;
when a review holds the stage, the payload also carries the review_needs to
re-review and their content fingerprints, so a reviewer needs no second lookup.
When there is nothing to do, stage is
null and a reason tells you why — empty (nothing authored yet), done
(this feature is complete), or blocked (a dependency is not ready).
The --id anchors the work on one need’s stream — that story plus everything
traced beneath it — which is the deterministic choice for scripts and agents. Drop it
and the engine infers the stream from your git working tree instead.
You rarely read this JSON yourself: it runs where you already work. Your AI assistant
polls next to drive the loop one stage at a time; a CodeLens on each requirement
shows its coverage and next action in VS Code; and because every gate is a command with
an honest exit code, the same checks run in CI.
Vocabulary¶
The engine is smaller than its glossary — six words cover the whole system:
- stage
One step of your process, declared as a
[[workflow.stages]]entry. A stage produces a need type (or gates code coverage) and depends on other stages.- gate
A per-stage rule that must pass — trace links present, code covered, lifecycle valid, review done. The
gates_to_passlist above names the ones still open.- gap
A specific unmet obligation, attributed to a stage — for example
REQ_42has no satisfying architecture. Gaps are what make a stage ready: there is work to do.- heartbeat
The one deterministic evaluation that resolves every stage’s state (
done/ready/blocked) from the graph. Every report and gate is a projection of it, so they can never disagree.- stream
One feature’s slice of the graph: an entry root (a user story, say) plus everything traced beneath it.
ubc agent nextdrives one stream at a time.- verdict
An independent review record for a need, stored in
.pharaoh/verdicts/— per-axis scores against a rubric, judged pass/fail at read time against the floors you set. A review-required stage is held — never reported done — until its needs carry a fresh, passing verdict. Reviews and quality analysis covers it.
Why it holds up¶
Deterministic, not vibes. Completeness is computed from your requirements graph — no LLM ever decides whether your process is done, so the answer is reproducible and auditable.
Your process, your ontology. The V-model is only the default profile; rename the types and links, or model a completely different process. Configuring the workflow shows how.
Brownfield-ready. Adopt it on a project you already have: accept today’s gaps as a baseline and gate only on the new ones.
Dive in¶
From zero — or from an existing project — to a driven loop in minutes.
The ontology, the stages, the routes, and the AI runner — explained.
The substance gate: AI-scored reviews, per-axis floors, and freshness.
Every verb of the engine, and the conventions behind them.
Panels, graph colouring, gap overlay, and CodeLenses.