---
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, skill/MCP mapping, planning templates, and delegate mode fast path.
> **CONTEXT NOTE:** This file stays in context and is reused by step-03. Do NOT re-read it there.

---

## 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-3. Layer Mapping, Skill Assignment, Parallelization

> **Reference:** All planning procedures are now in `references/smartstack-layers.md` (already loaded above):
> - Layer assignment matrix (Domain/Infrastructure/Application/API/Seed/Frontend/Tests)
> - Entity definition template (tenantMode, codePattern, fkFields, ACs)
> - Skill/MCP assignment table (per file, per layer)
> - Layer 0/1/2b/3 file lists with tools (see "Planning Template" section)
> - FK field guidance (EntityLookup + backend ?search= parameter)
> - Parallelization strategy (Agent Teams for Layer 1 backend+frontend)
> - Delegate mode fast path (PRD task mapping to layers)

```
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`
