Changelog

Changelog

v0.6.10

July 22, 2026

Fixed

• Mode keywords (fein/sonar/blitz) no longer fail silently after installing the plugin from npm.

v0.6.9

July 22, 2026

Fixed

• Mode keywords (fein/sonar/blitz) now work after installing the plugin from a package.

v0.6.7

July 21, 2026

• Mode commands (fein/sonar/blitz) now behave identically across all platforms including Hermes.

v0.6.6

July 21, 2026

Compact agent directives

Agent directives compressed to cut orchestrator context usage by ~38% without removing rules or intent. Sections for commit, review, and routing are now merged instead of spread across the prompt. Rules shared by all specialists now live in one place instead of being repeated.

Fixes

• Fix duplicate skill recommendations in diagnose and architect
• Fix formatting bug in global rules
• Fix stale cross-references

v0.6.5

July 14, 2026

Structured assumption tagging

Adventurer and architect outputs now require [verified] or [inferred] tags on every assumption. Downstream agents can distinguish confirmed facts from guesses.

Deterministic agents preferred

New CRITICAL RULE mandates defined output contracts before delegating. Open-ended exploration must be scoped with time and resource limits.

Cognitive hygiene for delegation

The orchestrator now has a 5-trap pre-flight checklist (vague, overcomplication, attachment, rumination, overwhelm) to catch weak delegation prompts.

Outcome specs over activity specs

Delegation now prefers specifying what to achieve over how to achieve it. Activity specs (step-by-step instructions) constrain specialist judgment.

Experiment framing for uncertainty

High-uncertainty tasks can be framed as experiments with explicit hypotheses and termination conditions. Output is a validated finding, not shipped code.

Parallel speculation pattern

The orchestrator can now dispatch the same open question to multiple specialists with different lenses, then synthesize results.

Incidental findings

Agents now surface relevant discoveries outside their brief after completing the primary task.

First-principles decomposition

When blocked, agents decompose problems into verifiable sub-problems instead of trying harder with the same approach.

v0.6.4

July 14, 2026

Structured PR descriptions

Pull request descriptions now follow a consistent format with Summary, Changes, Testing, and Breaking Changes sections. Reviews are faster when every PR uses the same structure.

v0.6.3

July 14, 2026

Auto-create feature branch when landing on main

The agent no longer asks for confirmation before creating a feature branch when it lands on main. It just creates the branch and continues.

Work results format streamlined

The post-task summary has been redesigned:

• Table-first format replaces the old multi-paragraph structure
• Every change is prefixed with + (added), ~ (modified), or - (deleted)
• Breaking changes are marked with !
• Test file changes are annotated with (test)
• The same table is reused in PR descriptions, so you see the same structured summary without anyone writing it twice

v0.6.2

July 14, 2026

Mandated work results format

The structured ## Changes summary table after builder tasks is now a hard requirement enforced by a non-negotiable CRITICAL RULE. This replaces the previous suggested behavior with a mandated format that overrides “write for humans” guidance for this specific output.

Mandated documentation audit before commits

The documentation audit step before every commit is now explicitly required. It covers four categories: internal docs, user-facing docs site, user-facing changelogs, and changesets. A new checklist item reinforces this requirement.

v0.6.1

July 10, 2026

Expanded agent shell permissions

Adventurer, architect, planner, reviewer, and writer now have expanded shell access to match the tools they actually use. Read-only file operations (ls, cat, grep, etc.) and role-specific tools (package managers, project CLI, git operations) are now pre-allowed. Unusual or dangerous commands still prompt for approval.

Affected files

• packages/opencode/sync.config.ts
• packages/opencode/agents/{adventurer,architect,planner,reviewer,writer}.md

v0.6.0

July 10, 2026

Autonomous commit protocol

Commits are now fully autonomous - the orchestrator reads recent commit history, composes the correct conventional commit message, and commits without asking for approval. Push happens automatically on feature branches; the orchestrator asks before pushing to main or master. PR creation is handled separately.

Expanded builder and diagnose permissions

Builder shell permissions expanded to cover read-only file operations (ls, cat, grep, etc.), git operations, package managers (pnpm, npm), and build/test/lint tools (tsc, vitest, vp, rtk, eslint, prettier). Unusual or dangerous commands still prompt for approval.

