In VS Code¶

The ubCode extension surfaces the whole Pharaoh loop without leaving the editor: two dedicated Pharaoh panels in the sidebar, workflow colouring and a gap overlay on the needs graph, and CodeLenses on every need. This page tours those surfaces.

Caution

The VS Code surfaces are the newest and most in-flux part of the feature. Panels, labels, and controls are still changing from release to release — treat the names below as a guide rather than a contract.

UI elements¶

The Pharaoh Workflows panel¶

In the ubCode activity-bar container, the Pharaoh Workflows panel is a vertical lineage graph of the need you are focused on: its ancestors above, the focused need in the middle, its descendants below. Each row is a need (not a stage), annotated with the workflow stage it belongs to and that stage’s state.

A row shows:

a type icon, chosen per need type (and overridable with [workflow.icons]);
the need id and title;
a state badge — ✓ done, ready, blocked, ▶ NEXT (the recommended next step), ⏳ awaiting review, or ⚠ stuck · <reason>;
a gap chip naming what the need is missing (for example ⚠ no test).

When the recommended next step is a need that does not exist yet, a ghost row with a to create badge marks where it will go.

Its controls:

Depth: A directional selector — ↑ Parents · N and ↓ Children · N — with − / + to show fewer or more levels in the active direction and Max for the full lineage. The depth is sticky as you move focus.
Expand / collapse gutter: When a lineage has more parallel rails than fit, a toggle switches between Graph clipped to fit and a scrollable expanded view.
Capture intent / Tailor workflow: Buttons for the same-named commands (see Commands).
Search and back: A Search a need to focus… box, and a ← Active work button that returns the panel to the git-derived list of what you are working on right now.
Per-row Drive (▶): Runs the next step for that need.
Title bar: Refresh re-indexes and redraws; Help toggles an in-panel help sheet.

When nothing is focused, the panel shows Active work — the stream derived from your uncommitted changes (ubc agent next with no anchor).

The Pharaoh Gaps Overview panel¶

Its sibling, the Pharaoh Gaps Overview panel, is a project-wide census — never scoped to the focused need. A header reads <N> needs · <M> gaps, and a By need / By type toggle switches between one row per gapped need (with a chip for each missing artefact) and one section per missing type (Missing test, and so on).

On a fresh project it doubles as an on-ramp: it offers Set up project (ubc agent install) when there is no configuration, and Capture intent / Tailor workflow when there are no needs yet.

The needs graph¶

The needs graph view gains workflow awareness: nodes are coloured by need type, the trace links between them are drawn as labelled edges, and a need still missing a required link carries a red marker naming that link.

Click any node to make it the focus, which also updates the Pharaoh panels.

The workflow editor and flow views¶

Two more webviews visualise the process itself:

Open Workflow Editor draws your [workflow] as a V of stages — each a node coloured by the type it produces, edges labelled leads_to, optional stages dashed and tagged [optional]. Selecting a stage shows its Produces type, its Authoring directive, its hard-gate and soft-review chips, and where it lives in ubproject.toml.
Open Flow shows the V-model stream for the currently focused need.

The workflow editor drawing the configured stages as a V, with one stage selected — The workflow editor: your `[workflow]` drawn as a V of stages, with the selected stage’s details.¶

Quality analysis (Run QA)¶

The review and quality gate has an in-editor front end. Run Quality Analysis (the ubcode.need.runQA command — command palette, the editor right-click menu, or Ctrl+Alt+Q / Cmd+Alt+Q — with a need under the cursor) scores that need against its criteria pack using the editor’s own language model. ubCode never calls a model provider itself; the first run asks which model to use, and you can pin it with the ubcode.qualityAnalysis.llmselection setting.

The result opens in the ubCode Quality Analysis panel (the Show Quality Analysis Results command, ubcode.need.qaResults): one row per axis with its score, the reviewer’s reason and suggestion, any floor breach highlighted, and a freshness banner when the verdict no longer matches the need or its rubric. Inline, a QA CodeLens shows a reviewed need’s verdict state and score at a glance.

