Skip to content
Maestria

Contributing

Contributing

Section titled “Contributing”

For general development setup, changesets, and pull request workflow, see the Contributing Guide.

Thank you for your interest in contributing to @maestria/opencode! This guide covers the project structure and how to make changes specific to the plugin.

Project Structure

Section titled “Project Structure”
maestria/
├── apps/
│   └── docs/              # Documentation site
└── packages/
    ├── core/
    │   └── agent-directives/
    │       ├── specialists/   # Canonical agent prompts (.md files)
    │       └── rules.md       # Canonical global rules
    └── opencode/          # @maestria/opencode plugin
        ├── agents/        # Generated copies (do not edit directly)
        ├── rules/         # Generated copies (do not edit directly)
        ├── src/           # Plugin source code
        └── tests/         # Plugin tests

Making Changes

Section titled “Making Changes”

Adding or Modifying Agents

Section titled “Adding or Modifying Agents”

Agent prompts and global rules are authored in the canonical source. See Canonical Source Workflow in the Contributing Guide.

Modifying Global Rules

Section titled “Modifying Global Rules”

See Adding or Modifying Agents above - global rules follow the same canonical-source flow.

Agent Definition Format

Section titled “Agent Definition Format”

The format below describes the generated output in packages/opencode/agents/. The canonical source in packages/core/agent-directives/ is plain Markdown without frontmatter - the YAML frontmatter is added by the sync pipeline’s transforms.

Each agent is a Markdown file with YAML frontmatter in packages/opencode/agents/. The frontmatter fields are:

Field Type Description Values
description string What the agent does Free text
mode string Agent invocation mode all, subagent
permission object Tool access permissions See below
color string (optional) Tab color in the UI Hex color (e.g., #ff6600)
maxSteps number (optional) Max delegation steps per invocation Integer

Permission model: Each tool has one of three levels - allow (use freely), ask (prompt before use), deny (cannot use). Bash permissions support glob pattern matching for granular control.

Agent modes:

  • all - Full agent, invocable directly or via task()
  • subagent - Invocable only via task()

The orchestrator uses all; all 7 specialists use subagent.

Example:

---
description: Focused implementation agent for atomic tasks.
mode: subagent
permission:
  read: allow
  edit: allow
  bash:
    '*': ask
---

Modifying Plugin Code

Section titled “Modifying Plugin Code”

The plugin source is packages/opencode/src/index.ts (~190 lines). This file handles loading agent files, parsing frontmatter, and registering agents with OpenCode.

See Also

Section titled “See Also”