From 8025b00daa36390038dd4b6061f65d14173e22b4 Mon Sep 17 00:00:00 2001 From: William Zujkowski Date: Mon, 10 Aug 2026 17:04:12 -0400 Subject: [PATCH 1/2] docs(backend): correct stale 'msb from Phase 2' framing; msb is the default (#307) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The workspace now ships two isolation backends via acq — msb (the DEFAULT) and sbx — with ppp deferred. But the acq-kits READMEs + kits.yaml still described 'sbx today; msb from Phase 2', and repository-ecosystem.md framed cross-repo mounting as an sbx-only ('Docker's sbx CLI') capability. Both are now factually wrong and steer users to sbx over the default. - acq-kits/README.md, git-ssh-sign, agentic-coding-playbook, usai-provider, zscaler-ca-certificate READMEs + kits.yaml: 'sbx today; msb from Phase 2' -> 'msb (the default) and sbx today; ppp later'. - docs/repository-ecosystem.md: cross-repo multi-workspace mounting reframed to acq (either backend, msb default); 'Quickstart owns sbx CLI setup' -> 'owns acq backend setup (msb and sbx)'; command-syntax pointer now leads with the neutral acq Quick Start, keeping QUICKSTART_SBX as the sbx-specific detail. Left legitimately-sbx content untouched (frozen sbx-kits/ shim, verify scripts, schema enum, per-kit parity tables, sbx-specific historical notes). Framing avoids hardcoding the backend set so ppp slots in without further churn. make validate passes; INDEX/CATALOG regenerate with no change. Sibling of quickstart#296 + the playbook feat/backend-agnostic-references PR. Closes #307. AI-assisted (OpenCode). Requires human review. Co-authored-by: OpenCode Agent --- docs/repository-ecosystem.md | 12 +++++++----- integrations/isolation/acq-kits/README.md | 2 +- .../acq-kits/agentic-coding-playbook/README.md | 4 ++-- .../isolation/acq-kits/git-ssh-sign/README.md | 4 ++-- integrations/isolation/acq-kits/kits.yaml | 2 +- .../isolation/acq-kits/usai-provider/README.md | 4 ++-- .../acq-kits/zscaler-ca-certificate/README.md | 4 ++-- 7 files changed, 17 insertions(+), 15 deletions(-) diff --git a/docs/repository-ecosystem.md b/docs/repository-ecosystem.md index ea3bbb8..8a6145b 100644 --- a/docs/repository-ecosystem.md +++ b/docs/repository-ecosystem.md @@ -198,8 +198,8 @@ If you find patterns diverging between repos: ## Cross-Repo Multi-Workspace Patterns When working with multiple repositories simultaneously, you can mount them into a single sandbox -using Docker's `sbx` CLI. This enables workflows where an agent can reference one repo while -editing another. +via `acq` (the wrapper that runs on either backend — `msb`, the default, or `sbx`). This enables +workflows where an agent can reference one repo while editing another. ### Common Cross-Repo Modes @@ -212,13 +212,15 @@ editing another. ### Repository Ownership -- **Quickstart** owns the detailed `sbx` CLI setup instructions +- **Quickstart** owns the detailed `acq` backend setup instructions (`msb` and `sbx`) - **Patterns** provides high-level guidance on when to use cross-repo workflows - **Playbook** defines standards that may be referenced from other repos -For `sbx` command syntax and examples, see the +For backend command syntax and examples, see the quickstart guide — the neutral +[Quick Start](https://github.com/GSA-TTS/agentic-coding-quickstart/blob/main/docs/QUICKSTART.md) +for `acq`, and the sbx-specific [Multiple Workspaces](https://github.com/GSA-TTS/agentic-coding-quickstart/blob/main/docs/QUICKSTART_SBX.md#multiple-workspaces) -section in the quickstart guide. +section for `sbx` details. ### Security Best Practice diff --git a/integrations/isolation/acq-kits/README.md b/integrations/isolation/acq-kits/README.md index c747065..d45fff3 100644 --- a/integrations/isolation/acq-kits/README.md +++ b/integrations/isolation/acq-kits/README.md @@ -5,7 +5,7 @@ Neutral, backend-agnostic **mixin kits** for isolation-backend wrapper. A kit configures an agentic-coding sandbox declaratively (network egress, files to drop, lifecycle commands, agent context); `acq` translates the neutral spec into whichever backend is active -(`sbx` today; `msb` from Phase 2; `ppp` later). +(`msb` — the default — and `sbx` today; `ppp` later). These are isolation/environment building blocks — they configure the *sandbox*, not agent behavior. (Behavioral patterns live in `skills/`, `prompts/`, etc.) diff --git a/integrations/isolation/acq-kits/agentic-coding-playbook/README.md b/integrations/isolation/acq-kits/agentic-coding-playbook/README.md index 05c6aa3..6d7bea1 100644 --- a/integrations/isolation/acq-kits/agentic-coding-playbook/README.md +++ b/integrations/isolation/acq-kits/agentic-coding-playbook/README.md @@ -6,8 +6,8 @@ kit** that delivers the GSA the federal `AGENTS.md` rules and the Agent Skills — into a sandbox. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`sbx` today; `msb` -> from Phase 2). It replaces the former `sbx-kits/playbook-kit/` sbx-only spec. +> form consumed by `acq`, which selects an isolation backend (`msb` — the +> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/playbook-kit/` sbx-only spec. > See [backend parity](#backend-parity) and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). diff --git a/integrations/isolation/acq-kits/git-ssh-sign/README.md b/integrations/isolation/acq-kits/git-ssh-sign/README.md index 10c2cfd..9bc3ba2 100644 --- a/integrations/isolation/acq-kits/git-ssh-sign/README.md +++ b/integrations/isolation/acq-kits/git-ssh-sign/README.md @@ -9,8 +9,8 @@ Your **private key never leaves the host** — the sandbox forwards the SSH agen and signing resolves the public key from that agent at signing time. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`sbx` today; `msb` -> from Phase 2). It replaces the former `sbx-kits/git-ssh-sign/` sbx-only spec. +> form consumed by `acq`, which selects an isolation backend (`msb` — the +> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/git-ssh-sign/` sbx-only spec. > See [backend parity](#backend-parity) and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). > diff --git a/integrations/isolation/acq-kits/kits.yaml b/integrations/isolation/acq-kits/kits.yaml index 8872d92..310e3dd 100644 --- a/integrations/isolation/acq-kits/kits.yaml +++ b/integrations/isolation/acq-kits/kits.yaml @@ -2,7 +2,7 @@ # # Maps each neutral (schemaVersion: "hybrid/v1") kit to the backends that # support it and a prose parity note describing any per-backend capability -# difference. For Phase 2 the supported backends are sbx and msb; ppp arrives in +# difference. The supported backends today are msb (the default) and sbx; ppp arrives in # Phase 3. Parity is ADVISORY (documented, not machine-enforced) — the source of # truth for a per-backend difference is the kit's spec.yaml backend_shortcuts and # its README parity note. diff --git a/integrations/isolation/acq-kits/usai-provider/README.md b/integrations/isolation/acq-kits/usai-provider/README.md index ec71e36..61fa12b 100644 --- a/integrations/isolation/acq-kits/usai-provider/README.md +++ b/integrations/isolation/acq-kits/usai-provider/README.md @@ -5,8 +5,8 @@ kit** that configures a coding agent to use the GSA **USAi** OpenAI-compatible endpoint as its model provider, with network egress allow-listed. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`sbx` today; `msb` -> from Phase 2). It replaces the former `sbx-kits/usai-provider-kit/` sbx-only +> form consumed by `acq`, which selects an isolation backend (`msb` — the +> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/usai-provider-kit/` sbx-only > spec. See the [backend parity](#backend-parity) note and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). diff --git a/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md b/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md index 1ba0f7c..d6e0861 100644 --- a/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md +++ b/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md @@ -7,8 +7,8 @@ HTTPS-inspecting proxy — so outbound HTTPS works on networks where Zscaler intercepts and re-signs TLS traffic. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`sbx` today; `msb` -> from Phase 2). It replaces the former `sbx-kits/zscaler-ca-certificate/` +> form consumed by `acq`, which selects an isolation backend (`msb` — the +> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/zscaler-ca-certificate/` > sbx-only spec. See [backend parity](#backend-parity) and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). From e7559ae5f65df638b68946553c51dbafd79cab2c Mon Sep 17 00:00:00 2001 From: William Zujkowski Date: Tue, 11 Aug 2026 08:46:49 -0400 Subject: [PATCH 2/2] =?UTF-8?q?docs(backend):=20address=20review=20?= =?UTF-8?q?=E2=80=94=20acq=20abstracts=20the=20backend;=20drop=20enumerati?= =?UTF-8?q?ons?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per Bret's review (#308): don't name concrete backends or phases in the kit docs — acq is the abstraction and any list will go stale. Applied his suggestions verbatim: - acq-kits READMEs: 'selects an isolation backend (msb — default — and sbx today; ppp later)' -> 'abstracts the isolation backend'. - acq-kits/README.md intro: drop the trailing backend-list clause; 'acq translates the neutral spec into whichever backend is active.' - kits.yaml header: drop 'backends today are msb and sbx; ppp in Phase 3' -> 'acq abstracts the isolation backend; the authoritative set lives in the acq wrapper, not here.' - repository-ecosystem.md: cross-repo mounting via 'acq (the sandboxing wrapper)'; 'Quickstart owns the detailed acq setup instructions'; command pointer no longer labels the section sbx-specific. Co-authored-by: OpenCode Agent --- docs/repository-ecosystem.md | 11 +++++------ integrations/isolation/acq-kits/README.md | 3 +-- .../acq-kits/agentic-coding-playbook/README.md | 3 +-- .../isolation/acq-kits/git-ssh-sign/README.md | 3 +-- integrations/isolation/acq-kits/kits.yaml | 8 ++++---- .../isolation/acq-kits/usai-provider/README.md | 3 +-- .../acq-kits/zscaler-ca-certificate/README.md | 3 +-- 7 files changed, 14 insertions(+), 20 deletions(-) diff --git a/docs/repository-ecosystem.md b/docs/repository-ecosystem.md index 8a6145b..cf0dab2 100644 --- a/docs/repository-ecosystem.md +++ b/docs/repository-ecosystem.md @@ -198,7 +198,7 @@ If you find patterns diverging between repos: ## Cross-Repo Multi-Workspace Patterns When working with multiple repositories simultaneously, you can mount them into a single sandbox -via `acq` (the wrapper that runs on either backend — `msb`, the default, or `sbx`). This enables +via `acq` (the sandboxing wrapper). This enables workflows where an agent can reference one repo while editing another. ### Common Cross-Repo Modes @@ -212,15 +212,14 @@ workflows where an agent can reference one repo while editing another. ### Repository Ownership -- **Quickstart** owns the detailed `acq` backend setup instructions (`msb` and `sbx`) +- **Quickstart** owns the detailed `acq` setup instructions - **Patterns** provides high-level guidance on when to use cross-repo workflows - **Playbook** defines standards that may be referenced from other repos -For backend command syntax and examples, see the quickstart guide — the neutral +For command syntax and examples, see the quickstart guide's [Quick Start](https://github.com/GSA-TTS/agentic-coding-quickstart/blob/main/docs/QUICKSTART.md) -for `acq`, and the sbx-specific -[Multiple Workspaces](https://github.com/GSA-TTS/agentic-coding-quickstart/blob/main/docs/QUICKSTART_SBX.md#multiple-workspaces) -section for `sbx` details. +and its [Multiple Workspaces](https://github.com/GSA-TTS/agentic-coding-quickstart/blob/main/docs/QUICKSTART_SBX.md#multiple-workspaces) +section. ### Security Best Practice diff --git a/integrations/isolation/acq-kits/README.md b/integrations/isolation/acq-kits/README.md index d45fff3..cdfbf64 100644 --- a/integrations/isolation/acq-kits/README.md +++ b/integrations/isolation/acq-kits/README.md @@ -4,8 +4,7 @@ Neutral, backend-agnostic **mixin kits** for [`acq`](https://github.com/GSA-TTS/agentic-coding-quickstart) — the pluggable isolation-backend wrapper. A kit configures an agentic-coding sandbox declaratively (network egress, files to drop, lifecycle commands, agent -context); `acq` translates the neutral spec into whichever backend is active -(`msb` — the default — and `sbx` today; `ppp` later). +context); `acq` translates the neutral spec into whichever backend is active. These are isolation/environment building blocks — they configure the *sandbox*, not agent behavior. (Behavioral patterns live in `skills/`, `prompts/`, etc.) diff --git a/integrations/isolation/acq-kits/agentic-coding-playbook/README.md b/integrations/isolation/acq-kits/agentic-coding-playbook/README.md index 6d7bea1..2b13adc 100644 --- a/integrations/isolation/acq-kits/agentic-coding-playbook/README.md +++ b/integrations/isolation/acq-kits/agentic-coding-playbook/README.md @@ -6,8 +6,7 @@ kit** that delivers the GSA the federal `AGENTS.md` rules and the Agent Skills — into a sandbox. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`msb` — the -> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/playbook-kit/` sbx-only spec. +> form consumed by `acq`, which abstracts the isolation backend. It replaces the former `sbx-kits/playbook-kit/` sbx-only spec. > See [backend parity](#backend-parity) and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). diff --git a/integrations/isolation/acq-kits/git-ssh-sign/README.md b/integrations/isolation/acq-kits/git-ssh-sign/README.md index 9bc3ba2..0588e15 100644 --- a/integrations/isolation/acq-kits/git-ssh-sign/README.md +++ b/integrations/isolation/acq-kits/git-ssh-sign/README.md @@ -9,8 +9,7 @@ Your **private key never leaves the host** — the sandbox forwards the SSH agen and signing resolves the public key from that agent at signing time. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`msb` — the -> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/git-ssh-sign/` sbx-only spec. +> form consumed by `acq`, which abstracts the isolation backend. It replaces the former `sbx-kits/git-ssh-sign/` sbx-only spec. > See [backend parity](#backend-parity) and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). > diff --git a/integrations/isolation/acq-kits/kits.yaml b/integrations/isolation/acq-kits/kits.yaml index 310e3dd..7850867 100644 --- a/integrations/isolation/acq-kits/kits.yaml +++ b/integrations/isolation/acq-kits/kits.yaml @@ -2,10 +2,10 @@ # # Maps each neutral (schemaVersion: "hybrid/v1") kit to the backends that # support it and a prose parity note describing any per-backend capability -# difference. The supported backends today are msb (the default) and sbx; ppp arrives in -# Phase 3. Parity is ADVISORY (documented, not machine-enforced) — the source of -# truth for a per-backend difference is the kit's spec.yaml backend_shortcuts and -# its README parity note. +# difference. `acq` abstracts the isolation backend; the authoritative backend +# set lives in the acq wrapper, not here. Parity is ADVISORY (documented, not +# machine-enforced) — the source of truth for a per-backend difference is the +# kit's spec.yaml backend_shortcuts and its README parity note. # # See integrations/isolation/docs/decisions/0001-neutral-hybrid-v1-acq-kits.md. schemaVersion: "acq-kits-registry/v1" diff --git a/integrations/isolation/acq-kits/usai-provider/README.md b/integrations/isolation/acq-kits/usai-provider/README.md index 61fa12b..7559162 100644 --- a/integrations/isolation/acq-kits/usai-provider/README.md +++ b/integrations/isolation/acq-kits/usai-provider/README.md @@ -5,8 +5,7 @@ kit** that configures a coding agent to use the GSA **USAi** OpenAI-compatible endpoint as its model provider, with network egress allow-listed. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`msb` — the -> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/usai-provider-kit/` sbx-only +> form consumed by `acq`, which abstracts the isolation backend. It replaces the former `sbx-kits/usai-provider-kit/` sbx-only > spec. See the [backend parity](#backend-parity) note and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md). diff --git a/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md b/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md index d6e0861..0fc6719 100644 --- a/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md +++ b/integrations/isolation/acq-kits/zscaler-ca-certificate/README.md @@ -7,8 +7,7 @@ HTTPS-inspecting proxy — so outbound HTTPS works on networks where Zscaler intercepts and re-signs TLS traffic. > **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"` -> form consumed by `acq`, which selects an isolation backend (`msb` — the -> default — and `sbx` today; `ppp` later). It replaces the former `sbx-kits/zscaler-ca-certificate/` +> form consumed by `acq`, which abstracts the isolation backend. It replaces the former `sbx-kits/zscaler-ca-certificate/` > sbx-only spec. See [backend parity](#backend-parity) and > [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md).