[agent]

The [agent] process configuration consumed by ubc agent.

Only ubc agent reads and validates this table, so a key it does not know fails the ubc agent commands that read it and no other command. No path in it is resolved. Its three sub-tables inherit across extend one by one, so a child that declares [agent.runner] keeps the base’s [agent.forge] and [agent.reverse].

Guide: Configuring the workflow.

agent.forge
Type:
table

The [agent.forge] sub-table: the facts about the git remote that detection cannot read off the remote URL. Absent leaves detection to the remote’s own host and suppresses the Jira pattern entirely.

agent.forge.host
Type:
string

The host the declaration is about. Absent means “the origin remote’s own host”, which is the common case: a project has one origin.

agent.forge.jira_keys
Type:
array of strings
Default:
[]

Jira project keys that may be extracted from commit text. Empty (the default) suppresses the Jira pattern entirely.

agent.forge.system
Type:
string

Which forge system that host runs: github, gitlab or bitbucket. An unrecognised value is ignored rather than fatal, so a project naming a system this ubc does not know still gets detection from the host.

agent.reverse
Type:
table

The [agent.reverse] sub-table: what recovery may do to a repository it did not author. Absent is the same as the table’s own defaults, which means codelinks markers are written.

agent.reverse.code_stage
Type:
string

The id of the stage the reverse ladder climbs from, the stage whose route holds the code. Absent means code, the shipped preset’s code stage.

agent.reverse.requirement_stage
Type:
string

The id of the stage recovery extracts requirements into. Set it when that stage’s need type is not spelled req or requirement. Absent means the stage producing req or requirement above the code stage, else the nearest need-producing stage above it.

agent.reverse.write_code_markers
Type:
boolean
Default:
true

Whether recovery may write codelinks markers into your source files. Absent means true. With false, recovered architecture elements are still authored, but without the link down to the code.

agent.runner
Type:
table

The [agent.runner] sub-table: which AI runner ubc agent run spawns. Absent means no runner is configured, and ubc agent run reports that rather than spawning any default tool.

agent.runner.command
Type:
string

The runner command line, parsed quote-aware into an argv at spawn time. Absent (or empty) means no runner is configured, and ubc agent run reports that rather than spawning any default tool. Overridden by the UBC_AGENT_RUNNER environment variable.

agent.runner.model
Type:
string

The model passed to the runner. Absent leaves the runner’s own default. Overridden by the UBC_AGENT_RUNNER_MODEL environment variable.

agent.runner.timeout_secs
Type:
integer

The per-spawn wall-clock timeout in seconds. Absent leaves the built-in default of 600 seconds, and a wedged runner is killed once it elapses. Overridden by the UBC_AGENT_RUNNER_TIMEOUT environment variable.