/query (bro)
All mechanics live in the bro CLI. This skill is policy only.
A query plan is a TOML list of independent GraphQL steps. bro plan run
fans them out over connectors under a concurrency cap and prints one
merged JSON document keyed by step id — declaration order, never
completion order. bro plan query <file> is the same pipeline in one step;
bro plan validate <file> checks without executing.
The contract
provider names a connector (the data plane: github,
gitlab, atlassian, …) — never a providers[] entry; that
registry is the model plane. Absent → connectors.queries pin →
auto-detect.
- Read-only.
mutation/subscription documents are rejected at
validate time — v1 has no write path, and the keyword sniff
over-rejects by design (a field literally named mutation can't be
expressed; that's the safe direction).
- No secrets in plans.
env is a literal overlay — a token value
written there is committed as text. Auth always comes from the
spawned CLI's own login (gh auth, glab auth, atlassian auth) or
the operator's inherited process.env. Execution-shaping vars
(ATLASSIAN_API_URL, PATH, HOME) are rejected outright — they
could exfiltrate an inherited Authorization header or swap which
binary/config the connector spawns. Operators pin endpoints via the
query.env config section instead.
vars are scalars (string/number/bool) for github/gitlab —
serialized as -f k=v CLI fields. atlassian takes the table as the
JSON variables body verbatim.
- A failed step records
{ provider, error } (transport) or
{ provider, data?, errors? } (GraphQL response) and never aborts
siblings. Any failure → exit 1; results still print.
- Output is raw — no item normalization in v1. If you need
title/status/url rows, write the jq yourself or file the follow-up.
Plan shape
# "$schema" = "https://unpkg.com/@broject/bro/schemas/plans/query.schema.json"
kind = "query"
version = 1
concurrency = 4 # optional; config default is query.concurrency
[[steps]]
id = "gh-prs"
provider = "github"
graphql = """
query ($owner: String!, $name: String!) {
repository(owner: $owner, name: $name) {
pullRequests(first: 20, states: OPEN) { nodes { number title url } }
}
}
"""
[steps.vars]
owner = "theplenkov"
name = "bro"
The machine-readable plan schema ships at
schemas/plans/query.schema.json — bro plan describe query prints it
(the example as a TOML template); a file may pin it via the commented
"$schema" key above.
Commands
| Command |
What it does |
bro plan query <plan.toml> |
validate + run; merged JSON on stdout, exit 1 on any step failure |
bro plan run <plan.toml> |
same execution via the kind router |
bro plan validate <plan.toml> |
schema + read-only gate only |
bro plan describe query |
the kind's shipped JSON Schema (schemas/plans/query.schema.json) — --json for a {kind, version, schema} envelope |
Config
{ "query": { "concurrency": 4, "env": { "GITLAB_HOST": "gl.corp.example" } } }
query.env applies under every step's env — it is where endpoint
pins belong, including the ones plans are forbidden to carry.
Policy
- Prefer one plan over N serial
gh api calls — the fan-out is the
point, and the merged document is the artifact.
- A step failure is data, not a crash: read
error/errors per key,
retry only the failed step.
1---23name: query4description: "Use when writing or running a `kind = \"query\"` plan — cross-provider GraphQL fan-out over bro connectors (github/gitlab/atlassian), one merged JSON answer. Thin wrapper over `bro plan query` — mechanics live in the CLI (spec: specs/bro-14h8.1.md)."5metadata:6 source: https://skillmd.com/skills/theplenkov/query7---89# /query (bro)1011**All mechanics live in the `bro` CLI.** This skill is policy only.1213A `query` plan is a TOML list of independent GraphQL steps. `bro plan run`14fans them out over connectors under a concurrency cap and prints one15merged JSON document keyed by step `id` — declaration order, never16completion order. `bro plan query <file>` is the same pipeline in one step;17`bro plan validate <file>` checks without executing.1819## The contract2021- `provider` names a **connector** (the data plane: `github`,22 `gitlab`, `atlassian`, …) — never a `providers[]` entry; that23 registry is the _model_ plane. Absent → `connectors.queries` pin →24 auto-detect.25- **Read-only.** `mutation`/`subscription` documents are rejected at26 validate time — v1 has no write path, and the keyword sniff27 over-rejects by design (a field literally named `mutation` can't be28 expressed; that's the safe direction).29- **No secrets in plans.** `env` is a _literal_ overlay — a token value30 written there is committed as text. Auth always comes from the31 spawned CLI's own login (`gh auth`, `glab auth`, `atlassian auth`) or32 the operator's inherited `process.env`. Execution-shaping vars33 (`ATLASSIAN_API_URL`, `PATH`, `HOME`) are rejected outright — they34 could exfiltrate an inherited `Authorization` header or swap which35 binary/config the connector spawns. Operators pin endpoints via the36 `query.env` config section instead.37- `vars` are scalars (string/number/bool) for `github`/`gitlab` —38 serialized as `-f k=v` CLI fields. `atlassian` takes the table as the39 JSON `variables` body verbatim.40- A failed step records `{ provider, error }` (transport) or41 `{ provider, data?, errors? }` (GraphQL response) and never aborts42 siblings. Any failure → exit 1; results still print.43- Output is **raw** — no item normalization in v1. If you need44 title/status/url rows, write the jq yourself or file the follow-up.4546## Plan shape4748```toml49# "$schema" = "https://unpkg.com/@broject/bro/schemas/plans/query.schema.json"50kind = "query"51version = 152concurrency = 4 # optional; config default is query.concurrency5354[[steps]]55id = "gh-prs"56provider = "github"57graphql = """58query ($owner: String!, $name: String!) {59 repository(owner: $owner, name: $name) {60 pullRequests(first: 20, states: OPEN) { nodes { number title url } }61 }62}63"""64[steps.vars]65owner = "theplenkov"66name = "bro"67```6869The machine-readable plan schema ships at70`schemas/plans/query.schema.json` — `bro plan describe query` prints it71(the example as a TOML template); a file may pin it via the commented72`"$schema"` key above.7374## Commands7576| Command | What it does |77| ------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |78| `bro plan query <plan.toml>` | validate + run; merged JSON on stdout, exit 1 on any step failure |79| `bro plan run <plan.toml>` | same execution via the `kind` router |80| `bro plan validate <plan.toml>` | schema + read-only gate only |81| `bro plan describe query` | the kind's shipped JSON Schema (`schemas/plans/query.schema.json`) — `--json` for a `{kind, version, schema}` envelope |8283## Config8485```jsonc86{ "query": { "concurrency": 4, "env": { "GITLAB_HOST": "gl.corp.example" } } }87```8889`query.env` applies under every step's `env` — it is where endpoint90pins belong, including the ones plans are forbidden to carry.9192## Policy9394- Prefer one plan over N serial `gh api` calls — the fan-out is the95 point, and the merged document is the artifact.96- A step failure is data, not a crash: read `error`/`errors` per key,97 retry only the failed step.