OpenCode for Production Website Development

OpenCode is a sensible choice for website teams that want the agent interface and the production repository to remain separate from the model provider. Its official documentation describes an open-source coding agent available in a terminal interface, desktop app, and IDE extension, with configurable model providers. The repository still needs to carry the architecture, design constraints, and definition of done.

That separation is the main reason to consider it. OpenCode supplies an execution environment. Brief & Ship supplies the website system.

What OpenCode brings to the project

OpenCode can inspect a codebase, plan a change, edit files, and run the commands needed to check the result. Its documented Plan mode disables changes while the agent proposes an approach; Build mode performs the implementation. The official workflow also includes undo and redo controls.

For a static Astro site, this maps to a clean operating loop:

1. read the brief and project instructions;
2. inspect the collection, layout, styles, and QA scripts;
3. propose the narrowest coherent change;
4. edit content or components;
5. run the production checks;
6. inspect the output before delivery.

OpenCode’s provider configuration gives teams a practical choice of models. It does not make models interchangeable. Different models may interpret a vague instruction differently, use tools differently, or stop at different points. The way to make the workflow portable is to improve the repository’s constraints, not assume identical agent behavior.

Permissions need deliberate defaults

OpenCode documents allow, ask, and deny permission outcomes with granular rules for commands and paths. Its current defaults permit many ordinary actions, while Plan mode changes editing and shell behavior to require approval. Review those defaults before placing it in a repository with deployment credentials or adjacent private files.

Permissions should match the phase of work. Planning needs repository reads and perhaps official documentation. Implementation needs writes only in assigned paths plus the local build toolchain. Verification may need a server process or static-file inspection. Deployment needs separate authorization and should not be available merely because the earlier phases used the same terminal.

Provider credentials create another boundary. Store them through the supported secret mechanism, not in opencode.json, AGENTS.md, or a copied shell command. If several providers are configured, document which environments they may access and which model was used for any formal evaluation.

AGENTS.md is the shared contract

OpenCode uses AGENTS.md for project guidance and recommends committing it to Git. Its rules documentation says /init can scan a repository and create or update a concise instruction file containing commands, architecture, conventions, and operational details.

For Brief & Ship, AGENTS.md should be maintained intentionally rather than treated as generated setup. It can establish:

• Astro static output as an architectural requirement;
• the approved content and component directories;
• design tokens that must not be bypassed;
• the metadata and structured-data conventions;
• the quality commands and expected order;
• external actions that need explicit approval.

OpenCode also supports extra instruction files through opencode.json. That can help a larger project route specific standards without making the root instructions unwieldy. The website AGENTS.md guide explains how to keep shared guidance concise enough to remain useful.

The precedence model deserves attention during migration. OpenCode documents AGENTS.md as the project rule and supports CLAUDE.md as a fallback in specific circumstances. A fallback is not a merge. If both files exist, verify which content reaches the current version rather than assuming the agent receives every rule written for another tool.

Use opencode.json instruction paths for maintained documents that genuinely apply to the agent. Do not point it at a directory of long strategy notes and expect it to infer precedence. A short route to a relevant standard is easier to update and easier to audit.

Building an Astro feature with OpenCode

Consider a request to add a technical guide. The visible result is an article, but the work may touch frontmatter, a content collection, internal relationships, a source list, and the sitemap. A disciplined task gives OpenCode the intent and the checks:

Add one indexable guide for deploying a static Astro site to Cloudflare. Use the existing editorial collection and technical voice. Cite official sources. Keep all rendering static. Do not change design tokens. Run content validation and the production build.

The task does not prescribe every file. It does establish what cannot be improvised.

During planning, ask the agent to identify the current route model and likely cannibalization. During implementation, keep file ownership explicit if other work is happening in parallel. At verification, request the actual command output and inspect the emitted page.

The same method applies to a component change. If a comparison table is missing, OpenCode can extend the existing article system. The brief should require semantic table markup, keyboard-safe overflow behavior, existing border and type tokens, and no client hydration.

A provider-neutral acceptance test

The acceptance criteria should not change when the selected model changes. For the guide example, require the same route, source fields, link integrity, heading order, static output, and asset budget. Save the task brief and command results if you are evaluating two providers.

Then compare artifacts, not conversation style. Did each run respect file ownership? Did the page need corrections for unsupported claims? Did it reuse the design system? Did all commands finish? Those observations are useful internal evidence. One successful run is still not a general benchmark.

This approach lets provider choice remain reversible. The repository defines the target while the agent and model combination is one implementation variable.

Where OpenCode is particularly useful

OpenCode is attractive when model and provider choice is an operating requirement. A team can keep its repository conventions stable while evaluating which supported provider fits a task, budget, or policy. The source-controlled instructions and tests stay in place.

It also fits teams that prefer terminal-first work but do not want the website architecture coupled to one coding product. That matters over a multi-year site lifespan. Agents will change faster than the content model, URL structure, or design system should.

Its open-source distribution may also make the tool easier to inspect or integrate into an existing developer environment. That does not remove the need to review configured providers, permissions, data handling, and release changes for your own environment.

The tradeoffs

Provider flexibility creates more configuration surface. Authentication, model selection, permissions, and provider-specific behavior all become part of the operating setup. A person who wants one supported default may prefer a more vertically integrated agent.

Portability can also be overstated. AGENTS.md gives several agents a common starting point, but tool names, permission models, rule precedence, and context behavior differ. Keep shared instructions at the level of outcomes and repository facts. Put tool-specific commands in the tool’s own configuration only when required.

OpenCode’s documentation changes as the project evolves. Pin operational assumptions in your repository, record the version used for sensitive automation, and check official docs before relying on a recently added feature.

There is also a context cost to extensibility. OpenCode’s documentation warns that MCP tools consume context and that too many servers or tools can become expensive to carry. Configure the tools required for the task instead of connecting every available service. A static Astro content change rarely needs access to analytics, billing, or infrastructure APIs.

Provider flexibility can complicate support. If a run behaves unexpectedly, isolate whether the cause is the repository instructions, OpenCode configuration, selected provider, model, permission rule, or tool integration. Record those variables before changing the prompt repeatedly.

What it should not be asked to invent

OpenCode should not define a brand from a blank page while also implementing it. It should not generate dozens of near-identical routes because the schema accepts them. It should not infer that a successful Astro build proves accessibility, search quality, or business accuracy.

Those gaps are systemic. A static page can still ship poor metadata, vague copy, unverified claims, or unnecessary JavaScript. The AI website performance guide shows why output budgets and hydration rules belong in the repository.

It should also not treat /undo as a substitute for Git. OpenCode can reverse changes in its session, but production work needs a durable diff, known branch state, and a clear account of untracked files. Check Git before and after a wide edit.

How Brief & Ship works with OpenCode

Brief & Ship gives OpenCode a prepared environment: Astro structure, content schemas, native editorial components, design tokens, quality gates, and deployment documentation. The goal is not to script every edit. It is to prevent familiar production mistakes before the agent reaches them.

A non-developer can then work at the level of the brief: audience, commercial goal, content, examples, and acceptance criteria. The agent can translate those requirements into the project’s established code patterns. The checks provide a second opinion that does not depend on the prose of the final response.

The practical decision

Choose OpenCode if model-provider choice and an open-source agent interface matter to your workflow. Expect to own more configuration and to verify behavior across the models you select. Use AGENTS.md as the portable contract, but do not pretend it makes every agent identical.

For Brief & Ship, that is a healthy division of responsibility: the agent may change; the production system remains legible.