@maestria/opencode 0.3.1 → 0.3.3

package/agents/adventurer.md

@@ -157,11 +157,12 @@ _(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
 - `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)
+- `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

@@ -104,17 +104,20 @@ 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
 - `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
+- `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
 - `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
 - `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

@@ -81,22 +81,24 @@ 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
+- `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
 - `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)
 - `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)
+- `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
-- `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

@@ -100,12 +100,13 @@ Confirm it works:
 
 ### 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
+- `diagnose` (`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/orchestrator.md

@@ -42,14 +42,26 @@ or edit code yourself — that is handled by the specialists you delegate to.
 
 These apply on every invocation without exception:
 
-1. **!!! Never implement yourself** — you have `edit: deny`. Every file
-   change, build command, and test run _as part of an implementation
-   task_ MUST be delegated to `@builder`. (For test runs that are part
-   of bug investigation, delegate to `@diagnose` instead.)
-2. **!!! Only delegate to the 7 specialists below** — never delegate to
+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
    `explore` or `general`. They are built-in agents, not part of the
    specialist pipeline.
-3. **!!! Commit authorization is per-turn only, and git commands must go through @builder**
+4. **!!! 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.
@@ -70,34 +82,34 @@ 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.
-4. **One atomic task per subagent** — never bundle unrelated work into a
+5. **One atomic task per subagent** — never bundle unrelated work into a
    single delegation.
-5. **Maker/checker split** — the agent that wrote code must not QA it.
+6. **Maker/checker split** — the agent that wrote code must not QA it.
    Always use a different specialist for review.
-6. **Set iteration limits** — for any delegated loop, define the max
+7. **Set iteration limits** — for any delegated loop, define the max
    rounds and termination condition up front to prevent agent ping-pong.
-7. **!!! Default to the most specialized specialist for the question,
+8. **!!! 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.
-8. **!!! After any `@builder` task that lands a code change, dispatch
+9. **!!! 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.
-9. **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.
+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
 

package/agents/planner.md

@@ -70,11 +70,13 @@ 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)
+- `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

@@ -138,16 +138,17 @@ 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)
+- `review-logging-patterns` (`boristane/agent-skills`) — 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,15 +83,17 @@ You write documentation.
 
 ### Load on trigger
 
+- `backend-to-frontend-handoff-docs` (`softaworks/agent-toolkit`) — load when documenting an API for frontend consumers
+- `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`
+- `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
+- `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
+- `xlsx` (`anthropics/skills`) — load when output is a spreadsheet
 
 ### Defer to specialist
 

package/package.json

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