maestria

Structured AI engineering workflows for your coding agent.

Plugins that bring disciplined AI engineering workflows to your coding agent.

📖 Full documentation: maestria.sznm.dev

Start Here

• Use maestria: choose your coding agent in the package table below, then follow its installation guide.
• Choose a workflow: read when to use maestria.
• Contribute: start with CONTRIBUTING.md and the engineering documentation index.
• Understand the design: read the vision and workflow patterns.

Packages

Package	Description	README
@maestria/opencode	maestria methodology plugin for OpenCode V2 (0.8.0 and earlier: OpenCode V1)	README
@maestria/agent-plugins	Shared plugin for Codex, Claude Code, Cursor, Kimi Code, Devin, ZCode, Hermes, OMP, and Agent Plugins clients	README
@maestria/pi	maestria methodology plugin for Pi	README

Canonical agent directives and the sync pipeline live in the private @maestria/core package (packages/core/agent-directives/); packages/shared/* holds private host-neutral utilities. Neither is published to npm.

Project Structure

maestria/
├── apps/
│   ├── docs/            - Documentation site (Astro + Starlight)
│   └── maestria-cli/    - CLI for managing maestria plugins
├── docs/
│   ├── adr/             - Architecture Decision Records
│   │   ├── core/        - Cross-cutting decisions (ADR-CORE-*)
│   │   ├── opencode/    - @maestria/opencode decisions (ADR-OC-*)
│   │   ├── cursor/      - Cursor host boundaries (ADR-CR-*)
│   │   ├── kimi-code/   - Kimi host boundaries (ADR-KC-*)
│   │   └── pi/          - @maestria/pi decisions (ADR-PI-*)
│   ├── guides/          - Development guides and conventions
│   └── plans/           - Historical implementation plans
├── packages/
│   ├── core/            - Canonical agent directives + sync pipeline (private)
│   ├── agent-plugins/   - Shared declarative plugin and native host resources
│   ├── opencode/        - @maestria/opencode plugin
│   ├── pi/              - @maestria/pi plugin
│   └── shared/
│       ├── mode/        - Shared neutral mode mechanics (private, pure-TS, no host SDK)
│       └── pi/          - Shared pure-TS utilities for pi (private)
├── scripts/             - Sync and CI verification scripts
├── VISION.md            - Project vision and principles
├── PATTERNS.md          - Reusable workflow patterns
└── README.md            - This file

Development

This monorepo uses Vite+ as its unified toolchain.

# Install dependencies
vp install

# Format, lint, and type-check
vp check

# Run tests
vp run test

# Build all packages
vp run build

# Run the docs site locally
vp run dev

Release

This project uses Changesets for versioning and publishing.

pnpm changeset        # Create a changeset
pnpm version-packages # Apply changesets and bump versions
pnpm release          # Publish to npm

Contributors ✨

Thanks goes to these wonderful people (emoji key):

This project follows the all-contributors specification. Contributions of any kind welcome!

Uninstalling

For per-package uninstall instructions, see:

• @maestria/opencode uninstall
• @maestria/pi uninstall
• @maestria/agent-plugins uninstall: one section per host (Claude Code, Codex, Cursor, Kimi Code, Devin, ZCode, OMP, Hermes)