---
name: step-03-execute
description: Orchestrate code creation via existing skills and MCP tools
model: opus
prev_step: steps/step-02-plan.md
next_step: steps/step-04-validate.md
---

# Step 3: Execute

**CRITICAL PRINCIPLE: /apex ORCHESTRATES. It NEVER writes SmartStack code directly.**
All code goes through skills (/controller, /application, /ui-components, /efcore) or MCP tools.

## LOAD CONDITIONALLY

- Read `references/smartstack-layers.md` for execution rules per layer
- If NOT `{economy_mode}` AND Layer 1 has parallel work: read `references/agent-teams-protocol.md`

---

## Layer 0 — Domain + Infrastructure (sequential, agent principal)

### Domain Entities

```
For each entity to create/modify:
  → MCP scaffold_extension (type: "entity", target: entity_name)
  → Verify: inherits AuditableEntity, has IHasData if multi-tenant
```

### EF Core Configurations

```
For each entity:
  → MCP scaffold_extension (type: "configuration", target: entity_name)
  → Verify: table name, relationships, indexes
  → Register DbSet in ExtensionsDbContext if new entity
```

### Migration (BLOCKING)

```
1. MCP suggest_migration → get standardized name
2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
3. dotnet ef database update (if local DB)
4. dotnet build --no-restore → MUST PASS
```

**BLOCKING:** If build fails after migration, fix EF configs before proceeding.

### Post-Layer 0 Build Gate

```bash
dotnet build --no-restore
```

**MUST PASS before Layer 1. If failure, fix and retry.**

---

## Layer 1 — Application + API + Seed Data

### If economy_mode: Sequential execution

Execute each item from the plan sequentially using skills and MCP.

### If NOT economy_mode: Agent Teams (parallel)

> **Protocol:** See `references/agent-teams-protocol.md`

```
TeamCreate("apex-exec", description: "Execute Layer 1 in parallel")

Spawn 2 teammates (Opus, full tools):

1. exec-backend (team_name: "apex-exec", name: "exec-backend"):
   "Execute these Layer 1 backend tasks for module {module_code}:
    {list of application + api + seed data tasks from plan}

    For each task:
    - Application services/DTOs: MCP scaffold_extension
    - Controllers: use /controller skill for complex, MCP scaffold_extension for simple
    - Seed data: MCP generate_permissions, then follow smartstack-layers.md templates

    After ALL tasks done:
    SendMessage(type:'message', recipient:'team-lead', content:'BACKEND_COMPLETE', summary:'Backend layer done')"

2. exec-frontend (team_name: "apex-exec", name: "exec-frontend"):
   "Execute these Layer 1 frontend tasks for module {module_code}:
    {list of frontend + i18n tasks from plan}

    For each task:
    - API client: MCP scaffold_api_client
    - Routes: MCP scaffold_routes
    - Pages: use /ui-components skill
    - I18n: 4 languages (fr, en, it, de)
    - MUST use src/pages/{Context}/{App}/{Module}/ hierarchy (NOT flat)

    After ALL tasks done:
    SendMessage(type:'message', recipient:'team-lead', content:'FRONTEND_COMPLETE', summary:'Frontend layer done')"

Wait for both teammates to report completion.

Build verification:
  dotnet build --no-restore  (backend)
  npm run typecheck           (frontend, if applicable)

shutdown_request → shutdown_response → TeamDelete("apex-exec")
```

---

## Layer 1 — Skill Delegation

| Skill | When | Context to provide |
|-------|------|--------------------|
| /controller | Custom routes, complex auth, file upload | entity, CRUD actions, permissions, routes |
| /application | Full context/app/module from scratch | context, app, module names |
| /ui-components | Complex pages (tables, grids, dashboards) | entity, fields, page type |
| /efcore | Complex EF configs, inheritance | relationships, indexes |
| /notification | In-app or email notifications | trigger, recipients, template |
| /workflow | Automated workflows | trigger, steps, conditions |

---

## Layer 2 — Final Seed Data + Validation (sequential)

After Layer 1 completes:

```
1. Verify seed data completeness:
   - NavigationModuleSeedData.cs with 4 languages
   - PermissionsSeedData.cs with deterministic GUIDs
   - RolesSeedData.cs with context-based role mapping
   - IClientSeedDataProvider updated
   - DI registration added

2. Build gate:
   dotnet build --no-restore → MUST PASS
   npm run typecheck → MUST PASS (if frontend)
```

---

## Commits Per Layer

After each layer completes and builds pass:

```
Layer 0: feat({module}): [domain+infra] {short description}
Layer 1: feat({module}): [app+api] {short description}
Layer 1: feat({module}): [frontend] {short description}  # if applicable
Layer 2: feat({module}): [seed] {short description}       # if applicable
```

---

## Save Output (if save_mode)

Write to `{output_dir}/03-execute.md` with execution log per layer.

---

## NEXT STEP

Load `steps/step-04-validate.md`
