Skip to content

nicolasfmelo/masa-skill

masa-framework

Verified

Apply the MASA (Modular Agentic Semantic Architecture) framework when writing, reviewing, or refactoring code. Use when implementing features, reviewing architecture, checking layer compliance, or setting up a new project in Python, JavaScript/TypeScript, or Go.

references/task-execution-protocol.md

View on GitHub
# MASA Task Execution Protocol

## Overview

Every feature implementation in a MASA codebase follows a strict **five-step protocol**
in bottom-up layer order. The protocol is not optional — skipping steps or reversing
order introduces layer violations.

The key insight: layers with fewer dependencies are implemented first. This makes each
step independently testable and eliminates the circular reading loops agents encounter
in conventional codebases.

---

## The Five Steps

```
Step 1: domain_models/   ← no dependencies (start here always)
Step 2: engines/         ← depends on domain_models only
Step 3: integrations/    ← depends on domain_models only
Step 4: services/        ← depends on domain_models + engines + integrations
Step 5: delivery/        ← depends on domain_models + services
```

---

## Step-by-Step Protocol

### Step 1 — Domain Review (`domain_models/`)

**Goal:** Establish the business vocabulary for the feature before writing any logic.

Actions:
1. Identify the domain concepts involved (entities, value objects, IDs, events)
2. Create or update data structures in `domain_models/`
3. Define any new Domain Exceptions in `domain_models/exceptions`
4. Define typed IDs if new entities are introduced

**Checklist before moving to Step 2:**
- [ ] All domain concepts have typed representations
- [ ] No imports from other layers
- [ ] No ORM annotations or infrastructure concerns
- [ ] Domain exceptions defined for all expected error cases

---

### Step 2 — Engine Draft (`engines/`)

**Goal:** Implement pure business logic as stateless functions.

Actions:
1. Identify the calculation, transformation, or business rule at the core of the feature
2. Write pure functions that take domain models and return domain models
3. Write unit tests — engines require no mocks (no I/O)

**Checklist before moving to Step 3:**
- [ ] All functions are pure (no I/O, no state)
- [ ] All inputs/outputs are domain models
- [ ] Imports from `domain_models/` only
- [ ] Unit tested without any infrastructure setup

**Decision node — does this feature have no pure logic?**
If the feature is purely orchestration (fetch + transform + save), Step 2 produces
an empty file or no file. Proceed to Step 3. Do not invent artificial engine logic.

---

### Step 3 — Integration Preparation (`integrations/`)

**Goal:** Build the infrastructure adapters the service will need.

Actions:
1. If new data needs persistence: create/update `integrations/database/models/` and
   `integrations/database/repos/`
2. If external APIs are involved: create/update `integrations/external_apis/`
3. Implement all infrastructure exception → domain exception translations here

**Checklist before moving to Step 4:**
- [ ] Repository/client returns domain models, not ORM/SDK types
- [ ] All infrastructure exceptions caught and re-raised as domain exceptions
- [ ] DB auto-increments stay internal; domain UUIDs exposed upward
- [ ] Integration tests or mocks can verify these in isolation

---

### Step 4 — Orchestration (`services/`)

**Goal:** Compose the business flow using engines and integrations.

Actions:
1. Create or update the service class
2. Declare all dependencies (repos, clients, other services) as constructor parameters
3. Implement the use-case method: call repos → dress data → call engines → save results
4. Handle domain exceptions where appropriate

**Checklist before moving to Step 5:**
- [ ] All dependencies are constructor parameters (no globals, no DI magic)
- [ ] All data entering engine calls is a domain model (no raw types)
- [ ] No direct DB calls — all via repository interfaces
- [ ] No HTTP-specific types in method signatures

**Service method skeleton:**
```python
def execute_feature(self, domain_input: DomainInput) -> DomainOutput:
    # 1. Fetch what we need
    existing = self._repo.find_by_id(domain_input.id)
    # 2. Apply business logic (engine)
    result = calculate_something(existing, domain_input)
    # 3. Persist result
    saved = self._repo.save(result)
    # 4. Side effects (notifications, events)
    self._email_client.send_confirmation(saved)
    return saved
```

---

### Step 5 — Exposure (`delivery/`)

**Goal:** Expose the feature via the transport protocol (HTTP, CLI, events).

Actions:
1. Create a request/response schema in `delivery/schemas/` with `.to_domain()` / `.from_domain()`
2. Add a thin route handler in `delivery/http/` that validates + dispatches
3. Wire the service in the dependency setup (main.py, bootstrap, wire.go)

**Checklist:**
- [ ] Handler has exactly 2 operations: validate schema + call service
- [ ] No business logic or conditional branches in handler
- [ ] Request schema maps to domain model in `to_domain()`
- [ ] Response schema maps from domain model in `from_domain()`
- [ ] Handler does not import from `engines/` or `integrations/` directly

---

## Boundary Violation Detection

During any step, if you find yourself wanting to:

| Urge | This means | Correct action |
|---|---|---|
| Import a DB model into `services/` | Missing repo translation | Add mapping in `repos/`, expose domain model |
| Call a DB query directly in `services/` | Repo not yet created | Create repo in Step 3, inject in service |
| Add business logic in a handler | Missing service method | Extract to service in Step 4 |
| Import from `engines/` in `delivery/` | Handler bypassing service | Route through `services/` |
| Use a raw `dict` in an engine | Missing domain model | Add to `domain_models/` in Step 1 |
| Pass an `int` DB ID to a service | ID not encapsulated | Introduce typed domain ID in Step 1 |

**Always fix at the correct layer. Never adjust the import to work around the violation.**

---

## Feature Implementation Walkthrough Example

**Feature:** "Create a new order from an HTTP POST request"

```
Step 1 — domain_models/
  + order.py          → Order dataclass with OrderId, items_total, shipping_cost
  + ids.py            → OrderId(UUID) typed value object
  + exceptions.py     → DuplicateOrderError, StorageUnavailableError

Step 2 — engines/
  + order_calculator.py → calculate_total(order: Order) -> float (pure function)

Step 3 — integrations/
  + database/models/order_model.py → SQLAlchemy OrderModel (pk + uuid + fields)
  + database/repos/order_repo.py   → OrderRepository.save(Order) -> Order
                                      (catches psycopg2 → re-raises StorageUnavailableError)

Step 4 — services/
  + order_service.py → OrderService(repo: OrderRepository)
                        .create(order: Order) -> Order
                        (dresses input, calls calculator, saves via repo)

Step 5 — delivery/
  + schemas/create_order_request.py → CreateOrderRequest + .to_domain()
  + schemas/create_order_response.py → CreateOrderResponse + .from_domain()
  + http/order_handler.py           → POST /orders → validate → service.create()
```

Total files for a complete feature: ~7–9 files, each with a single clear responsibility.
An agent can regenerate any one of them from its file path alone.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 471kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall