@maestria/opencode 0.3.2 → 0.3.4

package/README.md

@@ -2,12 +2,49 @@
 
 An OpenCode plugin that encodes learned AI-engineering patterns into a portable, self-wiring configuration.
 
+> This package is part of Maestria. See [VISION.md](../../VISION.md) for the project vision, motivation, and scope.
+
+## Motivation
+
+Raw LLMs are powerful but unreliable for production engineering work. They guess instead of verifying, implement instead of delegating, and produce plausible-sounding results that are subtly wrong. OpenCode's built-in agents give you a foundation, but they don't encode the methodology, discipline, and guardrails that turn a model into a reliable engineering partner.
+
+This plugin exists to close that gap. It packages the harness — the rules, agents, and workflows — that makes AI engineering consistent and trustworthy. The principle is simple:
+
+**Agent = Model + Harness**
+
+The model provides capability. The harness provides reliability. Most agent failures are harness failures, not model failures.
+
+The patterns in this plugin were extracted from months of daily AI-assisted engineering work. They represent configurations and workflows that survived repeated use — not theoretical best practices, but scar tissue from real failures. The orchestrator's delegation rules, the maker/checker split, the iteration limits, the `!!!` convention for non-negotiable rules — all of these came from specific failures that happened more than once.
+
+This is not just another agent pack. Most agent packs focus on capability — giving agents more tools, more context, more autonomy. This plugin focuses on discipline: giving agents clear boundaries, explicit methodology, and structured handoffs. Capability is the default. Discipline is the differentiator.
+
+To that end, the plugin is built on five design principles:
+
+## Goals
+
+- **Interoperability** — The methodology is harness-agnostic. Works with any LLM provider that OpenCode supports. No vendor lock-in, no model-specific prompt tricks.
+- **Discipline** — Maker/checker split prevents self-approval. Iteration limits prevent infinite loops. Delegation chains prevent scope creep. These are first-class concepts, not afterthoughts.
+- **Transparency** — Every agent is a markdown file with YAML frontmatter. Readable, editable, versionable. No TypeScript abstraction layer between you and the prompts. What you see is what the agent runs.
+- **Evolvability** — Versioned releases encode new patterns as they're proven. The plugin improves by curation — patterns that survive repeated use get promoted; patterns that don't, don't.
+- **Composability** — Agents are designed as pipeline stages. Adventurer discovers context, architect evaluates trade-offs, planner structures the work, builder implements, reviewer validates. The orchestrator chains them together. Each step produces a structured handoff for the next.
+
+## Non-Goals
+
+- **Does NOT bundle skills** — Skills (methodology packages for specific domains) are installed separately via the skills CLI. The plugin prescribes which skills to load and when, but does not include them.
+- **Does NOT replace OpenCode's built-in agents** — `explore` and `general` remain available for unstructured work. The plugin's 8 subagents are specialists for structured workflows on top of that foundation.
+- **Does NOT auto-extract patterns from sessions** — All rules and agent prompts are manually curated. No automated pattern extraction, no session mining, no implicit learning.
+- **Does NOT require or provide a specific LLM provider** — Model selection is OpenCode configuration. No provider lock-in, no subscription or API key required. MIT-licensed, open source.
+- **Does NOT work outside OpenCode** — This is an OpenCode plugin. Kimi Code and Hermes adaptations are in development as separate packages under the `@maestria` scope, each independently versioned and maintained.
+- **Does NOT include telemetry, usage tracking, or external data collection** — No data leaves your machine. No analytics. No crash reporting. The plugin has zero network calls of its own.
+- **Does NOT enforce rules programmatically** — Rules are guidance, not gates. The `!!!` convention signals non-negotiable rules, but the agent can still violate them. Enforcement happens through permissions and review, not runtime checks.
+
 ## What It Does
 
 This plugin bundles a set of agents and rules that encode effective AI-engineering workflows:
 
-- **Agents** — 7 specialized subagents for different phases of work:
+- **Agents** — 8 specialized subagents for different phases of work:
   - `@orchestrator` — Manager for complex multi-step tasks; restricted to delegating only to the 7 registered subagents via task permissions
+  - `@adventurer` — Codebase reconnaissance and deep code understanding before implementation
   - `@architect` — Architecture decisions with decision matrices
   - `@builder` — Focused implementation agent for atomic tasks
   - `@diagnose` — Systematic 6-step regression tracing
@@ -34,7 +71,7 @@ If you want to pin a specific version, you can also keep a `package.json` in you
 1. **Plugin loads** — OpenCode installs `@maestria/opencode` from npm
 2. **Config hook** — The plugin reads bundled agent markdown files, parses their frontmatter, and registers them programmatically with OpenCode
 3. **Rules injected** — `system.transform` hook appends rules to every session
-4. **Agents available** — All 7 agents are available as subagents via `@` mention
+4. **Agents available** — All 8 agents are available as subagents via `@` mention
 5. **State preserved** — `session.compacting` hook preserves task status across compaction events
 
 ### Design Philosophy

package/agents/adventurer.md

@@ -157,11 +157,13 @@ _(none — adventurer is read-only; skills load only on trigger)_
 
 ### Load on trigger
 
-- `zoom-out` (`mattpocock/skills`) — load when scoping crosses >1 module or the area is unfamiliar
-- `opensrc` (`vercel-labs/opensrc`) — load when external library internals affect the answer
+- `agent-browser` (`vercel-labs/agent-browser`) — load when exploring a running web app, visual references/links provided, or Electron apps need inspection (skip if backend-only)
 - `c4-architecture` (`softaworks/agent-toolkit`) — load when output requires a context/container diagram
+- `domain-modeling` (`mattpocock/skills`) — load when mapping domain concepts, terminology, and ubiquitous language during reconnaissance
 - `mermaid-diagrams` (`softaworks/agent-toolkit`) — load when a sequence/flow/ER diagram is requested
-- `agent-browser` (`vercel-labs/agent-browser`) — load when exploring a running web app, visual references/links provided, or Electron apps need inspection (skip if backend-only)
+- `resolving-merge-conflicts` (`mattpocock/skills`) — load when investigating merge conflict history or understanding why a conflict occurred
+- `opensrc` (`vercel-labs/opensrc`) — load when external library internals affect the answer
+- `session-handoff` (`softaworks/agent-toolkit`) — load when creating a recon report or handoff document for another agent
 
 ### Defer to specialist
 

package/agents/architect.md

@@ -103,19 +103,23 @@ After the ADR is written, your handoff should cover:
 
 ### Always load
 
-- `architecture-decision-records` (`softaworks/agent-toolkit`) — Phase 5 (Document as ADR) requires this skill
-- `improve-codebase-architecture` (`mattpocock/skills`) — architect's home for codebase-deepen opportunities
+- `architecture-decision-records` (`wshobson/agents`) — Phase 5 (Document as ADR) requires this skill
 - `improve` (`shadcn/improve`) — survey codebase and produce prioritized implementation plans
 
 ### Load on trigger
 
+- `api-design-principles` (`wshobson/agents`) — load when designing APIs, choosing REST vs GraphQL, or defining endpoint structures
+- `architecture-decision-framework` (`agustinusnathaniel/skills`) — load when using decision matrices, weighted scoring, or comparing implementation approaches
+- `architecture-decision-records` (`wshobson/agents`) — load when documenting an architecture decision as an ADR
 - `c4-architecture` (`softaworks/agent-toolkit`) — load when output requires a container/component diagram
-- `mermaid-diagrams` (`softaworks/agent-toolkit`) — load when a sequence/flow/ER diagram is needed
+- `codebase-design` (`mattpocock/skills`) — load when designing module boundaries, deciding where seams go, or improving codebase structure
+- `domain-modeling` (`mattpocock/skills`) — load when building or sharpening the project's domain model and ubiquitous language
 - `draw-io` (`softaworks/agent-toolkit`) — load when user asks for a `.drawio` file
 - `excalidraw` (`softaworks/agent-toolkit`) — load when user asks for an `.excalidraw` file
 - `grill-me` (`mattpocock/skills`) — load before recommending a final option
 - `grill-with-docs` (`mattpocock/skills`) — load when validating against this project's ADR/CONTEXT.md
