Skip to content

architecture.md

Latest commit

 

History

History
75 lines (52 loc) · 3.65 KB

architecture.md

File metadata and controls

75 lines (52 loc) · 3.65 KB

OpenCode-First Architecture

Overview

This repository documents the native-first OpenCode workflow adopted in April 2026.

The core rule is still the same:

one primary owner per task phase, with overlays only when they add a distinct kind of value.

What changed is the implementation strategy. Instead of keeping multiple heavyweight workflow systems active all the time, the current stack uses OpenCode's native agents, commands, and plugins as the baseline, then brings in stronger models or external evidence only when the task actually needs them.

Design goals

  • keep the always-loaded context small
  • make planning, testing, implementation, review, and verification explicit
  • route strong models on demand instead of paying their cost on every turn
  • preserve one clear owner at a time
  • keep optional extensions optional

Layers

Layer Tooling Responsibility
0. Native runtime OpenCode agents, subagents, model routing, variants Default ownership, day-to-day execution, model selection
1. Durable instructions AGENTS.md, CONTRIBUTING.md, project docs Stable rules, safety boundaries, coding standards
2. On-demand skills Optional framework/domain skills such as Superpowers Specialist guidance only when the domain clearly matches
3. Workflow commands /plan, /spec, /implement, /review, /verify, /release Repeatable task flows with explicit models and outputs
4. Runtime plugins smart-compaction, verify-gate Context retention and soft verification gates
5. External evidence Sentry MCP, optional OpenSpec or issue systems Runtime validation and artifacts beyond one local session

Active owners in the current stack

The active owner is now selected inside OpenCode itself.

  • build and build-deep own implementation work
  • plan and plan-deep own design and requirement clarification
  • subagents such as reviewer and explore assist with narrow responsibilities
  • commands intentionally bind heavyweight phases to stronger models
  • Sentry contributes evidence without taking ownership

OpenSpec is no longer a required baseline dependency in this repository's default flow. It remains useful when you want a larger tracked lifecycle beyond PLAN.md, but the native stack does not depend on it.

Planning-to-execution chain

The default flow documented by this repo is:

  1. /plan for interactive planning with clarifying questions and a persisted PLAN.md
  2. /spec to turn acceptance criteria into Vitest-oriented test skeletons
  3. /implement to execute against the plan and test anchors
  4. /review for focused review feedback
  5. /verify for tests, lint, and type checks

This replaces the older pattern where planning discipline and lifecycle management were spread across multiple separate tools.

Why the stack changed

The earlier five-tool stack proved useful, but it carried real costs:

  • overlapping responsibilities
  • larger always-loaded prompts
  • slower model reasoning
  • more opportunities for configuration drift

The native-first stack keeps the same principles while reducing duplication. Planning rigor, TDD discipline, and runtime validation still exist, but they now live closer to OpenCode's own primitives.

Related reading