Maestro is a standalone backend agent framework designed to operate within GitHub Copilot and VS Code environments. It uses a multi-model architecture alongside Model Context Protocol (MCP) servers to write code, enforce workflow constraints, execute testing pipelines, and operate against feature branches.
This repository serves as the Toolchain Trunk. It is meant to be merged/overlaid into any target repository to immediately enable advanced Copilot execution rails.
When integrating Maestro into a new project, follow these steps to securely sync the files without polluting your app's core architecture.
To pull the Maestro toolchain directly into your existing app repository, run the makefile sync operation. (You only need to copy the Makefile manually during the first initialization):
wget https://raw.githubusercontent.com/blecx/maestro/main/Makefile -O Makefile.maestro
make -f Makefile.maestro sync-maestroThe AI architecture runs locally via Python and Docker. Generate the python environment for the agent runner:
python -m venv .venv
source .venv/bin/activate
pip install -r agents/requirements.txt # Or similar dependency rootNote: Ensure your .env contains the required keys for MCP tools (e.g. CONTEXT7_API_KEY).
Maestro agents are blind without Context Gateways (MCPs). Start the dockerized MCP suite using the automated Makefile:
make mcp-up(To stop them later, run make mcp-down).
The repository now uses a .copilot-first ownership model for workflow logic and agent configuration, with .github/agents kept as thin discovery wrappers for VS Code.
Primary docs:
- Automation Architecture - ownership model, canonical sources, wrappers, and runtime entrypoints.
- Fresh Clone Bootstrap - explicit setup and projection steps for a new workspace.
- VS Code Settings Guidance - projection-first guidance for workspace and optional user settings.
- Agents Overview - current Copilot custom-agent registry and wrapper model.
Maestro enforces a strict boundary between development-time aids and runtime applications:
- Software Factory Agents (residing in
.github/,.copilot/) assist developers in building the app. - Maestro Agents (residing in
agents/,apps/) are the runtime orchestrators that serve the end user.
Please ensure prompts for Maestro Agents are placed in agents/prompts/ and never commingled with developer tooling.