@maestria/opencode 0.6.21 → 0.6.22

package/README.md

@@ -1,180 +1,42 @@
 # @maestria/opencode
 
-An OpenCode plugin that encodes learned AI-engineering patterns into a portable, self-wiring configuration.
+An OpenCode plugin that encodes Maestria's AI-engineering methodology as agents, rules, and workflows - a harness that makes model output consistent and reliable (`Agent = Model + Harness`).
 
-> 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** - 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
-  - `@planner` - Create detailed implementation plans with phased milestones
-  - `@reviewer` - Code review with quality gates
-  - `@writer` - Documentation following structured patterns
-
-- **Rules** - Global directives injected into every session's system prompt
+> This package is part of Maestria. See [VISION.md](https://github.com/agustinusnathaniel/maestria/blob/main/VISION.md) for the project vision, motivation, and scope. The agents and rules are **generated** from the canonical directives in `packages/core/agent-directives/` by the [sync pipeline](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md#3-the-sync-pipeline-core-concept).
 
 ## Installation
 
-### Option 1: Via CLI (recommended)
-
-Install globally (available in all projects):
-
 ```bash
+# Global install (recommended)
 opencode plugin @maestria/opencode@latest -g
-```
 
-Or install for the current project only:
-
-```bash
+# Project-level install
 opencode plugin @maestria/opencode@latest
 ```
 
-### Option 2: Manual config
-
-Add to your OpenCode config file:
-
-- **Global:** `~/.config/opencode/opencode.jsonc`
-- **Project-level:** `.opencode/opencode.jsonc` (in your project root)
-
-```jsonc
-{
-  "plugin": ["@maestria/opencode@latest"],
-}
-```
-
-To pin a specific version, use `"@maestria/opencode@0.3.3"` instead of `"@maestria/opencode@latest"`. Restart OpenCode after adding the plugin.
-
-## How It Works
-
-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 8 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 does not auto-update plugins. Packages are cached locally at `~/.cache/opencode/packages/<name>@<version>/` - the npm registry is not consulted if the package is already cached. To update, re-run the install command with the same scope as the original install:
-
-```bash
-# If installed globally
-opencode plugin @maestria/opencode@latest -g --force
-
-# If installed at project level
-opencode plugin @maestria/opencode@latest --force
-```
-
-Use `--force` to replace an existing config entry. To force a fresh install from npm (bypassing the local cache), clear the cache first:
+OpenCode does not auto-update plugins; re-run the install command with `--force` to update. To uninstall, remove the `@maestria/opencode` entry from the `plugin` array in `~/.config/opencode/opencode.jsonc` (global) or `.opencode/opencode.jsonc` (project), then optionally delete the cached package under `~/.cache/opencode/packages/`. Alternatively, use the [maestria CLI](https://maestria.sznm.dev/cli/) to manage installation across all platforms.
 
-**macOS / Linux:**
+## What It Provides
 
-```bash
-rm -rf ~/.cache/opencode/packages/@maestria/opencode*
-```
+- **8 agents** - `@orchestrator` (delegates to the 7 specialists) plus `@adventurer`, `@architect`, `@builder`, `@diagnose`, `@planner`, `@reviewer`, and `@writer`, each a readable, editable markdown file with YAML frontmatter.
+- **Global rules** - a rules file injected into every session (`rules/AGENTS.md`) encoding the universal floors: evidence, safety, delegation, review, and bounded repair.
+- **Zero telemetry** - no data leaves your machine; the plugin makes no network calls of its own.
 
-**Windows (PowerShell):**
+## Support / Platform Notes
 
-```powershell
-Remove-Item -Recurse -Force "$env:USERPROFILE\.cache\opencode\packages\@maestria\opencode*"
-```
+- OpenCode-specific; Kimi Code, Hermes, Cursor, and other adaptations ship as separate `@maestria` packages.
+- Does not bundle skills; domain skills are installed separately via the skills CLI.
+- Rules are advisory prompt guidance, not a sandbox. The only structural enforcement is OpenCode's `permission` frontmatter (for example, the orchestrator cannot edit).
+- The generated agents are projections of the canonical core directives. To change behavior, edit `packages/core/agent-directives/` and re-run the sync pipeline - never edit the generated files under `agents/` directly.
 
-**Windows (Command Prompt):**
+## Documentation and Changelog
 
-```cmd
-rmdir /s /q "%USERPROFILE%\.cache\opencode\packages\@maestria"
-```
+- [User-facing documentation](https://maestria.sznm.dev/opencode/) on the docs site
+- [Changelog](https://github.com/agustinusnathaniel/maestria/blob/main/packages/opencode/CHANGELOG.md)
 
-Then re-run the install command (with or without `-g` as appropriate).
-
-> **Tip:** Run `opencode debug paths` to see the cache directory resolved for your platform.
-
-To pin a specific version, use `@<version>` instead of `@latest`:
-
-```bash
-opencode plugin @maestria/opencode@0.3.3
-```
-
-## Uninstalling
-
-There is no CLI command to remove a plugin. To uninstall, edit your OpenCode config file and remove the entry from the `plugin` array:
-
-- **Global:** `~/.config/opencode/opencode.jsonc`
-- **Project-level:** `.opencode/opencode.jsonc` (in your project root)
-
-```jsonc
-{
-  "plugin": [
-    // Remove or comment out the line below:
-    // "@maestria/opencode@latest",
-  ],
-}
-```
-
-You can also optionally delete the cached package:
-
-```bash
-rm -rf ~/.cache/opencode/packages/@maestria/opencode*
-```
+## Development
 
-Alternatively, use the [maestria CLI](https://maestria.sznm.dev/cli/) to manage installation across all platforms from a single command.
+See the [contributing guide](https://github.com/agustinusnathaniel/maestria/blob/main/CONTRIBUTING.md) for repository conventions.
 
 ## License
 

package/agents/orchestrator.md

@@ -120,7 +120,13 @@ Modes are case-insensitive and per-turn unless the platform documents another li
 
 ## Commit and Session Flow
 
-For normal engineering work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair material blockers -> commit -> push -> PR`. Branch before editing when needed, then inspect status and the intended diff, stage only intended files, use logical conventional commits, push the feature branch, and open a PR with a useful summary and validation notes. Do not ask for routine authorization when the task, base, remote, and ownership are clear. Stop only at the safety, authorization, ambiguity, or host-capability boundaries defined in the global rules; merge, release, and production actions remain separate.
+For implementation work, own the delivery path: `inspect -> plan -> implement -> validate -> review -> repair -> commit -> push -> PR`.
+
+When the repository, branch, remote, ownership, and host capabilities support PR delivery, complete it without ceremonial approval. Do not stop at a local diff, commit, pushed branch, or `PR pending`. Merge, release, and production actions remain separate.
+
+The parent session owns continuation until the selected implementation outcome reaches its terminal artifact. Incomplete todos or specialist handoffs are not user checkpoints: take the next bounded action, recover one incomplete delegation with a changed brief, or report the structured blocker. Freeze acceptance, non-goals, and repair limits; classify adjacent findings as follow-ups rather than expanding scope or resetting limits.
+
+Research-only, planning-only, explicitly read-only, `sonar`, and host-blocked routes terminate at their requested artifact or exact blocker. Safety, authorization, ambiguity, and host-capability boundaries always take precedence.
 
 An explicitly authorized checkpoint may preserve unreviewed work but never authorizes shipping. If the host cannot perform a delivery action, report the exact pending step rather than claiming completion or asking a ceremonial question.
 

package/package.json

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

package/rules/AGENTS.md

@@ -32,6 +32,14 @@ This is the cross-platform behavior contract. It defines outcomes, evidence, saf
 - Adjacent findings do not expand the current task automatically. A follow-up blocks only when it invalidates acceptance or creates an immediate safety, authorization, or production risk.
 - Security, authentication, authorization, and permission findings are mandatory stops. Route design-level issues to `@architect` and obtain the applicable authorization before proceeding.
 
+## Session Continuation and Delivery
+
+- **!!! The orchestrator owns continuation for implementation and delivery work.** An incomplete todo, pending handoff, unresolved acceptance item, or specialist message saying “continue if needed” is not a user checkpoint. Take or delegate the next bounded action; do not end the turn or ask the user to say “continue.” Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker.
+- A specialist's read-only or no-edit result ends that delegation, not the parent work unit. If the result is empty, malformed, or incomplete, make one changed-brief recovery attempt when useful, then report the exact blocked delta instead of silently abandoning the outcome.
+- Freeze the outcome, acceptance criteria, non-goals, and review budget at the start of the work unit. New findings are not permission to restart the project: repair only findings that are in scope and affect acceptance; record adjacent findings as follow-ups unless they create an applicable safety or authorization stop.
+- Do not reset a review or repair budget by splitting the same outcome into more delegations, changing specialist names, or relabelling the finding. A new scope requires a new outcome and acceptance criteria.
+- For implementation work, continue through validation and the project's normal delivery artifact. When the repository, branch, remote, ownership, and host capabilities support PR delivery, create a reviewable PR without ceremonial approval; do not stop at a local diff, commit, or pushed branch. Research-only, planning-only, explicitly read-only, and host-blocked work terminates at its requested artifact or exact blocker. Stop at a defined safety, authorization, ambiguity, or host-capability boundary and name the exact pending action.
+
 ## Delegation and Context
 
 Supported specialists are `adventurer`, `architect`, `builder`, `diagnose`, `planner`, `reviewer`, and `writer`.