Best practices

Unit tests:
- All public functions/methods tested
- Edge cases covered
- Error scenarios handled
- Mock external dependencies

Integration tests:
- Component interactions verified
- End-to-end flows tested
- External service integration validated

Performance tests:
- Benchmarks for critical paths
- Load testing where relevant
- Regression prevention

Maestro: "I've implemented the feature. It should work."
You: "Great, let's move on"

Maestro: "I've implemented the feature"
You: "Run the full test suite and show me the results"
Maestro: [Runs tests, shows output]
You: [Reviews output] "All tests pass. Show me code coverage"
Maestro: [Shows coverage report]
You: "Coverage is 92%. Run performance benchmarks"
Maestro: [Runs benchmarks, shows results]
You: "Performance meets targets. Now it's complete."

"Run the authentication tests only"

"Run the FULL test suite. Show complete output including:
- Number of tests run
- Pass/fail breakdown
- Code coverage percentage
- Execution time
- Any warnings or deprecation notices"

Every 20-30 turns:
- Check capacity indicator
- Consider /refresh if many file iterations
- Use /compact if capacity >70%

Before major validation:
- /refresh to clean file context
- Ensure Maestro sees current state only

After major milestone:
- /synopsis to document learnings
- Consider /compact to free capacity
- /download-changed for backup

Capacity warning appears:
- /refresh immediately
- /compact if still high
- /forget if necessary

Last resort:
- /download-all
- Create new session
- Upload critical files
- Resume with clean capacity

Use /refresh regularly to avoid:
- Hundreds of iterations consuming capacity
- Maestro viewing obsolete code
- Confusion about "current" state

Exception: Keep iterations when:
- Comparing approaches
- Documenting evolution
- May need to restore earlier version

Don't activate all files at once

Start with:
- View high-level structure (README, config)
- View specific files needed for current task

Expand as needed:
- View related files when referenced
- Activate dependencies when modifying code

After major milestone:
/synopsis → Document state
/compact → Compress implementation details
Keep: Synopsis + current validated state

1. Read PR description thoroughly
2. Review all changed files
3. Check test additions/changes
4. Run tests yourself (verify claims)
5. Check for:
   - Security issues
   - Performance concerns
   - Maintainability problems
   - Missing edge cases

6. Request changes if needed
7. Approve only when satisfied

"Clone PR #123 and review for:
- Code quality
- Test coverage
- Performance implications
- Security vulnerabilities
- Best practice adherence

Provide detailed feedback on issues found."

Clear assignment:
- Developer A: Authentication (Session 1)
- Developer B: Payment processing (Session 2)
- Developer C: Notifications (Session 3)

Integration session:
- Clone all three PRs
- Verify compatibility
- Integration testing

When handing off work:
1. /synopsis to document state
2. Clear commit message on last change
3. Brief handoff document
4. /download-changed for backup

Recipient:
1. Clone repository at handoff point
2. Read synopsis
3. Verify understanding
4. Continue or ask clarifying questions

For all user inputs:
- Type validation
- Range/length limits
- Sanitization
- SQL injection prevention
- XSS prevention

Explicitly request:
"Implement strict input validation for all endpoints. Include tests that attempt injection attacks and verify they're blocked."

"Review all dependencies for:
- Known vulnerabilities
- Maintenance status
- License compatibility
- Size and complexity"

Tools: Use npm audit, pip-audit, etc.

"Update dependencies to latest stable versions.

Process:
1. Update dependency files
2. Run full test suite
3. Verify no breaking changes
4. Document any required code changes"

Validation before every PR:
"Scan all files for potential secrets:
- API keys
- Passwords
- Connection strings
- Private keys

Report any found. Ensure .gitignore covers them."

Require:
- All secrets via environment variables
- No hardcoded credentials
- Configuration separate from code
- Document required env vars in README

1. Profile first (never guess)
2. Identify actual bottleneck
3. Estimate optimization impact
4. Implement change
5. Benchmark with same conditions
6. Verify improvement
7. Check for regressions

Document: Baseline → Change → Result

Fix in order:
1. Algorithmic inefficiency (O(n²) → O(n log n))
2. I/O bottlenecks (database, network)
3. CPU-bound hotspots
4. Memory usage
5. Micro-optimizations (last resort)

Process:
1. Enable query logging
2. Identify slow queries (>100ms)
3. Analyze execution plans
4. Add indexes where beneficial
5. Optimize query structure
6. Benchmark before/after

Always use connection pools:
- PostgreSQL: pgbouncer or app-level pooling
- MySQL: connection pooling enabled
- MongoDB: connection pool configured

Test pool behavior under load

Implement:
1. Application-level (in-memory)
2. Distributed (Redis/Memcached)
3. CDN (for static assets)
4. Database query cache

Validate cache effectiveness:
- Measure hit rates
- Verify invalidation works
- Test stale data scenarios

Document:
- Why, not what (code shows what)
- Non-obvious logic
- Performance trade-offs
- Security considerations
- Future improvement notes

For all public APIs:
- Purpose and use cases
- Parameters with types and constraints
- Return values with types
- Exceptions that may be thrown
- Usage examples
- Performance characteristics

Must include:
- Project purpose
- Installation instructions
- Configuration guide
- Usage examples
- Development setup
- Testing instructions
- Deployment guide
- License information

Create:
- Architecture diagrams (use Mermaid tool)
- Component interaction diagrams
- Data flow diagrams
- Deployment architecture

Update:
- When architecture changes
- When components added/removed
- When interactions change

For all operations that can fail:
- Catch specific exceptions
- Log errors appropriately
- Provide useful error messages
- Graceful degradation
- Retry with exponential backoff (where appropriate)

Test error scenarios:
- Network failures
- Database unavailability
- Invalid inputs
- Resource exhaustion
- Timeout conditions

If caching layer fails:
- System continues without cache
- Performance degrades but functionality intact
- Errors logged for monitoring
- Recovery automatic when cache available

For external services:
- Detect sustained failures
- Stop calling failing service temporarily
- Return cached data or default responses
- Retry after cooldown period
- Resume when service healthy

Add to all production code:
- Structured logging (JSON format)
- Metrics emission (request rates, latencies, errors)
- Distributed tracing (for microservices)
- Health check endpoints

Make observable:
- Request/response cycles
- Database query performance
- External API calls
- Error rates and types
- Resource utilization

Before deploying to production:
☑ All tests pass (100%)
☑ Code coverage meets standards
☑ Performance benchmarks acceptable
☑ Security scan passed
☑ Documentation complete
☑ Rollback plan documented
☑ Monitoring configured
☑ Secrets in environment (not code)
☑ Configuration for each environment
☑ Database migrations tested
☑ Dependency versions locked
☑ Health check endpoint implemented

Never deploy directly to production

Workflow:
1. Deploy to staging environment
2. Run smoke tests
3. Perform manual validation
4. Monitor for errors (24 hours)
5. If stable, deploy to production
6. Monitor closely post-deployment

Before deployment:
- Document rollback procedure
- Test rollback in staging
- Have rollback trigger criteria
- Know rollback time estimate

If issues detected:
- Rollback immediately
- Investigate in non-production
- Fix and redeploy

Bad: Implement feature → Create tests as afterthought
Good: Design tests → Implement to satisfy tests

Bad: Test fails → Change code to make test pass (without understanding)
Good: Test fails → Understand why → Fix implementation OR fix test (whichever is wrong)

Bad: Feature done → Skip tests → Create PR → Hope for best
Good: Feature done → Full validation → Proven working → Create PR

Bad: Maestro says "Performance improved" → Accept
Good: Maestro says "Performance improved" → Demand benchmarks

