Day 21

Multi-CLI development and context architecture

You ship
An agentic development setup across 3 CLIs, a company brain, and a one-page guide.

What you'll build today

For four weeks you have built WorkBot mostly with one coding agent, Claude Code. Week 5 starts by upgrading the way you work. Other agents, such as the Codex CLI and OpenCode, are good at different jobs. But each one reads its instructions, permissions and tools from its own files, so a team that uses all three needs one policy that every agent follows.

Today you write that policy once and check that each agent loads it. Then you give the agents the background they need: the brain, a folder of short notes on the product, the decisions behind it, the customer and the house style. An agent reads a note only when a task needs it. Each task arrives as a brief, an issue with a goal, acceptance criteria and constraints, so you learn to separate the context that lasts from the context of one task.

By the end of the day you have shipped 3 tasks, one with each agent, and written a one-page guide on where each was faster or clearer.

By the end of the day you can

  • Work across Claude Code, Codex CLI and OpenCode, and choose one for each task
  • Design the context an agent gets: the company brain, which stays from task to task, and the brief for one task
  • Configure instruction files, skills and permissions once, and share them across a team

Topics

The CLIs

  • Claude Code, Codex CLI and OpenCode have the same shape: a terminal agent with tools, instruction files, Model Context Protocol (MCP) servers and permissions. They differ in defaults, models and strengths
  • Instruction files: AGENTS.md as the one source, and a CLAUDE.md that imports it, at repository, package and user level
  • Permissions and sandboxes: approval modes, allowed commands and network access, in a team policy committed to the repository
  • Skills and custom commands across CLIs, and MCP servers declared from one list in each CLI's configuration

Terminals + Editors

  • Terminals built for agents: Ghostty, cmux, Orca. What matters is panes, notifications and session persistence
  • Editors: Cursor for code with agents, and Obsidian for the notes, specs and brain the agents read
  • The layout: one pane per agent, one browser, one notes app

Context Architecture

  • Global context: the company brain (product docs, architecture decisions, customer notes, style guides), kept as files the agent reads
  • Per-task context: the issue, its acceptance criteria, the design, the related code, the session link
  • Connecting the brain: a folder or vault of Markdown that agents read by path, with an index. Decide what to keep current and what to archive
  • Briefs from GitHub issues: the issue is the spec (Day 3). Its template requires a goal and acceptance criteria, and asks for constraints
  • Session links: a cloud or remote-control session is the unit of handoff between people and agents. Link it from the issue and the pull request
  • Context budgets: what every session gets, and what the agent fetches only when it needs it

Working Practices

  • Plan mode before edits, for anything that touches more than one package
  • Small pull requests, with the brief, the plan and the session link in the description
  • Reviewing an agent's output: read the diff, run the tests, check the brief. Never approve on the agent's summary

Build

Features shipped today

  • WorkBot: Instruction files for the repository and each package, and WorkBot described in the company brain

Set up your agentic development environment and use it for a day:

  1. Install Claude Code, Codex CLI and OpenCode. Write one shared repository policy: instruction files at repository and package level, a permission policy, MCP servers (such as GitHub, Linear and the Day 5 database server) and skills. Check that each CLI picks them up
  2. Build the company brain: a folder of Markdown notes on the product, architecture, customer and style, with an index and a retention rule. Point all 3 CLIs at it from their instruction files
  3. Write issue templates that require a goal and acceptance criteria and ask for constraints. Add a session-link convention to pull request descriptions
  4. Ship the day's tasks, each with a different CLI, from issue to merged pull request. Record where each CLI was faster or clearer
  5. Write your agentic development guide from the findings: one page, committed to the repository

Step by step

One policy for 3 CLIs

Claude Code, Codex and OpenCode all read instruction files, permissions, skills and Model Context Protocol (MCP) servers, the tool servers you built on Day 5. Each one reads them from different files, so keep one source for the policy and check that every CLI loads it.

Study first

  • Instruction files: Codex and OpenCode read AGENTS.md, while Claude Code reads CLAUDE.md (version 2.1 in the reference run). A CLAUDE.md of one line, @AGENTS.md, imports AGENTS.md, so one file serves all three. Nested files work differently in each CLI. Codex reads a nested AGENTS.md as it works in that folder, and Claude Code reads a nested CLAUDE.md the same way. OpenCode 1.19 needs the nested files listed in its instructions, and falls back to CLAUDE.md only where no AGENTS.md exists.
  • Configuration for each CLI: Claude Code reads .claude/settings.json for permissions and hooks, and .mcp.json for its servers. Codex reads .codex/config.toml, but only for a project that ~/.codex/config.toml marks as trusted. OpenCode reads opencode.jsonc, with the keys mcp, instructions and permission.
  • Skills: Claude Code reads .claude/skills/<name>/SKILL.md, and Codex needs a [[skills.config]] entry pointing at each of the same folders. OpenCode 1.19 loads .claude/skills by itself, on demand, through its skill tool. OpenCode's commands, which a person runs as /name, are plain files in .opencode/commands/ with a description in their front matter.
  • Flags and keys change between versions, so before you rely on one, read codex exec --help and the configuration references for Codex and OpenCode.

