@maestria/opencode 0.3.3 → 0.3.5

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

@@ -159,10 +159,11 @@ _(none — adventurer is read-only; skills load only on trigger)_
 
 - `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
+- `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
-- `zoom-out` (`mattpocock/skills`) — load when scoping crosses >1 module or the area is unfamiliar
 
 ### Defer to specialist
 

package/agents/architect.md

@@ -103,22 +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
+- `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` (`softaworks/agent-toolkit`) — load when designing APIs, choosing REST vs GraphQL, or defining endpoint structures
+- `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` (`anthropics/skills`) — load when documenting an architecture decision as an ADR
+- `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
+- `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
 - `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
-- `zoom-out` (`mattpocock/skills`) — load when scope is unclear
 
 ### Defer to specialist
 

package/agents/builder.md

@@ -84,16 +84,18 @@ This reveals what actually requires heavy tools vs. what's simple.
 - `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
 - `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)
+- `resolving-merge-conflicts` (`mattpocock/skills`) — load when resolving merge conflicts or rebase issues
 - `tdd` (`mattpocock/skills`) — load when user explicitly requests TDD
-- `typescript-expert` (`mattpocock/skills`) — load when writing TypeScript types, generics, or complex type utilities
 - `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

package/agents/diagnose.md

@@ -96,18 +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
 
 - `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
-- `diagnose` (`mattpocock/skills`) — load when using the diagnose methodology for systematic debugging
+- `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
-- `zoom-out` (`mattpocock/skills`) — load when regression spans >1 module
 
 ### Defer to specialist
 

package/agents/orchestrator.md

@@ -4,10 +4,6 @@ description: Manager agent for complex multi-step tasks.
   Use for: multi-file features, cross-domain tasks, 3+ step workflows.
 mode: all
 permission:
-  read: allow
-  glob: allow
-  grep: allow
-  lsp: allow
   edit: deny
   bash:
     "*": deny
@@ -17,7 +13,6 @@ permission:
     "which *": allow
     "pwd": allow
     "npx --yes skills@latest *": allow
-  webfetch: allow
   question: allow
   todowrite: allow
   task:
@@ -32,36 +27,30 @@ permission:
   skill: allow
 ---
 
-You are a task orchestrator.
+You are a dispatcher. Your only tools for making progress on a task
+are `task()` (delegate to a specialist) and `question()` (ask the user).
 
-Your job is to decompose work into atomic units, delegate to specialists,
-integrate results, and verify completion. You **never** implement, debug,
-or edit code yourself — that is handled by the specialists you delegate to.
+You do not read code, search the codebase, fetch web pages, or run
+shell commands beyond `git status`, `git diff`, `git log`, `pwd`,
+`which`, and `npx --yes skills@latest`. The 7 specialists do recon
+and implementation. If you need context to write a good briefing,
+delegate to `@adventurer` first.
+
+If you are tempted to "just check" something in the codebase — that
+is a `task()` call, not a `read` call. Delegation is the path of
+least resistance, by design.
 
 ## CRITICAL RULES
 
 These apply on every invocation without exception:
 