Diagnose can now apply fixes without asking for edit permission. Read-only investigation commands are pre-allowed.

Structured work results

After completing work, the orchestrator now presents a file-by-file summary focused on what changed at the signature and interface level - not function body details. Users can review changes in 1-2 prompts instead of reading the full diff.

Smarter agent behavior

• Orchestrator classifies tasks by complexity before dispatching - simple tasks go directly to builder, complex ones get an architecture review first
• Agents proactively suggest next steps instead of going silent after completing work
• Agents stop and re-evaluate after repeated user corrections instead of iterating in the wrong direction
• Agents never delete existing code without understanding what it does - they adapt rather than remove
• Agent writing style is cleaner - the “Write for humans” rule is now enforced as a hard requirement

Affected files

• packages/opencode/sync.config.ts - permission definitions
• packages/opencode/agents/builder.md - bash allow-list
• packages/opencode/agents/diagnose.md - edit permission + bash allow-list
• docs/adr/core/ADR-CORE-011-eliminate-questions-autonomy.md - decision record

v0.5.7

July 1, 2026

Code intelligence tool preference

Agents now prefer code intelligence tools (MCP, CLI, or other) before falling back to grep and read when exploring the codebase. If you use a tool like CodeGraph, agents will route through it automatically.

v0.5.3

June 30, 2026

Fixed

• Plugin now throws an error when the agents directory is missing or unreadable, instead of silently loading zero agents.

v0.5.1

June 27, 2026

Two new design principles

Agents now check from first principles before adopting existing patterns, and check for existing solutions before building from scratch. This pushes toward better design decisions with less wasted effort.

v0.5.0

June 24, 2026

Project workflow configuration (.maestria/)

Introduces a lightweight protocol for project-specific agent workflows. Projects can now define .maestria/workflow.md for custom delegation sequencing and .maestria/rules.md for project-specific non-negotiable rules.

The orchestrator prompt includes a new “Project Workflows (.maestria/)” section that instructs the orchestrator to load these files via @adventurer delegation and follow their guidance. Core rules always take precedence over project instructions.

• packages/core/agent-directives/specialists/orchestrator.md - new “Project Workflows (.maestria/)” section
• packages/core/agent-directives/rules.md - awareness bullet referencing the protocol

Effort anthropomorphism guard and writing style guidance

The orchestrator and all specialists now include explicit guardrails against two common failure modes:

• Don’t anthropomorphize effort - A new Critical Rule tells the dispatcher that thinking “that analysis would be too much work” is a category error for a machine that only routes. The same principle is instilled in all specialists via the global agent rules.

v0.4.9

June 24, 2026

Single source of truth for agent directives

Agent prompts and global rules now live in one canonical location (packages/core/agent-directives/) and sync automatically to all platform plugins (OpenCode, Kimi Code, Pi). The scripts/sync-all and scripts/check-sync tools handle the pipeline. No more drift between platforms.

v0.4.8

June 23, 2026

• Moved @opencode-ai/plugin to peerDependencies (community convention)
• Added graceful error handling in loadAgents() with per-file try/catch
• Added opencode metadata block to package.json for plugin discovery

v0.4.7

June 23, 2026

Pipeline redesigned

The orchestrator pipeline refactored to use role-based abstraction (thinker/worker/verifier) with dynamic sequencing. The pipeline stops as soon as the verifier accepts - no unnecessary refinement loops.

Removed toolchain-specific CLI references

Replaced hard-coded vp check / vp test references with generic validation language so the plugin is toolchain-agnostic.

v0.4.6

June 22, 2026

Commit authorization rules hardened

The orchestrator now follows an explicit COMMIT PROTOCOL with five sequential steps: inspect git status, propose the full commit message via a user prompt, delegate to the builder with validation checks, report results, and ask separately before pushing. Rules now explicitly state that commit authorization resets to zero after each commit, preventing auto-committing on subsequent work instructions.

Affected files:

• agents/orchestrator.md - new COMMIT PROTOCOL section
• rules/AGENTS.md - new Commit Policy section
• docs/adr/opencode/ADR-OC-004-commit-authorization-rules.md - decision record

v0.4.3

June 22, 2026

• Internal refactoring and reliability improvements

v0.4.2

June 20, 2026

• Infrastructure improvements and bug fixes

v0.4.1

June 21, 2026

Fixed

• Fix ESM compatibility: added .js extensions to relative imports, preventing ERR_MODULE_NOT_FOUND in Node ESM environments.

v0.4.0

June 20, 2026

Keyword-triggered workflow modes

Three plain-word keywords that override the orchestrator’s default delegation pipeline:

Keyword	Mode	Pipeline	Use case
fein	Full pipeline	adventurer → architect/planner → builder → reviewer (mandatory gates, tests required)	Production-grade changes, cross-module work
sonar	Research only	adventurer → architect/planner → STOP (no code, structured doc output)	Discovery, feasibility, understanding before committing
blitz	Fast implementation	builder direct (skip recon/design/review)	Quick fixes, prototypes, known territory

Detection uses a word-boundary regex at any position in the message, is code-block-aware, and the most restrictive keyword wins (fein > sonar > blitz), and detection is case-insensitive. Modes can be disabled via modes.disabledKeywords in plugin options (denylist-only). The full design is documented in ADR-OC-003.

v0.3.11

June 20, 2026

Orchestrator stripped of read-only bash permissions

The orchestrator’s remaining read-only bash permissions - git status/diff/log/show/branch, ls, which, pwd - have been stripped. Its only bash exception is npx --yes skills@latest * for skill installation. Any codebase inspection must now go through @adventurer or @builder.

This completes the orchestrator’s transition to a pure dispatcher role, consistent with v0.3.10’s removal of read-side tools (read, glob, grep).

v0.3.10

June 19, 2026

Orchestrator reverted to pure dispatcher

After real-world testing, the read/glob/grep permissions granted in v0.3.9 caused workaround behavior - the orchestrator preferred direct reconnaissance over delegation to specialists. Structural permission denial proved to be the only reliable enforcement for an LLM-based orchestrator.

The orchestrator is now limited to task() delegation and question() - no read, glob, grep, webfetch, edit, or lsp.

Prompt streamlined

Removed directives that redundantly restated permission blocks (tool restrictions, bash allow-lists, task routing limits) which are already structurally enforced through YAML frontmatter.

v0.3.9

June 19, 2026

Websearch for agents

@architect, @adventurer, and @diagnose now have websearch permission set to ask. When these agents need to find information they don’t have a URL for, they can search the web - but the tool requires user approval before each search.

Other agents (@builder, @planner, @reviewer, @writer) remain websearch-free.

Orchestrator gains read-only recon

The orchestrator now has read, glob, and grep for quick verification before delegation. This lets it check file existence, skim exports, and confirm references - without leaving the dispatcher role.

Structural boundaries remain:

• edit: deny - orchestrator cannot implement
• webfetch: deny - orchestrator delegates web research
• lsp: deny - deep code intelligence is for specialists

A new Read-Side Tool Policy in the orchestrator’s instructions caps read/glob/grep at 3 calls per task before delegating deeper recon to @adventurer.

v0.3.8

June 18, 2026

Permission refinements after audit

A systematic review uncovered several gaps in agent permissions. Three agents (adventurer, diagnose, writer) gained todowrite for multi-step task tracking. Git read commands (status, show, diff, log) - needed for inspecting history without leaving a role - were missing from four agents (adventurer, architect, reviewer, writer), now added. Writer gained lsp for code navigation during doc generation. Builder can now run npm view for dependency checks, and planner has which for tool discovery.

v0.3.7

June 18, 2026

Permission parser bug fix

Fixed a bug where permission rules (e.g., "*": deny, "git status*": allow) were silently ignored due to a custom YAML frontmatter parser that stored quote characters as literal parts of pattern keys. All 8 agents were affected: the orchestrator’s strict permissions didn’t actually block anything, and subagents’ bash allowlists were dead code.

v0.3.6

June 18, 2026

Orchestrator’s read-side tools now explicitly denied

