Skip to content

Commit 35ea9b0

Browse files
authored
feat(isolation): add the scope-layers pattern and a team-kit template (#441)
## Summary Adds `integrations/isolation/docs/scope-layers.md`: how global, team, and personal `acq` kits stack through `ACQ_EXTRA_KITS`, a per-field composition table, what belongs in each layer, authoring gotchas, one list of backend differences, and the parser rules to check against your `acq`. Adds the copy-and-rename template `acq-kits/examples/team-kit/`: a valid hybrid/v1 mixin with one live, harmless value per extension point, a host-side `env.sh`, a sample ADR, README, TROUBLESHOOTING, and a `scripts/verify` that asserts the composition live. Second of three stacked PRs for #421: #476, then this one, then the `personal-kit` template. **Reviewer ask: correct the composition table if any field composes differently than described**, especially the rows marked "sbx: composed natively". It was checked against acq v4.0.1 (GSA-TTS/agentic-coding-quickstart `1679530`), which includes the `environment` and `publishedPorts[]` fixes (GSA-TTS/agentic-coding-quickstart#519, GSA-TTS/agentic-coding-quickstart#526) and adds the pinned OpenCode agent kit between the global and team layers. The `volumes[]` and `commands[]` rows describe current behavior while the stacked-kit conflict rule is decided in GSA-TTS/agentic-coding-quickstart#533, which names this PR as its trigger. ## Eligibility & Accountability - [x] I am a **federal employee or contractor** (PRs merge with `@GSA-TTS/agentic-coding-team` code-owner approval; eligibility is attested here, not authenticated). *Anyone may open issues without this.* - [x] **I understand this change and can explain it in my own words** — I am the author of record and accountable for it. - [x] By opening this PR, I **attest I have the right to release this work** under the repository's [CC0-1.0](../LICENSE) dedication. ## AI Assistance Disclosure - [x] AI tools were used in this contribution. - [x] I verified all AI-generated content: no fabricated/hallucinated APIs, dependencies, citations, or placeholder content; any AI-suggested dependency was confirmed to exist. - [x] Any inherited/reused third-party material retains its original license and is identified (not represented as public domain). ## Type of Change - [x] New tool/editor integration (`integrations/`) - [x] Documentation update ## Motivation Every team adopting `acq` builds the same team layer between the global kits and each repo's agent config, then a personal layer on top. `ACQ_EXTRA_KITS` supports this, but nothing here said how stacked kits compose, what belongs in each layer, or gave a validated starting point. login.gov Team Data runs such a kit in production; this generalizes what that team learned. Parser and adapter defects the doc works around, stated once under "Check against your acq" and filed upstream: - a trailing `# comment` is kept in top-level fields and in `commands[]`, where it skips the command or changes an argument (GSA-TTS/agentic-coding-quickstart#558); - `environment` values are cut at the first `#`, even inside quotes (GSA-TTS/agentic-coding-quickstart#559); - `acq kit validate` passes commands the translator skips or empties (GSA-TTS/agentic-coding-quickstart#563); - flow-style argv parses as an empty command (GSA-TTS/agentic-coding-quickstart#560); - on msb an empty file fails its drop, and a failed drop stops that kit's `environment` and `commands[]` (GSA-TTS/agentic-coding-quickstart#561). OpenCode 2.x never loads `instructions` files (anomalyco/opencode#51341, fix in anomalyco/opencode#51422, tracked in #482), and the template delivers team conventions that way. Which OpenCode runs depends on the image: the agent kit installs 2.0.22, but an image that bakes 1.x puts it first on `PATH`. Checked live on msb 0.7.7 with acq v4.0.1: acq's own template image for `acq run opencode` (`sandbox-templates:opencode-docker`) runs 1.18.32 and `devenv-opencode:1.0.0` runs 1.18.23, so the conventions load; `sandbox-templates:shell-docker` has no OpenCode of its own and runs only 2.0.22, so they are ignored. `scripts/verify` now fails when 2.x is what runs, and did on `shell-docker`. The doc states this in prose, and the permission sketch follows the global kit's default-allow posture (ask before posting, deny merge/approve, pipeline runs, CI variables, and API writes). Not shipped: an optional `tui.jsonc` with `OPENCODE_TUI_CONFIG`. TUI settings are mostly personal, a personal kit would replace the team file whole, and `verify` could assert only that the variable and file exist. ## Testing - [x] Ran `make validate` locally (all checks pass) - [x] Ran `make test` (if applicable): 448 passed; `scripts/tests/test_validate_kits_*.py`: 95 passed - [x] Tested with at least one real scenario: `examples/team-kit/scripts/verify` on msb 0.7.7 with acq v4.0.1: 20 passed, 0 failed, 1 skipped (the empty TEAM-SPECIFIC section). Not re-run on sbx for this revision (the host's sbx session needed `sbx login`); the doc no longer claims sbx observations. - [x] Examples are concrete and realistic - [x] Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/) format Also run: `validate-kits.py --strict`, `acq kit validate` on the template, `ruff check scripts/`, `ruff format --check scripts/`, `make generate-check`, markdownlint, `shellcheck -s sh env.sh`, and `env.sh` under sh, bash, zsh, and dash. ## Safety Checklist - [x] No secrets, API keys, tokens, or passwords included - [x] No PII (names, emails, SSNs, addresses) - [x] No CUI (Controlled Unclassified Information) - [x] No internal URLs, hostnames, or system paths (the reference implementation is named, not linked; examples use `example.gov`/`example.org`) - [x] No customer data or proprietary information - [x] Pattern defines `prohibited_content` in output contract (if applicable): not applicable, no SKILL.md pattern ## Quality Checklist - [x] Plain language used (Grade 10 or below preferred) - [x] Examples included - [x] Prerequisites clearly stated ## Validation Results ``` make validate ✓ All validators passed ``` ## Related Issues Relates to #421 (followed by the `personal-kit` template) Depends on #476 (placement B) Relates to GSA-TTS/agentic-coding-quickstart#533 (stacked-kit merge rules for volumes and startup steps) Relates to GSA-TTS/agentic-coding-quickstart#517 (symlinked `files[]` sources on msb) Relates to GSA-TTS/agentic-coding-quickstart#482 (acq's `~/.rc.d` login hook; the personal-kit row relies on it) Relates to #482 (OpenCode 2.x ignores `instructions`) Relates to GSA-TTS/agentic-coding-quickstart#557 (`acq configure` and team kits), GSA-TTS/agentic-coding-quickstart#558, GSA-TTS/agentic-coding-quickstart#559, GSA-TTS/agentic-coding-quickstart#560, GSA-TTS/agentic-coding-quickstart#561, GSA-TTS/agentic-coding-quickstart#562, GSA-TTS/agentic-coding-quickstart#563 (filed from this work) Relates to GSA-TTS/agentic-coding-quickstart#500, GSA-TTS/agentic-coding-quickstart#509, GSA-TTS/agentic-coding-quickstart#519, GSA-TTS/agentic-coding-quickstart#526 ## Additional Context - `scripts/verify` cannot run in this repo's CI (no nested sandboxes); the offline gate is `validate-kits.py`. - The template README links the pattern doc through the repository root with the file path as text: a copied kit cannot follow relative links, and `blob/main/…` links to files added here would fail link-check until merge. ## Reviewer Notes **Reviewers should verify:** - [ ] The composition table matches acq's behavior on msb, and the rows marked "sbx: composed natively" describe sbx correctly - [ ] Backend differences and Check against your acq match what you see on your acq - [ ] Safety checklist items confirmed - [ ] `make validate` passes in CI
1 parent 3aeae67 commit 35ea9b0

12 files changed

Lines changed: 1397 additions & 10 deletions

File tree

‎integrations/isolation/acq-kits/README.md‎

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -37,14 +37,18 @@ The [`kits.yaml`](kits.yaml) registry is the human-readable parity summary
3737

3838
## Templates
3939

40-
Copy-and-rename starting points under `examples/`. They are **not kits `acq`
41-
applies**: `hybrid/v1` has no parameters, so a template carries one live,
42-
harmless value per extension point for you to replace, plus a `scripts/verify`
43-
that asserts how the kit composes with the global layer. CI validates them like
44-
kits (schema, `files[]` sources, env names, README) but they are exempt from —
45-
and must stay out of — the `kits.yaml` registry. See
40+
Copy-and-rename starting points under [`examples/`](examples/). They are **not
41+
kits `acq` applies**: `hybrid/v1` has no parameters, so a template carries one
42+
live, harmless value per extension point for you to replace, plus a
43+
`scripts/verify` that asserts how the kit composes with the global layer. CI
44+
validates them like kits (schema, `files[]` sources, env names, README) but
45+
they are exempt from — and must stay out of — the `kits.yaml` registry. See
4646
[`../docs/decisions/0005-kit-templates.md`](../docs/decisions/0005-kit-templates.md).
4747

48+
| Template | Purpose |
49+
|----------|---------|
50+
| [`examples/team-kit/`](examples/team-kit/) | A team's scope-layer mixin: conventions and agent settings through the OpenCode config tier, applied via `ACQ_EXTRA_KITS` after the global kits. Pattern and composition rules: [`../docs/scope-layers.md`](../docs/scope-layers.md). |
51+
4852
## What is a hybrid/v1 kit?
4953

5054
A kit is a directory with a `spec.yaml` (`schemaVersion: "hybrid/v1"`). A
Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# team-kit (template for a team's acq mixin kit, `hybrid/v1`)
2+
3+
A **template, not a deployable kit**: the starting point for a team's own
4+
scope-layer mixin, the layer between the global kits `acq` applies for
5+
everyone and each repo's own agent config. `acq` never applies this directory;
6+
you copy it into a repo your team owns, rename it, and grow it. The pattern,
7+
the per-field composition rules, the authoring gotchas, the backend
8+
differences, and the parser rules to check against your `acq` are in
9+
`integrations/isolation/docs/scope-layers.md` in
10+
[agentic-coding-patterns](https://github.com/GSA-TTS/agentic-coding-patterns)
11+
(the pattern doc); the placement decision is ADR 0005 beside it, in
12+
`docs/decisions/`.
13+
14+
> **Tested on msb only.** This template and its `scripts/verify` have not been
15+
> tested on sbx and may not work there. Run `scripts/verify` on sbx before
16+
> relying on it.
17+
18+
```text
19+
global zscaler-ca-certificate · usai-provider · agentic-coding-playbook · git-ssh-sign (acq, everyone)
20+
agent the agent's own kit (opencode for `acq run opencode`) (acq, per agent)
21+
team your copy of this kit (ACQ_EXTRA_KITS)
22+
personal a teammate's own kit (ACQ_EXTRA_KITS, later)
23+
repo the repo's AGENTS.md / .opencode/ (read by the agent)
24+
```
25+
26+
## Use
27+
28+
1. Copy this directory into your team's repo and **rename both the directory
29+
and `name:` in `spec.yaml`** (kebab-case; keep them equal). Update
30+
`displayName:` and `description:`.
31+
2. Replace every value marked `REPLACE` in `spec.yaml`, and rewrite
32+
`files/home/team-config/team-conventions.md` for your team. Each extension
33+
point ships one live, harmless value so the schema and `scripts/verify`
34+
exercise it; leave a value in place only if you actually want it.
35+
3. Apply it after the global kits. Each teammate sources the kit's `env.sh`
36+
from their shell rc, then starts sandboxes as usual:
37+
38+
```bash
39+
# shell rc (bash or zsh)
40+
export TEAM_KIT=/path/to/your-team-repo/acq-kits/your-team
41+
. "$TEAM_KIT/env.sh"
42+
```
43+
44+
```bash
45+
acq run opencode /path/to/project
46+
```
47+
48+
`env.sh` puts the team kit first in `ACQ_EXTRA_KITS`, and sets `ACQ_IMAGE`
49+
if you enable it. It is host-side: keep it out of `files[]`. How it works,
50+
and how it interacts with `acq configure`: "Host-side defaults" in the
51+
pattern doc.
52+
53+
4. Validate on every change, and run the live check when the spec or a payload
54+
changes:
55+
56+
```bash
57+
acq kit validate /path/to/your-team-kit
58+
/path/to/your-team-kit/scripts/verify
59+
```
60+
61+
Teammates stack their own kits *after* yours by listing them in
62+
`PERSONAL_KITS` before sourcing `env.sh` (a catalog kit's `git+https` ref
63+
goes here too):
64+
65+
```bash
66+
PERSONAL_KITS="/path/to/personal-kit"
67+
```
68+
69+
Later kits win wherever a field is last-wins (`environment`, `files[]` by
70+
path). Say in this README which of your settings a personal kit may override.
71+
72+
## What it carries (as shipped)
73+
74+
| Extension point | Live value | Replace with |
75+
|-----------------|------------|--------------|
76+
| `caps.network.allow` | `example.org` (an IANA-reserved example domain the global layer does not allow, so `scripts/verify` can observe it) | your team's VCS, package-mirror, and MCP hosts |
77+
| `files[]` | `team-config/opencode.jsonc`, `team-config/team-conventions.md`, a non-empty `.agents/skills/.gitkeep` placeholder (msb rejects empty files) | your conventions, settings, and skills (one `files[]` record per file) |
78+
| `commands[]` | `git config --global push.autoSetupRemote true` at startup | your idempotent per-sandbox setup steps |
79+
| `environment` | `OPENCODE_CONFIG` → the team `opencode.jsonc` | more non-secret settings; never a credential |
80+
81+
The OpenCode wiring gives the settings tier global → team → repo: the global
82+
`usai-provider` kit merges into OpenCode's global config path and leaves
83+
`OPENCODE_CONFIG` free for this layer. The rest of the kit is agent-agnostic.
84+
The conventions file reaches the agent through OpenCode's `instructions`
85+
field, which only OpenCode 1.x loads; `scripts/verify` fails when sandbox
86+
shells run 2.x (see "Check against your acq" in the pattern doc).
87+
88+
## What it does not carry, on purpose
89+
90+
- **Tools and toolchains.** Bake them into the image and point `ACQ_IMAGE` at
91+
it; the published devenv image in this repo is the precedent.
92+
- **Secrets.** `acq secret set -g <service> --host <host> --env <VAR>` on the
93+
host; the sandbox only ever sees a placeholder.
94+
- **Whole shared files** (`~/.bashrc`, `~/.gitconfig`) or **binary files**.
95+
- **Anything the global layer already owns.**
96+
97+
## Writing a skill
98+
99+
A skill is a directory under `files/home/.agents/skills/<name>/` holding a
100+
`SKILL.md` with two frontmatter fields, `name` and `description`, followed by
101+
the procedure. The agent picks a skill by matching its description to the
102+
request.
103+
104+
- **Pick a name the global playbook kit does not use.** The playbook symlinks
105+
its own skills into the same directory at every start, so a same-named team
106+
skill collides with one of them (use `team-code-review`, not
107+
`code-review`).
108+
- **Put the trigger phrases in the description**, worded the way a teammate
109+
would ask, plus one sentence on what the skill produces.
110+
- **Write only the delta:** team conventions, sandbox constraints, the output
111+
contract. Generic advice on how to do the task is padding.
112+
- **Say what the agent must never do on its own** (post, approve, push). The
113+
team `opencode.jsonc` can gate the commands; the skill is where the agent
114+
learns the rule.
115+
- **Keep it small.** Every session loads the description, so keep it under
116+
1024 characters; keep the body under 500 lines and move reference material
117+
into sibling files the body points to.
118+
- **Register every file** in the skill directory as a `files[]` record.
119+
- **Check that the description wins.** Several playbook skills cover nearby
120+
tasks. In a sandbox, ask for the task three ways, one without naming the
121+
skill, and confirm yours loads. Repeat when the playbook pin changes.
122+
123+
## Verifying
124+
125+
```bash
126+
./scripts/verify # needs acq on PATH (or ACQ_DIR) and a sandbox-capable host
127+
KEEP=1 ./scripts/verify # keep the sandbox and work dir for inspection
128+
```
129+
130+
It validates the spec, then creates a throwaway sandbox through `acq`, which
131+
applies the pinned built-in bundle plus, via `ACQ_EXTRA_KITS`, a generated
132+
**lower fixture kit** and then this kit. It asserts that the global layer is
133+
intact, that every live value above landed, and that the composition rules from
134+
the pattern doc hold against the fixture: `environment` last-wins, `files[]`
135+
last-wins by path, `commands[]` append in order, `caps.network.allow` union.
136+
Run it on each backend your team uses; select the backend with `ACQ_BACKEND`.
137+
The values at the top of `scripts/verify` (`TEAM_CONFIG`, `TEAM_CONVENTIONS`,
138+
`TEAM_EGRESS_HOST`) mirror `spec.yaml`: update them whenever you change the
139+
matching path or host. If you replace the git startup step, also update the
140+
startup poll and the `commands[]` check, which both read its git key. Extend its clearly marked **TEAM-SPECIFIC** section as your kit
141+
grows, one assertion per mechanism you add.
142+
143+
## Backend parity
144+
145+
The kit uses no backend-specific features: it is declarative only (`caps`,
146+
`files[]`, `commands[]`, `environment`), with no `backend_shortcuts` or
147+
`backend_extras`, and `scripts/verify` uses only `acq` verbs. The backends
148+
still behave differently (who runs a command with no `user:`, `agentContext`,
149+
how kits re-apply, unlisted files, SSH egress, secret rotation); "Backend
150+
differences" in the pattern doc is the list. Keep this section in your copy
151+
and add anything backend-specific your kit introduces.
152+
153+
## Troubleshooting
154+
155+
See [`TROUBLESHOOTING.md`](TROUBLESHOOTING.md). Record your team's non-obvious
156+
choices as ADRs next to the kit, in [`docs/decisions/`](docs/decisions/). The
157+
sample there records the template's own choice of `OPENCODE_CONFIG`; keep it,
158+
rewrite it, or replace it with your first real decision.
Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
# Troubleshooting — team kit (template)
2+
3+
Failure modes any team's copy inherits. Keep this file in your copy and grow it
4+
with your team's own entries. Every command is an `acq` command. The rules
5+
behind these entries live in the pattern doc (`scope-layers.md`, see the
6+
README); each entry names the section.
7+
8+
## Kit content missing (`OPENCODE_CONFIG` empty, files absent)
9+
10+
Almost always: the shell that *created* the sandbox did not source `env.sh`
11+
(or `TEAM_KIT` pointed at the wrong path), so only the global kits applied.
12+
Check:
13+
14+
```bash
15+
acq exec <sandbox> -- printenv OPENCODE_CONFIG # empty => the kit did not apply
16+
echo "$ACQ_EXTRA_KITS" # on the host: the team kit should come first
17+
```
18+
19+
Fix the rc, then recreate:
20+
21+
```bash
22+
acq rm <sandbox> && acq run opencode /path/to/project
23+
```
24+
25+
Re-running `acq run` alone is not enough: `acq` records a sandbox's extra kits
26+
at creation and reuses that record on reattach. See "Recreating a sandbox" in
27+
the pattern doc.
28+
29+
## Create fails: the backend rejects the kit / unsupported `schemaVersion`
30+
31+
The kit is neutral `hybrid/v1`, which no backend parses natively; `acq`
32+
translates it. If the raw spec reaches the backend (parse errors naming your
33+
spec's fields), the `agentic-coding-quickstart` checkout predates acq's
34+
kit-translate layer. Update it with `git pull`. A bare backend command that
35+
bypasses `acq` fails for the same reason.
36+
37+
## Create fails fetching a global kit over SSH
38+
39+
The create output shows a `[email protected]:` URL and `Permission denied
40+
(publickey)` for one of the pinned kits. A host `url.*.insteadOf` rewrite (for
41+
example `[email protected]:.insteadOf https://github.com/`) sends acq's
42+
anonymous kit fetch over SSH, which fails whenever your SSH key is not
43+
available. Check for one:
44+
45+
```bash
46+
git config --get-regexp 'url\..*insteadOf'
47+
```
48+
49+
Make the key available (load it into your agent) and retry the create.
50+
51+
## A needed host is blocked
52+
53+
On msb, a blocked fetch fails at acq's egress proxy and `acq` prints a diagnosis
54+
naming the host. Add it to `caps.network.allow` and recreate the sandbox:
55+
egress is fixed at creation on every backend. Under org governance, org network
56+
rules override kit rules; a host that stays blocked despite the kit entry must
57+
be allowed at the org level.
58+
59+
## A team setting has the wrong value, or is missing
60+
61+
A kit applied *after* yours (a personal kit) can shadow a team value
62+
silently (see the composition table in the pattern doc). Check what the
63+
sandbox actually has, then look for the same variable name or file path in the
64+
kits listed after yours:
65+
66+
```bash
67+
acq exec <sandbox> -- printenv OPENCODE_CONFIG
68+
acq kit list # the pinned kits plus THIS shell's ACQ_EXTRA_KITS
69+
```
70+
71+
`acq kit list` shows neither `--kit` refs nor the extras recorded for an
72+
existing sandbox, so compare against the `ACQ_EXTRA_KITS` the sandbox was
73+
created with. Move the override, or document it as an allowed personal
74+
override.
75+
76+
## The agent ignores the team conventions
77+
78+
`opencode debug config` lists `team-conventions.md` under `instructions`, but
79+
the agent does not follow it or cannot quote it. Check which OpenCode the
80+
sandbox runs:
81+
82+
```bash
83+
acq exec <sandbox> -- opencode --version
84+
```
85+
86+
OpenCode 2.x accepts `instructions` but never loads the files it lists. See
87+
"Check against your acq" in the pattern doc.
88+
89+
## A daemon still uses the old team settings
90+
91+
A background process that a startup step launched (a web UI serving agent
92+
sessions, for example) read its configuration when it started, so kit changes
93+
that reached the sandbox since then do not reach it. Restart the sandbox:
94+
95+
```bash
96+
acq restart <sandbox>
97+
```
98+
99+
## A startup command did nothing, and validate said OK
100+
101+
`acq kit validate` passes several spec shapes that run nothing or run the
102+
wrong thing: a comment after `phase:` or `user:` (the command is skipped with
103+
only a warning in the create output), a comment after an argv item (it becomes
104+
part of the argument), and flow-style argv (`command: [a, b]`, parsed as
105+
empty). See "Check against your acq" in the pattern doc for the exact rules.
106+
107+
## Files landed, but the env var and startup effects are missing (msb)
108+
109+
One of the kit's `files[]` drops failed, which stops the rest of that kit's
110+
apply on msb. The create output names the file ("could not place kit file at
111+
..."); the usual cause is an empty payload. See "Check against your acq" in the
112+
pattern doc.
113+
114+
## A shipped file is present on sbx but missing on msb
115+
116+
The file is under `files/` but has no `files[]` record in `spec.yaml`. Add the
117+
record with the in-guest absolute path. See "Backend differences" in the
118+
pattern doc.
119+
120+
## git push/fetch hangs or is refused on an SSH remote (msb)
121+
122+
The remote is `git@host:…` or `ssh://git@host/…`, and msb does not carry SSH
123+
to allowed hosts (see "Backend differences"). Adding `host:22` to the allow
124+
list does not help. A `--clone` workspace inherits the host checkout's SSH
125+
origin, so this is the default case for a team VCS and for GitHub. Check what
126+
git will actually contact:
127+
128+
```bash
129+
acq exec <sandbox> -- git -C /path/in/guest/to/repo ls-remote --get-url origin
130+
```
131+
132+
Fix: add the startup step from "Git over HTTPS" in the pattern doc.
133+
134+
## OpenCode: `The socket connection was closed unexpectedly` (msb)
135+
136+
Every request in one session fails the same way, on any model, and reopening
137+
the sandbox does not help, while `curl` to the model endpoint from the same
138+
sandbox succeeds. The session transcript contains a secret placeholder,
139+
usually from a command that printed the environment (`env`, `printenv`), and
140+
msb's proxy fails closed on it (see "Backend differences").
141+
142+
Fix: start a new session; the affected one cannot be sent as-is. Prevent it by
143+
keeping "never print the environment" in the team conventions file.
144+
145+
## Rotating a team token breaks existing sandboxes
146+
147+
The new secret got a new placeholder; existing sandboxes still hold the old
148+
one. Rotate with the same placeholder: see "Backend differences" in the
149+
pattern doc for the command on each backend.
150+
151+
## Inspecting startup state
152+
153+
Startup-command output only prints during `acq run` or `acq create`. Inspect
154+
later with a probe, and recreate to watch the output again:
155+
156+
```bash
157+
acq exec <sandbox> -- sh -c 'git config --global push.autoSetupRemote'
158+
```
Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Decision: Deliver team agent settings through `OPENCODE_CONFIG`
2+
3+
**Status:** accepted (sample: keep, rewrite, or replace it in your copy)
4+
5+
## Context
6+
7+
The team needs settings every teammate's agent shares: team instructions,
8+
permission rules for team tools. OpenCode reads config from three places, in
9+
order: its global config path, the file `OPENCODE_CONFIG` names, and the
10+
repo's own config. Later sources override earlier ones key by key.
11+
12+
The global `usai-provider` kit merges its provider settings into the global
13+
config path at every start, and leaves `OPENCODE_CONFIG` unset. Writing the
14+
team's settings to the global path as well would mean merging with that kit,
15+
or overwriting it.
16+
17+
## Decision
18+
19+
Ship the team's settings as `files/home/team-config/opencode.jsonc` and set
20+
`OPENCODE_CONFIG` to its in-guest path in `environment`. The team kit owns
21+
that variable; a personal kit does not override it.
22+
23+
## Consequences
24+
25+
- Settings tier global → team → repo, with no merge script in this kit.
26+
- `OPENCODE_CONFIG` is single-valued and last-wins across kits, so any later
27+
kit that sets it hides the team settings without a warning.
28+
- The conventions reach the agent through OpenCode's `instructions` field,
29+
which OpenCode 2.x ignores. On an image whose sandbox shells run 2.x, the
30+
team settings still apply but the conventions do not load; `scripts/verify`
31+
fails there.

0 commit comments

Comments
 (0)