Maestro
Govern complex repos with Plan-Act-Verify, persistent project memory, and TDD before your agent writes production code.
Overview
Maestro is a journey-wide agent skill that enforces Elite Software Architect governance—session boot order, Socratic planning, RFC-lite plans, TDD, and verification—whenever a solo builder needs disciplined orchestration
Install
npx skills add https://github.com/xenitv1/claude-code-maestro --skill maestroWhat is this skill?
- Mandatory session boot sequence: SKILL.md → agents/ → skills/ before any work
- Socratic Gate plus Architecture First (implementation_plan.md) before production code
- Iron Law of TDD: failing test before implementation; Verification Matrix with evidence
- Plan-Act-Verify lifecycle with persistent Brain memory across sessions
- Why over How philosophy for Elite Software Architect persona
- 5 prime directives including Iron Law of TDD and Verification Matrix
- Mandatory 3-step session initiation: SKILL.md, agents/, skills/
Adoption & trust: 551 installs on skills.sh; 211 GitHub stars; 2/3 security scanners passed (skills.sh audits).
What problem does it solve?
Your agent forgets prior decisions, ships on assumptions, and skips tests while large repos lose architectural continuity across sessions.
Who is it for?
Solo builders on complex or long-lived codebases who want mandatory planning, TDD, and sub-skill orchestration instead of ad-hoc agent coding.
Skip if: Quick one-off scripts where you already have an approved spec and do not want governance overhead, Socratic questioning, or RFC-style planning gates.
When should I use this skill?
You need to act as an Elite Software Architect (Maestro) to manage complex repositories with Why over How, persistent Brain memory, and Plan-Act-Verify orchestration.
What do I get? / Deliverables
Sessions run under Plan-Act-Verify with a maintained Brain, approved implementation_plan.md for complex work, and evidence-backed completion after failing tests precede production code.
- implementation_plan.md for complex work
- Verification evidence per deliverable
- Test-first code changes under TDD
Recommended Skills
Journey fit
Useful at every journey phase - explore requirements and options before committing to a direction.
Where it fits
Turn a fuzzy feature request into an implementation_plan.md after the Socratic Gate surfaces edge cases and scope.
Orchestrate domain sub-skills only after governance and persona files are loaded so integrations follow Architecture First.
Maintain Brain memory so agent tooling changes stay consistent with prior architectural decisions.
Enforce failing tests before production code and collect verification evidence before marking work complete.
Resume sessions with the mandatory read sequence so production iteration does not drop institutional context.
How it compares
Use instead of unconstrained agent coding when you need a repeatable architect protocol, not a single-purpose linter or MCP integration.
Common Questions / FAQ
Who is maestro for?
Indie and solo developers using Claude Code (or similar) on non-trivial repos who need session continuity, architectural discipline, and test-first delivery.
When should I use maestro?
At the start of any Maestro-governed repo session (build planning), before complex features (validate scope into implementation_plan.md), and throughout ship when verifying deliverables with evidence—not only during initial scaffolding.
Is maestro safe to install?
It is a procedural governance skill that directs file reads, planning docs, and TDD workflows; review the Security Audits panel on this Prism page before trusting it with production repos.
SKILL.md
READMESKILL.md - Maestro
# 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 `/