> ## Documentation Index
> Fetch the complete documentation index at: https://docs.igent.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick start

Get productive with Maestro in your first session.

## Your First Session

### 1. Start with a Clear Goal

Maestro works best when you define clear objectives. Instead of:

**Bad**: "Help me with my code"

Try:

**Good**: "Implement a Redis-based rate limiter that supports token bucket algorithm, handles distributed scenarios, and includes comprehensive tests with performance benchmarks"

### 2. Understand Session Structure

Every Maestro interaction happens within a **session**--an independent, resumable workspace containing:

* **Memories**: Dialog history and learnings
* **Files**: Your project's complete file tree with full iteration history
* **Tools**: Maestro's capabilities for this session
* **Sandbox**: Isolated execution environment

Sessions are **checkpointed automatically** and can be resumed across days or weeks.

### 3. Set Success Criteria

Help Maestro understand what "done" looks like:

```
Implement user authentication with the following requirements:
- JWT-based with refresh tokens
- Rate limiting on login endpoints
- Comprehensive test coverage (>90%)
- Performance: <100ms for token validation
- Security: resistant to timing attacks

Success criteria:
- All tests pass
- Performance benchmarks meet targets
- No security vulnerabilities in static analysis
- Clean, documented code ready for PR
```

### 4. Let Maestro Plan

Maestro will often create an implementation plan. Review it:

* Does it understand the requirements correctly?
* Are there architectural concerns to address?
* Any constraints or edge cases to highlight?

This planning phase prevents costly mistakes later.

### 5. Watch Maestro Work

As Maestro executes, you'll see:

* **Terminal streams**: Real-time sandbox output
* **File changes**: Code proposals and applications
* **Test results**: Validation and benchmarks
* **Status updates**: Current activity and progress

### 6. Validate and Push Back

When Maestro claims completion:

**Don't accept**: "The implementation is performing well"

**Demand**: "Show me the benchmark results comparing this to the baseline using the same methodology"

**Core principle**: Evidence, not confidence.

## Example Session: Adding a Feature

Let's walk through adding a caching layer to an existing API:

### Initial Request

```
I need to add Redis caching to our REST API to reduce database load.

Requirements:
- Cache GET requests for user profiles
- 5-minute TTL
- Cache invalidation on user updates
- Must not break existing tests

Clone github.com/myorg/api-server branch main to get started.
```

### Maestro's Response Pattern

1. **Understanding Phase**
   * Clones repository
   * Reviews existing architecture
   * Identifies integration points
   * Asks clarifying questions if needed

2. **Planning Phase**
   * Proposes caching strategy
   * Identifies files to modify
   * Outlines test approach
   * Estimates scope

3. **Implementation Phase**
   * Creates cache middleware
   * Integrates with existing routes
   * Updates tests
   * Adds configuration

4. **Validation Phase**
   * Runs existing test suite
   * Adds cache-specific tests
   * Benchmarks performance improvement
   * Verifies cache invalidation

### Your Role During This

* **Review the plan**: Challenge if anything seems off
* **Monitor progress**: Watch terminal streams and file changes
* **Validate thoroughly**: When Maestro says "done", verify:
  * Do all tests actually pass?
  * Are the benchmarks real?
  * Does the code handle edge cases?
* **Push back**: If validation is insufficient, demand more

## Common First-Session Patterns

### Pattern 1: Understanding Existing Code

```
Clone repository X and explain how the authentication system works.
Focus on:
- Token generation and validation flow
- Session management
- Security considerations
- Integration with other services
```

### Pattern 2: Implementing a New Feature

```
Add real-time notifications to our app using WebSockets.

Requirements:
- Server-side: Node.js with Socket.IO
- Client-side: React hooks for subscription
- Authentication: reuse existing JWT
- Must handle reconnection gracefully

Validate with:
- Unit tests for server logic
- Integration tests for end-to-end flow
- Load testing for 1000 concurrent connections
```

### Pattern 3: Performance Optimization

```
Our image processing pipeline is too slow. Current: 2 seconds per image.

Goal: Reduce to <500ms per image

Approach:
1. Profile current implementation
2. Identify bottlenecks
3. Propose optimization strategies
4. Implement and benchmark
5. Compare new vs old performance with same test images

Provide detailed evidence for each optimization.
```

## Best Practices for Success

### Clear Success Criteria

Define measurable outcomes:

* "Performance should exceed baseline by 20%"
* "All existing tests must continue passing"
* "Implementation must handle 10,000 concurrent users"

### Demand Evidence, Not Claims

Always ask for validation:

* **Bad**: "The implementation is working"
* **Good**: "Show me the test output proving it works"

### Never Accept Shortcuts

Maintain quality standards:

* Zero test failures tolerated
* Every performance claim must be validated
* All edge cases must be tested
* Regressions are unacceptable

### Use Existing Infrastructure

Don't reinvent testing tools:

* "Use the existing test suite structure"
* "Run the benchmark scripts already in the codebase"
* "Follow the established patterns"

## Understanding Capacity

Sessions consume tokens based on:

* Dialog history (memories)
* Files you're viewing
* Tools available
* Sandbox state

Watch the **capacity indicator** in the top right. If capacity gets tight:

* Use `/forget` to remove old dialog
* Use `/hidefiles` to reduce file context
* Use `/refresh` to view only latest file versions

The system will warn you and suggest actions when needed.

## What to Expect

### First Session (Typically)

* Learning Maestro's capabilities
* Understanding the partnership model
* Getting comfortable with goal-driven delegation
* Discovering how much autonomy is appropriate

### After a Few Sessions

* Tackling larger, more complex projects
* Trusting Maestro with more significant work
* Developing efficient communication patterns
* Understanding when to intervene vs delegate

### Experienced Users

* Running multiple parallel sessions for different projects
* Delegating entire features with minimal oversight
* Leveraging advanced commands and workflows
* Pushing Maestro to its capability limits

## Next Steps

Now that you understand the basics:

1. **[Core Concepts](getting-started/core-concepts)**: Deep dive into sessions, memories, files, and tools
2. **[Working with Maestro](getting-started/working-with-maestro)**: Learn effective collaboration patterns
3. **[Commands Reference](getting-started/commands)**: Master session control and utilities
4. **[Tools Overview](getting-started/tools)**: Understand Maestro's capabilities

## Need Help?

* Something unclear? Ask Maestro to explain
* Hit a problem? Describe what went wrong
* Want to try something? Just ask

Remember: Maestro is designed to help you succeed. Be clear, be specific, and demand high standards.