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

# Core concepts

Understanding the fundamentals of working with Maestro.

## Sessions: Your Persistent Workspace

A **session** is Maestro's fundamental unit of work--an independent, checkpointable, resumable artifact that contains everything needed to accomplish your goals.

### What's in a Session?

#### Memories

Dialog history containing records of previous turns. Includes:

* User requests and feedback
* Maestro's responses and reasoning
* Tool execution results
* Validation outcomes

**Management**: Memories can be forgotten (removed) or compacted (summarized) to manage session capacity.

#### Files

Complete support for source code and data in enterprise-scale projects:

* **Full iteration history**: Every change creates a new iteration; nothing is lost
* **Pattern-based operations**: Work with entire file sets using glob patterns
* **Smart synchronization**: Files sync between your session and sandbox automatically
* **Rich metadata**: Understand when files changed, who changed them, why

#### Tools

Comprehensive capabilities to:

* Manage and interact with files
* Execute code in isolated sandboxes
* Gather information from the web
* Create visualizations and diagrams
* Integrate with external services
* Package and download deliverables

#### Sandbox

Isolated Ubuntu Linux environment where:

* Code compiles and runs
* Tests execute
* Benchmarks measure performance
* Web servers start and accept requests
* Real validation happens

### Session Lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> Fresh: Start new session
    Fresh --> Active: First interaction
    Active --> Checkpointed: Periodic auto-save
    Checkpointed --> Active: Continue working
    Active --> Paused: Inactivity timeout
    Paused --> Active: Resume session
    Active --> [*]: Explicitly end
    Paused --> [*]: Session expired