-- `zoom-out` (`mattpocock/skills`) — load when scope is unclear
+- `improve-codebase-architecture` (`mattpocock/skills`) — load when surveying the codebase for architecture improvement opportunities
+- `mermaid-diagrams` (`softaworks/agent-toolkit`) — load when a sequence/flow/ER diagram is needed
 
 ### Defer to specialist
 

package/agents/builder.md

@@ -81,22 +81,26 @@ This reveals what actually requires heavy tools vs. what's simple.
 
 ### Load on trigger
 
-- `opensrc` (`vercel-labs/opensrc`) — load when library internals are unclear
+- `agent-browser` (`vercel-labs/agent-browser`) — load when task involves UI verification, visual references, web app interaction, or Electron app automation (skip if backend-only)
+- `ai-sdk` (`vercel/ai`) — load when task is AI SDK (skip if unrelated)
+- `commit-work` (`softaworks/agent-toolkit`) — load when committing, staging changes, or crafting commit messages
+- `codebase-design` (`mattpocock/skills`) — load when implementing a designed interface or building to match module boundary specifications
+- `database-schema-designer` (`softaworks/agent-toolkit`) — load when designing database schemas, tables, or data models
+- `frontend-design` (`anthropics/skills`) — load when task is UI/visual
 - `karpathy-guidelines` (`multica-ai/andrej-karpathy-skills`) — load when writing non-trivial logic
+- `mcp-builder` (`anthropics/skills`) — load when building or modifying MCP servers (skip if non-MCP work)
 - `naming-analyzer` (`softaworks/agent-toolkit`) — load when introducing new identifiers
-- `frontend-design` (`anthropics/skills`) — load when task is UI/visual
-- `vercel-react-best-practices` (`vercel-labs/agent-skills`) — load when task involves React (skip if non-frontend)
-- `vercel-composition-patterns` (`vercel-labs/agent-skills`) — load when task involves React composition (skip if non-frontend)
+- `opensrc` (`vercel-labs/opensrc`) — load when library internals are unclear
+- `pnpm` (`antfu/skills`) — load when changing `package.json`/lockfile
 - `react-dev` (`softaworks/agent-toolkit`) — load when task is React (skip if non-frontend)
 - `react-useeffect` (`softaworks/agent-toolkit`) — load when modifying `useEffect` (skip if non-frontend)
-- `ai-sdk` (`vercel/ai`) — load when task is AI SDK (skip if unrelated)
+- `resolving-merge-conflicts` (`mattpocock/skills`) — load when resolving merge conflicts or rebase issues
 - `tdd` (`mattpocock/skills`) — load when user explicitly requests TDD
-- `webapp-testing` (`anthropics/skills`) — load when task needs browser-level test
-- `agent-browser` (`vercel-labs/agent-browser`) — load when task involves UI verification, visual references, web app interaction, or Electron app automation (skip if backend-only)
-- `vitest` (`antfu/skills`) — load when writing Vitest tests (skip if no tests)
+- `vercel-composition-patterns` (`vercel-labs/agent-skills`) — load when task involves React composition (skip if non-frontend)
+- `vercel-react-best-practices` (`vercel-labs/agent-skills`) — load when task involves React (skip if non-frontend)
 - `vite` (`antfu/skills`) — load when modifying `vite.config` or build
-- `pnpm` (`antfu/skills`) — load when changing `package.json`/lockfile
-- `commit-work` (`softaworks/agent-toolkit`) — load when committing, staging changes, or crafting commit messages
+- `vitest` (`antfu/skills`) — load when writing Vitest tests (skip if no tests)
+- `webapp-testing` (`anthropics/skills`) — load when task needs browser-level test
 - `writing-clearly-and-concisely` (`softaworks/agent-toolkit`) — load when writing a commit message
 
 ### Defer to specialist

