Changelog

v0.14.0

Pinned Pi prerequisite

• maestria install pi pins the @gotgenes/pi-subagents prerequisite to its supported range instead of installing bare latest, so a new upstream major can no longer change what an install puts on your machine. A failed prerequisite install still cannot block the main package install.

v0.13.5

Safer package staging

• Stage npm archives in an isolated temporary directory and clean them up after success or failure. Failed downloads preserve the existing plugin files.
• Stop child commands when their Effect is interrupted, and surface unexpected version-probe defects instead of attempting an update.

Correct version precedence

• Compare prerelease identifiers in SemVer order, including case-sensitive text. Reject numeric identifiers with leading zeroes while preserving build metadata support.

v0.13.4

Fewer redundant version checks

• Interactive updates reuse versions already detected instead of re-checking, and install, uninstall, doctor, setup, and bulk updates skip latest-version lookups when they only need installation state.

v0.13.3

Reliable setup and skill recovery

• Keep recorded skill ownership when an add or removal fails alongside a successful skill operation, so a retry can recover safely.
• Verify project-scoped skill sources in the requested --cwd and recognize xtarterize JSON statuses containing nested data.

Clearer setup scope and cancel semantics

• Setup skill prompts, review lines, summary output, and action reports carry global scope labels, and the final confirmation states the target directory role plus full cancel semantics; display strings only, no behavior change.

v0.13.2

Strict flag handling

• Passing --compact to maestria check or maestria doctor fails loud with exit code 1 and guidance to use --json or --quiet, instead of silently ignoring the flag.

Setup no-op runs

• maestria setup skips redundant confirmations when there is nothing to change: fully no-op plans exit 0 with an already-set-up summary, unchanged selections no longer trigger the trailing skills confirmation, and the ecosystem picker labels detected tools as already installed.

v0.13.1

Tidier doctor output

• maestria doctor human output now shows managed skills only with an omitted count pointing to --json for the full list, platforms sharing one agent inventory render it once with later platforms referencing the first, and Next shows a single actionable step. JSON output and behavior are unchanged.

v0.13.0

Read-only doctor diagnostics

• Added maestria doctor to report skill setup per platform: install state, recorded skill selection, and observed inventory, with actionable next commands.
• Supports --json and --quiet; home directories render as ~. No installs, updates, removals, or record writes.

Optional setup coordinator

• Added maestria setup to walk through ecosystem tools and skills with a review screen plus final confirmation before any change.
• Ecosystem tools report detected or manual steps and are never auto-installed; non-TTY runs require full flags plus --yes, with per-action reports and resume guidance.

Skill flags and selection

• install and update accept --skills, --exclude-skills, and --yes; per-platform selections persist only after actual success.
• Fresh installs default to create-pull-request plus docs-update; recorded choices (including empty) are preserved, and legacy installs without a record infer only create-pull-request.
• Reconcile, preflight, and removal now operate per skill, with partial successes recorded recoverably.

v0.12.5

Reliable host plugin upgrades

• maestria update no longer falsely reports failure for host plugin upgrades: install and update commands share a generous deadline for slow plugin fetches, and failed commands report the exit code plus captured output instead of a bare failure message.

v0.12.4

Terminal compatibility

• Fixed the group-multiselect fallback prompt to use ASCII glyphs on terminals without Unicode support; Unicode terminals are unchanged.

v0.12.3

Internal maintenance

• Internal deduplication across platform handlers, model configuration, and plugin validation; no CLI behavior, output, or exit-code changes.

v0.12.2

Smaller published package

• Stopped publishing generated JavaScript sourcemaps from the CLI and platform packages, reducing published package sizes.

v0.12.1

Documentation clarity

• Clarified installation paths, prerequisites, and support boundaries in package documentation, and removed stale pre-release wording.

v0.12.0

Portable Agent Plugin workflow

