"Maestro" - MultiAgent Builder

English Version | Versión en Español

---

English Version

English Version

Reference repository to define and evolve the global Maestro agent and its project-level team templates.

Goal

Use a global agent (user profile) that:

• analyzes the currently open project,
• generates a specialized team in .github/agents/ inside that project,
• supports existing, greenfield, and agent-audit modes,
• initializes structured memory in .github/agent-memory/,
• can use terminal commands for controlled bootstrap when needed.

Quick Setup (Global Maestro)

1. Open Chat in VS Code.
2. In the agent selector, choose Configure custom agents....
3. Create an agent in User profile location.
4. Copy the content of documentation/templates/maestro-global.agent.md.
5. Save and return to the agent selector.

Included Templates

• documentation/templates/maestro-global.agent.md
• documentation/templates/project-orchestrator.agent.md
• documentation/templates/greenfield-kickoff.agent.md

Recommended Usage

Existing project (existing)

• Invoke Maestro and request team design/generation.
• Maestro inspects stack and conventions, proposes a team, and creates agents in .github/agents/.
• Team sizing policy: baseline 4-8 agents, but can exceed 8 when project depth justifies it (no overengineering).

New project (greenfield)

• Invoke Maestro and confirm greenfield mode.
• Maestro opens two intake paths:
  • Natural-language idea (fixed 6-question script).
  • Complete Markdown document.
• If the document exceeds 200 lines, Maestro uses phased consultation:
  • logical chunking,
  • per-phase summary,
  • short validation per phase,
  • consolidation into a brief source of truth.
• Before stack recommendation, Maestro must output a rigid Markdown Initial Discovery Summary (sections 1 to 8).
• Then it compares 2-3 stack options, recommends 1, and creates the baseline team.
• Then it compares 2-3 stack options, recommends 1, and creates the baseline team.
• Agent count remains dynamic: baseline 4-8, extend only with explicit justification and non-overlapping scope.
• Expected quality gates v1: lint, test smoke, build, and minimal CI.
• Expected Milestone 1 (recommended baseline): E2E vertical slice with verifiable acceptance criteria, or an equivalent first milestone if the project context requires a different sequence.
• Expected Milestone 2: Real scenario validation in staging/UAT with evidence, observability baseline, and rollback plan.

Agent audit (agent-audit)

• Inventories agents in .github/agents/.
• If memory is missing, creates .github/agent-memory/ and base files.
• Reports coverage gaps (orchestrator/planner/code-auditor), overlaps, and outdated tools.
• Does not modify agents without explicit confirmation.

Quick Validation Checklist

• Maestro appears in the agent selector.
• After execution, .github/agents/ exists in the target project.
• .github/agent-memory/ exists with base files.
• project-orchestrator.agent.md exists (or versioned -v2, -v3, etc.).
• In greenfield mode, greenfield-kickoff.agent.md also exists.

Note

This repository is for agent-system design/documentation. Operational agents are generated inside each target project.

The repository does not pre-create project agents or memory files; Maestro generates them on demand per project.

---

Versión en Español

Versión en Español

Repositorio de referencia para definir y evolucionar el agente global Maestro y sus plantillas de equipo por proyecto.

Objetivo

Usar un agente global (perfil de usuario) que:

• analice el proyecto abierto,
• genere un equipo especializado en .github/agents/ del proyecto actual,
• soporte modo existing, greenfield y agent-audit,
• inicialice memoria estructurada en .github/agent-memory/,
• pueda usar terminal para bootstrap controlado cuando aplique.

Instalación rápida (Maestro global)

1. Abre Chat en VS Code.
2. En el selector de agentes, elige Configurar agentes personalizados....
3. Crea un agente en ubicación User profile.
4. Copia el contenido de documentation/templates/maestro-global.agent.md.
5. Guarda y vuelve al selector de agentes.

Plantillas incluidas

• documentation/templates/maestro-global.agent.md
• documentation/templates/project-orchestrator.agent.md
• documentation/templates/greenfield-kickoff.agent.md

Uso recomendado

Proyecto existente (existing)

• Invoca Maestro y pide diseño/generación del equipo.
• Maestro analiza stack y convenciones, propone equipo y crea agentes en .github/agents/.
• Política de tamaño de equipo: baseline 4-8 agentes, pudiendo superar 8 si la profundidad del proyecto lo justifica (sin sobreingeniería).

Proyecto desde cero (greenfield)

• Invoca Maestro y confirma modo greenfield.
• Maestro abre una puerta de entrada con 2 rutas:
  • Idea en lenguaje natural (script fijo de 6 preguntas).
  • Documento completo en Markdown.
• Si el documento supera 200 líneas, Maestro entra en consulta por fases:
  • segmentación por bloques,
  • resumen por fase,
  • validación corta por fase,
  • consolidación en una fuente de verdad breve.
• Antes de proponer stack, Maestro debe emitir un Resumen de Discovery Inicial en plantilla Markdown rígida (secciones 1 a 8).
• Luego compara 2-3 stacks, recomienda 1 y crea equipo base.
• Luego compara 2-3 stacks, recomienda 1 y crea equipo base.
• El conteo de agentes es dinámico: baseline 4-8, ampliable solo con justificación explícita y sin solapamiento de alcance.
• Quality gates v1 esperados: lint, test smoke, build, CI mínima.
• Hito 1 esperado (baseline recomendado): vertical slice E2E con criterios verificables, o un hito equivalente si el contexto del proyecto requiere otra secuencia.
• Hito 2 esperado: validación de escenario real en staging/UAT con evidencia, observabilidad mínima y plan de rollback.

Auditoría de agentes (agent-audit)

• Inventaria agentes en .github/agents/.
• Si falta memoria, crea .github/agent-memory/ y archivos base.
• Reporta gaps (orquestador/planner/code-auditor), solapamientos y tools desactualizadas.
• No modifica agentes sin confirmación explícita.

Checklist de validación rápida

• Aparece Maestro en el selector de agentes.
• Tras ejecutar Maestro, existe .github/agents/ en el proyecto objetivo.
• Existe .github/agent-memory/ con archivos base.
• Existe project-orchestrator.agent.md (o versión -v2, -v3, etc.).
• En greenfield, existe también greenfield-kickoff.agent.md.

Nota

Este repositorio es de diseño/documentación del sistema de agentes. Los agentes operativos se generan dentro de cada proyecto destino.

El repositorio no pre-crea agentes ni archivos de memoria del proyecto; Maestro los genera bajo demanda por proyecto.