Bad: Use Maestro for changing button color
Good: Use IDE for trivial changes, Maestro for substantial features

Bad: Single session doing everything for 200 turns
Good: Focused sessions with clear boundaries

Bad: Let capacity hit 100%, then struggle
Good: Proactive management at 70%

Bad: Long session with no backups
Good: Regular checkpoints and /synopsis

Bad: "Make it better"
Good: "Improve performance. Target: <100ms latency. Current: 500ms. Benchmark with same test harness."

Bad: "Use the database credentials" (mentioned 50 turns ago)
Good: "Use DATABASE_URL=postgresql://..." (explicit)

Bad: Let Maestro continue with wrong assumption
Good: Immediately correct: "Stop. That's wrong. Here's the correct understanding: ..."

Session 1: Quick prototype
- Core functionality only
- Minimal error handling
- Basic tests
- Validate concept

Result: Proven approach

Session 2: Production version
- Comprehensive implementation
- Full error handling
- Complete test coverage
- Performance optimization
- Documentation

Result: Production-ready feature

"Research [domain/technology].

Deliverables:
- Current state-of-the-art
- Best practices
- Recommended approach with evidence
- Potential pitfalls

Save research to markdown file."

Upload research from Session 1

"Create technical specification:
- Architecture
- Data models
- API contracts
- Security considerations
- Performance targets
- Testing strategy

Comprehensive but concise."

Upload specification from Session 2

"Implement the specification.

Success criteria:
- All spec requirements met
- Comprehensive tests
- Performance targets achieved
- Documentation complete

Validate systematically at each phase."

Every 5-10 turns of implementation:
1. "Pause implementation"
2. "Run all tests so far"
3. "Show test output"
4. "Verify code coverage for new code"
5. If issues: Fix before continuing
6. If good: "Continue implementation"

Prevents late-stage surprises
Catches regressions early
Maintains quality throughout

Pre-release:
☑ All tests passing (100%)
☑ Code review complete
☑ Performance validated
☑ Security scan clear
☑ Staging deployment successful
☑ Smoke tests passed
☑ Monitoring configured
☑ Runbook updated
☑ Rollback tested

Post-release:
☑ Deployment verified
☑ Smoke tests in production
☑ Monitoring alerts configured
☑ Error rates normal
☑ Performance metrics nominal
☑ Document release notes

After major sessions:
1. What went well?
2. What could improve?
3. What did we learn?
4. How could we work better together?

Document insights:
- Better requirement patterns
- Effective communication styles
- Successful validation approaches
- Pitfalls to avoid

1. Research framework and best practices
2. Design API contract (OpenAPI spec)
3. Implement endpoints with validation
4. Comprehensive test coverage (>90%)
5. Performance benchmarking
6. Documentation with examples
7. Security review
8. Create PR

1. Establish baseline metrics
2. Profile current implementation
3. Identify bottlenecks (top 3)
4. Estimate optimization impact
5. Implement optimizations incrementally
6. Benchmark after each change
7. Validate no regressions
8. Document optimizations

Save proven workflows as custom instructions
Consistency across sessions
Faster setup and execution
Higher quality through standardization

"Run mutation testing on critical authentication code.

Process:
1. Use mutation testing framework
2. Inject faults into code
3. Verify tests catch mutations
4. Improve tests for uncaught mutations
5. Achieve high mutation score

Goal: Prove tests actually validate logic, not just achieve coverage"

"Implement property-based tests for sorting algorithm.

Properties to test:
- Output length equals input length
- Output elements are subset of input
- Output is sorted (∀i: output[i] ≤ output[i+1])
- Idempotent (sorting twice gives same result)

Use hypothesis library. Run 1000 random test cases."

"Implement chaos testing:
- Random service failures
- Network latency injection
- Resource exhaustion
- Cascading failures

Verify system:
- Degrades gracefully
- Recovers automatically
- Logs errors appropriately
- Maintains data consistency"