--- name: bworlds-brief description: "Free orientation on a Build you have just been given access to: who you are on it, what the app is, whether production is watched, what is failing now, what is already tracked and who settles it, and what must not break. It runs no Audit and no Control, so it spends no Workspace credits. Use when the user says 'I just joined this Build', 'what is this app', 'get me up to speed on [slug]', 'brief me on this Build', or 'what do I need to know before I touch this'. For the recurring paid rhythm, use bworlds-check. For the deep read, use bworlds-audit." --- # Build orientation You have access to a Build you did not write. This is the reading that tells you what it is before you touch it. Everything here runs with your own credential through the `bworlds` CLI. Load `bworlds-cli` for the command contract, the exit codes, the safety rules and the Findings protocol. Reading is free, and this skill only reads. Every command below is free: it starts no AuditRun and settles no Control, so the brief spends no Workspace credits. The brief also changes nothing on the Build: it records no Finding, touches no repository, and edits no Dossier. Locally it writes one thing, the Dossier copy that `dossier pull` downloads into the Operator Workspace. That path sits outside every checkout, so your own working tree is untouched. ## What the brief is not - Not a health check. `bworlds-check` is the recurring rhythm, and its step 4 runs the First Look Audit, which debits the Workspace. - Not an Audit. `bworlds-audit` is the deep read, and it asks which Audits are worth running before it spends anything. - Not a Finding. When the brief sees something worth tracking, hand it to `bworlds-triage` for a live production error, or to `bworlds-fix` for a Finding the Build already carries. ## 1. Know who you are on this Build ```bash bworlds auth status --json bworlds build info ``` `auth status` names the identity and the Workspaces it holds a Membership in. Your access to this Build comes from that Membership and nothing else. When a command fails here, the exit code says why: | Exit code | Meaning | What the brief does | |---|---|---| | `3` | no session, or an expired or revoked one | ask the user to run `bworlds auth login` and relay its one-time code and approval URL, then start again | | `4` | signed in, but no Membership gives access to this Build | report it and stop; the Workspace Owner grants access | | `5` | the slug is absent or outside your Workspaces | check the slug with the user; never try other slugs | Every later step needs this one to succeed, so a brief that cannot name the Build stops here and says why. `build info` reports three things you need before any later step: the Build's authorized areas, its Workspace's credit balance, and whether GitHub is connected. Say the balance out loud in the report, because the next skill the user reaches for may need it. ## 2. Read the code in your own checkout You were invited into this Workspace because you work on this app, so you already hold the code and your own GitHub access. Read it from your own checkout. The brief runs no repository command. Confirm it is the right repository before you read a line of it. `build info` printed `GitHub: connected to /`. Compare that with your checkout's `origin`: ```bash git -C remote get-url origin ``` A Builder can connect a repository their app does not ship from. A mismatch means BWorlds and you are reading two different apps, and every later line of the brief would be wrong. Report it and settle it with the Builder before going on. When `build info` reported `GitHub: not connected`, BWorlds holds no repository for this Build. Your checkout still tells you what the app is, so read it, and say in the report that BWorlds reads no code for this Build. When you hold no checkout either, skip this step, fill the **App** line from the Dossier and the Build's name alone, and mark it unconfirmed. Steps 3 to 5 need no code. Read for shape, not for defects: - **Toolchain**: the slug often encodes the builder tool (`-lovable`, `-bolt`, `-replit`). Check the git authors too. All-agent commits mean a non-technical Builder. - **App shape**: pages, routes, components. A small CRUD app, or a workflow tool with roles? - **Data**: tables, foreign keys, whether row-level policies exist per table. - **Auth model**: who signs in, what separates one customer's data from another's. - **Recent history**: `git log --oneline -20` says what the team has been fighting this month. Stay read-only. The brief changes no file in your checkout and commits nothing. ## 3. Read what BWorlds already knows ```bash bworlds audit list --json bworlds findings list --json ``` `audit list` names every Audit the Build carries, its `availability` and, for the ones that have run, what they already cover. An Audit nobody has run is the honest answer "we have not looked at this yet", and it belongs in the report as such. `findings list` is the work already on the table. Group it by `status` and `severity`, and read each Finding's `detection`: `audit` came from a Control, `telemetry` from BWorlds' analysis of the runtime, `manual` from a person. Detection decides whether the Builder's own Findings list shows it, so your list can be longer than theirs. Then split the list in two, because part of it is not yours to fix: - **Yours.** The remediation names files, routes or queries in the repository. You settle these in your own checkout, through `bworlds-fix`. - **The Builder's.** The Finding reads `needs_user` and carries a `pendingDecision`, or its remediation names a setting in a hosting, database or payment console or in the builder tool. BWorlds is waiting on a decision, an account you do not hold, or an answer only the Builder can give. A question Control is the same case: `bworlds audit show ` prints its question, and only `bworlds audit answer` settles it. Report the two counts separately. For each Builder-settled Finding, give the Builder its own link, the `appUrl` every `findings list --json` result carries, and one sentence naming what they must decide or change. Never answer on their behalf. An empty `findings list` is an answer: nothing is tracked yet. An empty `audit list` run history is the same: no Audit has looked at this Build. Report both as such, never as a clean bill of health. An Audit marked `planned` has nothing to read. Propose nothing yet. This step tells you what exists; it does not decide what to do next. ## 4. Read production ```bash bworlds telemetry uptime bworlds telemetry errors bworlds telemetry sessions ``` Read the heartbeat line that opens `telemetry errors` before the lists, because it decides whether they mean anything. `bworlds-cli` states what its three values mean. - `alive`: the lists are measurements. Report the error groups and whether the app has real usage. - `no_signal`: the SDK reported before and not in the last ten minutes. A quiet app and a removed SDK read the same here. - `no_data`: the SDK never reported. Nothing was measured. Call this Build **unmonitored**. Never call it healthy, quiet or error-free. An empty error list here is the absence of measurement, not the absence of errors. `telemetry uptime` is BWorlds' own probe of the Build's URL and detected backend, so it answers whatever the SDK does. A green uptime line never proves that production is watched. Telemetry withholds the email address of the Builder's end users and reports `"userEmailWithheld": true` instead. Leave it withheld. The brief has no reason to ask for it. ## 5. Read the Dossier ```bash bworlds dossier pull ``` The pull prints the Operator Workspace path and downloads the Build Dossier into it, outside every checkout. Read `context.md` for how this app works and `guardrails.md` for what must not break. If the pull reports no Dossier, nobody has audited or checked this Build yet. Say "no baseline yet" and move on; the brief still works, it just has nothing inherited to lean on. A Dossier without `guardrails.md`, or with an empty one, reads the same for the **Must not break** section: "no guardrails recorded yet". A pull that fails on an exit code in step 1's table stops at the same remedy. When `guardrails.md` exists, do not restate it in your own words here. Point the user at `bworlds-guardrails`, which hands the guardrails over in the form their own coding agent consumes. ## 6. Report Six lines and the exceptions. The user wants a mental model, not a document. ``` ## [Slug] Brief — [Date] **You**: Member of [Workspace] · credit balance [N] · GitHub [connected / not connected] **App**: [one sentence: what it does, for whom] · built with [tool] **Monitoring**: [SDK reporting / SDK reported before, silent since DATE / SDK never reported, production is unwatched] **Production**: [N error groups, top one: X / not measured] · [N sessions in 7 days / dormant] **Tracked**: [N open Findings: N critical, N high] · [N you can fix in code, N the Builder settles] · Audits run: [LIST / none] **Baseline**: [Dossier from DATE by WHO / no baseline yet] ### Must not break - [One line per guardrail, or "no guardrails recorded yet"] ### Where to go next - [One line per suggested skill, with the reason drawn from what you just read] ``` ## 7. Hand off The brief ends by naming the next move, never by making it: - A live production error and the heartbeat is `alive`: `bworlds-triage`, free, traces one grouped error to the code path. - Open Findings you can fix in code: `bworlds-fix`, which reads and prompts for free, fixes in your own checkout, and verifies the Finding's recorded evidence. - Findings the Builder settles: hand each one over with its link and the one sentence from step 3. Nothing a developer runs closes them. - Guardrails in the Dossier: `bworlds-guardrails`, free, hands them to the user's own coding agent. - Nothing known about this Build yet: `bworlds-audit`, which names each Audit's price and waits for an answer before spending. - The SDK never reported: the install is at `https://docs.bworlds.co/docs/guides/sdk`. It changes the Builder's app and needs a publish from their builder tool, so get their agreement first. Credit rates for whatever comes next are at `https://docs.bworlds.co/docs/reference/pricing`.