Agent Workflow

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 4e163a7a8095 · 19 Oct 2026Report an issue or request a re-scan

• Publishersharpdeveye GitHub userOwner of the repository this skill is read from
• Source foldersharpdeveye/maestro/source/skills/agent-workflowThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict4e163a7a8095A new audit runs when the source changes
• Repository statusNot archivedLast push 173 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Use when any Maestro command is invoked — provides foundational workflow design principles across prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, and…

---
name: agent-workflow
description: "Use when any Maestro command is invoked — provides foundational workflow design principles across prompt engineering, context management, tool orchestration, agent architecture, feedback loops, knowledge systems, and guardrails."
category: core
version: 2.0.0
user-invocable: false
---

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

Excerpt, first 6,000 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/sharpdeveye/maestro
git -C maestro checkout 4e163a7a8095

Works in

1. 2026-10-19
   ✓SAFE B 89 / 100

   first audit · source 4e163a7a8095

Questions about Agent Workflow

• github.com/sharpdeveye/maestro/tree/main/source/skills/agent-wor — the audited source at commit 4e163a7a8095 and every finding aboveObserved · 19 Oct 2026

Spotted something wrong? Report a correction · Methodology