Motia Agent Architecture Guide

Expert Aider configuration for autonomous browser-control engine projects powered by Motia framework and Google ADK Computer Use capabilities.

Overview

This skill configures Aider to work with high-performance, autonomous browser-control systems built on the Motia architecture. It provides context-aware assistance for agent orchestration, durable backend patterns, and ADK integration.

Instructions

When working on Motia projects, follow these architectural principles and context loading patterns:

1. Context Loading Strategy

**Primary Reference:**

Always load `AGENTS.md` first - this is your project overview and navigation hub

It references all detailed implementation guides in `.cursor/rules/` and `.cursor/architecture/`

**Load Additional Context As Needed:**

When working on specific features, uncomment relevant guides:

**API Development:** `.cursor/rules/motia/api-steps.mdc`

**Event Handling:** `.cursor/rules/motia/event-steps.mdc`

**Scheduled Tasks:** `.cursor/rules/motia/cron-steps.mdc`

**State Management:** `.cursor/rules/motia/state-management.mdc`

**Middleware Patterns:** `.cursor/rules/motia/middlewares.mdc`

**Real-time Streaming:** `.cursor/rules/motia/realtime-streaming.mdc`

**Virtual Steps:** `.cursor/rules/motia/virtual-steps.mdc`

**UI Integration:** `.cursor/rules/motia/ui-steps.mdc`

**System Architecture:** `.cursor/architecture/architecture.mdc`

**Error Handling:** `.cursor/architecture/error-handling.mdc`

2. Core Architectural Principles

**Agent Orchestration:**

Design agents as autonomous, durable units

Follow separation of concerns (API, events, cron, state)

Use step-based composition patterns

Implement proper error boundaries

**Backend Durability:**

Maintain persistent state across operations

Design for fault tolerance and recovery

Use appropriate retry mechanisms

Log comprehensively for debugging

**Computer Use Integration:**

Leverage Google ADK native capabilities

Follow ADK best practices for browser control

Optimize for performance and reliability

Handle visual feedback appropriately

3. Model Selection

Choose appropriate model based on task complexity:

```yaml

For complex architectural changes:

model: claude-3-5-sonnet-20241022

For standard feature development:

model: gpt-4

```

4. Development Workflow

**When Starting Work:**

1. Read `AGENTS.md` to understand project structure

2. Identify relevant subsystem (API, events, cron, etc.)

3. Load specific guide files for that subsystem

4. Review architecture patterns before implementing

5. Follow error handling conventions

**When Making Changes:**

Respect existing patterns in AGENTS.md references

Maintain consistency with guide specifications

Update tests alongside implementation

Document significant architectural decisions

**Optional - Enable Auto-commits:**

```yaml

auto-commits: true

```

5. Key File References

Always consider these project essentials:

`AGENTS.md` - Central architecture guide

`.cursor/rules/motia/*` - Implementation patterns

`.cursor/architecture/*` - System design docs

`config.yml` - Project configuration

`package.json` - Dependencies and scripts

6. Code Quality Standards

Follow TypeScript best practices

Use strong typing throughout

Implement proper error handling (see error-handling.mdc)

Write comprehensive tests

Document complex logic

Maintain clean separation of concerns

7. Browser Automation Best Practices

Use ADK Computer Use capabilities efficiently

Handle asynchronous operations properly

Implement proper timeout handling

Optimize for reliability over speed

Add visual feedback for user actions

Log browser interactions for debugging

Example Usage

Initial Setup

```yaml

.aider.conf.yml

read:

- AGENTS.md

model: claude-3-5-sonnet-20241022

```

Working on API Features

```yaml

read:

- AGENTS.md

- .cursor/rules/motia/api-steps.mdc

- .cursor/rules/motia/state-management.mdc

- .cursor/architecture/error-handling.mdc

```

Working on Event System

```yaml

read:

- AGENTS.md

- .cursor/rules/motia/event-steps.mdc

- .cursor/rules/motia/middlewares.mdc

- .cursor/architecture/architecture.mdc

```

Full Context Mode

```yaml

read:

- AGENTS.md

- .cursor/rules/motia/api-steps.mdc

- .cursor/rules/motia/event-steps.mdc

- .cursor/rules/motia/cron-steps.mdc

- .cursor/rules/motia/state-management.mdc

- .cursor/rules/motia/middlewares.mdc

- .cursor/rules/motia/realtime-streaming.mdc

- .cursor/rules/motia/virtual-steps.mdc

- .cursor/rules/motia/ui-steps.mdc

- .cursor/architecture/architecture.mdc

- .cursor/architecture/error-handling.mdc

- config.yml

- package.json

```

Important Notes

**AGENTS.md is your single source of truth** - it references all other guides

Load additional guides incrementally as needed to avoid context overflow

Follow the step-based architecture patterns consistently

Respect the durable backend design principles

Always implement proper error handling

Test autonomous agent behavior thoroughly

Document complex browser automation logic

Constraints

Must maintain backwards compatibility with existing Motia patterns

Follow ADK Computer Use API specifications strictly

Respect project-specific conventions in AGENTS.md

Use TypeScript for all new code

Maintain test coverage for critical paths

Document breaking changes clearly

Motia Agent Architecture Guide

Motia Agent Architecture Guide

Overview

Instructions

1. Context Loading Strategy

2. Core Architectural Principles

3. Model Selection

For complex architectural changes:

For standard feature development:

4. Development Workflow

5. Key File References

6. Code Quality Standards

7. Browser Automation Best Practices

Example Usage

Initial Setup

.aider.conf.yml

Working on API Features

Working on Event System

Full Context Mode

Important Notes

Constraints

Reviews (0)