Skip to content

Commit f386458

Browse files
mogulOpenCode Agent
andauthored
feat(integrations): add neutral hybrid/v1 acq-kits + schema + registry (#221)
* feat(integrations): add kit-hybrid-v1 schema + sbx-kits redirect First slice of Phase 2 Part A (neutral acq-kits). Adds the backend-agnostic kit JSON Schema (schemaVersion: "hybrid/v1") that the four converted kits will validate against, and turns the old sbx-kits/ README into a one-release redirect pointing at the new integrations/isolation/acq-kits/ home. Kits, registry, and the migration ADR land in follow-up commits on this branch. Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * feat(integrations): add usai-provider acq-kit (hybrid/v1) Convert the usai-provider sbx kit to the neutral hybrid/v1 spec under integrations/isolation/acq-kits/usai-provider/. Payloads (opencode.jsonc, merge-global-config.mjs) carried verbatim; the node tooling and tests (package.json, scripts/sync-usai-models.mjs, tests/) move here so the new home is the single source of truth. Also: - extend kit-hybrid-v1 schema with files[].source (payload file under the kit's files/ tree) as an alternative to inline content, for multi-line payloads. - add integrations/isolation/acq-kits/validate-kits.py: schema-validates every acq-kit spec and checks source paths + known-backend keys + README presence (the backend-agnostic gate; live per-backend checks stay in scripts/verify). Verification: - validate-kits.py: usai-provider OK - node --test tests/**: 41 pass / 0 fail - bash -n scripts/verify: clean - scan_unsafe_shell.py acq-kits/: 0 errors, 0 warnings Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * feat(integrations): add agentic-coding-playbook acq-kit (hybrid/v1) Convert the playbook sbx kit to the neutral hybrid/v1 spec. Per the acq design doc §6, the ~80-line inline startup shell is extracted into a standalone, lintable, testable script at files/home/playbook-clone.sh (dropped to /home/agent/playbook-clone.sh, run at startup). Clone-integrity SHA gate, idempotency, and graceful non-fatal degradation are unchanged. New decision record: extract-clone-script-to-file.md. Verification: - validate-kits.py: agentic-coding-playbook OK - bash -n playbook-clone.sh + scripts/verify: clean - scan_unsafe_shell.py acq-kits/: 0 errors, 0 warnings - ran playbook-clone.sh with a bad ref: exits 0, no clone left behind (graceful degradation path confirmed) Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * feat(integrations): add zscaler-ca-certificate acq-kit (hybrid/v1) Convert the Zscaler CA sbx kit to the neutral hybrid/v1 spec. This kit is the showcase for backend_shortcuts: declares backend_shortcuts.msb.trust_host_cas so the msb adapter uses its native --trust-host-cas primitive (and skips the file-drop), while sbx (and ppp later) fall through to the file-drop + update-ca-certificates path. Behavioral parity: the guest trusts the Zscaler CA either way (README parity note). The public Zscaler Root CA moves from an inline spec PEM to a files/ payload (files/home/zscaler-ca.crt) with the initFiles phase hint, preserving the exact create-time ordering. scripts/verify now reads the payload (falls back to inline). Verification: - validate-kits.py: zscaler-ca-certificate OK - openssl fingerprint == documented Zscaler Root CA (04:F6:1F:...:1A:53) - bash -n scripts/verify: clean - scan_unsafe_shell.py acq-kits/: 0 errors, 0 warnings Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * feat(integrations): add git-ssh-sign acq-kit (hybrid/v1) Convert the vendored git-ssh-sign kit to the neutral hybrid/v1 spec. The signing-time key-resolution command moves from an inline initFiles blob to a files/ payload (files/home/.config/git/ssh-signing-key-command, mode 0755); the system-gitconfig install command carries the install phase. No backend shortcut — SSH-agent forwarding is the shared mechanism, enabled natively per backend (sbx socket forward; msb 'ssh authorize'; ppp 'podman machine ssh -A'), noted in the README parity table. Apache-2.0 provenance retained: LICENSE + NOTICE (updated with the hybrid/v1 port note) + docs/decisions/vendored-from-sbx-kits-contrib.md + docs/security-skill-intake.md carried over. Verification: - validate-kits.py: git-ssh-sign OK (all 4 kits valid) - bash -n ssh-signing-key-command + scripts/verify: clean - scan_unsafe_shell.py acq-kits/: 0 errors, 0 warnings Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * feat(integrations): add acq-kits registry + area README Add integrations/isolation/acq-kits/kits.yaml (name -> backends + parity prose, sourced from the acq design doc §6) and the acq-kits/ area README. Extend validate-kits.py with a registry cross-check: kits.yaml must list exactly the kits present (no missing, no unknown entries). For Phase 2 each kit lists backends: [sbx, msb] (ppp arrives in Phase 3). Verification: - validate-kits.py: all 4 kits valid + registry cross-check passes - kits.yaml parses as YAML Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * docs(integrations): ADR for neutral hybrid/v1 acq-kits migration Area-scoped ADR (integrations/isolation/docs/decisions/0001) recording the sbx-kits -> acq-kits move: why the neutral hybrid/v1 spec, the four kits' new shape, the msb --trust-host-cas shortcut for zscaler-ca, the registry, the dir-name normalization, and the one-release redirect. Also records deferred live per-backend verification (no nested sandboxes) and the Part B follow-ups gated on this PR's merge SHA. Verification: - relative links resolved (schema, registry, repo-wide ADR) - validate-kits.py + validate_repo.py green Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * fix(integrations): join adjacent blockquotes in git-ssh-sign README (MD028) Markdown Lint CI flagged MD028 (blank line inside blockquote) at integrations/isolation/acq-kits/git-ssh-sign/README.md:16 — two consecutive blockquotes separated by a blank line. Join them with a '>' continuation line. AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * fix(integrations): harden validate-kits, wire kit gate into CI, normalize usai-provider name Address review feedback from PR #221: - validate-kits.py: guard against a non-dict spec (empty/scalar spec.yaml) before the dict-shaped checks so a malformed kit is reported as invalid rather than crashing the whole run with an AttributeError; also validate the registry root is a mapping. - Wire the offline gate into CI + one-command entry points so the ADR claim ('runs offline in CI') is true: 'make validate-kits' / 'make test-kits' (folded into 'make ci'), a 'validate-acq-kits' pre-commit hook, and CI steps in ci.yml (Pattern Validation runs the schema gate; new 'acq-kits Tests' job runs the node suites). ADR + acq-kits README updated to point at them. - Normalize the lingering '-kit' suffix to match the normalized dir/spec name: package.json name -> usai-provider, and the ownership marker comment usai-provider:owns-opencode-config (opencode.jsonc, merge test, ADR-0002, README) — the marker is a fresh token, no existing sandboxes depend on it. Verification: - validate-kits.py: 4/4 valid; malformed empty+scalar specs now report cleanly (exit 1, no traceback) - node --test: 41/41 pass (marker rename reflected in tests) - validate_repo.py + scan_unsafe_shell.py: clean - ci.yml / .pre-commit-config.yaml parse as YAML Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * docs(integrations): note git-ssh-sign allowed_signers trust scope (L1) Review finding L1 (documentation-only): the signing-key command trusts whatever key the forwarded SSH agent presents first and writes allowed_signers keyed to a possibly-unset email. Add a header comment stating this is a sandbox self-signing convenience and the emitted allowed_signers file must not be reused as an authorization root outside the ephemeral sandbox. No behavior change. AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> * fix(integrations): harden acq-kits validator gate per adversarial review Address @wz-gsa CHANGES_REQUESTED on PR #221 — make the validator the PR sells as its safety net actually fail closed. Finding 1 (fail-closed): already landed in the prior commit — a non-dict/empty spec.yaml now returns a clean per-kit error (exit 1, no AttributeError traceback), and the registry name-harvest catch is narrowed to (yaml.YAMLError, OSError) instead of bare Exception. Re-confirmed with empty and top-level-list spec repros. Finding 2 (can-pass-but-broken): add a best-effort commands[] <-> files[] consistency check. A kit-owned payload path (/home/... .sh/.mjs/.py/.crt/.pem) referenced by commands[] argv but dropped by no files[] entry is almost always a re-home typo. Emitted as a WARN by default (heuristic: a command may create a file at runtime); a new --strict flag promotes warnings to failures, and the Makefile / pre-commit / CI gate all run --strict so a re-home typo fails the offline gate instead of only failing live. Nits: - backend_shortcuts/backend_extras: schema descriptions + ADR + acq-kits README now state the per-backend values are unconstrained objects, human-review-only and NOT schema-enforced (was 'kept in-spec so review covers it'). - ppp: kept (Podman backend is in active development, imminent Phase 3) but explicitly documented as a RESERVED slot with no consumer yet, in the schema descriptions, ADR, and README — so it no longer reads as already-supported. Verification: - validate-kits.py --strict: 4/4 valid, 0 warnings - negative repros: empty/list spec -> exit 1; commands-without-drop -> WARN (exit 0 default) / exit 1 (--strict) - node --test: 41/41; validate_repo + scan_unsafe_shell clean; schema check_schema OK; unknown backend key still rejected, ppp extras accepted - ci.yml / .pre-commit-config.yaml parse as YAML Part A of the acq Phase 2 handoff (agentic-coding-quickstart#202). AI-assisted (OpenCode Agent, model: claude_4_8_opus). Co-authored-by: OpenCode Agent <[email protected]> --------- Co-authored-by: OpenCode Agent <[email protected]>
1 parent 58d7d81 commit f386458

48 files changed

Lines changed: 6401 additions & 38 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.github/workflows/ci.yml‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -155,3 +155,24 @@ jobs:
155155
156156
- name: Run validation
157157
run: make validate
158+
159+
- name: Validate acq-kits (hybrid/v1 schema)
160+
run: make validate-kits
161+
162+
# acq-kits node test suites (offline, no sandbox required)
163+
acq-kits:
164+
name: acq-kits Tests
165+
runs-on: ubuntu-latest
166+
timeout-minutes: 10
167+
steps:
168+
- uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
169+
with:
170+
persist-credentials: false
171+
172+
- name: Setup Node.js
173+
uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
174+
with:
175+
node-version: '22'
176+
177+
- name: Run acq-kits node tests
178+
run: make test-kits

‎.pre-commit-config.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -56,3 +56,8 @@ repos:
5656
entry: python scripts/validate_repo.py
5757
language: unsupported
5858
pass_filenames: false
59+
- id: validate-acq-kits
60+
name: Validate acq-kits (hybrid/v1 schema)
61+
entry: python integrations/isolation/acq-kits/validate-kits.py --strict
62+
language: unsupported
63+
pass_filenames: false

‎Makefile‎

Lines changed: 18 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
.PHONY: setup validate generate generate-check test coverage security ci clean search install-hooks help
1+
.PHONY: setup validate validate-kits test-kits generate generate-check test coverage security ci clean search install-hooks help
22

33
help: ## Show this help message
44
@echo "agentic-coding-patterns — Available targets:"
@@ -33,6 +33,17 @@ install-hooks: ## Install pre-commit hooks (opt-in for contributors)
3333
validate: ## Run all validators (frontmatter + sensitive terms)
3434
python scripts/validate_repo.py
3535

36+
validate-kits: ## Validate neutral acq-kits specs against the hybrid/v1 schema (strict: warnings fail)
37+
python integrations/isolation/acq-kits/validate-kits.py --strict
38+
39+
test-kits: ## Run the acq-kits node test suites (usai-provider generator + merge)
40+
@if command -v node >/dev/null 2>&1; then \
41+
echo "==> usai-provider kit tests"; \
42+
cd integrations/isolation/acq-kits/usai-provider && node --test 'tests/**/*.test.mjs'; \
43+
else \
44+
echo "⚠️ node not installed — skipping acq-kits node tests"; \
45+
fi
46+
3647
scan-shell: ## Scan shell scripts + markdown bash blocks for unsafe patterns (#154)
3748
python scripts/scan_unsafe_shell.py .
3849

@@ -88,6 +99,9 @@ ci: ## Full CI check (validate + security + test + pre-commit checks)
8899
@echo "==> Scanning for unsafe shell patterns..."
89100
python scripts/scan_unsafe_shell.py .
90101
@echo ""
102+
@echo "==> Validating acq-kits (hybrid/v1 schema)..."
103+
python integrations/isolation/acq-kits/validate-kits.py --strict
104+
@echo ""
91105
@echo "==> Running security audit..."
92106
pip-audit
93107
@echo ""
@@ -98,6 +112,9 @@ ci: ## Full CI check (validate + security + test + pre-commit checks)
98112
echo "⚠️ No tests found — skipping"; \
99113
fi
100114
@echo ""
115+
@echo "==> Running acq-kits node tests..."
116+
@$(MAKE) --no-print-directory test-kits
117+
@echo ""
101118
@echo "✓ All checks passed"
102119

103120
clean: ## Remove generated files and caches
Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
# acq mixin kits (`hybrid/v1`)
2+
3+
Neutral, backend-agnostic **mixin kits** for
4+
[`acq`](https://github.com/GSA-TTS/agentic-coding-quickstart) — the pluggable
5+
isolation-backend wrapper. A kit configures an agentic-coding sandbox
6+
declaratively (network egress, files to drop, lifecycle commands, agent
7+
context); `acq` translates the neutral spec into whichever backend is active
8+
(`sbx` today; `msb` from Phase 2; `ppp` later).
9+
10+
These are isolation/environment building blocks — they configure the *sandbox*,
11+
not agent behavior. (Behavioral patterns live in `skills/`, `prompts/`, etc.)
12+
13+
> **Why `acq-kits/` (not `sbx-kits/`)?** These kits are consumed by `acq`, which
14+
> selects a backend, rather than by `sbx` alone. The former
15+
> [`../sbx-kits/`](../sbx-kits/) is a one-release redirect to here. See
16+
> [`../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md).
17+
18+
## Available kits
19+
20+
| Kit | Purpose |
21+
|-----|---------|
22+
| [`usai-provider/`](usai-provider/) | Configure the agent to use the GSA USAi model provider (OpenCode today), with egress allow-listed. |
23+
| [`agentic-coding-playbook/`](agentic-coding-playbook/) | Clone the GSA agentic-coding-playbook at startup and link its `AGENTS.md` + skills into each agent's search paths. |
24+
| [`zscaler-ca-certificate/`](zscaler-ca-certificate/) | Trust the public Zscaler Root CA in the sandbox (msb: native `--trust-host-cas`; sbx: file-drop + `update-ca-certificates`). |
25+
| [`git-ssh-sign/`](git-ssh-sign/) | Sign git commits and tags with the SSH key forwarded from the host agent (vendored from sbx-kits-contrib). |
26+
27+
Each kit is self-contained: a `spec.yaml` (`hybrid/v1`), any `files/` payload, a
28+
`scripts/verify` host-side check, a `README.md` (with a **backend parity** note),
29+
a `TROUBLESHOOTING.md`, and `docs/decisions/` records.
30+
31+
The [`kits.yaml`](kits.yaml) registry is the human-readable parity summary
32+
(kit → supported backends + parity prose).
33+
34+
## What is a hybrid/v1 kit?
35+
36+
A kit is a directory with a `spec.yaml` (`schemaVersion: "hybrid/v1"`). A
37+
`kind: mixin` kit layers onto a base agent sandbox and declares, in a neutral
38+
vocabulary:
39+
40+
- `caps.network.allow` — outbound egress hosts.
41+
- `files[]` — files to drop into the guest (inline `content` or a `source:`
42+
under the kit's `files/` tree), optionally tagged with a lifecycle `phase`.
43+
- `commands[]` — lifecycle commands, each with a `phase` (`install` /
44+
`initFiles` / `startup`), `user`, and argv `command`.
45+
- `agentContext` — markdown surfaced to the agent.
46+
- `backend_shortcuts.<backend>` — a native primitive that replaces the
47+
declarative path for one backend (e.g. msb's `--trust-host-cas` for the
48+
Zscaler kit). Adapters check this first; if present, `caps`/`files`/`commands`
49+
are skipped for that backend.
50+
- `backend_extras.<backend>` — free-form per-backend config the neutral spec
51+
doesn't model.
52+
53+
> The `backend_shortcuts` / `backend_extras` values are **unconstrained
54+
> objects** — the schema fixes only the set of backend keys (`sbx`, `msb`,
55+
> `ppp`), not the shape of what's inside. Their content is **human-review-only,
56+
> not schema-enforced**. `ppp` (Podman) is a **reserved** backend slot for the
57+
> in-flight Phase 3 adapter; `sbx` and `msb` have live consumers today.
58+
59+
The schema is [`schemas/kit-hybrid-v1.schema.json`](../../../schemas/kit-hybrid-v1.schema.json).
60+
61+
## Validating kits
62+
63+
```bash
64+
# Backend-agnostic gate: schema + source paths + known backends + registry.
65+
# Wired into CI (Pattern Validation job) + pre-commit + `make ci`.
66+
python integrations/isolation/acq-kits/validate-kits.py # or: make validate-kits
67+
68+
# Kit unit tests (usai-provider generator + merge). CI: acq-kits Tests job.
69+
make test-kits
70+
71+
# Live, per-backend end-to-end check (needs a backend CLI + a sandbox-capable host):
72+
<kit>/scripts/verify
73+
```
Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# agentic-coding-playbook (acq mixin kit, `hybrid/v1`)
2+
3+
A neutral [`acq`](https://github.com/GSA-TTS/agentic-coding-quickstart) **mixin
4+
kit** that delivers the GSA
5+
[agentic-coding-playbook](https://github.com/GSA-TTS/agentic-coding-playbook) —
6+
the federal `AGENTS.md` rules and the Agent Skills — into a sandbox.
7+
8+
> **Neutral (backend-agnostic) kit.** This is the `schemaVersion: "hybrid/v1"`
9+
> form consumed by `acq`, which selects an isolation backend (`sbx` today; `msb`
10+
> from Phase 2). It replaces the former `sbx-kits/playbook-kit/` sbx-only spec.
11+
> See [backend parity](#backend-parity) and
12+
> [`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md).
13+
14+
The kit ships one small script. At container **startup** it:
15+
16+
1. clones the playbook at a pinned ref into `~/.agentic-coding-playbook`, then
17+
2. symlinks the playbook's `AGENTS.md` and skills into each supported agent's
18+
search paths.
19+
20+
Clone-at-startup (rather than vendoring the playbook into the kit's `files/`)
21+
keeps the kit tiny and lets the playbook version be pinned and bumped
22+
independently. See [Failure behavior](#failure-behavior) for how it degrades
23+
when the clone can't run.
24+
25+
## Backend parity
26+
27+
All backends use the **same** mechanism: allow-list `github.com` /
28+
`codeload.github.com` and run the same clone+link script
29+
(`files/home/playbook-clone.sh`) at startup. No backend shortcut. The GitHub
30+
token needed while the playbook repo is private is injected by the active
31+
backend on the outbound clone (see [Prerequisites](#prerequisites)); the kit
32+
never holds it. Behavioral parity: the playbook's `AGENTS.md` + skills end up
33+
linked into the agent search paths on every backend.
34+
35+
## Usage
36+
37+
```bash
38+
acq run opencode /path/to/project # acq applies the pinned kits, incl. this one
39+
```
40+
41+
The kit is a `mixin`, so it composes with the other acq-kits.
42+
43+
## Prerequisites
44+
45+
While the playbook repo is **private**, the clone needs a GitHub token. This kit
46+
does **not** declare its own `github` credential — the base agent sandbox
47+
already provides one, and `acq`'s backend injects it on the outbound clone (the
48+
container never sees the real token). Set it once:
49+
50+
```bash
51+
acq secret set github
52+
```
53+
54+
If you apply this kit on a base agent whose kit doesn't provide `github`, a
55+
private-repo clone has no credential and will fail — the kit degrades gracefully
56+
(warns and continues). Make the playbook repo public or supply a GitHub
57+
credential via that base. Once the repo is public, no token is needed.
58+
59+
## What it links
60+
61+
`AGENTS.md` is linked to each agent's user-level rules path; skills are linked
62+
per the cross-agent [agentskills.io](https://agentskills.io) standard root
63+
(`~/.agents/skills`) plus per-agent roots for agents that only scan their own
64+
directory.
65+
66+
| Agent | Rules file linked | Skills root linked | Confidence |
67+
|-------|-------------------|--------------------|-----------|
68+
| OpenCode | `~/.config/opencode/AGENTS.md` | `~/.agents/skills` | high |
69+
| Codex | `~/.codex/AGENTS.md` | `~/.agents/skills` | high |
70+
| Droid (Factory.ai) | `~/.factory/AGENTS.md` | `~/.factory/skills` | high |
71+
| Claude Code | `~/.claude/CLAUDE.md` | `~/.claude/skills` | high |
72+
| GitHub Copilot CLI | `~/.copilot/copilot-instructions.md` | `~/.copilot/skills` | high |
73+
| Cursor | — (rules live in app settings) | `~/.cursor/skills` | medium |
74+
| Kiro | — (steering dir, not a rules file) | — (no confirmed skills dir) | low |
75+
| Docker Agent (cagent) | — (instructions in agent YAML) | `~/.agents/skills` | high |
76+
77+
Notes:
78+
79+
- **`~/.agents/skills`** is read natively by Codex, OpenCode, Docker Agent, and
80+
Copilot CLI — one symlink root covers them all. The per-agent roots
81+
(`~/.claude/skills`, `~/.factory/skills`, `~/.cursor/skills`,
82+
`~/.copilot/skills`) cover agents that only scan their own directory.
83+
- **Cursor / Kiro / Docker Agent** have no user-level rules *file* convention
84+
(rules live in app settings or the agent's YAML), so they get skills only.
85+
- Low/medium-confidence rows should be **verified in-sandbox**; the kit links
86+
them best-effort and never fails if a path is wrong.
87+
88+
## Pinning the playbook version
89+
90+
The kit pins the playbook with two values passed to the startup script:
91+
92+
- `PLAYBOOK_REF` — a human-legible release tag (e.g. `v0.14.0`), what the clone
93+
fetches.
94+
- `PLAYBOOK_SHA` — the exact commit that tag must resolve to (the integrity pin).
95+
96+
At startup the script shallow-clones `PLAYBOOK_REF`, then verifies the cloned
97+
`HEAD` equals `PLAYBOOK_SHA`; on mismatch it removes the clone and starts
98+
without the playbook rather than linking unexpected content. A tag is a
99+
**mutable** ref, and (with the sibling CA kit) the clone traverses a Zscaler MITM
100+
proxy, so a tag match alone is not sufficient integrity — hence the SHA gate.
101+
102+
To adopt a newer playbook release, bump **both** `PLAYBOOK_REF` and
103+
`PLAYBOOK_SHA` together — in `spec.yaml`'s startup command **and** the matching
104+
fallback defaults in `files/home/playbook-clone.sh` — then recreate sandboxes.
105+
106+
> Signed-tag verification (`git verify-tag`) is a possible future hardening;
107+
> it depends on the playbook signing its releases and is tracked separately.
108+
109+
## Failure behavior
110+
111+
The startup script is **idempotent** and **non-fatal**:
112+
113+
- Clones once (clone-if-missing); no refetch on later starts.
114+
- On clone failure (offline, missing token, bad ref) it **warns and exits 0** —
115+
the sandbox starts **without** the playbook rather than failing to create.
116+
- Because startup runs on every container start, a sandbox created offline
117+
**self-heals**: the clone is retried on the next start once the network/token
118+
is available.
119+
120+
## Troubleshooting
121+
122+
See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md).
123+
124+
## Design decisions
125+
126+
- [`docs/decisions/playbook-clone-at-startup.md`](docs/decisions/playbook-clone-at-startup.md)
127+
— why the kit clones the playbook at startup (vs. a vendored copy or a `files/`
128+
payload), startup vs install, pinning, and the GitHub auth approach.
129+
- [`docs/decisions/extract-clone-script-to-file.md`](docs/decisions/extract-clone-script-to-file.md)
130+
— why Phase 2 extracted the inline startup shell into
131+
`files/home/playbook-clone.sh`.
132+
133+
The move to the neutral `hybrid/v1` spec is recorded in the area-level ADR
134+
[`../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md`](../../docs/decisions/0001-neutral-hybrid-v1-acq-kits.md).
135+
136+
## Verifying
137+
138+
Run the bundled check on a host with a backend CLI (e.g. `sbx`) installed and
139+
logged in:
140+
141+
```bash
142+
./scripts/verify
143+
```
144+
145+
It validates the spec, creates a throwaway sandbox with the kit, and confirms
146+
the playbook cloned and `AGENTS.md` + skills resolved at the agent paths. Set
147+
`KEEP=1` to keep the sandbox for inspection.
Lines changed: 54 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# Troubleshooting — agentic-coding-playbook kit
2+
3+
These are failure modes specific to the playbook kit, which clones the GSA
4+
playbook at container startup and links its `AGENTS.md` + skills into each
5+
agent's search paths.
6+
7+
## No playbook rules or skills in the sandbox
8+
9+
**Symptoms:** `~/.agents/skills` is empty; the agent has no federal `AGENTS.md`;
10+
`~/.agentic-coding-playbook` is missing.
11+
12+
**Cause:** the startup clone didn't run or failed. The startup command is
13+
non-fatal — on failure it warns and lets the sandbox start without the playbook.
14+
15+
**Fix / diagnose:**
16+
17+
- Check startup logs for the kit's warning (it names the likely cause).
18+
- **Missing GitHub token (private repo).** While the playbook repo is private the
19+
clone needs auth. Set it once: `sbx secret set -g github`. The kit relies on
20+
the **opencode base kit's** `github` credential — applying the kit on a base
21+
agent that doesn't declare `github` leaves the clone unauthenticated.
22+
- **Egress blocked.** Confirm `github.com` / `codeload.github.com` were allowed:
23+
`sbx policy log <sandbox>`; add blocked hosts to `caps.network.allow`.
24+
- **Bad ref.** Confirm `PLAYBOOK_REF` in `spec.yaml` names a real tag/branch.
25+
- **Self-heal:** the clone is retried on every container start, so once the
26+
network/token is fixed, stop/start the sandbox (or `sbx kit add <sandbox>
27+
<kit>` then restart) and it will clone.
28+
29+
## Skills are present but the agent doesn't use them
30+
31+
**Cause:** the agent reads skills from a path this kit didn't populate. The kit
32+
links `~/.agents/skills` (the cross-agent standard) plus per-agent roots
33+
(`~/.claude/skills`, `~/.factory/skills`, `~/.cursor/skills`, `~/.copilot/skills`).
34+
35+
**Fix:** confirm your agent's expected skills directory is among those (see the
36+
README's table) and that the symlinks resolve:
37+
`sbx exec <sandbox> -- sh -c 'ls -l ~/.agents/skills'`. Cursor/Kiro support is
38+
lower-confidence — verify in-sandbox and adjust the kit's link targets if needed.
39+
40+
## Playbook is pinned to an old version
41+
42+
**Cause:** the kit pins `PLAYBOOK_REF`, and an existing clone is never re-fetched
43+
(clone-if-missing only).
44+
45+
**Fix:** bump `PLAYBOOK_REF` in `spec.yaml`, then recreate the sandbox (or remove
46+
`~/.agentic-coding-playbook` inside it and restart so the kit re-clones).
47+
48+
## `AGENTS.md` links are dangling
49+
50+
**Cause:** the clone partially failed, or the playbook layout changed.
51+
52+
**Fix:** confirm `~/.agentic-coding-playbook/AGENTS.md` exists; if not, re-clone
53+
(see the self-heal note above). The kit links best-effort and never fails the
54+
sandbox start on a missing link target.

0 commit comments

Comments
 (0)