---
name: step-02-plan
description: Create layer-by-layer execution plan with skill/MCP mapping per file
model: opus
prev_step: steps/step-01-analyze.md
next_step: steps/step-03-execute.md
---

# Step 2: Plan

**Goal:** Create a precise, file-by-file plan. Each file mapped to a SKILL or MCP tool.

## LOAD CONDITIONALLY

Read `references/smartstack-layers.md` for layer execution rules and skill/MCP mapping.

---

## 0. Delegate Mode Fast Path (if delegate_mode)

> **When called via `/ralph-loop -d`, PRD tasks already define the scope. Map directly to layers.**

```
IF delegate_mode:
  Read PRD from {delegate_prd_path}

  Map each PRD task to a layer based on task.category:
    domain          → Layer 0
    infrastructure  → Layer 0
    application     → Layer 1
    api             → Layer 1
    seedData        → Layer 1
    frontend        → Layer 2
    test            → Layer 3

  For each task:
    file_path    = task.files_changed.created[0] (primary file)
    action       = "create" (default for delegate mode)
    tool         = infer from category:
                   domain/infrastructure → MCP scaffold_extension
                   api → /controller skill or MCP scaffold_extension
                   seedData → MCP generate_permissions + ref core-seed-data.md
                   frontend → /ui-components skill + MCP scaffold_api_client + MCP scaffold_routes
                   test → MCP scaffold_tests
    acceptance_criteria = task.acceptance_criteria

  Use task._seedDataMeta, _frontendMeta, _migrationMeta for enriched context.

  SKIP: User checkpoint (section 6) — auto_mode implied
  Jump to section 5 (Estimated Commits) → NEXT STEP
```

---

## 1. Map Changes to Layers

For each element identified in step-01 (create or modify), assign to a SmartStack layer:

| Layer | Category | Order |
|-------|----------|-------|
| 0 | Domain (entities, enums, exceptions) | Sequential |
| 0 | Infrastructure - EF Configs | Sequential |
| 0 | Infrastructure - Migration (BLOCKING) | Sequential |
| 1 | Application (services, DTOs, validators) | Parallel |
| 1 | API (controllers) | Parallel |
| 1 | Infrastructure - Seed Data | Parallel |
| 2 | Frontend (pages, components) | Parallel |
| 2 | I18n (translations) | Parallel |
| 3 | Tests | Sequential |

**Entity Definition Template:** Each entity in the plan MUST include:
```
Entity: {EntityName}
  - tenantMode: strict | optional | scoped | none
  - codePattern: auto-generated strategy (if applicable)
  - fkFields: [{field, targetEntity}] (if applicable)
  - acceptance criteria: [AC1, AC2, ...]
```

The `tenantMode` decision (from step-01, section 4a) drives EF query filters, seed data approach, and API authorization. See `smartstack-layers.md` for tenant mode seed data strategies.

---

## 2. Assign Skill/MCP per File

For EACH file in the plan, specify HOW it will be created/modified:

```markdown
### Layer 0 — Domain + Infrastructure (sequential)

| # | File | Action | Tool |
|---|------|--------|------|
| 1 | Domain/Entities/.../MyEntity.cs | create | MCP scaffold_extension |
| 2 | Infrastructure/.../MyEntityConfiguration.cs | create | MCP scaffold_extension |
| 3 | Migration | create | MCP suggest_migration + dotnet ef |

### Layer 1 — Application + API (parallel)

| # | File | Action | Tool |
|---|------|--------|------|
| 4 | Application/Services/.../MyService.cs | create | MCP scaffold_extension |
| 5 | Application/DTOs/.../MyDto.cs | create | MCP scaffold_extension |
| 6 | Api/Controllers/.../MyController.cs | create | /controller skill |
| 7 | Seeding/Data/NavigationApplicationSeedData.cs | create | ref smartstack-layers.md (once per app) |
| 7b | Seeding/Data/ApplicationRolesSeedData.cs | create | ref smartstack-layers.md (once per app) |
| 7c | Infrastructure/Services/CodeGeneration/ | create | ref code-generation.md (ICodeGenerator<T> + DI, per entity with codePattern != manual) |
| 8 | Seeding/Data/.../NavigationModuleSeedData.cs | create | ref smartstack-layers.md |
| 8b | Application/Authorization/Permissions.cs | create | MCP generate_permissions → static constants |
| 9 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
| 10 | Seeding/Data/.../RolesSeedData.cs | create | ref smartstack-layers.md |

### Layer 2 — Frontend + I18n (parallel)

| # | File | Action | Tool |
|---|------|--------|------|
| 11 | src/pages/{Ctx}/{App}/{Mod}/ListPage.tsx | create | /ui-components skill |
| 11b | src/pages/{Ctx}/{App}/{Mod}/CreatePage.tsx | create | /ui-components skill (EntityLookup for FK fields) |
| 11c | src/pages/{Ctx}/{App}/{Mod}/EditPage.tsx | create | /ui-components skill (EntityLookup for FK fields) |
| 11d | src/pages/{Ctx}/{App}/{Mod}/{Section}Page.tsx | create | /ui-components skill (per section in `{sections}`) |
| 11e | src/pages/{Ctx}/{App}/{Mod}/{Section}DetailPage.tsx | create | /ui-components skill (per section in `{sections}`) |
| 12 | src/services/api/{module}Api.ts | create | MCP scaffold_api_client |
| 13 | src/routes/{module}.tsx | create | MCP scaffold_routes |
| 14 | src/i18n/locales/{lang}/{module}.json | create | ref smartstack-frontend.md (4 languages: fr, en, it, de) |

**FK Field Guidance:** If step-01 identified `fkFields[]`, every Create/Edit page MUST use `EntityLookup` for those fields (see `smartstack-frontend.md` section 6). The corresponding backend GetAll endpoints (Layer 1) MUST support `?search=` parameter.

### Layer 2b — Documentation (after frontend pages exist)

| # | File | Action | Tool |
|---|------|--------|------|
| 14b | src/pages/docs/business/{app}/{module}/doc-data.ts | create | /documentation skill |
| 14c | src/pages/docs/business/{app}/{module}/index.tsx | create | /documentation skill |

### Layer 3 — Tests (sequential)

| # | File | Action | Tool |
|---|------|--------|------|
| 15 | tests/.../MyEntityTests.cs | create | MCP scaffold_tests |
| 16 | tests/.../MyServiceTests.cs | create | MCP scaffold_tests |
```

---

## 3. Identify Parallelization (Agent Teams)

If NOT economy_mode AND Layer 1 has both backend and frontend work:

```
Layer 0: SEQUENTIAL (agent principal)
  → domain + infra + migration
  → dotnet build --no-restore (BLOCKING)

Layer 1: PARALLEL (Agent Teams)
  → exec-backend: application + api + seed data
  → exec-frontend: frontend + i18n

Layer 2: SEQUENTIAL (agent principal)
  → final validation + tests
```

If economy_mode: ALL layers sequential, agent principal only.

---

## 4. Dependency Validation

Verify the plan respects dependencies:

```
- Migration AFTER EF configs (always)
- Application services AFTER domain entities (always)
- Code generator service AFTER entity + EF config (needs DbSet for sequence query)
- CreateDto adjustments AFTER code pattern decision (remove Code property if auto-generated)
- Controllers AFTER application services (always)
- Frontend AFTER API controllers (API contract needed)
- Seed data AFTER navigation module exists
- Tests AFTER all code layers complete
- Build check between Layer 0 and Layer 1 (BLOCKING)
```

---

## 5. Estimated Commits

```
feat({module}): [domain+infra] {description}
feat({module}): [app+api] {description}
feat({module}): [frontend] {description}
feat({module}): [seed] {description}
feat({module}): [tests] {description}
```

---

## 6. User Checkpoint (if NOT auto_mode)

Present the plan and ask for validation:

```yaml
questions:
  - header: "Plan"
    question: "Does this execution plan look correct?"
    options:
      - label: "Approve and execute (Recommended)"
        description: "Proceed with the plan as described"
      - label: "Modify plan"
        description: "I want to adjust some items"
      - label: "Cancel"
        description: "Abort the workflow"
    multiSelect: false
```

If "Modify plan": ask what to change, update plan, re-present.
If "Cancel": abort workflow.

---

## 7. Save Output (if save_mode)

Write to `{output_dir}/02-plan.md` with the complete plan.

---

## NEXT STEP

Load `steps/step-03-execute.md`