• Added the first-class Agent Plugins v1 package, which exposes maestria’s methodology as a portable, skills-only plugin.
• Added maestria plugin validate for read-only validation of Agent Plugins v1 directory packages.
• Added maestria plugin install to fetch or stage a validated portable package for a compatible client’s own installer or directory loader.
• Portable packages remain separate from runtime platform detection, status, and native activation.
• Hardened portable MCP validation against lookalike loopback domains and cross-platform PLUGIN_DATA path traversal.

v0.11.1

CLI cache handling

• Centralized the version cache path and tarball temporary-directory handling.
• Respect XDG_CACHE_HOME when resolving maestria’s cache directory.

v0.11.0

Native Codex and Kimi Code support

• Added native Codex custom-agent templates, marketplace installation, primary-session orchestration guidance, and CLI-managed model configuration.
• Updated the Kimi Code integration to use its native plugin registry, system prompt, namespaced commands, and current delegation contracts.

Cursor and shared validation

• Aligned Cursor packaging and native per-agent model configuration while preserving user settings across updates.
• Shared neutral mode and skill validation logic through the hybrid package topology.

v0.10.2

Safer status and update checks

• maestria check now reports when an installed integration is behind the latest published version and exits with a distinct outdated status.
• Implicit updates no longer downgrade installations that are newer than the registry’s latest version.

v0.10.1

Reliable command results

• install, update, and uninstall now exit non-zero when any selected platform fails.
• Non-semver latest-version values are treated as incomparable during update detection.

v0.10.0

Prime Agent support

• Added Prime Agent detection and native package-manager-backed install, update, status, check, and uninstall support.
• Prime operations are user-scoped and do not scan or modify project registrations.
• Exact version pinning is unavailable because Prime updates always select the latest package.

v0.9.0

August 13, 2026

Prime Agent support

• Added prime-agent platform detection to status and check.
• Added install, update, and uninstall adapters that delegate to Prime’s native package manager (prime-agent package install/update/remove npm:@maestria/prime-agent).
• Prime support is global (user scope only): every Prime command runs from a freshly created empty temporary directory, so project registrations are never scanned or modified, and the temporary directory is removed afterwards.
• Registration state is read from prime-agent package list, and the installed version is read from the installed package’s manifest.
• Updates use Prime’s latest-only package semantics, so exact version pinning is unavailable. A version-pinned user registration is reported as an error rather than silently skipped.

Claude Code and Codex CLI support

• Added claude-code and codex platform detection to status and check.
• Added install, update, and uninstall adapters for both host CLIs.
• The CLI stages the published npm packages under ~/.cache/maestria/ and delegates plugin state to each host’s native marketplace manager.
• Exact version pinning is unavailable for these two marketplace-backed adapters.

v0.8.0

August 3, 2026

New maestria configure command

Choose which model each maestria specialist agent uses, per platform.

• Supported platforms: opencode, pi, omp - writes agent.<name>.model into opencode configs or the model: line into pi/omp agent frontmatter, preserving all other content
• Interactive: group-multiselect of the 7 specialists, then a per-agent model picker with the current model pre-selected and an Inherit (session model) option; model lists are fetched live from the platform
• Non-interactive: --set <agent>=<model>[,...] with empty values to reset, --global/--project levels, --json/--quiet/--compact output modes
• Models are validated against the platform’s live model list before writing

Fix: per-agent model config now applies on opencode

@maestria/opencode’s config hook shallow-merged its bundled agents over the user’s config, silently dropping user-set model/variant keys from opencode.jsonc. The hook now deep-merges, so maestria configure opencode (and manual agent.<name>.model edits) actually take effect - subagents use their configured model instead of inheriting the primary agent’s.

v0.7.0

July 22, 2026

Oh My Pi (omp) platform support

New @maestria/omp package adds maestria support for the Oh My Pi coding agent. CLI integration: maestria install omp, maestria update omp.

v0.6.1

July 21, 2026

• Switch kimi-code to npm-based install (fixes maestria update kimi-code version comparison)
• Add Cursor plugin support: maestria install cursor, maestria update cursor

v0.6.0

July 17, 2026

New maestria check command

Check whether a maestria plugin is installed on any platform. Returns the installation status of each plugin so you can verify your setup.

