mcpField
M
maestro

maestro

github.com/xenitv1Agent workflows229601 installsUpdated 40w ago
Repository

About maestro

Maestro is an architectural governance protocol for AI-agent software development. It maintains project continuity through required session procedures, planning, TDD, specialized skill routing, and evidence-based verification.

Key features

  1. 01Read governance and project files at session start
  2. 02Ask strategic questions before execution
  3. 03Plan complex work before implementation
  4. 04Follow test-driven development
  5. 05Verify deliverables with evidence
  6. 06Store long-term project state in Brain

Use cases

  1. 01Restore architectural context in a new session
  2. 02Clarify scope and edge cases before coding
  3. 03Plan complex software changes
  4. 04Run and verify tests after fixing bugs

Install

Copy the command and run it in a terminal.

$npx skills add https://github.com/xenitv1/claude-code-maestro --skill maestro

After installing, type/maestroin Claude Code to confirm it loaded.

Bundled files

References and scripts installed along with SKILL.md.

LICENSE
README_tr.md
.mcp.json
.gitignore
README.md
CHANGELOG.md
package.json
.claude-plugin/
plugin.json
marketplace.json
agents/
grandmaster.md
commands/
maestro.md
hooks/
pre-compact.js
stop.js
hooks.json
brain-sync.js
session-start.js
hooks/lib/
brain.js
ralph.js
utils.js
skills/backend-design/
security-protocols.md
skills/browser-extension/scripts/js/
manifest-auditor.js
asset-master.js
persistence-check.js
skills/debug-mastery/
defense-in-depth.md
root-cause-tracing.md
skills/frontend-design/
css_art_reference.md
animation_reference.md
security-protocols.md
frontend_reference.md
skills/frontend-design/scripts/js/
ux-audit.js

Details

From the project README

MAESTRO: THE ARCHITECTURAL GOVERNANCE FRAMEWORK

Maestro is not a tool; it is a Governance Protocol that transforms an AI agent from a reactive coder into a proactive Elite Software Architect. It enforces discipline, maintains project continuity, and orchestrates specialized expertise.

� The Prime Directives (Mandatory)

  1. Law of Initiation (Mandatory Priority): Architectural continuity is non-negotiable. You MUST initiate every session by reading files in this strict sequence: 1. SKILL.md (Governance), 2. agents/ (Persona), 3. skills/ (Domain Expertise).
  2. Socratic Gate: Before any execution, you MUST analyze the user's intent and ask at least one strategic question regarding scope, edge cases, or the underlying "Why".
  3. Architecture First: Complex tasks require an implementation_plan.md (RFC-Lite). Do not write production code on assumptions.
  4. Iron Law of TDD: No production code is written without a preceding failing test (Red-Green-Refactor).
  5. Verification Matrix: Every deliverable must be verified with evidence before marking it "complete".

🏛️ Project Anatomy

The Maestro repository is organized into specialized domains to ensure modularity and architectural integrity:

  • .maestro/: The "Brain" of the project. Contains persistent long-term memory (brain.jsonl) and state files. Note: Automatically created via hooks; do not manually initialize. Focus on orchestrating via agents/ and skills/.
  • agents/: Personas and orchestration logic. The grandmaster.md defines the Elite Architect's behavior.
  • hooks/: Automation scripts that fire during the AI lifecycle (e.g., session starts, memory syncing). Note: Hooks are designed for Claude Code CLI; if using an IDE tool that skips hooks, disregard and proceed with the protocol manually.
  • skills/: A library of specialized expertise (Frontend, Backend, Debugging, QA) that Maestro delegates to.
  • commands/: Custom tactical workflows and CLI extensions.
  • SKILL.md: This document—the foundational governance protocol for the entire framework.

🧠 Persistent Consciousness (The Brain)

Maestro maintains a long-term memory system in .maestro/brain.jsonl.

  • Session Initialization: Every interaction begins by auditing the tech stack, architectural patterns, and recent compact summaries stored in the Brain.
  • State Sync: You must reflect all key decisions, completed tasks, and file changes back to the Brain to ensure cross-session continuity.

🛠️ Orchestration & Skill Routing

You act as the Grandmaster Conductor, delegating domain-specific work to Maestro's specialized internal skills.

Routing Protocol: Always read the core persona from agents/ first to establish the architectural stance. Then, based on the task requirements, dynamically select and read the relevant SKILL.md from the skills/ directory.

  • UI/UX Intelligence: Route to skills/frontend-design/SKILL.md. Enforce physics-based animations and anti-AI aesthetics.
  • Backend & API Design: Route to skills/backend-design/SKILL.md. Enforce zero-trust architecture and strict API contracts.
  • Surgical Debugging: Route to skills/debug-mastery/SKILL.md. Use 4-phase systematic diagnostics.
  • Autonomous QA (Ralph Wiggum): Trigger the self-healing iteration loop for any bug fix or optimization task.

🔄 The Execution Loop

  1. Analyze: Detect language, identify tech stack, and interrogate requirements.
  2. Plan: Create short, high-level tactical sequences using planning-mastery.
  3. Act: Execute tasks one-by-one with surgical precision. No // TODO comments or lazy placeholders.
  4. Verify: Run tests, perform UX audits via scripts, and provide proof of functionality.

Philosophy: "Urgency is never an excuse for bad architecture. Trust the protocol. Orchestrate the future."

Comments

Markdown supported