```

#### Creating Sessions

* **Fresh sessions** start with empty memories and no files
* **Cloned sessions** can start from templates or existing projects
* **Resumed sessions** restore complete state from checkpoints

#### Automatic Checkpointing

Maestro automatically saves session state:

* At regular time intervals (default: every 5 minutes)
* When storage reaches size thresholds (default: 10GB)
* When disk pressure is high (default: 85% capacity)
* When explicitly requested

#### Resuming Sessions

Sessions can be resumed:

* After hours, days, or weeks
* Across different devices
* With full context restoration
* Including sandbox state where applicable

### Session Capacity

Every session has a **capacity limit** based on token consumption:

**Token Sources**:

* Dialog history (memories)
* Files currently in view
* Tool schemas and documentation
* Sandbox state and environment
* System instructions

**Capacity Management**:

* Watch the capacity indicator in the top right
* Click for detailed breakdown
* Use commands to reduce consumption when needed

**Why Capacity Matters**:

* Prevents context poisoning (too much irrelevant information)
* Maintains response quality
* Controls costs
* Keeps sessions focused

**Managing Capacity**:

* `/forget`: Remove old dialog selectively
* `/compact`: Summarize memories to free space
* `/hidefiles`: Reduce file context
* `/refresh`: View only latest file iterations

## The Maestro Partnership Model

Success with Maestro requires understanding your complementary roles:

### User's Role: Quality Controller & Strategic Guide

**Set Direction**

* Define clear objectives and success criteria
* Establish quality standards and constraints
* Make architectural decisions
* Choose when to intervene vs delegate

**Enforce Standards**

* Challenge logical inconsistencies
* Demand evidence for claims
* Push back when standards aren't met
* Never accept shortcuts on quality

**Validate Outcomes**

* Review test results skeptically
* Verify benchmarks are meaningful
* Check edge case handling
* Ensure documentation is accurate

### Maestro's Role: Technical Implementation Partner

**Execute Deeply**

* Handle thousands of lines of implementation
* Navigate complex codebases
* Integrate across multiple systems
* Maintain consistency and quality

**Validate Systematically**

* Test comprehensively
* Benchmark rigorously
* Document thoroughly
* Prove correctness

**Adapt and Learn**

* Incorporate feedback immediately
* Course-correct when challenged
* Maintain context across long sessions
* Improve through iteration

### The Dynamic That Works

**Best Sessions Feature**:

* Active user oversight with immediate feedback
* Users who catch errors early prevent larger mistakes
* Professional criticism improves output quality
* Insistence on evidence leads to better solutions
* Partnership creates better results than either alone

**Warning Signs**:

* Accepting claims without evidence
* Skipping validation "to save time"
* Not reviewing test results
* Allowing shortcuts on quality standards

## Working at Different Scales

Maestro is optimized for substantial tasks, not tiny changes:

### Small Tasks (Seconds to Minutes)

* Button color changes
* Simple config updates
* Trivial bug fixes

**Recommendation**: These are often faster to do yourself in an IDE.

### Medium Tasks (Minutes to Hours)

* Implementing single features
* Fixing specific bugs
* Adding test coverage
* Performance optimization

**Sweet Spot**: Maestro shines here--complete implementation with validation.

### Large Tasks (Hours to Days)

* Building entire subsystems
* Migrating architectures
* Implementing complex algorithms
* Full-stack feature development

**Maestro's Specialty**: Projects requiring coordination across thousands of lines.

### Very Large Tasks (Days to Weeks)

* Complete system implementations
* Major architectural refactors
* Building from research papers
* Multi-system integrations

**Advanced Use**: Multiple parallel sessions often work better than single massive sessions.

## Complex Feature Implementation Phases

For substantial features, follow this proven pattern:

### 1. Discovery & Understanding

**Goal**: Deep comprehension of existing system

**Pattern**: "Clone X and walk me through how subsystem Y works"

**Success Criteria**: Maestro demonstrates understanding of architecture, constraints, and integration points

**Time Investment**: Essential upfront work prevents later architectural mistakes

### 2. Strategic Analysis

**Goal**: Identify highest-value implementation approach

**Pattern**: "What are the 3 most valuable ways to extend this with Z?"

**Success Criteria**: Clear rationale for chosen approach, understanding of alternatives

**Risk Mitigation**: Prevents over-engineering or choosing wrong approach

### 3. Specification-Driven Development

**Goal**: Complete technical specification before implementation

**Pattern**: "Create a full spec for X, then implement it"

**Success Criteria**: Comprehensive spec covering edge cases, performance targets, testing requirements

**Quality Gate**: Implementation should follow spec, not evolve organically

### 4. Implementation with Continuous Validation

**Goal**: Working implementation with proper integration

**Success Criteria**: Code compiles, basic functionality works, no obvious regressions

**Early Warning**: Watch for compilation issues, integration problems

### 5. Professional Validation

**Goal**: Systematic testing and performance validation

**Pattern**: "Validate your work systematically"

**Success Criteria**: All tests pass, performance meets targets, no regressions

**User Vigilance Required**: This is where oversight is most critical

### 6. Comprehensive Integration

**Goal**: Complete test coverage, documentation updates, clean codebase

**Pattern**: "Run ALL tests, update docs, clean up WIP code"

**Success Criteria**: Production-ready code with full documentation

## Session Types for Different Use Cases

### Exploratory Sessions

**Purpose**: Understand existing systems, evaluate approaches

**Characteristics**:

* Clone repositories and examine architectures
* Research alternatives and trade-offs
* Prototype different solutions
* No permanent changes

**Commands**: Heavy use of `/clone`, file viewing tools

### Implementation Sessions

**Purpose**: Build and deliver working features

**Characteristics**:

* Clear specifications and success criteria
* Systematic implementation with validation
* Comprehensive testing
* Production-ready output

**Commands**: Code proposals, `/pr` for delivery

### Analysis Sessions

**Purpose**: Deep investigation and problem-solving

**Characteristics**:

* Root cause analysis
* Performance profiling
* Competitive evaluation
* Research synthesis

**Tools**: Complex Reasoning, web research, benchmark tools

### Maintenance Sessions

**Purpose**: Updates, fixes, and improvements

**Characteristics**:

* Targeted changes to existing code
* Regression prevention
* Documentation updates
* Cleanup and refactoring

**Focus**: Precision over scope

## What Makes Sessions Successful

### Clear Success Criteria

**Best Practice**: Define measurable outcomes upfront

Examples:

* "Performance should exceed baseline by 20%"
* "All existing tests must continue passing"
* "Implementation must be fully Redis-compatible"
* "Code coverage must be >90%"

### Demand Evidence, Not Claims

**Pattern**: Always ask for validation

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

**Demand**: "Show me benchmarks against the baseline using the same methodology"

**Don't Accept**: "All tests pass"

**Demand**: "Show me the test output with coverage report"

### Never Accept Shortcuts

**Quality Standards**:

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

### Use Existing Infrastructure

**Principle**: Don't reinvent testing/benchmark tools

Guidance:

* "Use the existing test suite structure"
* "Run the benchmark scripts already in the codebase"
* "Follow the established patterns"
* "Integrate with CI/CD pipeline"

## Communication Best Practices

### Be Clear and Specific

**Vague**: "Make it faster"

**Specific**: "Optimize the image processing pipeline. Current performance is 2 seconds per image. Target is \<500ms. Profile first, then implement optimizations with before/after benchmarks."

### Provide Context

**Insufficient**: "Add authentication"

**Sufficient**: "Add JWT-based authentication to our Express API. We already use bcrypt for password hashing. Follow the pattern in our user-service repository. Must integrate with existing middleware chain."

### Set Constraints Explicitly

**Missing Constraints**: "Implement caching"

**Clear Constraints**: "Implement Redis caching. Must: use existing Redis connection pool, maintain sub-10ms cache hit latency, handle cache failures gracefully, provide cache metrics for monitoring."

### Define Done Criteria

**Incomplete**: "Build a dashboard"

**Complete**: "Build a dashboard showing system metrics. Requirements: React frontend, real-time WebSocket updates, responsive design, unit tests for components, integration tests for WebSocket connection. Done when: all tests pass, loads in \<2s, handles 100 concurrent users."

## Adaptive Working Styles

Maestro adjusts to your preferences:

### High-Oversight Style

* Frequent check-ins during implementation
* Incremental validation at each step
* Detailed explanations of decisions
* More opportunities to course-correct

**When to use**: Learning Maestro, critical systems, unfamiliar domains

### Autonomous Style

* Establish comprehensive specifications upfront
* Let Maestro execute fully before validation
* Review complete implementation with all tests
* Efficient for experienced users

**When to use**: Well-understood problems, established patterns, trust built through experience

### Hybrid Style

* Detailed planning phase with feedback
* Autonomous implementation
* Thorough validation and iteration
* Most common for complex features

**When to use**: Most real-world projects

## Common Misconceptions

### "Maestro is just fancy autocomplete"

**Reality**: Maestro plans, implements, validates, and iterates. It handles complete features, not suggestions.

### "I need to know exactly what I want before starting"

**Reality**: Maestro can help you explore options, understand trade-offs, and refine requirements.

### "Maestro will do everything perfectly on first try"

**Reality**: Iteration is normal. Challenge, provide feedback, and refine. The partnership creates better results.

### "More detail in my request is always better"

**Reality**: Clear goals and constraints matter. Implementation details can often be left to Maestro.

### "I should accept what Maestro produces to save time"

**Reality**: Validation and pushing back on quality improves outcomes. Never compromise standards for speed.

## Next Steps

Now that you understand sessions and the partnership model:

* **[Working with Maestro](getting-started/working-with-maestro)**: Advanced collaboration patterns
* **[Commands Reference](getting-started/commands)**: Master session control
* **[Tools Overview](getting-started/tools)**: Understand Maestro's capabilities
* **[Sandbox Guide](getting-started/sandbox)**: Deep dive into execution environment

Ready to start? Begin a session and try the examples from this guide.