mirror of
https://github.com/jlengrand/Maestro.git
synced 2026-03-10 08:31:19 +00:00
c5a0e99bbf
Replace 'multi-document batch runs' and 'batch processing' terminology with 'Auto Run' (individual documents) and 'Playbook' (collections of Auto Run documents) across user-facing documentation. Preserves 'batch mode' references where they describe Claude Code's actual non-interactive operation mode.
3.7 KiB
3.7 KiB
title, description, icon
| title | description | icon |
|---|---|---|
| Overview | Learn about Maestro's spec-driven workflow for AI-assisted development with multiple agents. | compass |
Maestro hones fractured attention into focused intent. It is built for developers who need to coordinate multiple AI agents, repositories, and long-running tasks without leaving a keyboard-first workflow.
Spec-Driven Workflow
Maestro enables a specification-first approach to AI-assisted development. Instead of ad-hoc prompting, you collaboratively build detailed specs with the AI, then execute them systematically:
- PLAN — Discuss the feature with the AI agent
- SPECIFY — Create markdown docs with task checklists in the Auto Run document folder
- EXECUTE — Auto Run works through tasks, spawning a fresh session per task
- REFINE — Review results, update specs, and repeat
Why this works:
- Deliberate planning — Conversation forces you to think through requirements before coding
- Documented specs — Your markdown files become living documentation
- Clean execution — Each task runs in isolation with no context bleed
- Iterative refinement — Review, adjust specs, re-run — specs evolve with your understanding
Example workflow:
- Plan: In the AI Terminal, discuss your feature: "I want to add user authentication with OAuth support"
- Specify: Ask the AI to help create a spec: "Create a markdown checklist for implementing this feature"
- Save: Copy the spec to your Auto Run document folder (or have the AI write it directly)
- Execute: Switch to Auto Run tab, select the doc, click Run — Maestro handles the rest
- Review: Check the History tab for results, refine specs as needed
This approach mirrors methodologies like Spec-Kit, but with a graphical interface, real-time AI collaboration, and multi-agent parallelism.
Key Concepts
| Concept | Description |
|---|---|
| Agent | A Maestro workspace tied to a project directory, backed by a provider (Claude Code, Codex, or OpenCode). Each agent has a Command Terminal and AI Terminal. |
| Provider | The underlying AI coding assistant (Claude Code, OpenAI Codex, or OpenCode) that powers an agent. |
| Session / Tab | A conversation with the AI provider. Sessions and tabs are 1:1 — each tab represents one session. Agents can have multiple tabs for parallel conversations. |
| Group | Organizational container for agents. Group by project, client, or workflow. |
| Group Chat | Multi-agent conversation coordinated by a moderator. Ask questions across multiple agents and get synthesized answers. |
| Git Worktree | An isolated working directory linked to a separate branch. Worktree sub-agents appear nested under their parent in the agent list and can create PRs. |
| AI Terminal | The conversation interface with your AI provider. Supports @ file mentions, slash commands, and image attachments. |
| Command Terminal | A PTY shell for running commands directly. Tab completion for files, git branches, and command history. |
| Session Explorer | Browse all past sessions for an agent. Star, rename, search, and resume any previous conversation. |
| Auto Run | Automated task runner that processes markdown checklists. Spawns a fresh session per task. |
| Playbook | A saved collection of Auto Run documents with document order, options, and settings for repeatable workflows. |
| History | Timestamped log of all actions (user commands, AI responses, Auto Run completions) with session links. |
| Remote Control | Web interface for mobile access. Local network or remote via Cloudflare tunnel. |
| CLI | Headless command-line tool for scripting, automation, and CI/CD integration. |