Workflow¶
CLI VS Code Experimental
See also
The [workflow] table configures Pharaoh.
Added in version 0.31.0.
Every key, with its type and default: [workflow] and [agent].
The [workflow] section declares a project’s process model —
the ordered stages a requirement passes through,
the traceability each stage must satisfy,
and the lifecycle states a need may take.
It is consumed by the ubc agent workflow engine,
which evaluates the declared gates against your needs
and reports where the process is incomplete.
Caution
The [workflow] section drives the ubc agent engine,
which is an evolving feature.
The keys below are stable enough to author against
(they are validated by the schema and rejected on a typo),
but new keys may be added as the engine grows.
See also
This page is the key-by-key reference for [workflow]
and the sibling [agent.runner] table.
For the concepts, a quick start, the ubc agent command,
and the VS Code surfaces, see the
Pharaoh Agentic Engineer guide —
in particular its configuration walkthrough.
Unlike the other sections,
[workflow] is read only by ubc agent —
it does not affect ubc build or ubc check,
and it is not part of a project’s reproducible build hash.
It still inherits through extend and responds to -c overrides.
Across extend it inherits key by key:
a project that declares only [workflow.diagnostics] keeps the [[workflow.stages]] its base declares,
and a top-level key the project declares (stages, diagnostics, lifecycle, …)
replaces the base’s key of the same name entirely.
A -c override merges key by key inside each table
and keeps every key it does not name.
Every key is validated:
an unknown key, or an invalid value for one of the closed-set fields
(such as a stage route scope or a trace direction),
is a hard error rather than a silently-ignored setting.
Minimal example¶
[workflow]
exempt_status = ["deprecated"]
[[workflow.stages]]
id = "requirements"
produces = "requirement"
[workflow.stages.route]
scope = "stream"
granularity = "per-root"
path = "specs/{stream}/requirements.rst"
[[workflow.stages.trace]]
up = "user_story"
link = "implements"
Top-level options¶
- exempt_status
Type:
arrayofstring(default:[])Statuses whose needs are dropped before coverage is computed. A need in one of these states is ignored by the process gates, so a deprecated or descoped item does not count as an open gap.
- release_disallow_status
Type:
arrayofstring(default:[])Statuses that are forbidden at release time. A need left in one of these states blocks a release check.
- orphan_exempt_types
Type:
arrayofstring(default:[])Need types excluded from the orphan check only. A type listed here may exist without an incoming trace without being reported as orphaned.
Lifecycle¶
The [workflow.lifecycle] sub-table declares the legal status values
a need may take, in order, and (optionally) the legal transitions between them.
[workflow.lifecycle]
states = ["open", "in_progress", "done"]
transitions = [
{ from = "open", to = "in_progress" },
{ from = "in_progress", to = "done" },
]
- states
Type:
arrayofstring(default:[])The declared lifecycle states, in order. The first entry is the state a new need opens in. When non-empty, a need whose status is not one of these values is reported by the
status_undeclaredgate. An absent table, or an empty list, keeps that gate off.- transitions
Type:
arrayoftableorpair(default:[])The legal state transitions. Each entry may be written either as a table with
fromandtokeys, or as a positional two-element[from, to]pair, so you can use whichever form reads better. When present,ubc agent config-validatecross-checks everyfrom/toagainststates, and also checks thatstatesandtransitionsagree on which state is first. If exactly one declared state is never a transition target and it is notstates[0], that is a contradiction betweenstatesandtransitions(either the order is wrong, or a transition into that state is missing, and the check cannot tell which), andubc agent config-validateexits non-zero.ubc agent doctorreports the same finding as itsconfig-validitycheck, aterror. Nativeubc checkdoes not run this cross-check (see the note at the top of this page).[workflow.lifecycle] states = ["open", "done"] transitions = [ { from = "open", to = "done" }, # table form ["open", "done"], # positional form ]
Diagram gate¶
The [workflow.diagram] sub-table configures the diagram gate,
which validates diagram blocks in authored needs.
[workflow.diagram]
enabled = true
engine = "mermaid"
- enabled
Type:
boolean(default:truewhen the table is present)Whether the diagram gate is enabled. A present
[workflow.diagram]table is opt-in, soenableddefaults totrue; setenabled = falseto keep the table parsed but the gate off.- engine
Type:
string(default:"mermaid")Which diagram engine the gate validates against. One of:
mermaid— validate Mermaid blocks.plantuml— validate PlantUML blocks.both— validate both engines.
- format
Type:
string(default: none)The diagram syntax the agent should author any diagram as (for example
mermaidorplantuml). This is independent ofenabledandengine: it is an authoring hint, so a project can pin a diagram format for authoring even when the diagram gate itself is off.
Diagnostics gate¶
The [workflow.diagnostics] sub-table configures the diagnostics gate.
A diagnostic reported on a workflow need,
such as a duplicate id or an invalid field value,
holds the stage that produces the need until the finding is cleared.
[workflow.diagnostics]
severity = "warning"
schema_severity = "warning"
allow = ["needs.dead_link", "codelinks.*"]
deny = ["needs.dynamic_function"]
- severity
Type:
string(default:"warning")The lowest diagnostic severity that holds a stage. One of
none,info,warning, orerror. A finding at or above this level holds the stage of the need it is reported on; a lower one does not, andnonenever holds. This bar judges ordinary diagnostics by their own severity (info<warning<error).- schema_severity
Type:
string(default:"warning")The lowest schema-rule severity that holds a stage, for schema-definition findings only. One of
none,info,warning, orviolation, judged in the schema’s own words (info<warning<violation). It applies to theneeds.schema_definition_*codes. Schema-network findings have no bar (see below), and every other code is judged byseverity.- allow
Type:
arrayofstring(default:[])Diagnostic codes that never hold a stage, whatever their severity. An entry matches a code exactly, or with a trailing
.*a whole family, socodelinks.*covers everycodelinks.finding.allowbeats both severity bars.- deny
Type:
arrayofstring(default:[])Diagnostic codes that always hold a stage, even below
severityorschema_severity. The same matching asallow.
When both allow and deny match a code, the more specific entry wins:
an exact code beats a family.* entry,
and a longer family beats a shorter one.
Listing the same entry string in both lists is a config error,
which ubc agent config-validate reports.
Schema-network findings
(needs.schema_network_info, needs.schema_network_warning and needs.schema_network_violation)
hold a stage only when deny lists them; neither bar holds them.
A network rule judges the links between needs.
One that asks for an incoming link, such as an architecture element that a software requirement must refine,
can only be met by a need that a later stage authors.
The workflow’s trace gates already require those links, in stage order,
so holding the earlier stage on the rule would stall the loop on a fix that no edit to that stage can make.
A broken link the need itself carries still holds its stage through its own code, such as needs.dead_link.
To hold on network findings anyway, list their codes under deny,
for example deny = ["needs.schema_network_violation"].
List each code you want held:
only a trailing .* is a wildcard, so needs.schema_network_* would match no code.
Scope¶
A finding holds a stage only when it belongs to a workflow need:
it is reported on the need by id
(field, link and schema findings are, and needs.duplicate names the duplicated id;
this covers imported, test-report and external needs too),
or it sits inside the need’s source.
A workflow need is active (its status is not in exempt_status)
and has a type that a stage produces.
Findings in prose, in config, in a toctree,
or on a need of a type no stage produces are ignored by the gate.
The one exception is a finding that means a need failed to exist,
so it sits in no need:
a code marker that failed to parse (codelinks.*),
or a need directive whose build was aborted
(needs.build_error for a field or link value that cannot be converted,
needs.create_need for a required field without a value,
needs.type_resolution for a type that does not resolve).
It is held by the stage whose route path contains the finding’s file
(for example a src route holds a marker in src/module.py,
and a per-need specs/{stream}/reqs/{id}.rst route holds specs/login/reqs/REQ_1.rst),
with the longest matching route path winning.
The gate is on by default:
a project with a [workflow] section gets the defaults above
even without a [workflow.diagnostics] table.
Note
The gate reads the same diagnostics ubc check reports
after [lint] filtering.
A code ignored under [lint] is hidden from the gate entirely;
allow keeps a finding visible but stops it holding a stage.
These two are the only ways to accept a finding:
a ubc agent release-check baseline never accepts one,
so a finding fails the release until it is fixed, allowed or ignored.
Switching the gate off¶
The gate is on by default,
so any warning-or-worse finding on a workflow need holds its stage.
To switch it off for one run,
set both severity bars to none on the command line.
Nothing is committed, so no other ubc that reads the project sees it:
$ ubc agent release-check \
-c 'workflow.diagnostics.severity = "none"' \
-c 'workflow.diagnostics.schema_severity = "none"'
To switch it off for the project,
commit both bars as none and leave deny empty:
[workflow.diagnostics]
severity = "none"
schema_severity = "none"
deny = []
In a file that inherits from a base through extend,
this table switches off only the gate:
the project keeps the stages and every other [workflow] key the base declares.
It replaces the base’s [workflow.diagnostics] entirely,
so an allow or deny list the base declares does not carry over.
Warning
Commit a [workflow.diagnostics] table only once every ubc that reads the project knows it:
the CLI, your CI image and the VS Code extension.
ubc 0.37.0 and earlier do not know it and refuse the whole configuration,
so ubc check, ubc build and the language server stop working on the project.
Later versions refuse a [workflow] key they do not know only in their ubc agent commands.
Stages¶
Each [[workflow.stages]] entry is one step of the process,
in declaration order.
A stage produces a need type and declares the gates
that step must satisfy.
- id
Type:
string(required)The stage identifier, referenced by other stages’
depends_on.- produces
Type:
string(default: none)The need type this stage produces. A stage with no
producesis a code stage — it authors no need and is gated solely by itsrequire_codegate (which must then carry an explicittype).- depends_on
Type:
arrayofstring(default:[])The ids of stages this stage depends on. A stage whose dependencies are unmet is reported as blocked.
- author_skill
Type:
string(default: none)The name of the agent skill used to author this stage.
- review_skill
Type:
string(default: none)The name of the agent skill used to review this stage.
- authoring
Type:
string(default: none)A project-specific authoring directive for this stage (free text). It is injected into the agent’s authoring prompt, so process policy — for example “decompose into the full set of requirements” — lives in config rather than in the generic skill prose.
- optional
Type:
boolean(default:false)Whether this stage is informational-only, never a required blocking step in the dependency chain. An optional stage is never forced as blocked or as the next step; it surfaces only when the agent catches it during the process.
Stage route¶
The [workflow.stages.route] sub-table declares
where a stage’s needs are authored.
[workflow.stages.route]
scope = "stream"
granularity = "per-root"
path = "specs/{stream}/requirements.rst"
- scope
Type:
string(required)The authoring scope. One of:
stream— authored under a per-stream subtree.global— authored at one global location.
Scope also decides what an authoring run is briefed with. A
streamroute (or anypathstill carrying{stream}) is briefed with the active stream’s needs, aglobalone with the whole graph.- granularity
Type:
string(required)The authoring granularity. One of:
global— one authoring run for the whole graph.per-need— one authoring run per produced need.per-root— one authoring run per trace-chain root and its subtree.single— a single authoring run.
- path
Type:
string(required)The authoring path template. Supports the
{stream}and{id}placeholders.- group_field
Type:
string(default: none)An optional grouping field.
Stage code gate¶
The [workflow.stages.require_code] sub-table declares a
field-presence gate:
every need of the gated type must carry at least min
non-empty values in field.
[workflow.stages.require_code]
field = "code_url"
min = 1
- type
Type:
string(default: the stage’sproduces)The gated need type. For a need-producing stage it defaults to the produced type; for a code stage (a stage with no
produces) it must be set explicitly.- field
Type:
string(default:"code_url")The need field the gate ranges over.
- min
Type:
integer(default:1)The minimum number of non-empty values required in
field.
Note
The gated field (by default code_url) is populated by the
codelinks need-id reference mechanism —
an @need-ids: marker in source that back-attaches a URL onto the existing
need it names.
One-line need markers do not set this field; they materialise a new need
carrying a trace link instead. To gate coverage against one-line-materialised
impl / test needs — as the vmodel profile does — use a bidirectional
trace edge on the produced type rather than
require_code.
Stage trace edges¶
Each [[workflow.stages.trace]] entry declares a traceability edge:
the produced type must trace up to up via link.
[[workflow.stages.trace]]
up = "user_story"
link = "implements"
direction = "both"
min = 1
- up
Type:
string(required)The upstream need type the produced type traces up to.
- link
Type:
string(required)The link name the trace edge follows.
- direction
Type:
string(default:"both")The edge direction. One of:
both— bidirectional: the child must trace up vialinkto a need of theuptype, and everyupneed must be covered down by a need of the type the stage produces. A link whose far end is a need of some other type does not count toward either leg.incoming— the parent type must carry the incominglink. This direction builds no trace edge today, so it raises no trace gap of its own. The stage still declares atracegate and still owns orphan gaps on theuptype.outgoing— the produced child must carry the outgoinglink. This direction builds no trace edge today, so it raises no trace gap of its own. The stage still declares atracegate.
- min
Type:
integer(default:1)The minimum required link count. Under
both, only links whose far end carries the required type count toward it. Underincomingoroutgoingno trace gate counts it, so it is only the number the authoring prompt dictates to whoever writes the need.
Icons¶
The [workflow.icons] table maps a need type name to the icon
it renders with in the workflow view.
A type not listed here uses a default icon, chosen by matching its name against a
built-in alias table — for example an impl or implementation type renders with
the code icon (not a distinct one), and a config or configuration type with
the settings icon.
[workflow.icons]
requirement = "req"
architecture = "arch"
verification = "test"
The value must be one of the following presentation-neutral icon names.
The name is intentionally decoupled from your own type names, so you can — for
example — render a software_requirement type with the req icon.
The complete set, each shown with the icon it currently renders as:
Icon |
Name |
Depicts |
|---|---|---|
|
A user-facing feature, user story, or epic. |
|
|
A requirement (system, software, or component level). |
|
|
An architecture or design element. |
|
|
A source-code artefact. |
|
|
A test or verification case. |
|
|
A specification document. |
|
|
A risk or FMEA entry. |
|
|
A decision record. |
|
|
A task or work item. |
|
|
A functional safety requirement. |
|
|
A hazard or HARA entry. |
|
|
A safety goal. |
|
|
A release or milestone. |
|
|
A person, team, or role. |
|
|
An interface, API, or port. |
|
|
A component, module, or block. |
|
|
A settings or configuration element. |
Note
The glyphs are the VS Code codicons the workflow view currently maps each name to. The names are the stable configuration contract; the concrete glyph behind a name may be refined between releases.
Complete example¶
[workflow]
exempt_status = ["deprecated"]
release_disallow_status = ["open"]
orphan_exempt_types = ["release"]
[workflow.lifecycle]
states = ["open", "in_progress", "done"]
transitions = [
{ from = "open", to = "in_progress" },
{ from = "in_progress", to = "done" },
]
[workflow.icons]
requirement = "req"
architecture = "arch"
[[workflow.stages]]
id = "requirements"
produces = "requirement"
author_skill = "author-requirement"
[workflow.stages.route]
scope = "stream"
granularity = "per-root"
path = "specs/{stream}/requirements.rst"
[[workflow.stages.trace]]
up = "user_story"
link = "implements"
[[workflow.stages]]
id = "architecture"
produces = "architecture"
depends_on = ["requirements"]
[workflow.stages.route]
scope = "stream"
granularity = "per-root"
path = "specs/{stream}/architecture.rst"
[[workflow.stages.trace]]
up = "requirement"
link = "implements"
The [agent.runner] table¶
ubc agent run executes a workflow stage through a headless AI process,
configured by the [agent.runner] table —
a sibling of [workflow] in ubproject.toml:
[agent.runner]
command = "claude -p --permission-mode acceptEdits --output-format stream-json --verbose"
model = "sonnet"
timeout_secs = 600
- command
Type:
string(no default)The runner invocation. The assembled prompt (recommended skill + context briefing + resolved route) is passed on the process’s stdin. There is no built-in default and the shipped preset ships none, so with the key absent no runner is configured and
ubc agent runreports that rather than spawning a tool you did not name.ubc agent promptassembles the same prompt and prints it on stdout rather than spawning anything, so it reads no key of this table. It prefixes the printed text with a=== WORKING DIRECTORY ===header, since a reader of that text does not inherit the runner’s working directory. Either way, the commands the prompt writes out in full carry the project and the call’s discovery flags as far as each subcommand takes them (ubc agent updatetakes only-pand always looks forubproject.toml).- model
Type:
string(optional)A model to pin for the runner (for example
sonnetfor routine authoring).- timeout_secs
Type:
integer(default:600)The wall-clock budget for one authoring pass, in seconds. A runner that does not exit within the budget is killed;
0disables the bound.
Each key can be overridden per invocation with the UBC_AGENT_RUNNER,
UBC_AGENT_RUNNER_MODEL, and UBC_AGENT_RUNNER_TIMEOUT environment variables,
which take precedence over the table.
Note
[agent.runner] only affects the headless ubc agent run path.
Driving the loop interactively from your editor agent
(Copilot, Claude Code, Mistral Vibe, or another)
uses that agent directly and ignores this table.
Note
The [agent] table is strict,
so a key it does not declare
(under [agent.runner], [agent.forge] or [agent.reverse])
fails the ubc agent commands that read the table,
with the file and the line the key is on.
No other command reads it,
so such a key does not stop ubc build, ubc check or the language server.
[agent.forge] has its own reference section below,
beside [agent.reverse].
The [agent.forge] table¶
Added in version 0.37.0.
ubc agent reverse reads the git history of the code it recovers from, to report
the issues and pull requests that explain why that code exists.
Those live on your forge, the service that hosts the repository,
such as GitHub, GitLab or Bitbucket, which is what the table is named after.
The [agent.forge] table states the facts about your git remote
that the remote URL itself cannot carry,
and is a sibling of [agent.runner] above:
[agent.forge]
host = "git.example.com"
system = "gitlab"
jira_keys = ["DCA11Y"]
- host
Type:
string(optional)The host this declaration is about. Unset, it applies to whatever host the
originremote carries, which is the common case, since a project has oneorigin. Set, it applies only to that host, and a remote on any other host is classified by its host name alone. A port in the value is ignored when the hosts are compared.- system
Type:
string(optional)Which forge software that host runs:
github,gitlaborbitbucket. This is the one fact a URL cannot carry, because a self-managed GitLab on a corporate domain looks exactly like a Bitbucket Server one. Unset, the system is derived from the host name, which recognises the three cloud hosts and the conventionalgithub./gitlab./bitbucket.first label. A value that is none of the three names is ignored rather than fatal, so a project naming a system thisubcdoes not know still gets the host rule.- jira_keys
Type:
list[string](default: empty)The Jira project keys that may be read out of commit text, as an allowlist. Unset, the Jira pattern is never emitted at all, so no Jira reference ever reaches a recovery brief. It is an allowlist rather than a hint because the bare pattern matches any capitalised word followed by a hyphen and digits, so
UTF-8,BSD-3andSHA-256all read as issue keys on a repository that tracks no Jira project. Naming your own keys is what makes every extracted reference a real one. An extracted key reaches the recovery brief as a bare identifier (origin = "jira-key", no host) and is handed over unresolved by design. Nothing in[agent.forge]names a Jira instance, sincehostandsystemdescribe the git remote, and noissuesskill can be routed to Jira. A recovery run resolves a key only whenissuesis selected and an installed skill covers Jira. Otherwise the key stays an identifier: it is reported as unresolved, never looked up and never filled in from the surrounding commit.
Note
This table is read for DETECTION only. A named system means “a skill for this system is the one that applies here”, never that the host is reachable, that a credential exists, or that any tool is installed.
The [agent.reverse] table¶
Added in version 0.37.0.
ubc agent reverse reconstructs the decomposition arm of the V-model from an
existing codebase. The [agent.reverse] table configures what it may do to a
repository it did not author, and is a sibling of [agent.runner] above:
[agent.reverse]
code_stage = "implementation"
requirement_stage = "spec"
write_code_markers = false
- code_stage
Type:
string(default:"code")The id of the stage the reverse ladder climbs from, the stage whose route holds the code. Set it when your workflow’s code anchor is not called
code, soubc agent reverse sources/plan/statusclimb from the right stage without--code-stageon every invocation.- requirement_stage
Type:
string(default: none)The id of the stage recovery extracts requirements into. Set it only when that stage’s need type is not spelled
reqorrequirement. Without it, recovery takes the stage producingreqorrequirementabove the code stage, else the nearest need-producing stage above it, and says so in thenoteofubc agent reverse sources. An id that names no need-producing stage above the code stage is ignored, andubc agent reverse sourcesnames it in the samenote.- write_code_markers
Type:
bool(default:true)Whether recovery may write codelinks markers into your source files.
With it on, recovering the stage below your requirements writes one one-line marker into each file of each recovered module that its codelinks project parses (its
include,excludeandgitignoreapply). The marker goes at the top of the file, after any line the language needs first, such as a shebang (#!) or a Python encoding declaration. Those markers materialise the needs that link the code back up to the element recovered from it, which is what closes the gate below that element.A marker materialises only where a
.. src-trace::directive names its codelinks project in a built document. Recovery authors that directive into the document it writes when no document has one yet, and never a second one, since two directives for one project materialise every marker twice.The recovery skill proposes the file list and the ids before writing and waits for an answer. A run with no interactive user writes them and reports which files now carry one.
Set it to
falseand no brief carries a marker contract at all, so nothing is written into your source. The recovered elements are still authored, still recorded and still correct, and they carry no down-link to the code.
The three [agent] sub-tables inherit across extend one by one, so a project
that declares only [agent.runner] keeps a marker opt-out its base set, and a
project that declares only [agent.reverse] keeps the base’s runner.
A sub-table the project declares replaces the base’s sub-table of the same name entirely.
A -c override merges into [agent] key by key and keeps every key it does not name,
so -c 'agent.runner.command = "claude-next"' keeps the model and timeout_secs
the file declares.
It does not move where ubc agent reverse looks for source:
recovery reads its source roots ([codelinks.projects.*] src_dir)
and [source] extend_exclude from the files themselves,
so change those in ubproject.toml rather than with -c.