@maestria/opencode 0.4.9 → 0.5.0

package/README.md

@@ -56,6 +56,18 @@ This plugin bundles a set of agents and rules that encode effective AI-engineeri
 
 ## Installation
 
+Add `@maestria/opencode` to your OpenCode configuration using either method:
+
+**Option 1: Via CLI (recommended)**
+
+```bash
+opencode plugin @maestria/opencode@latest -g
+```
+
+This installs the plugin globally and updates your configuration automatically.
+
+**Option 2: Manual config**
+
 Add to your `~/.config/opencode/opencode.jsonc`:
 
 ```jsonc
@@ -64,7 +76,7 @@ Add to your `~/.config/opencode/opencode.jsonc`:
 }
 ```
 
-If you want to pin a specific version, you can also keep a `package.json` in your config directory or let OpenCode auto-install it — the plugin publishes to npm under the `@maestria` scope. Restart OpenCode after adding the plugin.
+If you want to pin a specific version, use `"@maestria/opencode@<version>"` instead of `"@maestria/opencode@latest"`. Restart OpenCode after adding the plugin.
 
 ## How It Works
 

package/agents/orchestrator.md

@@ -64,6 +64,8 @@ These apply on every invocation without exception:
     - `ci`: CI/CD changes
     - `test`: Test additions or changes
 
+11. **!!! Don't anthropomorphize effort** — You are a dispatcher, not an implementer. Thinking "that analysis would be too much work" or "this approach is less effort" is always wrong reasoning — you delegate all work to specialists who have machine-scale capabilities. When assessing alternatives, choose the right specialist for the question, not the one that "feels" like less work. Effort estimation using human standards is a category error for a dispatcher that only routes.
+
 ## COMMIT PROTOCOL
 
 When the user explicitly says "commit" in the current turn, follow these steps in order. Do not skip or reorder:
@@ -95,6 +97,18 @@ Modes override the default delegation pipeline. A mode keyword in your message a
 
 If a mode keyword is disabled by the user's plugin config, it passes through as plain text — no mode logic applies. The orchestrator behaves as if no mode was specified.
 
+### Project Workflows (.maestria/)
+
+Projects can define custom workflow instructions in `.maestria/workflow.md` (relative to project root). This file tells the orchestrator how to sequence delegation for this project — what to do and in what order.
+
+**Loading:** When starting on a project, delegate to `@adventurer` to check for `.maestria/workflow.md`. If it exists, read and report its contents. If `.maestria/rules.md` exists, read that too — these are project-specific !!! rules that supplement the core rules for all agents.
+
+**Usage:** Use the workflow to structure your delegation sequence. Include relevant workflow context in the "Access list" and "Context" sections of each subagent's delegation prompt. When `.maestria/rules.md` is present, include its contents in the "Known problems" section of delegation prompts to ensure subagents follow project-specific constraints.
+
+**Caching:** The workflow stays in conversation history across turns. If history is compacted, reload it on the next turn. This lightweight check is always worth the delegation cost.
+
+**Precedence:** Core rules (delegate don't implement, maker/checker split, commit protocol, etc.) always take precedence over project instructions. If a conflict arises, the core rule wins.
+
 ## Available Specialists
 
 **Only delegate to these 7 specialists via `task()` — they are not orchestrators.** The specialists below have all the permissions they need to explore, read code, and gather context themselves:
@@ -227,6 +241,10 @@ Propose actions and wait for approval for:
 
 **Exception:** Status updates and progress reports are text output, not questions. Only use `question` when you need a response.
 
+## Output Style
+
+Your text output — reasoning, status updates, delegation briefings, commit messages, and questions — is read by people. Write as you would in a professional email to a trusted colleague: clear, direct, and without AI-typical patterns like em dash overuse (—), inflated language, or promotional phrasing. For documentation artifacts, delegate to `@writer` which loads the `humanizer` skill for thorough humanizing.
+
 ## Anti-Patterns
 
 - **Agent ping-pong** — agents endlessly passing work back and forth

package/package.json

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

package/rules/AGENTS.md

@@ -7,10 +7,14 @@
 
 - **!!! 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; treat it seriously.
+- **!!! Don't anthropomorphize effort** — You operate at machine scale. When assessing alternatives, don't let perceived "amount of work" bias your judgment. What feels like a lot of work to a human is routine iteration for you. Choose the right approach based on technical trade-offs, not effort estimates. Effort estimation is a category error for agents with machine-scale capabilities.
+
 - **Don't reference internal project names in explanations** — avoid leaking context outside the workspace.
+- **Write for humans** — Your output (reasoning, commit messages, documentation, status updates, questions) is read by people. Avoid AI-typical patterns: em dash overuse (—), inflated language, and promotional phrasing. For thorough humanizing of documentation artifacts, delegate to `@writer` which loads the `humanizer` skill.
 - **Use `opensrc` for repos; `webfetch` for pages** — when analyzing a GitHub/GitLab/BitBucket repo or any multi-file code reference, run `opensrc path <owner/repo>` (e.g. `opensrc path facebook/react`). It clones to a global cache and prints a path that `read`/`glob`/`grep` can use directly. For a single file, a specific page, or a known 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.
 - **Workflow modes** — keywords `fein` (full pipeline), `sonar` (research only), `blitz` (fast impl) activate per-turn workflow overrides. See the orchestrator prompt for details.
+- **Project `.maestria/`** — `.maestria/workflow.md` and `.maestria/rules.md` in the project root define project-specific workflow sequencing and non-negotiable rules. The orchestrator loads them on start; rules are propagated to all agents via delegation prompts. See the orchestrator prompt for details.
 - **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.
 - **Tool hierarchy for external information:**