---
name: step-01-transform
description: Build handoff data per module - 8 categories from flat BA files
next_step: steps/step-02-export.md
---

# Step 01: Transform (Handoff Data Generation)

## MANDATORY EXECUTION RULES

- **ALWAYS** process modules in topological order (dependencies first)
- **ALWAYS** delegate each module to an **isolated Agent** (context isolation — CRITICAL for large projects)
- **ALWAYS** load data from **flat files** (entities.json, usecases.json, rules.json, screens.json, permissions.json)
- **ALWAYS** map to 8 categories (including "documentation")
- **ALWAYS** propagate personRoleConfig verbatim from entities
- **ALWAYS** separate seedData into core/business categories
- **ALWAYS** map entity to domain file path (1:1)
- **ALWAYS** include dependencies[] per file entry
- **NEVER** invent entities/BRs not in module JSON files
- **NEVER** load all module data in the main conversation (causes context overflow on 5+ modules)
- **ALWAYS** generate API endpoints from use cases + entities (BA does not produce apiEndpoints)
- **ALWAYS** canonicalize entity names before generating file paths — see `references/entity-canonicalization.md`

## FICHIERS A CREER — LISTE FERMEE (ba-009 fix)

> **Load** `references/handoff-file-inventory.md` for exhaustive file list, naming regex, and forbidden variants.

---

## YOUR TASK

Orchestrate the transform: determine module order, then delegate each module's transform to an Agent with isolated context. This prevents context accumulation across modules.

---

## CONTEXT ISOLATION ARCHITECTURE

> **Load** `references/context-isolation-pattern.md` for the orchestration pattern, agent delegation flow, and context budget rules.

---

## EXECUTION SEQUENCE

### 1. Determine Module Processing Order

From step-00 data, extract the topological order of modules. Display:

```
Module processing order:
  1. {module1} (0 dependencies)
  2. {module2} (depends on: module1)
  ...
```

### 2. Process Each Module via Agent

For **EACH module** in topological order, use the **Agent tool** (subagent_type: `ba-writer`) with:

> → **Load** `references/agent-handoff-transform-prompt.md` as the complete agent prompt for each module transformation.

### 3. Display Progress

After each Agent completes, display:

```
handoff {i+1}/{N}: {moduleCode} ({fileCount} files) ✓
```

### 4. Display Summary

```
================================================================
  TRANSFORM COMPLETE
================================================================
Modules processed: {N}/{N}
Total files mapped: {totalFiles}
Global complexity: {highest_complexity}
================================================================
```

---

## NEXT STEP

Load: `steps/step-02-export.md`
