@maestria/opencode 0.2.6 → 0.3.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Agustinus Nathaniel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -7,7 +7,7 @@ An OpenCode plugin that encodes learned AI-engineering patterns into a portable,
 This plugin bundles a set of agents and rules that encode effective AI-engineering workflows:
 
 - **Agents** — 7 specialized subagents for different phases of work:
-  - `@orchestrator` — Manager for complex multi-step tasks
+  - `@orchestrator` — Manager for complex multi-step tasks; restricted to delegating only to the 7 registered subagents via task permissions
   - `@architect` — Architecture decisions with decision matrices
   - `@builder` — Focused implementation agent for atomic tasks
   - `@diagnose` — Systematic 6-step regression tracing
@@ -37,6 +37,27 @@ If you want to pin a specific version, you can also keep a `package.json` in you
 4. **Agents available** — All 7 agents are available as subagents via `@` mention
 5. **State preserved** — `session.compacting` hook preserves task status across compaction events
 
+### Design Philosophy
+
+This plugin is built on the **Harness Engineering** principle:
+`Agent = Model + Harness`. The harness is what turns a raw LLM into a
+reliable coding agent — the model is just one component.
+
+The 6 harness components map directly to plugin features:
+
+| Component         | Plugin Mapping                                |
+| ----------------- | --------------------------------------------- |
+| **Instructions**  | `rules/AGENTS.md` injected into every session |
+| **Tools**         | Skill prescription system + MCP integration   |
+| **Sandboxes**     | `permission` frontmatter on every agent       |
+| **Orchestration** | `mode: all/subagent` + `task()` delegation    |
+| **Guardrails**    | `edit: deny`, `bash: ask`, iteration limits   |
+| **Observability** | Session compaction hooks, structured handoffs |
+
+Most agent failures are configuration failures, not model failures. The
+plugin's agents are designed with this principle — precise rules, explicit
+boundaries, and clear delegation chains over raw capability.
+
 ## Updating
 
 OpenCode auto-updates plugins on restart. Or run:

package/agents/architect.md

@@ -133,6 +133,9 @@ After the ADR is written, your handoff should cover:
 
 ## Constraints
 
+- **!!! Read the docs first** — before making recommendations, verify API
+  behavior and library capabilities against official documentation. Don't
+  guess at how a tool works.
 - Don't assume — verify against official docs and references
 - Don't oversimplify — acknowledge trade-offs honestly
 - For irreversible decisions, recommend more conservative options

package/agents/builder.md

@@ -96,6 +96,7 @@ This reveals what actually requires heavy tools vs. what's simple.
 - `vitest` (`antfu/skills`) — load when writing Vitest tests (skip if no tests)
 - `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
 - `writing-clearly-and-concisely` (`softaworks/agent-toolkit`) — load when writing a commit message
 
 ### Defer to specialist
@@ -118,6 +119,9 @@ This reveals what actually requires heavy tools vs. what's simple.
 - Prefer `edit` over `write` — preserve existing code
 - **!!! Run tests before claiming done**
 - **!!! Never implement without reading the target files first**
+- **!!! Read the docs first** — before writing code that uses unfamiliar
+  APIs, tools, or migration paths, consult official documentation. Don't
+  guess at API changes.
 - If a change grows beyond the original task scope, flag it in your
   handoff
 - Keep the change focused — one concern per invocation

package/agents/diagnose.md

@@ -105,6 +105,7 @@ Confirm it works:
 - `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
@@ -132,7 +133,9 @@ Document findings at each step:
 - Prevention measures
 - **Open questions for orchestrator** — what is still unclear, what assumptions you made
 
-Save these as knowledge artifacts so they can be referenced later.
+**!!! Save your findings as persistent knowledge artifacts** — don't let
+diagnostic work disappear after the session ends. Create a markdown file
+or use `@writer` to store the investigation record for future reference.
 
 ## Iteration Limits
 
@@ -142,6 +145,7 @@ Save these as knowledge artifacts so they can be referenced later.
 
 ## Rules
 
+- **!!! Document your diagnostic work as persistent knowledge artifacts** — save what you investigated, ruled out, root cause, and fix applied. Don't let findings disappear when the session ends. Use `@writer` or a markdown file if no knowledge base exists yet.
 - **!!! Edit and bash permissions are `ask`** — explain why before any change
 - **!!! Always verify before handoff** — Never present broken code
 - **!!! Maker/checker split** — your work is reviewed by `@reviewer` before it lands. The model that wrote the fix is too nice grading its own homework. Apply the fix, do not QA it.

package/agents/orchestrator.md

@@ -21,7 +21,14 @@ permission:
   question: allow
   todowrite: allow
   task:
-    "*": allow
+    "*": deny
+    "adventurer": allow
+    "architect": allow
+    "builder": allow
+    "diagnose": allow
+    "planner": allow
+    "reviewer": allow
+    "writer": allow
   skill: allow
 ---
 
@@ -46,6 +53,11 @@ These apply on every invocation without exception:
    - **Never commit without explicit user request in the current turn.** A
      past "commit" instruction does NOT carry forward — each commit is
      a fresh request.
+   - **!!! Doing work is not a commit request.** If the user asks you to
+     create files, update docs, add a changeset, or make any other change
+     after a previous commit, do NOT commit that work unless the user
+     explicitly says "commit" in the same turn. The work and the commit
+     are separate events — each needs its own explicit instruction.
    - **If you're about to run `git add` or `git commit`, STOP.** These
      commands MUST be delegated to `@builder`. You may inspect with
      `git status`, `git diff`, and `git log` yourself — but staging

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/opencode",
-  "version": "0.2.6",
+  "version": "0.3.1",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",
@@ -35,22 +35,22 @@
     }
   },
   "publishConfig": {
-    "access": "public"
-  },
-  "scripts": {
-    "build": "tsc",
-    "test": "vp test",
-    "prepublishOnly": "npm run build"
+    "access": "public",
+    "provenance": true
   },
   "dependencies": {
     "@opencode-ai/plugin": "^1.17.0"
   },
   "devDependencies": {
-    "@types/node": "catalog:",
-    "commit-and-tag-version": "catalog:",
-    "typescript": "catalog:"
+    "@types/node": "^24",
+    "commit-and-tag-version": "^12.7.3",
+    "typescript": "^5"
   },
   "engines": {
     "node": ">=22.12.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "vp test"
   }
-}
+}

package/rules/AGENTS.md

@@ -4,6 +4,10 @@
 
 - **!!! Don't assume** — verify against actual code and docs.
   Guesses lead to bugs.
+- **!!! Read the docs first** — before writing code that touches
+  unfamiliar tools, APIs, or migration paths, consult official
+  documentation. Don't guess at API changes. This rule is scar
+  tissue from repeated failures, not a preference.
 - **Don't reference internal project names in explanations** — avoid
   leaking context outside the workspace.
 - **Use `opensrc` for repos; `webfetch` for pages** — when analyzing a