Skip to content
maestria

Contributing

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

Package Boundary

Section titled “Package Boundary”

@maestria/opencode pairs a small OpenCode V2 Effect plugin with methodology generated from packages/core/agent-directives/. The plugin loads and validates the generated agents, commands, rules, and skills once, registers them through agent, command, and skill transforms, and adds mode expansion and rules through session hooks. Platform-specific lifecycle behavior belongs in packages/opencode/src/; shared methodology does not.

Change Methodology

Section titled “Change Methodology”

Edit the canonical source, never generated files under packages/opencode/agents/, packages/opencode/rules/, or packages/opencode/skills/. See the Canonical Source Workflow. After changing core content:

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

Keep permission changes in sync.config.ts, and test them against the generated output. It authors each agent’s permissions as a compact map and translates it to ordered OpenCode rules.

Changes that affect the host integration need the real-host probes, which run an isolated OpenCode V2 CLI with a local fake provider and write JSON evidence under artifacts/:

Terminal window
pnpm --filter @maestria/opencode build
pnpm e2e:opencode
pnpm --filter maestria build
pnpm e2e:opencode-cli

Architecture

Section titled “Architecture”

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