/wbContext — Exhaustive Simulation ()
/wbContext is the synchronizer. Its job is to catch the agent up on a package's current state without requiring the user to re-explain everything every session. It produces a context.md (or focused variants) that captures: what the package is, what it depends on, what conventions apply, what's been recently touched, and what not to touch (parked tech debt, intentional non-fixes).
Read this if you want to know what --focus actually scopes to, why --scope=global is rare and intentional, and where context ends and explanation (/wbExplain) begins.
1. Role & target
| Aspect | Behavior |
|---|---|
| Role | The Synchronizer — produces an agent-readable state snapshot of a package. |
| Target | A directory (default: CWD), with optional --focus to narrow to a sub-system. |
| Cell scope | None. /wbContext writes to .agents/workflows/context.md (or focused variants), not to plan cells. |
| Side effects allowed | Reading code, reading package.json, reading vite/build configs, reading memory, writing context files. |
| Side effects forbidden | Editing source code, mutating plans, running tests, fetching external resources. |
The "no external fetch" rule matters: context should be reproducible from the workspace + memory alone. If a context file claims something that can't be verified by reading the workspace, the next session can't trust it. The agent's read of the package is the source of truth; external links are cited but not depended on.
/wbContext is also the only QA-group command that primarily writes a file as its output (versus reports, plan rows, or stdout prose). The context file is meant to be re-read by the agent on subsequent sessions.
2. Argument resolution matrix
| Form | Example | What /wbContext does |
|---|---|---|
| No argument | Command: /wbContext | Uses CWD. Refuses if CWD is the monorepo root (too coarse) or a non-package directory. |
| Directory | Command: /wbContext core2/packages/wb-core/ | Scopes to one package. Most common usage. |
| Free-text scope | Command: /wbContext "the auth subsystem" | Triggers focused mode — searches for auth-related files across packages. |
--focus="<topic>" | Command: /wbContext --focus="state management" | Same as free-text but more explicit. Produces context_state-management_<date>.md. |
--refresh | Command: /wbContext --refresh | Force re-read; ignores cached context.md and rebuilds from scratch. |
The "refuse at monorepo root" behavior is intentional. A wb-labs-wide context.md would be enormous and immediately stale; /wbContext insists on package-level granularity. Cross-package context is the --scope="cross-package" job — which is also rare and warns about staleness.
3. Flag matrix
/wbContext has three flags, each shaping a different axis of the output.
| Flag | Shortcut | Purpose |
|---|---|---|
--focus="<topic>" | -f | Scopes the context file to one sub-system. Output filename includes the focus. |
--scope="<level>" | -s | local (default — one package), cross-package (multiple packages, single concern), global (rare; whole monorepo, lightweight only). |
--refresh | (none) | Force re-scan, ignoring cached context. |
How --focus shapes the output
Without --focus, /wbContext produces a broad context file: package identity, dependencies, key conventions, recent activity. With --focus, it produces a narrow file scoped to that topic — and also writes to a different filename (context_<focus>_<date>.md) so the broad context.md isn't overwritten.
The two outputs are complementary, not competing. Onboarding readers get the broad file; deep-dive readers get the focused file. Both can coexist.
How --scope interacts with --focus
--scope | --focus | Output |
|---|---|---|
local (default) | none | context.md for one package. |
local | auth | context_auth_<date>.md scoped to auth-related code in one package. |
cross-package | auth | Same focus, but reads auth-related code across multiple packages. Includes a warning header about staleness. |
global | (any) | Lightweight only — links between packages, key entry points, top-level conventions. Never the full code analysis of local mode. |
The global scope is intentionally lightweight because a deep global context is wrong: it'd be 10× bigger and 10× more stale than a single-package one. Global is for "where is what" navigation, not "how does it work" understanding.
4. Pipelines (the agent-native scenarios)
/wbContext core2/packages/wb-core/> /wbContext core2/packages/wb-core/💠 Pipeline First-time context for wb-core
A new agent session needs to come up to speed on core2/packages/wb-core/. No prior context.md exists.
💠 Pipeline Focused context for an active investigation
Mid-session, the user realizes they need a focused snapshot of "everything related to dev gating" before continuing:
💠 Pipeline The cross-package warning
5. Edge cases & refusals
| Trigger | What /wbContext does |
|---|---|
| Run from monorepo root | Halt. ❌ /wbContext is package-level. Run from a package directory or pass an explicit path. |
| Run from a non-package directory | Halt. ❌ Target has no package.json; cannot derive identity. |
--scope="global" | Permitted but produces a lightweight navigation file, not deep analysis. Includes warning. |
Existing context.md is more recent than any code change | Warns "context appears current" and offers to skip; user can --refresh to force. |
| Free-text focus with no matches in workspace | Honest "no relevant code found for that focus." Suggests checking spelling or running /wbContext (broad) first. |
--focus without a value | Halt. Empty focus is meaningless. |
| Memory contradicts derived context (e.g., code says X but memory says X is being removed) | Both surfaced. Memory's contradiction recorded as a "watch this" note in the context. |
| Multiple sub-packages within target | Refuses; asks user to pick one. Each sub-package needs its own context. |
The pattern: /wbContext produces an agent-readable state snapshot scoped to package-level by default. It refuses coarse-grained scopes that produce fragile context, refuses to invent content not verifiable from the workspace, and treats memory as a first-class input — surfacing not just what's there but what's deliberately left alone. The output is a file the next session reads; everything in it should still be true a week from now or be flagged as time-sensitive.