Both surfaces refresh live: a verdict is just a file under .pharaoh/verdicts/, so a verdict written out of band — by the drive loop, or by ubc agent verdict-submit on the command line — updates the panel and the lenses automatically.

The ubCode Quality Analysis panel showing per-axis scores with reasons and suggestions, one axis below its required floor and failing the gate — The **ubCode Quality Analysis** panel: per-axis scores with the reviewer’s reasons and suggestions, and a below-floor axis highlighted as failing the gate.¶

Commands¶

All of the following live under the ubCode category in the command palette (Ctrl+Shift+P):

Focus Need in Pharaoh Panel: Reveal the Pharaoh Workflows panel and focus the selected need. (Also reachable from the Focus CodeLens, and — from a need in an RST file — via the editor right-click entry Show ubcode need ID in the Pharaoh panel.)
Drive Next Step: Hand the focused need’s next step to your AI assistant. It prefills the prompt; you press Enter — nothing runs automatically.
Change Request: Prefill your assistant with a change-request prompt to propagate an edit downstream through the V (the change-request cascade).
Accept Authored Artefacts: Stage and commit the artefacts the assistant authored, with an attribution message.
Capture intent (/pharaoh-intent): Open Copilot Chat prefilled with @pharaoh /pharaoh-intent to capture a high-level intent as the root artefacts your workflow defines.
Tailor workflow: Derive a proposed [workflow] from the project’s need types and links, preview the TOML, and write it into ubproject.toml (with an option to refine it in chat).
Install agent skills: Run ubc agent install in a terminal to scaffold the profile’s skills into the project.
Run Quality Analysis / Show Quality Analysis Results: Score the need under the cursor against its criteria pack (using the editor’s model), and open the results panel. See Quality analysis (Run QA).
ubCode: Open Flow / ubCode: Open Workflow Editor: Open the two process webviews described above.

Settings¶

These settings tune how the agent commands behave:

ubcode.agent.id: Which assistant Drive Next Step and Change Request dispatch to — copilot (default) prefills Copilot Chat; claude-code opens a terminal with the claude CLI pre-typed.
ubcode.agent.cliPath: The path to the ubc binary the need-level agent commands invoke (default ubc).
ubcode.qualityAnalysis.llmselection: The Copilot model Run QA uses to score needs. Leave empty to be prompted on first use.

Gap diagnostics¶

Gaps also appear in the Problems panel, and as squiggles on the need’s directive line: a warning <id>: gap in <category> for a structural gap, and an information <id>: needs clarification for a clarification marker. The gap CodeLens jumps straight here.

CodeLens elements¶

On needs in .rst and Markdown files, ubCode renders a row of CodeLenses just above the directive — which lenses appear depends on the need. Each is one click:

Focus: Focus this need in the Pharaoh panel (the same action as the Focus Need command). Shown on every workflow-scope need — any need whose type the [workflow] covers (a type a stage produces, or the up target of a stage’s trace edge) — so you can jump into the lineage from a req or arch in the middle of the chain, not just from a feature root. A need whose type the workflow never references (a plain note, say) gets no Focus lens; the Focus Need command still works for any need.
Parents: Shown as N parent(s); jumps to the parent need’s source (a picker when there is more than one, and the parent’s id in the hover tooltip when there is exactly one).
Children: The mirror of Parents — shown as N child(ren), jumping down to a child need.
Code trace: Shown as N impl · M tests; opens the source file(s) the need’s codelinks point to. Omitted when the need links to no code.
Gap: Shown only when the need has a gap — the reason(s), such as no test, no impl, or clarify for a clarification marker. Clicking it opens the Problems panel.
QA: Shown on a reviewed need with its verdict state and score. Clicking it opens the ubCode Quality Analysis panel for the need. See Quality analysis (Run QA).

A need directive in the editor with its CodeLens row above it — The CodeLens row above a need: navigation and gaps, one click away.¶

Note

The CodeLens row is on by default. Disable it project-wide with the code_lenses key in the [server] section of ubproject.toml (see server configuration) to remove the lens line above every need.