v0.5.0

July 14, 2026

Enhanced interactive prompts

update and install commands now use a grouped multiselect prompt with an “All platforms” toggle and a keyboard shortcut to select/deselect all. maestria install kimi-code now works with the latest Kimi Code versions - the installer writes plugin files directly instead of relying on a removed CLI command.

v0.4.1

July 14, 2026

Network-first version lookup

maestria update and maestria status no longer serve stale cached versions. The CLI always fetches the latest version from npm, falling back to the cache only when the network is unavailable.

Improvements:

• No stale version window - Previously, published versions were missed for up to 1 hour due to TTL-based caching. Now the live npm version is fetched every time the network is available.
• Offline fallback - If the npm registry is unreachable, the CLI falls back to the last known cached version instead of failing.

v0.4.0

July 14, 2026

Multi-platform selection

maestria update and maestria install now support comma-separated platform IDs (e.g., maestria update opencode,pi) and interactive multiselect with checkboxes instead of single-option pickers.

Improvements:

• Comma-separated platforms - Target multiple platforms in one command: maestria install opencode,pi,kimi-code
• Multiselect in interactive mode - Checkbox-style picker replaces the old single-select for both install and update commands
• All platforms shortcut - Interactive maestria update includes a convenient “All platforms” option to update everything at once

v0.3.11

July 11, 2026

• Pi extension detection no longer fails during version checks
• Version comparison between releases is now more reliable

v0.3.10

July 11, 2026

• Pi package install and uninstall now work correctly

v0.3.9

July 3, 2026

• Pi extension detection no longer fails during version checks

v0.3.8

July 2, 2026

• OpenCode install no longer fails when tools are on a non-standard PATH.
• New maestria uninstall command with --all and interactive mode support.
• maestria --version now shows the correct package version.
• Error messages now include command output for easier debugging.

v0.3.2

July 1, 2026

Bundle CLI runtime dependencies

Bundled effect, @clack/prompts, citty, picocolors into output instead of externalizing them. End users no longer download 8.2 MB of transitive dependencies at install time.

v0.3.0

June 29, 2026

Agent-friendly CLI

Major improvements to make the CLI more suitable for AI agents and CI pipelines.

New flags:

• --compact - Minimal machine-friendly text output. Strips colors and decorative formatting. Supports status, install, and update commands.
• --version - Print the CLI version and exit.
• Root --json - The maestria command (no subcommand) now supports --json.
• --quiet on status - Decoupled from --json; each flag works independently.

Enhanced --help:

All commands now show EXAMPLES, EXIT CODES, and TIP FOR AI AGENTS sections in addition to the standard flag documentation.

Proper exit codes:

The CLI now exits with 0 (success), 1 (validation/command error), or 130 (user cancelled in interactive mode).

Non-interactive safety:

install and update commands detect non-TTY environments and print a clear error message instead of attempting an interactive prompt.

v0.2.1

June 29, 2026

Idempotent updates

The update command now detects when the installed version already matches the target version and skips the update gracefully. Previously, running npx maestria update <platform> when already on the latest version would re-run the install unnecessarily.

v0.2.0

June 22, 2026

Cross-platform plugin management

Initial release of the maestria CLI - a unified interface for managing maestria plugins across OpenCode, Pi, and Kimi Code from a single command.

Three subcommands:

• install - Install maestria for one or all detected platforms. Supports interactive mode (pick from a list), --all flag, and per-platform targets.
• update - Update installed plugins to the latest (or specified) version. Accepts --version for pinned updates and --all for bulk updates.
• status - Show installation status across platforms. Detects available coding agents on $PATH and reports installed vs. latest versions.

Key features:

• No npm install required - run via npx thanks to the bundled single-file .mjs distribution
• --json flag on all commands for CI/script consumption
• --quiet flag to suppress spinner animations
• Version caching (1-hour TTL in ~/.cache/maestria/versions.json)
• Input validation with clear error messages for unknown platforms, invalid versions, and conflicting flags