Coding agent workflows

Source code shows what an application is meant to do. BWorlds adds what has actually been observed around that code: current Audit results, production errors, user-session friction, uptime, prioritized Findings, and operator-maintained context. Give both to a coding agent so it can investigate the right problem and explain a change against real evidence.

Use --json when an agent consumes a command. Reads never ask for confirmation. Paid or sensitive changes require --confirm and should happen only after the user has authorized that specific action. This is a CLI safety check; the server separately authorizes and attributes the request. New to the vocabulary? Read the Product model first.

Start an investigation with Build context

Begin every agent session by resolving the identity and exact Build, then load the durable operational context:

bworlds auth status --json
bworlds build info storefront --json
bworlds dossier pull storefront --json
bworlds findings list storefront --json
bworlds audit show storefront --json

This gives the agent:

• the authenticated operator and Workspace that grant access;
• the Build and connected repository it is allowed to inspect;
• the Dossier's maintained context and guardrails;
• current Findings and their recommended next actions;
• the latest Audit's Control results, evidence, rationale, and remediation guidance.

dossier pull returns the path of the operator workspace it updated. Let the agent read the returned context.md and guardrails.md before proposing a change.

Investigate a production error

First retrieve grouped errors to identify frequency, recency, and source:

bworlds telemetry errors storefront --json

Then find recent sessions affected by an error and inspect one session in detail:

bworlds telemetry sessions storefront --time-range 24h --has-errors --json
bworlds telemetry sessions storefront SESSION_ID --json

The detail response provides the session timeline available to BWorlds, including visited pages, error events, console entries, and rage clicks. A coding agent can correlate those signals with routes and code paths, form a root-cause hypothesis, and identify the smallest useful reproduction before editing.

Understand user friction without a reported error

Users can struggle without triggering an exception. Start with sessions containing repeated clicks:

bworlds telemetry sessions storefront --time-range 7d --has-rage-clicks --json
bworlds telemetry sessions storefront SESSION_ID --json

Ask the agent to relate the clicked element and surrounding session events to the implementation. Treat the replay evidence as a clue, then verify the hypothesis in the code and tests.

Plan work from an Audit

Read the current Audit before starting a new one:

bworlds audit show storefront --json

Each entry of controls carries its current result, or null when the Control has none. A failed result can include whatWeFound, whyItMatters, howToFix, and supporting signals. Combine those fields with the repository and Dossier instead of turning a Control status directly into a code change.

Recheck one Control only after the relevant implementation or configuration has changed. control run checks any Control and waits for the verdict without changing the Audit. audit reevaluate records a new First Look result and waits for it. Both print the final ControlEvaluation and can consume Workspace tokens. After a timeout, control status reads the check without charging. A result with evidenceBasis: declared is the Builder's answer, not verified evidence:

bworlds control run storefront CONTROL_ID --confirm --json
bworlds audit reevaluate storefront CONTROL_ID --confirm --json
bworlds control status storefront EVALUATION_ID --json

Preserve the result for the next operator

When an investigation produces a durable issue, record it as a Finding with evidence and concrete remediation steps. When it discovers lasting context or a guardrail, update the Dossier. These writes require explicit authorization:

bworlds findings create storefront \
  --service-line run \
  --area operations \
  --severity high \
  --title "Checkout retries hide sustained failures" \
  --description "Payment requests repeatedly fail before the user sees an error." \
  --rationale "Customers can abandon checkout while the failure remains invisible." \
  --steps "Surface the terminal payment error" \
  --steps "Record retry exhaustion with the request identifier" \
  --confirm \
  --json

bworlds dossier push storefront --confirm --json

A reusable agent instruction

Give this instruction to a local coding agent after installing the portable BWorlds operator skill:

Use the bworlds CLI to inspect Build "storefront" before changing code.
Read Build info, Dossier, Findings, current Audit results, grouped errors, and
relevant sessions as JSON. Correlate that evidence with the repository, explain
the likely cause, and propose the smallest verified change. Do not start a paid
Audit or perform a mutation until I explicitly authorize that action.

See Authentication and tokens to create a personal token and Agents and automation for the JSON, exit code, and retry contracts.