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. Audit runs, Autofix, and sensitive changes require --confirm. Targeted checks (findings verify, control run, and audit reevaluate) display pricing and start without it. When a user has requested the fix or verification, perform its scoped recheck without asking for the same authorization again. 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 --status open --json
bworlds audit 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;
• the Findings still open, and their recommended next actions;
• which Audits the Build carries and which have ever run;
• the latest Audit's Control results, evidence, rationale, and remediation guidance.

Every result carries an appUrl that opens the same object in the app, so the agent can cite a Finding or a Session by link when it reports back.

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. The result opens with the SDK's heartbeat, and no_data there means nothing was measured, so read it before the groups:

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

A session detail is a summary: identity, visited pages, captured requests, detected signals, and the recorded errors and console lines. A coding agent can correlate those with routes and code paths, form a root-cause hypothesis, and identify the smallest useful reproduction before editing.

Add --failed-only to keep only the requests that failed. Add --depth full for the whole server record, including every recorded interaction and the signed replay media links. The full record is large; read it when the summary is missing what you need, not by default.

The email address of the Builder's end user is withheld from every telemetry result. An identified session reports "userEmailWithheld": true in its place. --include-personal-data returns the address, so use it only when you need to reach that person, never when the result feeds an agent.

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 Audits the Build carries, then the one you plan against:

bworlds audit list storefront --json
bworlds audit show storefront security --json

audit list names every Audit's slug and whether it is available, planned, or archived. audit show defaults to First Look; pass a slug for any other Audit. audit runs gives one Audit's recorded runs when you need to know what changed since the last one.

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 only after the relevant implementation or configuration has changed. When you are working from a Finding, name the Finding and nothing else. BWorlds reads its Audit origin and checks its Control or its recorded exploratory claim.

bworlds findings show storefront FINDING_ID --json
bworlds findings prompt storefront FINDING_ID
bworlds findings verify storefront FINDING_ID --json

A Control recheck returns a ControlEvaluation. A pass resolves the Finding and turns that Audit's Control result; a failure records the new evidence while the Finding stays open. An exploration recheck returns purpose: verify_discovery and a verificationStatus: resolved closes the Finding, confirmed means the problem remains, and inconclusive or error gives no verified fix and exits non-zero. It changes no Control result. Do not close an Audit Finding by hand after a refused or inconclusive recheck; restore the required evidence first.

Fix in your own checkout

You were invited into the Builder's Workspace, so you hold the code and your own GitHub access. Fix there. The CLI supplies the evidence and the verdict; your Git carries the change.

Confirm you are in the right repository first. bworlds build info storefront prints GitHub: connected to <owner>/<repo>, and a Builder can connect one their app does not ship from, so compare it with your checkout's origin. Then branch off the branch the Build ships from, take the fix prompt from findings prompt, let your agent write the change, run the repository's own checks, and open a pull request the way the Builder's team works.

A recheck reads the connected repository's default branch when it needs code and the deployed app when it needs live evidence. An exploratory claim can require both. Merge first, and wait for the publish when needed. A feature branch or pull request is never the verification target. Control rechecks cost their registered price on pass or fail; exploration verification bills actual usage, including inconclusive results. The starting-balance requirement is not a spending cap.

When you are working from a Control instead, audit reevaluate records a new result in the Audit you name, which must be available and must have run once, while control run checks any Control and waits for the verdict without changing an Audit, a Control result, or a Finding. These two commands print the final ControlEvaluation and can consume Workspace credits. After a timeout, control status reads a ControlEvaluation without charging. For either Finding origin, rerun findings verify with the same --request-id to resume waiting; never pass an exploration verification id to control status. A result with evidenceBasis: declared is the Builder's answer, not verified evidence:

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

A Control only the Builder can settle is answered, never probed:

bworlds audit answer storefront CONTROL_ID OPTION_ID --json

Hand back what only the Builder can settle

Part of a Build's Findings list is not a developer's to fix:

• a Finding reading needs_user that carries a pendingDecision, which is the question BWorlds already put to the Builder;
• a Finding whose remediation names a setting in a hosting, database, or payment console, or in the builder tool, because the Builder holds that account;
• a Control answered rather than probed. audit show prints its question and option ids, findings verify refuses it, and audit answer settles it.

Send the Builder the Finding's own appUrl and one sentence naming what they must decide or change. Do not answer for them: audit answer records the answer as the Builder's own declaration.

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-cli skill:

Use the bworlds CLI to inspect Build "storefront" before changing code.
Read Build info, Dossier, open Findings, the Audits it carries and their results,
grouped errors, and relevant sessions as JSON. To work one Finding, read it with
"findings show" and take its fix prompt from "findings prompt". Correlate that
evidence with this checkout, explain the likely cause, and propose the smallest
verified change. Write the change here, on a branch off the branch the Build ships
from, and open a pull request. Never clone or push through BWorlds. Hand back any
Finding only the Builder can settle, with the link its result carries. Cite each
object by the "appUrl" its result carries. Show the pricing of a targeted recheck
and run it when my request includes fixing or verifying that Finding. Do not ask
for that authorization again. Obtain separate approval for a paid Audit, Autofix,
or a sensitive change outside my request.

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