maestro

maestro

Language policy (.maestro/engine/docs/language-policy.md): framework documents, workflow rules, agent definitions, command definitions, templates, entry points, and methodology playbooks are written in English so AI agents read them with minimal ambiguity. The conversation follows the user. Identifiers such as paths, agent ids, rule ids, YAML keys, command names, and tool names remain English contract tokens.

maestro is a product-development control plane for building and operating real software with AI agents. It keeps product code, official documentation, design decisions, work history, runtime state, and agent memory in separate, auditable domains.

The root name stays stable as maestro. The actual product identity and namespace live in .maestro/project.yaml.

Documentation Entry Points

Need	File
Fast workspace startup	QUICKSTART.md
Slash command index	COMMAND.md
Framework overview	README.md
Install, upgrade, and validation guide	SETUP.md
Entry point for non-Claude AI agents	AGENTS.md
Entry point for Claude Code	CLAUDE.md
Entry point for Codex	.codex/AGENTS.md
Entry point for Cursor	.cursor/rules/maestro.mdc
Entry point for Gemini	.gemini/GEMINI.md
Entry point for Kiro	.kiro/steering/maestro.md
Workflow source of truth	.maestro/engine/workflow.md
Agent taxonomy	.maestro/engine/docs/agent-taxonomy.md

Why This Workspace Exists

AI coding tools are powerful, but in a real codebase the same problems repeat:

• Each conversation can start as a fresh context, so decisions, conventions, and known mistakes are easy to lose.
• Agents may jump into code before analyzing requirements, impact, ownership, or test policy.
• Without explicit write scope, agents may edit files outside the task boundary.
• Completion claims can happen without verification evidence.
• Review feedback and bug root causes are often not recorded for future work.

maestro adds a control plane before source edits happen.

Problem	Workspace mechanism
Agents forget durable context	.maestro/knowledge/ and .maestro/memory/ preserve reusable project knowledge
Every task is treated the same	direct, assisted, and governed modes scale process to task risk
Agents do not know write boundaries	Component registry and scoped coder agents define read/write scope
Quality gates are inconsistent	Dev Verification and QC Runner require evidence before handoff
Mistakes repeat	Memory Update promotes root causes, patterns, and anti-patterns
Context grows too large	Indexes, context hints, and task context_plan limit what agents read
Large tasks are not decomposed	Initiative -> Epic -> Task -> Subtask contracts create bounded work
Product documentation is missing	docs/ stores PRD, feature, user story, flow, HLD, LLD, ADR, quality, and runbook artifacts

Execution Modes

Mode	Use When	Verification
direct	Small, fast work where the user can verify quickly	User or shared
assisted	Bounded work that may need resume, progress, or lightweight evidence	Agent or shared
governed	High-risk, cross-component, security, migration, production, or compliance work	Agent evidence plus required gates

The methodology router can select risk-based-routing, spec-driven-development, enterprise-agent-governance, or eval-driven-ai based on the task and the artifact requirements. These names are workspace overlays mapped to current production-agent patterns in industry-alignment.md: durable workflows, human-in-the-loop, artifact management, eval-driven AI, trace evidence, plugins, hooks, and governed enterprise autonomy.

The operating model is run-centric: a task describes intended work; a run records one execution attempt with checkpoints, trace links, eval evidence, approvals, and reports when needed. Agents can use python3 scripts/agent-run.py create|heartbeat|checkpoint|complete to maintain .maestro/work/runs/ without depending on a specific coding harness.

System Architecture

Diagram: see System overview in visual-flow.md (Mermaid).