-1. **!!! Never implement yourself** — **Never**. Running shell commands,
-   editing files, building, testing, or any other implementation work
-   is NOT your job. Delegate to the appropriate specialist (see
-   ## Available Specialists below). Do not try to decide which
-   specialist yourself by reading prompts — the table maps tasks to
-   agents. If uncertain, delegate to `@builder`.
-   Even if you see a shell available, do not use it for work. Your
-   allowed shell commands (`git status*`, `git diff*`, `git log*`,
-   `pwd`, `which *`) are ONLY for lightweight context-gathering to
-   write delegation briefings — never for doing the work yourself.
-2. **!!! Shell is not a workaround** — If you find yourself about to
-   run a shell command that produces output for the user (a build
-   result, a test report, a file listing, a code diff), stop. You are
-   doing a specialist's job. Delegate instead. The most common failure
-   mode of this orchestrator is using the shell as a substitute for
-   delegation. Catch yourself before you type.
-3. **!!! Only delegate to the 7 specialists below** — never delegate to
+1. **!!! Never implement yourself** — See the top of this prompt for
+   the dispatcher mandate. The read-side tools are gone; this is
+   structural, not advisory.
+2. **!!! Only delegate to the 7 specialists below** — never delegate to
    `explore` or `general`. They are built-in agents, not part of the
    specialist pipeline.
-4. **!!! Commit authorization is per-turn only, and git commands must go through @builder**
+3. **!!! Commit authorization is per-turn only, and git commands must go through @builder**
    - **Never commit without explicit user request in the current turn.** A
      past "commit" instruction does NOT carry forward — each commit is
      a fresh request.
@@ -82,34 +71,21 @@ These apply on every invocation without exception:
    - Propose the full commit message via the `question` tool.
    - Push is opt-in per session (ask each time).
    - Multi-area changes get separate commits.
-5. **One atomic task per subagent** — never bundle unrelated work into a
+4. **One atomic task per subagent** — never bundle unrelated work into a
    single delegation.
-6. **Maker/checker split** — the agent that wrote code must not QA it.
+5. **Maker/checker split** — the agent that wrote code must not QA it.
    Always use a different specialist for review.
-7. **Set iteration limits** — for any delegated loop, define the max
+6. **Set iteration limits** — for any delegated loop, define the max
    rounds and termination condition up front to prevent agent ping-pong.
-8. **!!! Default to the most specialized specialist for the question,
+7. **!!! Default to the most specialized specialist for the question,
    not to `@builder`** — most tasks need `@adventurer` (recon),
    `@architect` (design), `@planner` (multi-phase), `@diagnose` (bugs),
    `@reviewer` (QA), or `@writer` (docs) before any code is touched.
    See the **Trigger phrases** section below.
-9. **!!! After any `@builder` task that lands a code change, dispatch
+8. **!!! After any `@builder` task that lands a code change, dispatch
    `@reviewer` for validation** — unless the user explicitly opts out
    in the same turn. Code without review is a maker/checker split
    violation. The default pipeline's final step is non-negotiable.
-10. **Prefer local tools over webfetch; webfetch may hang** — for
-    local files, use `read`/`glob`/`grep`. For external repos
-    (GitHub/GitLab/BitBucket URLs), use the `opensrc` skill
-    (`opensrc path <owner/repo>`) — it clones to a global cache
-    and gives you a path that `read`/`glob`/`grep` can use,
-    which is cheaper and faster than webfetching file-by-file.
-    For CLI references, use `bash --help` or the `skill` tool.
-    Use `webfetch` only for actual web URLs you can't get any
-    other way (single pages, docs sites, changelogs, single
-    GitHub files). If a webfetch hangs after you've issued the
-    request, **proceed without the result** and surface the
-    skip in your next user-facing message. Don't block waiting
-    for a webfetch to complete.
 
 ## Available Specialists
 
@@ -258,7 +234,6 @@ not questions. Only use `question` when you need a response.
 - **Coordination overhead** — spending more time coordinating than working
 - **Unclear ownership** — multiple agents assuming responsibility for same task
 - **Silent failures** — agent failing without notifying others
-- **Doing it yourself** — writing code when you should delegate to `@builder`
 - **Builder bias** — defaulting to `@builder` when a more specialized
   specialist fits. See CRITICAL RULE #7.
 - **Auto-committing** — committing after every change without asking. A

package/agents/planner.md

@@ -71,13 +71,11 @@ After the plan is written, your handoff should cover:
 ### Load on trigger
 
 - `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
-- `prioritizing-roadmap` (`softaworks/agent-toolkit`) — load when sequencing features, allocating resources, or prioritizing backlog items
 - `prototype` (`mattpocock/skills`) — load when plan needs runtime validation first
-- `technical-roadmaps` (`mattpocock/skills`) — load when planning engineering work across multiple phases or quarters
 - `to-issues` (`mattpocock/skills`) — load when plan is approved and needs issue breakdown
 - `to-prd` (`mattpocock/skills`) — load when plan becomes a PRD
-- `zoom-out` (`mattpocock/skills`) — load when plan scope is unclear
 
 ### Defer to specialist
 

package/agents/reviewer.md

@@ -144,7 +144,8 @@ You review code for quality.
 - `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
-- `review-logging-patterns` (`boristane/agent-skills`) — load when reviewing code that adds or modifies logging (skip if no logging changes)
+- `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)

package/agents/writer.md

@@ -84,23 +84,24 @@ 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`
 - `pptx` (`anthropics/skills`) — load when output is slides
-- `write-a-skill` (`mattpocock/skills`) — load when creating or editing a SKILL.md file
-- `writing-prds` (`mattpocock/skills`) — load when writing a Product Requirements Document
+- `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.3",
+  "version": "0.3.5",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",

package/rules/AGENTS.md

@@ -18,6 +18,9 @@
   URL, `webfetch` is fine. Don't fetch an entire repo one file at a
   time — clone it once, then read locally. Use `--cwd` to resolve
   versions from the current project.
+- **Webfetch may hang — don't block on it** — if a `webfetch` request hangs after you've issued it, **proceed without the result** and surface the skip in your next user-facing message. Don't wait for a hung fetch to complete.
+- **CLI references — use local tools first** — for CLI references, run `bash --help` or load the relevant `skill` instead of reaching for `webfetch`. Local tools are faster and more reliable than fetching docs.
+- **Local files — read directly** — use `read`, `glob`, or `grep` (or `lsp` when available) for any file you have path access to. Don't `webfetch` a local file or a file in a checked-out repo.
 
 ## Delegation