The v0.3.5 refactor removed the read, glob, grep, lsp, and webfetch permissions, but the opencode framework’s wildcard *: allow rule still let the orchestrator use them. A missing key is not an explicit deny. This release adds explicit deny entries for the same five tools, completing the strict-dispatcher role. The 7 specialist subagents retain full read-side access.

v0.3.5

June 18, 2026

Orchestrator is now a strict dispatcher

Its read-side tool permissions (read, glob, grep, lsp, webfetch) are removed, and the opening prompt is rewritten as a dispatcher mandate: task() and question() are the only tools for making progress. The 7 specialist subagents keep full read-side access for the work they pick up.

Three new directives added to global rules

“Webfetch may hang - don’t block on it”, “CLI references - use local tools first”, and “Local files - read directly” are added, closing 21 directive-coverage gaps (3 × 7 specialists) so the guidance now applies uniformly.

v0.3.4

June 18, 2026

Skill prescription audit

Updated skill prescriptions across all 7 agents. Fixed renamed skills, removed dead entries, corrected source repositories, and added 8 new skills with cross-references.

v0.3.3

June 17, 2026

Skill prescription gap fill

Audited and filled missing skill entries across agents. Added session-handoff to adventurer, prioritizing-roadmap and technical-roadmaps to planner, and sorted skill lists alphabetically.

v0.3.2

June 17, 2026

Stronger orchestrator delegation rules

The rule against shell-for-implementation was expanded. A new rule, “Shell is not a workaround”, catches the common failure mode of substituting shell commands for delegation.

v0.3.1

June 17, 2026

Orchestrator task permission lockdown

Restricted orchestrator task permissions to 7 registered subagents. Changed from "*": allow to deny-by-default with explicit allow-list for only the 7 specialists.

v0.3.0

June 17, 2026

AI engineering learnings incorporated

Incorporate learnings from knowledge base:

• “Read the docs first” - new non-negotiable directive across global rules, architect, and builder
• Diagnostic documentation mandate - elevated to non-negotiable in diagnose.md
• Skill prescription expansion - builder gains commit-work skill, diagnose gains dependency-updater

v0.2.6

June 14, 2026

Bug Fixes

• Fix typo in builder.md agent prompt

v0.2.5

June 13, 2026

(no user-facing changes)

v0.2.4

June 13, 2026

Bug Fixes

• Restore rules injection into subagent prompts - the previous removal was too aggressive and left subagents without cross-cutting instructions
• Remove a conflicting instruction that prevented subagents from fulfilling their designated roles

v0.2.3

June 13, 2026

(no user-facing changes)

v0.2.2

June 13, 2026

Features

• Astro Starlight documentation site - Added a full documentation site for @maestria/opencode with guides, API reference, and changelog

Bug Fixes

• Correct source repositories for 10 skills that pointed to wrong locations
• Restore commit discipline and counter builder dispatch bias - the builder agent was being over-selected for tasks better suited to other specialists
• Stop injecting global rules into subagent prompts - top-level rules were leaking into subagent context
• Unstick webfetch by skipping the approval step and preferring local tools over remote fetches

v0.2.1

June 12, 2026

Bug Fixes

• Force orchestrator delegation via permissions - orchestrator now has edit: deny and bash: * deny to prevent it from implementing itself
• Inject specialist table into global rules so the delegation rules are always present

v0.2.0

June 12, 2026

Features

• Initial plugin release - @maestria/opencode with full agent system and rule injection
• 7 specialist subagents - adventurer, architect, builder, diagnose, planner, reviewer, writer
• Orchestrator agent - @orchestrator with mode: all for managing multi-step workflows
• Global rules injection - Cross-cutting rules (orchestration, delegation, context management) injected into every session
• Config hook - Reads bundled agent .md files, parses frontmatter, registers agents programmatically
• Session compacting hook - Preserves task tracking state across compaction events
• Agent cross-references - Every agent lists related agents with delegation triggers
• Skill discovery guidance - Every agent follows a check → use → suggest pattern for skills
• Conventional Comments - Reviewer output uses standard labels (praise, suggestion, issue, nitpick, question)
• opensrc pattern - Global rule for analyzing reference repos without API calls