Build

  1. Rename the nested CLAUDE.md files in site/, src/app/api/ and content/knowledge/ to AGENTS.md, and leave a CLAUDE.md of one line, @AGENTS.md, beside each one.
  2. In .claude/settings.json, allow the checks and read-only git commands without asking, and deny both reading .env.local and rm -rf.
  3. In .codex/config.toml, set approval_policy = "on-request". Add a permission profile under [permissions.<name>] that extends :workspace and denies **/.env and **/.env.local in its workspace roots, then select it with default_permissions. Add the 5 MCP servers from .mcp.json as [mcp_servers.<name>] entries, and the 4 skills as [[skills.config]] entries.
  4. In opencode.jsonc, list the nested AGENTS.md files and brain/README.md under instructions. Add the 5 servers under mcp, where a local server takes type: "local" with a command array and a remote one takes type: "remote" with a url. Set permission so that edits are allowed, bash commands ask first, and reads of .env files are denied.
  5. Write scripts/sync-commands.mjs, which writes .opencode/commands/<skill>.md from each skill with OpenCode's front matter. Run pnpm sync:commands whenever a skill changes.
  6. Add a section to the root AGENTS.md that says where each CLI reads the policy from.
  7. Write scripts/agent-config.test.ts to keep the 3 configurations in step. It checks that .mcp.json, .codex/config.toml and opencode.jsonc name the same servers, and that every nested AGENTS.md is an OpenCode instruction with a CLAUDE.md beside it. It also checks that every skill has a Codex entry, and that its OpenCode command equals what the sync script writes. pnpm test scripts runs the test on its own, and pnpm test runs it with the rest.

Done when

  • pnpm test scripts passes.
  • Each CLI names its instruction files, servers and skills when you ask it. Ask Claude Code with claude -p --allowedTools "Read,Glob,Grep", which leaves it no write tool, and ask Codex with codex exec --sandbox read-only. Ask OpenCode with opencode run, and deny the shell for that run with OPENCODE_CONFIG_CONTENT='{"permission":{"bash":"deny"}}', because under bash: ask a non-interactive run ends at the first command it refuses.
  • An env file is out of reach. Asked to read one, opencode run answers with the rule that stops it, and codex sandbox --permission-profile <name> -C <repo> -- cat .env.local fails with "Operation not permitted" while .env.example still reads.
The 3 CLIs asked what they see
The same question to Claude Code, the Codex CLI and OpenCode, and the instruction files, MCP servers and skills each one reports.
OpenCode refusing an env file
Asked to read an env file, OpenCode answers with the rule that stops it. The project's deny pattern wins over OpenCode's default, which would ask.
Technical notes
  • Codex ignores some keys in a project config, such as model_provider, so keep those in your user config. A permission profile needs Codex 0.138 or later, and is in beta. It applies only when no loaded config sets the older sandbox_mode, your own user config included, and passing --sandbox on the command line brings the older settings back. To test the profile on its own, use codex sandbox --permission-profile.
  • Claude Code likewise ignores a project's permissions.allow entries until you have trusted the workspace once in an interactive session, and it says so at the start of a non-interactive run.
  • The sync script writes OpenCode's commands from the skills instead of linking to them, so each command carries only the front matter OpenCode documents. pnpm sync:commands rewrites the directory, and the test compares it with the skills.
  • OpenCode's glob tool does not match files under dot-directories, as the screenshot shows with 0 matches for .opencode/commands/*. Its read tool lists a directory, which is how the probe, the question you ask each CLI, reaches the commands.
  • In a non-interactive OpenCode run, a permission that would ask is refused, and the run ends there. A rule that denies instead returns to the model as an error it can work around, which is the kind a probe needs.
  • Never put a secret in a config file. The local MCP servers, which run over stdio, read .env.local through --env-file-if-exists. Each CLI has its own rule against reading that file: Claude Code's deny list, OpenCode's read pattern and Codex's profile.

The brain

With the policy in place, every agent starts from the same rules. But the rules do not say what the product is for, why it was built this way, or who the customer is. The brain is a folder of notes in your repository, brain/, that holds this context, which stays true from task to task. An agent finds a note in an index and reads it by its path when a task needs it, so nothing in the brain is loaded into every prompt. A retention rule keeps the notes from going stale.

Study first

  • Global context and per-task context: the brain is global context, which an agent reads by path when a task needs it. The brief is per-task context, written for one task. The budget rule is that every session reads AGENTS.md, and the agent fetches the rest when it needs it. Anthropic's post on context engineering for agents calls this just-in-time retrieval, where an agent keeps file paths and loads a file when it needs it.
  • What a decision note holds: what was decided, why, what it costs, what reversing it would take, and the date. When you reverse a decision, mark it superseded in place, and never delete it. Martin Fowler's note on the architecture decision record uses the same shape, and links a superseded record to the one that replaced it.