package/agents/diagnose.md

@@ -96,17 +96,18 @@ Confirm it works:
 
 ### Always load
 
-- `diagnose` (`mattpocock/skills`) — own skill, non-negotiable
+- `diagnosing-bugs` (`mattpocock/skills`) — own skill, non-negotiable
 
 ### Load on trigger
 
-- `logging-best-practices` (`boristane/agent-skills`) — load when bug surfaces in logs or you need to add logging
+- `agent-browser` (`vercel-labs/agent-browser`) — load when bug involves UI behavior, network requests, performance profiling, or needs visual reproduction (skip if backend-only)
+- `dependency-updater` (`softaworks/agent-toolkit`) — load when investigating dependency-related bugs, lockfile issues, or version conflicts
+- `resolving-merge-conflicts` (`mattpocock/skills`) — load when debugging regressions introduced by a merge or rebase
+- `diagnosing-bugs` (`mattpocock/skills`) — load when using the diagnose methodology for systematic debugging
 - `karpathy-guidelines` (`multica-ai/andrej-karpathy-skills`) — load when investigating pattern-level bugs
+- `logging-best-practices` (`boristane/agent-skills`) — load when bug surfaces in logs or you need to add logging
 - `opensrc` (`vercel-labs/opensrc`) — load when root cause is in an external library
 - `webapp-testing` (`anthropics/skills`) — load when UI reproduces the bug
-- `agent-browser` (`vercel-labs/agent-browser`) — load when bug involves UI behavior, network requests, performance profiling, or needs visual reproduction (skip if backend-only)
-- `dependency-updater` (`softaworks/agent-toolkit`) — load when investigating dependency-related bugs, lockfile issues, or version conflicts
-- `zoom-out` (`mattpocock/skills`) — load when regression spans >1 module
 
 ### Defer to specialist
 

package/agents/planner.md

@@ -70,12 +70,12 @@ After the plan is written, your handoff should cover:
 
 ### Load on trigger
 
-- `to-issues` (`mattpocock/skills`) — load when plan is approved and needs issue breakdown
-- `to-prd` (`mattpocock/skills`) — load when plan becomes a PRD
-- `grill-me` (`mattpocock/skills`) — load before finalising the plan
 - `game-changing-features` (`softaworks/agent-toolkit`) — load when user asks for product strategy (skip on pure implementation plans)
+- `domain-modeling` (`mattpocock/skills`) — load when planning around domain boundaries or aligning phases with domain contexts
+- `grill-me` (`mattpocock/skills`) — load before finalising the plan
 - `prototype` (`mattpocock/skills`) — load when plan needs runtime validation first
-- `zoom-out` (`mattpocock/skills`) — load when plan scope is unclear
+- `to-issues` (`mattpocock/skills`) — load when plan is approved and needs issue breakdown
+- `to-prd` (`mattpocock/skills`) — load when plan becomes a PRD
 
 ### Defer to specialist
 

package/agents/reviewer.md

@@ -138,16 +138,18 @@ You review code for quality.
 
 ### Load on trigger
 
-- `web-design-guidelines` (`antfu/skills`) — load when reviewing UI (skip if backend-only)
-- `skill-judge` (`softaworks/agent-toolkit`) — load when review target is a SKILL.md
+- `agent-browser` (`vercel-labs/agent-browser`) — load when reviewing UI changes, verifying visual fidelity, or testing interactive flows (skip if backend-only)
+- `baseline-ui` (`ibelick/ui-skills`) — load when reviewing UI (skip if non-UI)
 - `fixing-accessibility` (`ibelick/ui-skills`) — load when reviewing accessibility (skip if non-UI)
 - `fixing-metadata` (`ibelick/ui-skills`) — load when reviewing SEO/metadata (skip if non-UI)
 - `fixing-motion-performance` (`ibelick/ui-skills`) — load when reviewing animation (skip if non-UI)
 - `logging-best-practices` (`boristane/agent-skills`) — load when code adds/uses logs
