agent-workflow

What this skill does

## 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)

2. **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?

3. **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**:

- Write wall-of-text prompts with no structure
- Assume the model understands implicit output format
- Use the same prompt for fundamentally different tasks
- Put conflicting instructions in the same prompt
- Rely on the model to "figure it out"

→ *Consult [prompt engineering reference](reference/prompt-engineering.md) for structure, patterns, and output schemas.*

---

## 2. Context Management

**DO**:

- Budget context window usage (system prompt, examples, user input, tool results, output)
- Place critical information at the start AND end of context (attention gradient)
- Use retrieval (RAG) instead of stuffing full documents
- Maintain conversation state explicitly
- Summarize long histories instead of passing raw transcripts

**DON'T**:

- Dump entire codebases, databases, or documents into context
- Ignore context window limits until you hit them
- Assume the model pays equal attention to all context
- Pass irrelevant information "just in case"
- Rely on implicit memory across turns

→ *Consult [context management reference](reference/context-management.md) for window optimization and memory patterns.*

---

## 3. Tool Orchestration

**DO**:

- Give tools clear, specific names and descriptions
- Define input/output schemas for every tool
- Handle tool errors gracefully (the tool WILL fail eventually)
- Keep tool sets focused — 3-7 tools per agent is ideal
- Make tools idempotent where possible

**DON'T**:

- Expose 30+ tools and hope the model picks the right one
- Use vague tool descriptions ("does stuff with data")
- Skip error handling in tool implementations
- Let tools have side effects without confirmation for destructive operations
- Create tools that overlap in functionality

→ *Consult [tool orchestration reference](reference/tool-orchestration.md) for selection heuristics and composition patterns.*

---

## 4. Agent Architecture

**DO**:

- Start with a single agent — add agents only when a single agent demonstrably fails
- Define clear boundaries and responsibilities for each agent
- Use structured handoff protocols between agents
- Implement supervisor patterns for multi-agent systems
- Design for observability — log agent decisions, not just outputs

**DON'T**:

- Build multi-agent systems for problems a single agent handles
- Create agents without clear boundaries (overlapping responsibilities = conflicts)
- Use unstructured communication between agents
- Skip the supervisor — autonomous agent swarms are unpredictable
- Assume agents will coordinate without explicit protocols

→ *Consult [agent architecture reference](reference/agent-architecture.md) for topology patterns and delegation.*

---

## 5. Feedback Loops

**DO**:

- Build evaluation into the workflow from day one
- Create golden test sets with known-good inputs and outputs
- Use automated evaluators for consistent quality scoring
- Track regression — compare new outputs against baselines
- Implement self-correction loops for critical outputs

**DON'T**:

- Ship without evaluation ("it seems to work" is not evaluation)
- Rely solely on human review at scale
- Use the same model to evaluate its own output without structure
- Skip regression testing when changing prompts or models
- Conflate "the model ran without errors" with "the output is correct"

→ *Consult [feedback loops reference](reference/feedback-loops.md) for evaluation patterns and self-correction.*

---

## 6. Knowledge Systems

**DO**:

- Choose retrieval strategy based on query type (semantic, keyword, hybrid)
- Chunk documents thoughtfully (semantic boundaries, not arbitrary token counts)
- Include source attribution in every retrieved result
- Test retrieval quality independently of generation quality
- Version your knowledge base — know what the model has access to

**DON'T**:

- Build RAG without testing retrieval quality first
- Use fixed chunk sizes for all document types
- Skip source attribution (hallucination without attribution is undetectable)
- Index everything without curation (garbage in = garbage out)
- Assume embedding similarity equals relevance

→ *Consult [knowledge systems reference](reference/knowledge-systems.md) for RAG, embeddings, and grounding.*

---

## 7. Guardrails & Safety

**DO**:

- Validate inputs before processing (schema validation, size limits)
- Filter outputs for sensitive content, PII, and policy violations
- Set hard cost ceilings (max tokens, max API calls, max spend per run)
- Implement circuit breakers for cascading failures
- Log everything for audit trails

**DON'T**:

- Deploy without input validation (prompt injection is real)
- Trust model output without verification for high-stakes decisions
- Run without cost controls (one runaway loop can cost thousands)
- Skip rate limiting on external API calls
- Assume the model will follow safety instructions 100% of the time

→ *Consult [guardrails reference](reference/guardrails-safety.md) for validation, sandboxing, and constraints.*

---

## The Workflow Slop Test

If any of these are true, the workflow needs work:

- [ ] Prompts are unstructured walls of text → run `/refine`
- [ ] No output schema defined — model decides the format → run `/refine`
- [ ] Context window used without budget — everything stuffed in → run `/accelerate`
- [ ] More than 10 tools exposed to a single agent → run `/streamline`
- [ ] No error handling — happy path only → run `/fortify`
- [ ] No evaluation — "it seems to work" → run `/iterate`
- [ ] Multi-agent system for a single-agent problem → run `/temper`
- [ ] No cost controls — unbounded token usage → run `/guard`
- [ ] Tools have vague one-line descriptions → run `/calibrate`
- [ ] No logging — can't debug production issues → run `/fortify`

**Zero checked = production-ready. 3+ checked = workflow slop.**

---

## Available Commands

Use these commands to apply specific aspects of workflow mastery:

{{available_commands}}