Build

  1. Write brain/README.md, with an index table that gives each note a Reviewed date, the retention rule, and how to add a note. Under the retention rule, a note moves to archive/ after 90 days without a review, but decisions are never archived.
  2. Write 5 notes. brain/product/workbot.md covers WorkBot's surfaces, who uses each, and what WorkBot does not do. brain/architecture/decisions.md numbers the decisions from Days 5 to 21 as D1, D2 and so on, 11 in the reference run, and later days cite a decision by that number. brain/customers/fieldstone-supply.md covers the customer's teams, its documents, and what it asked for and was promised. Then write brain/style/writing.md and brain/style/code.md.
  3. Add a "Company brain" section to the root AGENTS.md, which tells an agent to read the index first and to cite the note it relied on. The knowledge base under content/knowledge/ is for a different audience, because it holds the customer's documents, which WorkBot's assistant answers from.

Done when

  • The index links every note, each with a Reviewed date.
  • brain/architecture/decisions.md has a numbered entry for each decision, with what it would take to reverse it.
Technical notes
  • WorkBot's assistant, which answers Fieldstone Supply's questions, never reads the brain.
  • When a note makes a claim taken from code, link the file, so the monthly review can read the file beside the note.

Briefs and a task per CLI

The brain holds what lasts, and a brief holds what one task needs. Give each brief a goal, acceptance criteria and constraints, and let the pull request carry the brief, the plan and a link to the session that produced the work. Then ship 3 tasks, one with each CLI, and write down where each was faster or clearer.

Study first

  • The issue is the spec (Day 3). An issue form requires acceptance criteria, and a team rule sends back any task without checkable outcomes before an agent reads it. The form cannot enforce that rule; people do.
  • Session links: put a cloud session's link, or a local session's id, in the pull request, one for each CLI you used. The next person can then continue the session instead of starting over.
  • Reviewing an agent's output: read the diff, run the tests, and check the criteria one by one.
  • The mode each CLI runs in today. Claude Code's plan mode reads and plans, and edits nothing until you approve the plan. The Codex page on non-interactive mode covers codex exec, its sandbox and approval flags, and how to resume a session. OpenCode's command reference lists the flags of opencode run, such as --dir, -m and --auto.

Build

  1. Specify the templates, which are one of today's 3 tasks. .github/ISSUE_TEMPLATE/task.yml is an issue form with Goal and Acceptance criteria required, plus Constraints, Related code and docs, and Session link. .github/ISSUE_TEMPLATE/config.yml turns blank issues off, and .github/pull_request_template.md has the sections Brief (Closes #), Plan, Session (one line per CLI used) and Checks.
  2. File the day's 3 tasks as issues with those fields: the policy and the brain, the templates themselves, and the configuration test.
  3. Do the open-ended task, the policy and the brain, in Claude Code, interactively. It touches 4 packages, so start in plan mode, the mode that reads and plans before any edit, and keep the plan for the pull request. The task is done when the issue's criteria hold.
  4. Give the templates to the Codex CLI to run non-interactively, with codex exec --approve-for-me -C <repo> "<the brief>", which runs in a sandbox that can write inside the working tree and nowhere else. Check the files against the criteria. In the commit body, record the CLI, its version, the model, the time, and Closes #<n>.
  5. Give the test to OpenCode, with opencode run --auto --dir <repo> -m <provider/model> "<the brief>", where opencode models lists the models you have configured. Put pnpm exec vitest run scripts/agent-config.test.ts and pnpm exec eslint --max-warnings 0 scripts in the brief. Then read the file, run both commands yourself, and commit the same way.
  6. Write docs/agentic-development.md, one page long. Describe the policy in files, the brain, and the workflow from issue to merged pull request with the session-link convention. Record the 3 tasks with their times and what happened, and where each CLI was faster or clearer. End with how to check that a CLI picks the policy up, and with your terminal and editor layout.

Done when

  • Commits on the day's pull request close the 3 issues, and each commit names the CLI, its version, the model and the time the task took.
  • The pull request carries the brief, the plan and a session for each CLI.
  • The guide's table has a row for each task.
Technical notes
  • Flags change between versions. In Codex 0.157, --full-auto is gone and --sandbox cannot be combined with --approve-for-me. In the reference run, that made the first 2 runs fail on the command line, not on the task. Read codex exec --help before a non-interactive run.
  • OpenCode runs on whichever providers you have configured. In the reference run the Anthropic provider was not configured, so the task ran on DeepSeek V4 Pro, which also tested the brief on a different model family.
  • A closed brief names the exact files and fields. With closed briefs in the reference run, Codex took 21 seconds of wall-clock time for 3 template files. OpenCode took 90 seconds for a test file, with a loop of writing, running and fixing. The open-ended task took a whole session, not seconds.
  • When an agent writes a commit, the commit body says so and names the brief it came from. The code itself never mentions a tool, a session or a ticket.
  • Claude Code, the Codex CLI and OpenCode each install with one command from their docs. The reference run used Claude Code 2.1, Codex 0.157 and OpenCode 1.19. Its layout was cmux, a terminal built for agents, with one pane per agent, beside the Chrome window the agents drive and the brain open in a Markdown editor.

Resources