-- `webapp-testing` (`anthropics/skills`) — load when reviewing tests
-- `agent-browser` (`vercel-labs/agent-browser`) — load when reviewing UI changes, verifying visual fidelity, or testing interactive flows (skip if backend-only)
-- `baseline-ui` (`ibelick/ui-skills`) — load when reviewing UI (skip if non-UI)
+- `codebase-design` (`mattpocock/skills`) — load when reviewing module boundaries, seam placement, or interface design
+- `review-logging-patterns` (`hugorcd/evlog`) — load when reviewing code that adds or modifies logging (skip if no logging changes)
+- `skill-judge` (`softaworks/agent-toolkit`) — load when review target is a SKILL.md
 - `userinterface-wiki` (`raphaelsalaja/userinterface-wiki`) — load when reviewing UI (skip if non-UI)
+- `web-design-guidelines` (`antfu/skills`) — load when reviewing UI (skip if backend-only)
+- `webapp-testing` (`anthropics/skills`) — load when reviewing tests
 
 ### Defer to specialist
 

package/agents/writer.md

@@ -83,22 +83,25 @@ You write documentation.
 
 ### Load on trigger
 
+- `backend-to-frontend-handoff-docs` (`softaworks/agent-toolkit`) — load when documenting an API for frontend consumers
+- `brand-guidelines` (`anthropics/skills`) — load when writing brand documentation, style guides, or tone-of-voice guidelines
+- `copy-editing` (`coreyhaines31/marketingskills`) — load when user wants in-place edits of existing copy
+- `crafting-effective-readmes` (`softaworks/agent-toolkit`) — load when output is a README
+- `doc-coauthoring` (`anthropics/skills`) — load when user wants to co-write, not just receive a doc
 - `docx` (`anthropics/skills`) — load when output must be `.docx`
+- `domain-modeling` (`mattpocock/skills`) — load when documenting the domain glossary, ubiquitous language, or domain concepts
+- `frontend-to-backend-requirements` (`softaworks/agent-toolkit`) — load when documenting frontend requirements for backend
 - `pdf` (`anthropics/skills`) — load when output must be `.pdf`
-- `xlsx` (`anthropics/skills`) — load when output is a spreadsheet
 - `pptx` (`anthropics/skills`) — load when output is slides
-- `doc-coauthoring` (`anthropics/skills`) — load when user wants to co-write, not just receive a doc
-- `crafting-effective-readmes` (`softaworks/agent-toolkit`) — load when output is a README
-- `backend-to-frontend-handoff-docs` (`softaworks/agent-toolkit`) — load when documenting an API for frontend consumers
-- `frontend-to-backend-requirements` (`softaworks/agent-toolkit`) — load when documenting frontend requirements for backend
-- `copy-editing` (`coreyhaines31/marketingskills`) — load when user wants in-place edits of existing copy
+- `writing-great-skills` (`mattpocock/skills`) — load when creating or editing a SKILL.md file
+- `xlsx` (`anthropics/skills`) — load when output is a spreadsheet
 
 ### Defer to specialist
 
 - `internal-comms` (`anthropics/skills`) → out of scope — internal comms is not a code/ADRs/API docs task
 - `professional-communication` (`softaworks/agent-toolkit`) → out of scope — emails/team messaging not in writer's role
-- `template-skill` (`softaworks/agent-toolkit`) → out of scope — skill creation is a separate workflow
-- `skill-creator` (`softaworks/agent-toolkit`) → out of scope — same as above
+- `template-skill` (`anthropics/skills`) → out of scope — skill creation is a separate workflow
+- `skill-creator` (`anthropics/skills`) → out of scope — same as above
 - `copywriting` (`coreyhaines31/marketingskills`) → out of scope — marketing copy is not documentation
 
 ### Skip if

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/opencode",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",