| name | maestro |
| description | Spec-driven development framework that integrates with OpenCode to provide structured project planning, track management, and implementation workflow. Use when you need to: (1) Initialize a new Maestro project with product definition, tech stack, and workflow configuration, (2) Create new tracks (features/bug fixes) with interactive specification generation, (3) Implement tracks with automatic agent selection based on task complexity, (4) View project status and progress across all tracks, (5) Revert work at track/phase/task level. This skill provides a complete TDD workflow with project memory, git-aware tracking, and multi-agent orchestration. |
| metadata | {"short-description":"Maestro spec-driven development"} |
Maestro Skill
Maestro is a spec-driven development framework that provides structured project planning, track management, and implementation workflow with automatic agent selection.
Quick Start
Initialize a new project:
/maestro setup
Create a new track:
/maestro newTrack "Add user authentication"
Implement a track:
/maestro implement <track_name_or_id>
View project status:
/maestro status
Revert work:
/maestro revert [track|phase|task]
Core Concepts
Tracks
A track is a feature, bug fix, or chore that goes through:
- Specification (
spec.md) - Interactive requirements gathering
- Planning (
plan.md) - Detailed task breakdown
- Implementation - Automatic agent selection based on complexity
Project Structure
maestro/
├── product.md # Product vision and guidelines
├── tech-stack.md # Technology stack choices
├── workflow.md # Development workflow rules
├── tracks.md # Track registry and overview
├── setup_state.json # Setup progress tracking
└── tracks/
└── <track_id>/
├── spec.md # Track specification
└── plan.md # Implementation plan
Agent Selection
Maestro automatically selects appropriate agents during implementation:
- oracle: Architecture, code review, strategy.
- librarian: Multi-repo analysis, doc lookup, implementation examples.
- explore: Fast codebase exploration and pattern matching.
- frontend-ui-ux-engineer: Designer turned developer. Builds gorgeous UIs.
- document-writer: Technical writing expert.
- multimodal-looker: Visual content specialist. Analyzes PDFs, images, diagrams.
Commands Reference
/maestro setup
Initialize the Maestro environment for a new or existing project.
Process:
- Detects if project is greenfield (new) or brownfield (existing)
- For brownfield: Analyzes existing code to understand tech stack
- Interactive product definition (vision, guidelines, tech stack)
- Workflow and code styleguide selection
- Generates initial track
When to use: First time setting up Maestro in a project directory.
/maestro newTrack <description>
Create a new track with interactive specification generation.
Process:
- Loads project context from
maestro/ directory
- Asks 3-5 clarifying questions based on track type
- Generates comprehensive
spec.md with:
- Overview
- Functional Requirements
- Non-Functional Requirements
- Acceptance Criteria
- Out of Scope
- Creates detailed
plan.md with task breakdown
- Registers track in
tracks.md
When to use: Starting any new feature, bug fix, or chore.
/maestro implement <track_name_or_id>
Execute the implementation plan for a specific track.
Process:
- Loads track specification and plan
- Identifies task complexity and requirements
- Automatically selects appropriate agent for each task:
- Architecture & Strategy → oracle
- Codebase Analysis → librarian
- UI/UX Implementation → frontend-ui-ux-engineer
- Documentation → document-writer
- Executes tasks with TDD workflow (test → implement → refactor)
- Tracks progress in
plan.md
- Stores context to memory system
When to use: Implementing a track that has been planned.
/maestro status
Display current progress across all tracks.
Output includes:
- Current phase and in-progress tasks
- Completion statistics (phases, tasks, percentage)
- Next pending actions
- Any blockers or dependencies
- Memory context timestamp
When to use: Checking project progress, identifying next actions.
/maestro revert [track|phase|task]
Revert previous work at specified granularity.
Options:
- track: Revert entire track to pre-implementation state
- phase: Revert specific phase within current track
- task: Revert specific task (default if not specified)
When to use: Undoing implementation work, recovering from errors.
Workflow
Development Cycle
- Plan - Use
/maestro newTrack to create spec and plan
- Implement - Use
/maestro implement to execute with automatic agent selection
- Review - Maestro includes built-in agent review for critical code
- Track - Use
/maestro status to monitor progress
TDD Integration
Maestro enforces Test-Driven Development:
- Write failing test first
- Implement minimal code to pass
- Refactor for quality
- Commit with test coverage
Integration with OpenCode
This skill integrates Maestro's workflow with OpenCode's agent system:
Command Mappings
/maestro setup → Loads ~/.config/opencode/commands/maestro:setup.md/maestro newTrack → Loads ~/.config/opencode/commands/maestro:newTrack.md/maestro implement → Loads ~/.config/opencode/commands/maestro:implement.md/maestro status → Loads ~/.config/opencode/commands/maestro:status.md/maestro revert → Loads ~/.config/opencode/commands/maestro:revert.md
Agent Delegation
Maestro commands automatically delegate to specialized agents:
- Code review & strategy → oracle
- Analysis & understanding → librarian
- UI/UX implementation → frontend-ui-ux-engineer
- Technical writing → document-writer
Dependencies
Required MCPs
- nexus-memory: Project context and memory storage
- memori-memory-mcp: Enhanced memory with categorization
Required Skills
None - Maestro works standalone
Compatible Agents
All OpenCode agents are compatible:
- oracle
- librarian
- explore
- frontend-ui-ux-engineer
- document-writer
- multimodal-looker
Best Practices
- Always run setup first - Ensures proper project context
- Be specific in track descriptions - Better specs = better plans
- Let agent selection work automatically - Trust the complexity analysis
- Check status regularly - Stay aligned with progress
- Use revert carefully - Can undo significant work
Troubleshooting
"Maestro is not set up"
→ Run /maestro setup first
"tracks.md not found"
→ Run /maestro setup to initialize project structure
Agent not found
→ Ensure OpenCode agent is properly configured in opencode.jsonc
Memory errors
→ Check nexus-memory MCP is running and configured
Advanced Features
Prompt Enhancer Integration
Maestro integrates with prompt enhancer for context-aware question generation during spec creation.
Git-Aware Tracking
Maestro tracks implementation progress alongside git commits for complete history.
Multi-Project Support
Each project directory maintains its own Maestro state.
Templates
Maestro uses templates for consistent project setup:
workflow.md - Development workflow rulescode_styleguides/* - Language-specific style guides- Located in the installed OpenCode skill directory:
~/.config/opencode/skill/maestro/templates/
See Also
