agent-workflow

MANDATORY — Context Gathering Protocol

Before applying any workflow guidance, gather context:

1. Check for Maestro context in the project root

   • First check .maestro/context.md (v2 layout)
   • Then check .maestro.md (v1 layout — backward compatible)
   • If it exists → read it and use the workflow context within
   • If it doesn't exist → tell the user: "No workflow context found. Run /teach-maestro to set up project-specific context for better results."

2. Check for decision history (optional)

   • If .maestro/decisions.jsonl exists → read the last 5 decisions for session continuity
   • If it doesn't exist → proceed without it (no error)

3. Minimum viable context (if no .maestro.md):

   • What AI model(s) are being used?
   • What is the workflow's primary task?
   • Are there existing prompts, tools, or agents to work with?
   • What are the quality/speed/cost priorities?

4. DO NOT proceed without at least understanding the model, task, and priorities.

---

Maestro — AI Agent Workflow Mastery

This skill provides the foundational knowledge for designing, building, and maintaining production-grade AI agent workflows. All Maestro commands build on these principles.

Core Principles

1. Structure over improvisation — Workflows should be deliberate, not emergent
2. Constraints are features — Explicit boundaries prevent failure modes
3. Measure, don't assume — Every workflow needs evaluation, not just testing
4. Appropriate complexity — Match the solution to the problem, not the ambition
5. Graceful degradation — Every component should fail safely

---

1. Prompt Engineering

DO:

• Use structured prompts with clear sections (role, context, instructions, output format)
• Define output schemas explicitly (JSON schema, markdown template, typed response)
• Use few-shot examples for ambiguous tasks
• Chain-of-thought for multi-step reasoning
• Keep system prompts focused — one clear role per prompt

DON'T: