Skip to content

Commit 44d58f3

Browse files
committed
chore(opencode): keep global instructions in AGENTS.md
OpenCode V2 accepts the instructions array but never loads the files it names, so the secrets policy would silently drop out after an upgrade. Inline it into AGENTS.md, which V1 and V2 both read, and remove the array. The private-overlay glob it also listed matched no files. Refs: anomalyco/opencode#51341
1 parent 074e06f commit 44d58f3

5 files changed

Lines changed: 48 additions & 47 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -11,7 +11,7 @@ actually loads it.
1111
| Reader | Loads | How |
1212
|---|---|---|
1313
| Maintainer — OpenCode, or a Hermes profile doing repo upkeep (Engineer via OpenCode, the Assistant's Admin topic) | this file, then the subtree's `AGENTS.md` | on demand, when a task touches the subtree |
14-
| OpenCode, every session | `opencode/AGENTS.md`, `opencode/instructions/*.md` | global instructions (`opencode.jsonc`) |
14+
| OpenCode, every session | `opencode/AGENTS.md` | global instructions (no `instructions` array: V2 does not load it) |
1515
| Hermes profiles at runtime | their `config.yaml` (`agent.system_prompt`), `SOUL.md`, skills | per `HERMES_HOME`; never this repo's docs |
1616
| Hermes Assistant at runtime | also `~/Workspaces/AGENTS.md` (private overlay) | its `terminal.cwd` is `~/Workspaces` |
1717
| Other CLIs (Claude, Codex, Gemini, Grok, Copilot) | `<tool>/` instruction files | symlinked to each tool's home by `install.sh` |

‎opencode/AGENTS.md‎

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -198,4 +198,44 @@ failures are non-obvious or require code changes.
198198

199199
</VerificationDelegation>
200200

201+
<SecretsPolicy>
202+
<StorageModel>
203+
204+
Secrets on this machine are injected from the macOS Keychain by PATH shims
205+
(`~/.config/bin/*` -> `secret-shim`), never from committed files.
206+
207+
</StorageModel>
208+
209+
<Rules>
210+
211+
- Never reveal secret values. The OpenCode process environment may already hold
212+
global/tool secrets such as `*_API_KEY`, `MCP_*`, `TAVILY_*`, or
213+
`OPENCODE_SERVER_PASSWORD`. Do not run `env`, `printenv`, or `echo $SECRET`,
214+
and never write a value into a file, log, or commit.
215+
- Secrets arrive as environment variables inside the launched program, not as
216+
values the parent shell can expand. Reference them by name at runtime:
217+
`process.env.X`, `os.environ["X"]`, or `$X` inside the program. Passing
218+
`cmd --key=$X` from the shell, or baking `$X` into a script run with
219+
`bash`/`sh`, yields empty or leaked values.
220+
- Project secrets auto-inject only into these commands, inside a git repo:
221+
`node npm pnpm bun bunx yarn npx python python3 uv docker docker-compose`.
222+
Other launchers (`cargo`, `go`, `make`, `pytest`, `ruby`, `php`, `deno`,
223+
`./script.sh`) get no project secrets. Route the work through an allowlisted
224+
command, or wrap the tool.
225+
- Use the `secret` CLI directly for metadata, for example `secret ls` or
226+
`secret show NAME`. A launcher in `~/.config/bin` makes it callable here.
227+
Reads are auto-approved; `get`, `rm`, `export`, and `import` are blocked.
228+
Prefer storing new secrets in the Keychain (`secret set NAME -p <project>`, or
229+
`-S` for repo scope) over writing plaintext `.env` files.
230+
231+
</Rules>
232+
233+
<SkillEscalation>
234+
235+
For injection modes, debugging missing environment variables, and wrapping new
236+
tools, load the `keychain-secrets` skill.
237+
238+
</SkillEscalation>
239+
</SecretsPolicy>
240+
201241
</GlobalAgentInstructions>

‎opencode/README.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -12,11 +12,14 @@ needed.
1212
| `AGENTS.md` | global instructions, loaded into every session |
1313
| `agent/` | custom agents / subagents (`*.md`) |
1414
| `command/` | custom slash commands (`*.md`) |
15-
| `instructions/` | extra instruction files referenced from `opencode.jsonc` |
1615
| `plugins/` | plugins (`*.ts`) |
1716
| `skills/` | opencode-only skills (`<name>/SKILL.md`) |
1817
| `tool/` | custom tools (`*.ts`) |
1918

19+
All global instructions live in `AGENTS.md`. Do not reintroduce an
20+
`instructions` array: OpenCode V2 accepts the key but does not load its files
21+
(anomalyco/opencode#51341).
22+
2023
Empty directories carry a `.gitkeep` so the skeleton survives a fresh clone.
2124

2225
`skills/` holds only the skills that depend on opencode itself — its

‎opencode/instructions/secrets.md‎

Lines changed: 0 additions & 39 deletions
This file was deleted.

‎opencode/opencode.jsonc‎

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -59,12 +59,9 @@
5959
// and would display Hermes' usage). Re-apply the patch after a version bump.
6060
"@slkiser/[email protected]"
6161
],
62-
"instructions": [
63-
"instructions/*.txt",
64-
"instructions/*.md",
65-
// Private-overlay instructions (silently empty on machines without ~/.config/private).
66-
"../private/opencode/instructions/*.md"
67-
],
62+
// No "instructions" array: OpenCode V2 accepts it but never loads the files
63+
// (anomalyco/opencode#51341). All global rules live in AGENTS.md, which both
64+
// V1 and V2 read.
6865
"small_model": "openai/gpt-6-luna",
6966
"agent": {
7067
"plan": {

0 commit comments

Comments
 (0)