Contributing

For repository setup, changesets, and pull requests, see the Contributing Guide.

Package Boundary

The OpenCode package has a small runtime adapter. Its methodology is generated from packages/core/agent-directives/:

packages/opencode/
├── agents/       generated agent definitions
├── rules/        generated global rules
├── src/          runtime registration and hooks
├── tests/        adapter and behavior tests
├── sync.config.ts
├── INSTALL.md
└── README.md

The runtime reads the generated agent files, parses their frontmatter, and registers them with OpenCode. Platform-specific lifecycle behavior belongs in src/. Shared methodology does not.

Change Methodology

Edit the canonical source, not packages/opencode/agents/ or packages/opencode/rules/. See Canonical Source Workflow.

After changing core content:

scripts/sync-all
scripts/check-sync
pnpm --filter @maestria/opencode test

OpenCode Agent Format

The sync transform adds the OpenCode frontmatter. The main fields are:

Field	Purpose
description	Role and trigger summary
mode	all for the orchestrator, subagent for specialists
permission	allow, ask, or deny rules for host tools
color	Optional UI color
maxSteps	Optional delegation limit

The orchestrator is directly invocable and dispatches through task(). Specialists are subagents. Keep permission changes in sync.config.ts and test them against the generated output.

Change Runtime Code

The adapter source is packages/opencode/src/index.ts. It handles loading generated agent files, parsing frontmatter, and registering agents with OpenCode. Test behavior through the package’s public registration boundary.

Architecture

Record OpenCode-specific boundary decisions in ADR-OC-001 or the relevant ADR.