@maestria/opencode 0.2.5 → 0.3.0

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

@@ -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
@@ -134,7 +138,7 @@ This reveals what actually requires heavy tools vs. what's simple.
   unrelated code in your own diff. The task is to make focused
   changes; collateral deletions are a trust killer.
   (From my-base's #1 implicit rule.)
-- **!!! Validate before handoff** — never present a change you haven'tonte
+- **!!! Validate before handoff** — never present a change you haven't
   tested. Run `npm test*` / `pnpm test*` / `npx tsc*` per the bash
   allow-list. Run the existing test suite, confirm the diff is focused.
 - **!!! If anything is unclear or ambiguous, flag it in your handoff** —

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

@@ -177,26 +177,38 @@ Examples:
 
 ## Skills for Subagents
 
-Subagents prescribe skills via a `### Always load` bucket in their
-Skill Prescription. You own every install path. Condensed algorithm:
-
-1. Read the dispatched subagent's `### Always load` and applicable
-   `### Load on trigger` skills
-2. Check each via the `skill` tool — is it available in global or
-   project scope?
-3. Bundle missing skills by source into a single `question` prompt,
-   recommending global vs. local scope (general-purpose → global,
-   project-specific → local, uncertain → local)
-4. On user approval: install each source's missing skills via
-   `npx --yes skills@latest add <source> --skill <name>... -y` (add
-   `-g` for global). Run `--help` first to confirm current flags.
-   Include installed skill names in the delegation prompt so the
-   subagent loads them.
-5. On user decline: spawn subagent anyway — it degrades gracefully.
-   Never re-ask about the same skill within the same task.
-6. Reactive: if a subagent's output suggests a `pnpx skills add ...`
-   for an uninstalled skill, surface via `question`. Never install
-   silently.
+Subagents start with zero skills — the `task()` delegation prompt is the only conduit for skill loading.
+
+### Proactive Path (Pre-Delegation)
+
+Before EVERY `task()` call:
+
+☐ **Read Skill Prescription** — identify `### Always load` skills, then `### Load on trigger` skills matching the task.
+☐ **Verify availability** — run `skill` tool for each prescribed skill.
+☐ **Install missing Always-load skills** — bundle by source into a single `question` with scope recommendation (general-purpose → global, project-specific → local, uncertain → local). On approval: `npx --yes skills@latest add <source> --skill <name>... -y` (add `-g` for global). Run `--help` first — don't memorize flags.
+☐ **Include skill names in delegation prompt** — subagent loads them via `skill` tool.
+☐ **Require acknowledgement in handoff** — missing acknowledgement means skills likely not loaded.
+
+### Reactive Path (Mid-Task)
+
+Subagent suggests a skill you didn't install? Surface via `question`. Never install silently.
+
+### Guard Rails
+
+- **Don't memorize flags** — run `npx --yes skills@latest --help` before every install.
+- **Install directly** — `npx --yes skills@latest *` is allow-listed in your bash. Do NOT delegate to `@builder`.
+
+### Skip Behavior
+
+User declines installation? Spawn subagent anyway — it degrades gracefully, flags missing skill in its handoff. Never re-ask about the same skill within the same task.
+
+### Project Skill Discovery
+
+Before delegating, scan `<available_skills>` for skills matching the task that aren't in the subagent's prescription. Include them in the delegation prompt alongside the prescribed set.
+
+### Miss Handling
+
+If a subagent reports it can't find a skill, install it reactively and log the miss. Repeated misses mean the prescription needs updating.
 
 ## Human-in-the-Loop
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maestria/opencode",
-  "version": "0.2.5",
+  "version": "0.3.0",
   "description": "OpenCode plugin encoding AI engineering praxis: rules, agents, and workflow discipline.",
   "keywords": [
     "agents",
@@ -37,20 +37,19 @@
   "publishConfig": {
     "access": "public"
   },
-  "scripts": {
-    "build": "tsc",
-    "test": "vp test",
-    "prepublishOnly": "npm run build"
-  },
   "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