Context
Roomy needs automated app store screenshot generation across 5 device configurations. The current monolithic Maestro flows cannot be invoked per-screen by agents. This change introduces a modular flow architecture enabling agents to:
- Launch any screen with specific data via parameters
- Capture screenshots at required resolutions
- Run full orchestration suites per device
Stakeholders
- Developers (flow maintenance)
- CI/CD pipelines (automated screenshot generation)
- AI agents (programmatic screen access via mobile-mcp)
Constraints
- Must work with existing seed data (4 users, 10 tasks, 5 lists, 8 payments)
- Must support
--dart-define=screenshots=true auto-login mode
- Must use semantic identifiers for cross-device reliability
Goals / Non-Goals
Goals
- Enable per-screen invocation with parameterized data
- Support all 5 mandatory device configurations
- Maintain backwards compatibility with existing flows
- Provide agent-facing documentation
Non-Goals
- Localization support (defer to future change)
- Video recording automation
- Performance benchmarking
Decisions
Decision: Per-Screen Flow Architecture
Each screen gets its own YAML flow file accepting environment parameters via -e flags.
Rationale:
- One flow per screen enables parallel execution and independent maintenance
- Parameters allow data variation without flow duplication
- Tags enable filtering for CI/CD (
--includeTags screenshot)
Alternatives considered:
- Single flow with conditional branching - Rejected: Complex, hard to maintain, cannot parallelize
- Deep linking only - Rejected: Not all screens support deep links, inconsistent navigation
Decision: Directory Structure
.maestro/
├── config.yaml
├── screens/{feature}/{screen}.yaml
├── utils/{helper}.yaml
└── orchestration/{device}.yaml
Rationale:
- Feature-based organization mirrors app structure
- Separates concerns: individual screens vs. helpers vs. full suites
- Enables glob patterns for feature-specific runs
Decision: mobile-mcp for Agent Integration
Use @mobilenext/mobile-mcp MCP server for agent-driven screenshot capture.
Rationale:
- Cross-platform (iOS + Android)
- Uses accessibility trees for reliable element identification
- Direct integration with Claude Code and other MCP clients
- Provides
mobile_take_screenshot tool for programmatic capture
Alternatives considered:
- ios-simulator-mcp - Rejected: iOS-only, less comprehensive
- Maestro CLI only - Rejected: No MCP integration for agent control
Decision: Parameter Naming Convention
Parameters use SCREAMING_SNAKE_CASE with defaults:
env:
TASK_ID: ${TASK_ID:-task-kitchen}
SCREENSHOT_PATH: ${SCREENSHOT_PATH:-screenshots}
Rationale:
- Consistent with Maestro conventions
- Defaults ensure flows work standalone for manual testing
- Clear distinction from flow internals
Risks / Trade-offs
Risk: Semantic Identifier Maintenance
Adding identifiers requires Flutter code changes that must stay synchronized with flows.
Mitigation:
- Document all identifiers in a central reference
- Add validation step to CI that checks identifier existence
- Use consistent naming pattern:
{feature}_{element} or {feature}_{item}_{id}
Risk: Device Configuration Drift
App store requirements may change (e.g., new iPhone sizes).
Mitigation:
- Centralize device specs in
config.yaml comments
- Document device matrix in agent instructions
- Review requirements before each app store submission
Risk: Flow Brittleness
UI changes may break flows silently.
Mitigation:
- Use semantic identifiers over coordinates where possible
- Add
extendedWaitUntil with timeouts for reliability
- CI runs flows on each release branch
Migration Plan
Phase 1: Infrastructure
- Create directory structure
- Update
config.yaml with tags
- Install mobile-mcp
Phase 2: Flows
- Create utility flows (login, navigation)
- Create 21 per-screen flows
- Add missing semantic identifiers to views
Phase 3: Orchestration
- Create device-specific orchestration flows
- Add agent documentation
- Validate full matrix capture
Rollback
- Original flows preserved at
.maestro/legacy/
- Can revert by restoring original structure
- No code changes required for rollback
Open Questions
None - all requirements clarified during planning.
Reacties