Skip to content
maestria

Installation & Setup

@maestria/claude-code is a declarative, self-contained Claude Code plugin: a .claude-plugin/plugin.json manifest plus agent, skill, and command files. No npm install, no build step, no runtime code.

Prerequisites

Section titled “Prerequisites”
  • Claude Code with the claude CLI on PATH - required for validation and local loading.
  • Node.js and npm - required when installing through maestria install claude-code.
  • Node.js and pnpm - only needed to regenerate files from the canonical core directives.

Persistent installation through the maestria CLI

Section titled “Persistent installation through the maestria CLI”
Terminal window
npx maestria@latest install claude-code

The CLI downloads @maestria/claude-code from npm, stages it in a local marketplace under ~/.cache/maestria/, and delegates installation to Claude Code. Plugin state and scope stay in the host runtime.

Check, update, or remove the installation with:

Terminal window
npx maestria@latest status
Terminal window
npx maestria@latest update claude-code
Terminal window
npx maestria@latest uninstall claude-code

Claude Code’s marketplace update path selects the latest package. Exact version pinning is not available through maestria update claude-code --version.

Local validation (no install)

Section titled “Local validation (no install)”

From a checkout of this repository:

Terminal window
claude plugin validate ./packages/claude-code --strict

--strict treats warnings as errors and is the recommended CI check. A clean run prints ✔ Validation passed.

Verify Installation

Section titled “Verify Installation”

  1. Start a session with the plugin loaded

    --plugin-dir is session-only and can be passed multiple times to load several plugins:

    Terminal window
    claude --plugin-dir ./packages/claude-code

  2. Confirm the plugin and its components loaded

    Check the /plugin manager and the /context Custom Agents tab. Components are namespaced under maestria; the identifiers are listed in the table below.

  3. Check the read-only roles

    @maestria:adventurer, @maestria:planner, and @maestria:reviewer cannot call the Write or Edit tools (denied via disallowedTools).

What’s Inside

Section titled “What’s Inside”
Component Namespaced identifier Purpose
Agents @maestria:<agent> 7 specialist agents: adventurer, architect, builder, diagnose, planner, reviewer, writer
Skills /maestria:orchestrator, maestria:global-rules Routing methodology (user-invocable) and universal rules contract (preload-only)
Commands /maestria:fein, /maestria:sonar, /maestria:blitz Full pipeline, research-only, and fast implementation modes

Plugin-scoped skill preload resolution is not yet verified against a live session.

Tool Restrictions

Section titled “Tool Restrictions”

The only runtime enforcement in this package is disallowedTools: Write, Edit on adventurer, planner, and reviewer; skills, preloaded rules, and role prompts are advisory guidance, not a security boundary.

Claude Code ignores the permissionMode, hooks, and mcpServers agent frontmatter fields for plugin-loaded agents, so this plugin ships none of them. To enforce those fields, copy an agent file into .claude/agents/ or ~/.claude/agents/. The plugin does not ship a rules/ directory and does not write project or user CLAUDE.md files.

Uninstalling

Section titled “Uninstalling”

Persistent install:

Terminal window
npx maestria@latest uninstall claude-code

Session-only load: stop passing --plugin-dir. The staging directory is safe to remove afterwards:

Terminal window
rm -rf ~/.cache/maestria/claude-code-marketplace

Direct Claude Code marketplace installation

Section titled “Direct Claude Code marketplace installation”
Terminal window
claude plugin marketplace add agustinusnathaniel/maestria
claude plugin install maestria@maestria --scope user

Next Steps

Section titled “Next Steps”