ai-build-config-tpl

Example enterprise-level opencode configuration for running opencode agents on a company Phoeniqs AI Build. This repository is a template: clients copy and adapt it to wire their own company-specific rules, agents, providers and MCP servers into opencode.

"Enterprise-specific" means: everything here is shared across all of a company's projects and all agents on the box — company context, coding standards, tooling rules, secret handling and the example agents. It is one of four configuration levels opencode merges together (see below).

The four configuration levels

opencode loads its configuration from four layers. They merge — you normally use all four at once.

Level	Where it lives	How it is wired
1. Base	A shared configuration repo (agents, rules, skills, templates) — its .opencode/ directory	OPENCODE_CONFIG_DIR=/path/to/base/.opencode; its rules load through the glob {env:OPENCODE_CONFIG_DIR}/rules/*.md in the instance opencode.json instructions array. Loaded exactly like a project-local .opencode/ directory, from any working directory.
2. Enterprise (this repo)	.opencode/rules/ in this repository	OPENCODE_COMPANY_RULES_DIR=/path/to/ai-build-config-tpl/.opencode/rules; the glob {env:OPENCODE_COMPANY_RULES_DIR}/*.md goes into the instance opencode.json instructions array alongside the base glob.
3. User	~/.config/opencode/	Writable user config: config.json (MCP servers, providers, settings — the file the frontend/API writes) plus agent/*.md for user-level agents. NOT opencode.json — on a Phoeniqs AI Build that file is the deployment baseline and is overwritten at every boot (see Level 3 below).
4. Project	.opencode/rules/project.md in each target repo	Auto-loaded via the project-relative glob .opencode/rules/*.md, plus an optional repo-local opencode.json for per-repo overrides.

Level 1 — Base. The shared backbone that ships agents, rules, skills and templates for all company boxes. OPENCODE_CONFIG_DIR points at its .opencode/ directory; opencode then treats it like a project-local .opencode/ and loads its rules through the {env:OPENCODE_CONFIG_DIR}/rules/*.md glob. It is read from any working directory, for every session on the box.

Level 2 — Enterprise (this repository). Holds only what is company-specific: company context, coding standards, tooling rules, secret handling. OPENCODE_COMPANY_RULES_DIR points at its .opencode/rules/ folder and the {env:OPENCODE_COMPANY_RULES_DIR}/*.md glob loads every rule file into every session, on top of the base rules.

Platform note. On the Phoeniqs AI Build platform this variable normally points INSIDE the shared config checkout — at .opencode/company/<name>/rules/, the per-box company knowledge (one name per box, e.g. one tenant per brand). This template reuses the variable and the glob for a separate enterprise repository instead: same mechanism, different target. On the platform the company settings repo is also not wired by hand — the first-time wizard checks it out into the workspace once git credentials exist, and the entrypoint activates it at every restart via OPENCODE_CONFIG; the manual wiring below is for a box without that wizard.

Level 3 — User. Each human's own config. ~/.config/opencode/config.json holds personal MCP servers, providers and settings — this is the runtime-writable file the frontend/API writes; ~/.config/opencode/agent/*.md holds personal agents. Nothing here is shared with anyone else. Do NOT hand-edit ~/.config/opencode/opencode.json: on a Phoeniqs AI Build that file is the deployment baseline — the image re-copies it over at every boot (a .bak is kept), so hand edits there are lost.

Level 4 — Project. Per-repo settings. .opencode/rules/project.md (plus any other .md in the repo's .opencode/rules/) is auto-loaded when working in that repo; a repo-local opencode.json can override other config keys — with one gotcha below.

Gotchas (read before wiring)

• Empty globs are silently ignored. opencode does not error when an instructions glob matches nothing — it just loads nothing from it. And files matched by more than one glob are deduplicated, so combining base + enterprise + project globs is always safe.
• instructions arrays concatenate. Config sources merge per key — a later source wins for conflicting keys — but instructions is the exception: entries from all sources are concatenated and deduplicated. A repo-local opencode.json that lists instructions therefore ADDS its globs on top of the base, enterprise and project rules rather than replacing them. Even so, prefer adding repo rules by dropping files into the repo's .opencode/rules/ instead of editing opencode.json — the project glob picks them up, no config edit needed.
• Config is loaded once at startup. After changing opencode.json, an agent file, a rule file or any of the env vars, restart opencode. Running sessions keep the already-loaded config. (On a Phoeniqs AI Build the Settings UI is the exception: it hot-applies the company layer without a restart by re-rendering the company config and patching the user file through the API — directly edited files still need a restart.)
• Shared agents override project agents. An agent file in the shared config directory (OPENCODE_CONFIG_DIR) is loaded after the project .opencode/ — so an agent file there wins over a project agent of the same name. Name your shared agents deliberately.

How the example agents load

This repo ships two example agents in .opencode/agent/: example-assistant (primary entry point) and example-reviewer (read-only subagent). Two options:

(a) Self-contained — use this repo AS the base config. Point OPENCODE_CONFIG_DIR at this repo's .opencode/ directory. The example agents then load directly as the shared agents for every session. Good for a first evaluation or a box without an existing base config.

(b) Combined with an existing base config. Keep your real base repo as OPENCODE_CONFIG_DIR and copy the example agents to one of:

• ~/.config/opencode/agent/ — user level, loaded for that person everywhere, or
• <project>/.opencode/agent/ — project level, loaded only in that repo.

Step-by-step wiring

1. Check out this repo on the box, e.g. git clone ssh://git@git-ssh.[company].example:2222/[org]/ai-build-config-tpl.git /path/to/ai-build-config-tpl.
2. Set OPENCODE_CONFIG_DIR — to this repo's .opencode/ for the self-contained setup (/path/to/ai-build-config-tpl/.opencode), or keep your existing base repo's path.
3. Set OPENCODE_COMPANY_RULES_DIR=/path/to/ai-build-config-tpl/.opencode/rules — this wires the enterprise rules (level 2).
4. Add the instruction globs to your instance opencode.json instructions array — the base and enterprise globs, plus the project-profile glob if your instance config does not already carry it; see opencode.example.json in this repo for the exact keys, globs and format (three globs).
5. Restart opencode. Directly edited config files are not hot-reloaded; the running session keeps the previously loaded config. (On a Phoeniqs AI Build, the Settings UI hot-applies the company layer without a restart — see Gotchas.)
6. Verify. In a new session, ask the agent "which company rules are loaded?" — it must list company-context, coding-standards, tooling and secrets (they appear in the session context). Also confirm the default agent is example-assistant and that a delegated review lands with example-reviewer.

opencode.example.json reference

Key	Purpose
$schema	Pins the opencode config schema so editors validate as you type.
default_agent	Entry point agent for sessions — example-assistant here.
instructions	The three rule globs: base (level 1), enterprise (level 2, this repo), project profiles (level 4).
permission	Safety net: ask before every edit and shell command, with read-only git allows.
provider (commented out)	Placeholder for your OpenAI-compatible / MaaS provider — plug your models in.
mcp (commented out)	Placeholder for your MCP servers — one remote and one local example.

Adaptation guide

Replace every placeholder before production use. Work through the files in this order:

Placeholder	What to put there	File
[Company Name], [Legal Entity Name], tagline, positioning, offices, values	Your company overview	.opencode/rules/company-context.md
[Product A], [Product B], [Product C]	Your products and services	.opencode/rules/company-context.md
Compliance rows	Your certifications and audit facts	.opencode/rules/company-context.md
https://….[company].example URLs	Your wiki, git host, CI, ticket system, registry	.opencode/rules/company-context.md, .opencode/rules/tooling.md
Approved stack, lint/format commands, test commands, PR rules	Your engineering conventions	.opencode/rules/coding-standards.md
Workspace layout, environment names, CI behaviour	Your tooling reality	.opencode/rules/tooling.md
Secret-store location, SOPS/KMS reference, settings path	Your secret-handling setup	.opencode/rules/secrets.md
Agent names, prompts, review criteria	Your own agents	.opencode/agent/example-assistant.md, .opencode/agent/example-reviewer.md
default_agent, provider, mcp values	Your instance wiring	opencode.example.json

Also decide how the agents load (option a or b above): keep example-assistant as the starting point and rewrite it into your real entry-point agent.

Repository layout

ai-build-config-tpl/
├── README.md                        # this file
├── opencode.example.json            # example instance config (jsonc) — copy keys from here
├── .gitignore                       # local env files, macOS noise
└── .opencode/
    ├── agent/
    │   ├── example-assistant.md     # example PRIMARY agent — session entry point
    │   └── example-reviewer.md      # example SUBAGENT — read-only reviewer
    ├── references/
    │   └── projects.yaml            # company projects catalog (Settings -> Projects); placeholder-only
    └── rules/
        ├── company-context.md       # level 2: company knowledge (names, products, URLs)
        ├── coding-standards.md      # level 2: engineering conventions
        ├── tooling.md               # level 2: git / CI-CD / environments rules
        └── secrets.md               # level 2: secret handling

Without .opencode/references/projects.yaml a Phoeniqs AI Build treats this repository as "no company catalog" — keep the file (even with example entries) so freshly pointed boxes come up with a visible, editable catalog.

The same applies to the root opencode.json: the Phoeniqs AI Build checks a company-settings checkout for both this file and the .opencode/ tree before treating it as active — the template therefore ships a working minimal one (the level-2 enterprise repo on the platform ALSO acts as the instance baseline; opencode.example.json stays the annotated tour and is never loaded).

Placeholders notice

All content in this repository is placeholder-only. Company names, products, URLs, hostnames, commands and credential-shaped strings are examples ([Company Name], [Product A], https://wiki.[company].example). Nothing here references a real system and no real credential appears anywhere, so the repo is safe to publish and share. Replace every placeholder with your company's real facts before running agents with this config in production — and never commit real credentials to git.