docs(backend): correct stale 'msb from Phase 2' framing; msb is the default (#307) by wz-gsa · Pull Request #308 · GSA-TTS/agentic-coding-patterns

wz-gsa · 2026-08-10T21:16:41Z

Summary

Closes #307. The acq-kits READMEs + kits.yaml described sbx today; msb from Phase 2, and docs/repository-ecosystem.md framed cross-repo mounting as an sbx-only ("Docker's sbx CLI") capability. Both are now factually wrong — msb ships and is the default.

Change

acq-kits READMEs (git-ssh-sign, agentic-coding-playbook, usai-provider, zscaler-ca-certificate, + acq-kits/README.md) + 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 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, historical notes). Framing avoids hardcoding the backend set.

Verification

make validate passes; INDEX/CATALOG regenerate with no change.

Rollback

Revert. Docs-only.

Sibling of GSA-TTS/agentic-coding-quickstart#296 + the playbook feat/backend-agnostic-references PR. AI-assisted (OpenCode). Requires human review.

mogul

With the exception of migration notes, we should avoid pinning any current doc to the specific set of backends supported by acq or the phases during which they're developed/added, so we can minimize what will go stale. This also respects acq as an abstraction; this repo should minimize its knowledge of the acq backends.

mogul · 2026-08-11T05:49:01Z

-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


This section is not SBX-specific.

mogul · 2026-08-11T05:49:36Z

 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


Suggested change

via `acq` (the wrapper that runs on either backend — `msb`, the default, or `sbx`). This enables

via `acq` (the sandboxing wrapper). This enables

mogul · 2026-08-11T05:50:00Z

 ### Repository Ownership

- **Quickstart** owns the detailed `sbx` CLI setup instructions
+- **Quickstart** owns the detailed `acq` backend setup instructions (`msb` and `sbx`)


Suggested change

- **Quickstart** owns the detailed `acq` backend setup instructions (`msb` and `sbx`)

- **Quickstart** owns the detailed `acq` setup instructions

mogul · 2026-08-11T05:51:06Z

+> 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.


Suggested change

> 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.

mogul · 2026-08-11T05:51:36Z

+> 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.


Suggested change

> 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.

mogul · 2026-08-11T05:51:57Z

+> 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


Suggested change

> 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

mogul · 2026-08-11T05:52:19Z

+> 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/`


Suggested change

> 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/`

mogul · 2026-08-11T05:53:27Z

 # 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


We should probably just update this to not refer to specific backends or phases, since it will only go stale.

mogul · 2026-08-11T05:54:19Z

@@ -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


Suggested change

context); `acq` translates the neutral spec into whichever backend is active

context); `acq` translates the neutral spec into whichever backend is active.

mogul · 2026-08-11T05:54:38Z

 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).


Suggested change

(`msb` — the default — and `sbx` today; `ppp` later).

…rations 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 <william.zujkowski@gsa.gov>

wz-gsa · 2026-08-11T12:47:55Z

Applied all suggestions verbatim — acq-kits READMEs now say 'acq abstracts the isolation backend', the intro drops the trailing backend-list clause, kits.yaml no longer names backends/phases, and repository-ecosystem.md uses 'acq (the sandboxing wrapper)' with a non-sbx-specific command pointer. Rebased on main.

…efault (#307) 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 <william.zujkowski@gsa.gov>

…rations 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 <william.zujkowski@gsa.gov>

wz-gsa requested a review from a team as a code owner August 10, 2026 21:16

mogul requested changes Aug 11, 2026

View reviewed changes

wz-gsa force-pushed the feat/backend-agnostic-docs-307 branch from d1918e4 to 07320d8 Compare August 11, 2026 12:46

mogul enabled auto-merge (squash) August 11, 2026 21:07

mogul approved these changes Aug 11, 2026

View reviewed changes

wz-gsa added 2 commits August 12, 2026 15:28

wz-gsa force-pushed the feat/backend-agnostic-docs-307 branch from 213208f to e7559ae Compare August 12, 2026 19:29

wz-gsa merged commit d882bd4 into main Aug 12, 2026
7 checks passed

wz-gsa deleted the feat/backend-agnostic-docs-307 branch August 12, 2026 19:30

Navigation Menu

Uh oh!

docs(backend): correct stale 'msb from Phase 2' framing; msb is the default (#307) - #308

docs(backend): correct stale 'msb from Phase 2' framing; msb is the default (#307)#308
wz-gsa merged 2 commits into
mainfrom
feat/backend-agnostic-docs-307

wz-gsa commented Aug 10, 2026

Uh oh!

mogul left a comment

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

mogul Aug 11, 2026

Uh oh!

wz-gsa commented Aug 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

	via `acq` (the wrapper that runs on either backend — `msb`, the default, or `sbx`). This enables
	via `acq` (the sandboxing wrapper). This enables

	- Quickstart owns the detailed `acq` backend setup instructions (`msb` and `sbx`)
	- Quickstart owns the detailed `acq` setup instructions

		> 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 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.

	context); `acq` translates the neutral spec into whichever backend is active
	context); `acq` translates the neutral spec into whichever backend is active.

Uh oh!

Conversation

wz-gsa commented Aug 10, 2026

Summary

Change

Verification

Rollback

Uh oh!

mogul left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wz-gsa commented Aug 11, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants