@atlashub/smartstack-cli 4.18.0 → 4.19.0

package/templates/skills/apex/steps/step-03-execute.md

@@ -8,16 +8,17 @@ next_step: steps/step-04-examine.md
 
 # Step 3: Execute
 
-**CRITICAL PRINCIPLE: /apex ORCHESTRATES. It NEVER writes SmartStack code directly.**
+/apex ORCHESTRATES. It does not write SmartStack code directly.
 All code goes through skills (/controller, /application, /ui-components, /efcore) or MCP tools.
 
 ## LOAD CONDITIONALLY
 
-> **CONTEXT REUSE:** `smartstack-api.md` (loaded in step-01) and `smartstack-layers.md` (loaded in step-02) are already in context. Do NOT re-read them.
+> CONTEXT REUSE: `smartstack-api.md` (loaded in step-01) and `smartstack-layers.md` (loaded in step-02) are already in context. Do not re-read them.
 
-- **ALWAYS** read `references/smartstack-frontend.md` — lazy loading, i18n, page structure, CSS variables, EntityLookup, compliance gates (sections 1-9)
-- **ALWAYS** read `references/core-seed-data.md` — comprehensive seed data templates (Layer 1)
-- If NOT `{economy_mode}` AND a layer has multi-entity work: read `references/agent-teams-protocol.md`
+- Read `references/core-seed-data.md` — comprehensive seed data templates (needed for Layer 1, released after)
+- Defer `references/smartstack-frontend.md` until Layer 3 — lazy loading, i18n, page structure, CSS variables, EntityLookup (sections 1-6)
+- Defer `references/smartstack-frontend-compliance.md` until Layer 3 — documentation, form testing, compliance gates (sections 7-9)
+- If NOT `{economy_mode}` AND a layer has multi-entity work: read `references/parallel-execution.md`
 - If build failure during execution: read `references/error-classification.md` — error diagnosis categories A-F
 
 ---
@@ -29,7 +30,7 @@ All code goes through skills (/controller, /application, /ui-components, /efcore
 This is a foundation-only execution (called by ralph-loop Phase 0). Execute ONLY:
 - Layer 0: Domain entities + EF configs + Migration
 
-**SKIP ALL OTHER LAYERS:**
+Skip all other layers:
 - Layer 1: Seed Data → SKIP
 - Layer 2: Backend → SKIP
 - Layer 3: Frontend → SKIP
@@ -41,7 +42,33 @@ After Layer 0 completes and builds successfully:
 - End execution
 
 **IF `{foundation_mode}` == false:**
-Execute ALL layers normally (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
+Execute all layers (Layer 0 → Layer 1 → Layer 2 → Layer 3 → Layer 4).
+
+---
+
+## Context Recovery Protocol
+
+> **Run this check BEFORE each layer** to survive context compression.
+
+```
+BEFORE starting Layer N:
+  Verify these variables are still accessible:
+    {app_name}, {module_code}, {sections}, {entities}, {code_patterns}
+
+  IF any variable is missing or empty:
+    1. Read .claude/output/apex/{task_id}/state.json (if exists)
+       → Restore: completed_layers, completed_entities, files_created
+    2. IF state.json missing:
+       → Re-derive from filesystem:
+         - {app_name}: Glob("docs/business/*/") → first directory name
+         - {module_code}: Glob("src/**/Domain/Entities/*/") → target module directory
+         - {entities}: Glob("src/**/Domain/Entities/{module_code}/*.cs") → entity names
+         - {sections}: Glob("src/**/Seeding/Data/{module_code}/*NavigationSeedData.cs") → parse GetSectionEntries
+    3. IF Layer N-1 was already completed (check state.json or git log):
+       → Skip to Layer N directly
+
+  Cost: ~5 tool calls. Only triggered if context was compressed.
+```
 
 ---
 
@@ -64,46 +91,42 @@ For each entity to create/modify:
 
 ### Person Extension Detection
 
+**If entity has personRoleConfig (mandatory or optional UserId link):**
+See `references/person-extension-pattern.md` for full entity, EF config, service, DTO, and frontend patterns.
+
 ```
-IF entity has personRoleConfig (from PRD or feature.json):
-  → LOAD references/person-extension-pattern.md
-  → Apply variant: mandatory or optional (from personRoleConfig.userLinkMode)
-  → scaffold_extension with options: { isPersonRole: true, userLinkMode: '{variant}' }
-  → VERIFY: UserId FK present, no duplicate person fields (mandatory)
-  → VERIFY: EF config has unique index on (TenantId, UserId)
-  → VERIFY (mandatory): entity has ZERO person fields (FirstName, LastName, Email, PhoneNumber)
-  → VERIFY (optional): entity has own person fields + computed Display* properties
+1. scaffold_extension with options: { isPersonRole: true, userLinkMode: 'mandatory' | 'optional' }
+2. Verify: EF config has unique index on (TenantId, UserId)
+   → Mandatory variant: plain .IsUnique()
+   → Optional variant: .IsUnique().HasFilter("[UserId] IS NOT NULL")
+3. Verify all build checks pass before continuing
 ```
 
 ### EF Core Configurations
 
 ```
 For each entity:
-  → MCP scaffold_extension (type: "configuration", target: entity_name)
+  → Create IEntityTypeConfiguration<T> manually per smartstack-api.md patterns
   → Verify: table name, relationships, indexes
   → Register DbSet in ExtensionsDbContext if new entity
 ```
 
-### Migration (BLOCKING)
+### Migration
 
-> **CRITICAL — Migration must cover ALL entities, not just the first batch.**
-> Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities
-> were added later without re-running migration → 4 entities had no database tables.
-> **RULE:** Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
-> If entities are added incrementally, create a NEW migration for each batch.
+> Migration must cover ALL entities. Root cause (test-apex-007): Migration was created once for 3 entities, then 4 more entities were added later without re-running → 4 entities had no tables. Create/update migration AFTER ALL entities and EF configs are registered in DbContext. If entities are added incrementally, create a new migration for each batch.
 
 ```
-1. Verify ALL entities have been added as DbSet in ExtensionsDbContext
-2. Verify ALL EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
+1. Verify all entities have been added as DbSet in ExtensionsDbContext
+2. Verify all EF configurations are registered (ApplyConfigurationsFromAssembly or individual)
 3. MCP suggest_migration → get standardized name
 4. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
 5. dotnet ef database update (if local DB)
-6. dotnet build → MUST PASS
-7. Verify: dotnet ef migrations has-pending-model-changes → MUST report "No pending model changes"
+6. dotnet build
+7. Verify: dotnet ef migrations has-pending-model-changes → must report "No pending model changes"
 ```
 
-**BLOCKING:** If build fails after migration, fix EF configs before proceeding.
-**BLOCKING:** If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
+If build fails after migration, fix EF configs before proceeding.
+If `has-pending-model-changes` reports pending changes, entities are missing from the migration — create a new migration.
 
 ### Post-Layer 0 Build Gate
 
@@ -112,7 +135,7 @@ dotnet build
 # Note: WSL bin\Debug cleanup handled by PostToolUse hook (wsl-dotnet-cleanup.sh)
 ```
 
-**MUST PASS before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.**
+Must pass before Layer 1. If NuGet error, run `dotnet restore` first. If file lock (MSB3021), use `--output /tmp/{project}_build`.
 
 TaskUpdate(taskId: layer0_task_id, status: "completed",
   metadata: { build_gate: "pass" })
@@ -133,21 +156,17 @@ TaskUpdate(taskId: progress_tracker_id,
   description: "Module: {module_code}. Current: step-03 (Execute), Layer 1",
   activeForm: "Executing Layer 1")
 
-> **This layer is DEDICATED and MANDATORY.** Seed data makes modules visible in the UI.
-> Without seed data, the module exists in code but is invisible to users.
-> Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
+> This layer is required. Seed data makes modules visible in the UI. Without it, the module exists in code but is invisible to users. Reference: `references/core-seed-data.md` (loaded above) for complete C# templates.
 
 ### Application-Level Seed Data (ONCE per application)
 
 ```
 1. NavigationApplicationSeedData.cs
    → Application-level navigation entry (MUST be first)
-   → Random GUID via Guid.NewGuid()
    → 4 language translations (fr, en, it, de)
 
 2. ApplicationRolesSeedData.cs
    → 4 roles: admin, manager, contributor, viewer
-   → Random GUIDs (Guid.NewGuid())
    → References NavigationApplicationSeedData.ApplicationId
 ```
 
@@ -155,8 +174,7 @@ TaskUpdate(taskId: progress_tracker_id,
 
 ```
 3. NavigationModuleSeedData.cs
-   → Random GUIDs (Guid.NewGuid()), 4 languages (fr, en, it, de)
-   → GetModuleEntry() + GetTranslationEntries()
+   → 4 languages (fr, en, it, de), GetModuleEntry() + GetTranslationEntries()
    → If sections defined: GetSectionEntries() + GetSectionTranslationEntries()
    → If resources defined: GetResourceEntries() + resource translations
    → Query actual parent from DB for FK (NOT deterministic GUID)
@@ -172,7 +190,7 @@ TaskUpdate(taskId: progress_tracker_id,
 
 6. RolesSeedData.cs
    → Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R
-   → Code-based role mapping (NEVER deterministic GUIDs for roles)
+   → Code-based role mapping (not deterministic GUIDs for roles)
    → Look up roles by Code at runtime
 ```
 
@@ -194,7 +212,7 @@ TaskUpdate(taskId: progress_tracker_id,
 dotnet build
 ```
 
-**MUST PASS before Layer 2.**
+Must pass before Layer 2.
 
 TaskUpdate(taskId: layer1_task_id, status: "completed",
   metadata: { build_gate: "pass" })
@@ -205,6 +223,8 @@ TaskUpdate(taskId: layer1_task_id, status: "completed",
 feat({module}): [seed] navigation, permissions, roles
 ```
 
+> **Context release:** `references/core-seed-data.md` is no longer needed after Layer 1. Its templates have been consumed. Do not reference it in Layer 2+.
+
 ---
 
 ## Layer 2 — Backend (Services + Controllers)
@@ -224,9 +244,9 @@ TaskUpdate(taskId: progress_tracker_id,
 
 ### Backend Tasks (sequential or parallel within layer)
 
-- **Services/DTOs:** MCP scaffold_extension
-- **Controllers:** use /controller skill for complex, MCP scaffold_extension for simple
-- **IMPORTANT:** ALL GetAll endpoints MUST support `?search=` query parameter (enables EntityLookup on frontend)
+- Services/DTOs: MCP scaffold_extension
+- Controllers: use /controller skill for complex, MCP scaffold_extension for simple
+- Important: All GetAll endpoints must support `?search=` query parameter (enables EntityLookup on frontend)
 
 ### Skill Delegation
 
@@ -239,40 +259,36 @@ TaskUpdate(taskId: progress_tracker_id,
 | /notification | In-app or email notifications | trigger, recipients, template |
 | /workflow | Automated workflows | trigger, steps, conditions |
 
-### If NOT economy_mode AND multiple entities: Agent Teams (parallel within layer)
+### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
 
-> **Protocol:** See `references/agent-teams-protocol.md`
+> **Protocol:** See `references/parallel-execution.md`
 
 ```
-TeamCreate("apex-layer2", description: "Execute Layer 2 backend in parallel")
-
-Spawn 1 teammate per entity (Opus, full tools):
-
-For each entity:
-  Task: "Execute Layer 2 backend for entity {EntityName}:
-    - Application service/DTO: MCP scaffold_extension
-    - Controller: /controller skill or MCP scaffold_extension
-    - IMPORTANT: GetAll endpoint MUST support ?search= parameter
-    - Validators: FluentValidation + DI registration
+IF NOT economy_mode AND entities.length > 1:
+  For each entity, launch in parallel (single message):
+    Agent(subagent_type='Snipper', model='opus',
+      prompt='Execute Layer 2 backend for {EntityName}:
+        - Application service/DTO: MCP scaffold_extension
+        - Controller: /controller skill or MCP scaffold_extension
+        - IMPORTANT: GetAll endpoint MUST support ?search= parameter
+        - Validators: FluentValidation + DI registration
+        - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
+        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
+  # All agents launched in parallel
 
-    After ALL tasks done:
-    SendMessage(type:'message', recipient:'team-lead', content:'ENTITY_COMPLETE: {EntityName}', summary:'{EntityName} backend done')"
-
-Wait for all teammates to report completion.
-shutdown_request → shutdown_response → TeamDelete("apex-layer2")
+ELSE:
+  # Agent principal handles all entities sequentially
 ```
 
-### Agent Teams + TaskCreate Integration
+### Parallel Agents + TaskCreate Integration
 
-When spawning teammates for multi-entity layers:
-- Each teammate receives its task ID and metadata context in the prompt
-- Teammate MUST call TaskUpdate(status: "in_progress") before starting
-- Teammate MUST call TaskUpdate(status: "completed", metadata: { files_created: [...] }) after SendMessage("ENTITY_COMPLETE")
-- Lead monitors via TaskList() between teammate completions
-- Lead updates activeForm after each entity completion:
+When launching agents for multi-entity layers:
+- Each agent receives its task ID and metadata context in the prompt
+- Agent must call TaskUpdate(status: "in_progress") before starting
+- Agent must call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done
+- Agent principal monitors via TaskList() after all agents complete
+- Agent principal updates activeForm after each entity completion:
   `TaskUpdate(taskId: layer2_task_id, activeForm: "Building {EntityName} backend (2/5 entities)")`
-- Lead updates metadata after each MCP scaffold:
-  `TaskUpdate(taskId: layer_task_id, metadata: { files_created: [...previous, "new_file.cs"] })`
 
 ### Post-Layer 2 Build Gate
 
@@ -280,7 +296,7 @@ When spawning teammates for multi-entity layers:
 dotnet build
 ```
 
-**MUST PASS before backend tests.**
+Must pass before backend tests.
 
 TaskUpdate(taskId: layer2_task_id, status: "completed",
   metadata: { build_gate: "pass" })
@@ -319,10 +335,17 @@ feat({module}): [app+api] {short description}
 test({module}): backend unit and integration tests
 ```
 
+> **Context release:** `references/smartstack-api.md` entity patterns and `references/smartstack-layers.md` Layer 2 rules have been consumed. Layer 3 only needs their frontend sections (already covered by `smartstack-frontend.md`).
+
 ---
 
 ## Layer 3 — Frontend (Pages + I18n + Documentation)
 
+### Load Frontend References (deferred from top of step)
+
+- Read `references/smartstack-frontend.md` now — lazy loading, i18n, page structure, CSS variables, EntityLookup (sections 1-6)
+- Read `references/smartstack-frontend-compliance.md` now — documentation, form testing, compliance gates (sections 7-9)
+
 ### Task Progress
 TaskUpdate(taskId: layer3_task_id, status: "in_progress")
 TaskUpdate(taskId: progress_tracker_id,
@@ -334,7 +357,7 @@ TaskUpdate(taskId: progress_tracker_id,
 > - Route scaffolding (MCP scaffold_routes) — section 1 + 3b
 > - Page types (ListPage, DetailPage, CreatePage, EditPage) — section 3
 > - FK field handling (EntityLookup component) — section 6
-> - Form structure (ZERO modals — all full pages) — section 3b
+> - Form structure (no modals — all full pages) — section 3b
 > - Detail page tabs (local state only) — section 3 "Tab Behavior Rules"
 > - Testing patterns (co-located form tests) — section 8
 > - Section-level routes and permissions — section 3b
@@ -344,50 +367,56 @@ TaskUpdate(taskId: progress_tracker_id,
 ### Frontend Tasks (sequential or parallel within layer)
 
 For each module:
-- **API client:** MCP scaffold_api_client
-- **Routes:** MCP scaffold_routes (outputFormat: 'applicationRoutes') → generates lazy imports + Suspense
-- **Wire Routes to App.tsx (BLOCKING):** After scaffold_routes, routes MUST be wired into App.tsx:
+- API client: MCP scaffold_api_client
+- Routes: MCP scaffold_routes (outputFormat: 'applicationRoutes') → generates lazy imports + Suspense
+- Wire Routes to App.tsx: After scaffold_routes, routes must be wired into App.tsx:
   → Read App.tsx and detect the routing pattern
-  → **Pattern A** (`applicationRoutes: ApplicationRouteExtensions`): add routes to `applicationRoutes['{application_kebab}'][]` with RELATIVE paths
-  → **Pattern B** (JSX `<Route>`): nest routes inside `<Route path="/{application}" element={<AppLayout />}>` + duplicate in tenant block
-  → **FORBIDDEN:** Adding business routes to `clientRoutes[]` — it is ONLY for non-app routes (`/about`, `/pricing`)
-  → ALL business applications use `<AppLayout />` as layout wrapper
+  → Pattern A (`applicationRoutes: ApplicationRouteExtensions`): add routes to `applicationRoutes['{application_kebab}'][]` with RELATIVE paths
+  → Pattern B (JSX `<Route>`): nest routes inside `<Route path="/{application}" element={<AppLayout />}>` + duplicate in tenant block
+  → Do not add business routes to `clientRoutes[]` — it is only for non-app routes (`/about`, `/pricing`)
+  → All business applications use `<AppLayout />` as layout wrapper
   → See `references/frontend-route-wiring-app-tsx.md` for full Pattern A/B detection and examples
   → Verify: `mcp__smartstack__validate_frontend_routes (scope: 'routes')`
-- **Pages:** use /ui-components skill — MUST follow smartstack-frontend.md patterns:
+- Pages: use /ui-components skill — follow smartstack-frontend.md patterns:
   → React.lazy() for all page imports (named export wrapping)
   → `<Suspense fallback={<PageLoader />}>` around all lazy components
   → Page structure: hooks → useEffect(load) → loading → error → content
   → CSS variables only: bg-[var(--bg-card)], text-[var(--text-primary)]
-  → DataTable/EntityCard (NEVER raw HTML `<table>`)
+  → DataTable/EntityCard (not raw HTML `<table>`)
   → If entity has FK Guid fields: generate EntityLookup component in @/components/ui/EntityLookup (see smartstack-frontend.md section 6)
   → Dashboard pages: generate StatCard + ChartCard locally (see ui-components patterns/dashboard-chart.md)
-- **FORM PAGES (CRITICAL):** Create/Edit forms are FULL PAGES with own routes:
+- Form pages: Create/Edit forms are full pages with own routes:
   → EntityCreatePage.tsx with route /{module}/create
   → EntityEditPage.tsx with route /{module}/:id/edit
-  → ZERO modals/popups/drawers/dialogs for forms
+  → Zero modals/popups/drawers/dialogs for forms
   → Back button with navigate(-1) on every form page
   → See smartstack-frontend.md section 3b for templates
-- **TABS ON DETAIL PAGES (CRITICAL):** Tabs MUST switch content LOCALLY:
-  → Tab click handler: setActiveTab(tabKey) ONLY — NEVER navigate() to another page
+- Tabs on detail pages: Tabs must switch content locally:
+  → Tab click handler: setActiveTab(tabKey) only — do not navigate() to another page
   → Tab content: render inline with {activeTab === 'tabKey' && <TabContent />}
   → Sub-resource data: fetch via API filtered by parent ID, display in tab panel
-  → FORBIDDEN: navigate('../leaves?employee=${id}') in tab handler
+  → Do not use navigate('../leaves?employee=${id}') in tab handler
   → See smartstack-frontend.md section 3 'Tab Behavior Rules'
-- **FK FIELDS (CRITICAL):** Foreign key Guid fields (e.g., EmployeeId) MUST use EntityLookup:
-  → NEVER render FK fields as `<input>` — users cannot type GUIDs
-  → NEVER render FK fields as `<select>` — even with API-loaded options, `<select>` is NOT acceptable
-  → ONLY use `<EntityLookup />` from @/components/ui/EntityLookup for searchable selection
+- FK fields: Foreign key Guid fields (e.g., EmployeeId) must use EntityLookup:
+  → Do not render FK fields as `<input>` — users cannot type GUIDs
+  → Do not render FK fields as `<select>` — even with API-loaded options, `<select>` is not acceptable
+  → Only use `<EntityLookup />` from @/components/ui/EntityLookup for searchable selection
   → Each FK field needs: apiEndpoint, mapOption (display name), search support on backend
-  → FORBIDDEN: `<select value={formData.departmentId}>`, `<option value={dept.id}>`, `e.target.value` for FK fields
+  → Do not use `<select value={formData.departmentId}>`, `<option value={dept.id}>`, `e.target.value` for FK fields
   → See smartstack-frontend.md section 6 for the full EntityLookup pattern
-- **I18n:** Generate 4 JSON files per module namespace (fr, en, it, de)
+- I18n: Generate 4 JSON files per module namespace (fr, en, it, de)
   → Follow JSON template from smartstack-frontend.md
   → Keys: actions, labels, errors, validation, columns, form, messages, empty
-  → ALL t() calls MUST use namespace prefix + fallback: t('ns:key', 'Default text')
-- **PERMISSIONS:** Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
-  then also call MCP generate_permissions for EACH section (3 segments: {app}.{module}.{section}).
-- **SECTION ROUTES:** Add section child routes to the module's children array.
+  → All t() calls must use namespace prefix + fallback: t('ns:key', 'Default text')
+  → **Register namespace in i18n config** (critical — POST-CHECK C39 catches this, but fix it now):
+    1. Find i18n config: `Glob("src/**/i18n/config.ts")` or `index.ts` or `i18n.ts`
+    2. Read the config → find the resources/ns registration pattern
+    3. Add the new namespace import + registration for all 4 languages
+    4. If config uses dynamic imports: add namespace to the `ns` array
+    5. Verify: `grep -q "{module_namespace}" src/**/i18n/config.ts` → must match
+- Permissions: Call MCP generate_permissions for the module permission root (2 segments: {app}.{module}),
+  then also call MCP generate_permissions for each section (3 segments: {app}.{module}.{section}).
+- Section routes: Add section child routes to the module's children array.
   Wire PermissionGuard for section routes with section-level permissions.
 - MUST use src/pages/{App}/{Module}/ hierarchy (NOT flat)
 
@@ -411,63 +440,55 @@ This generates:
 - Import: `import { DocToggleButton } from '@/components/docs/DocToggleButton';`
 - Placement: inside the header actions area (see `smartstack-frontend.md` section 7)
 
-### If NOT economy_mode AND multiple entities: Agent Teams (parallel within layer)
-
-> **Protocol:** See `references/agent-teams-protocol.md`
-
-```
-TeamCreate("apex-layer3", description: "Execute Layer 3 frontend in parallel")
-
-Spawn 1 teammate per entity (Opus, full tools):
-
-For each entity:
-  Task: "Execute Layer 3 frontend for entity {EntityName}:
-    **MANDATORY: Read references/smartstack-frontend.md FIRST**
-    - API client: MCP scaffold_api_client
-    - Routes: MCP scaffold_routes (outputFormat: 'applicationRoutes')
-    - Wire Routes to App.tsx (BLOCKING): After scaffold_routes, wire into App.tsx:
-      → Read App.tsx, detect Pattern A (applicationRoutes) or Pattern B (JSX Route)
-      → Pattern A: add to applicationRoutes['{application_kebab}'][] with RELATIVE paths
-      → Pattern B: nest inside <Route path='/{application}' element={<AppLayout />}> + tenant block
-      → FORBIDDEN: Adding business routes to clientRoutes[] (ONLY for /about, /pricing)
-      → See references/frontend-route-wiring-app-tsx.md for full patterns
-      → Verify: mcp__smartstack__validate_frontend_routes (scope: 'routes')
-    - Pages: /ui-components skill (ALL 4 types: List, Detail, Create, Edit)
-    - I18n: 4 JSON files (fr, en, it, de)
-    - FORM PAGES: Full pages with own routes (ZERO modals)
-    - FK FIELDS: EntityLookup for all FK Guid fields
-    - TABS: Local state only (NEVER navigate())
-    - FORM TESTS: Co-located .test.tsx for Create and Edit pages
-
-    After ALL tasks done:
-    SendMessage(type:'message', recipient:'team-lead', content:'ENTITY_COMPLETE: {EntityName}', summary:'{EntityName} frontend done')"
-
-Wait for all teammates to report completion.
-shutdown_request → shutdown_response → TeamDelete("apex-layer3")
-```
-
-### Agent Teams + TaskCreate Integration
-
-When spawning teammates for multi-entity layers:
-- Each teammate receives its task ID and metadata context in the prompt
-- Teammate MUST call TaskUpdate(status: "in_progress") before starting
-- Teammate MUST call TaskUpdate(status: "completed", metadata: { files_created: [...] }) after SendMessage("ENTITY_COMPLETE")
-- Lead monitors via TaskList() between teammate completions
-- Lead updates activeForm after each entity completion:
+### If NOT economy_mode AND multiple entities: Parallel Agents (within layer)
+
+> **Protocol:** See `references/parallel-execution.md`
+
+```
+IF NOT economy_mode AND entities.length > 1:
+  For each entity, launch in parallel (single message):
+    Agent(subagent_type='Snipper', model='opus',
+      prompt='Execute Layer 3 frontend for {EntityName}:
+        **MANDATORY: Read references/smartstack-frontend.md FIRST**
+        - API client: MCP scaffold_api_client
+        - Routes: MCP scaffold_routes (outputFormat: "applicationRoutes")
+        - Wire Routes to App.tsx (BLOCKING): detect Pattern A/B, wire accordingly
+          → See references/frontend-route-wiring-app-tsx.md for full patterns
+          → Verify: mcp__smartstack__validate_frontend_routes (scope: "routes")
+        - Pages: /ui-components skill (ALL 4 types: List, Detail, Create, Edit)
+        - I18n: 4 JSON files (fr, en, it, de) + REGISTER namespace in i18n config
+        - FORM PAGES: Full pages with own routes (no modals)
+        - FK FIELDS: EntityLookup for all FK Guid fields
+        - TABS: Local state only (NEVER navigate())
+        - FORM TESTS: Co-located .test.tsx for Create and Edit pages
+        - Your task ID is {task_id}. Call TaskUpdate(status: "in_progress") before starting.
+        - Call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done.')
+  # All agents launched in parallel
+
+ELSE:
+  # Agent principal handles all entities sequentially
+```
+
+### Parallel Agents + TaskCreate Integration
+
+When launching agents for multi-entity layers:
+- Each agent receives its task ID and metadata context in the prompt
+- Agent must call TaskUpdate(status: "in_progress") before starting
+- Agent must call TaskUpdate(status: "completed", metadata: { files_created: [...] }) when done
+- Agent principal monitors via TaskList() after all agents complete
+- Agent principal updates activeForm after each entity completion:
   `TaskUpdate(taskId: layer3_task_id, activeForm: "Building {EntityName} frontend (2/5 entities)")`
-- Lead updates metadata after each MCP scaffold:
-  `TaskUpdate(taskId: layer_task_id, metadata: { files_created: [...previous, "NewPage.tsx"] })`
 
-### FRONTEND COMPLIANCE GATE (MANDATORY before commit)
+### Frontend Compliance Gate
 
-> **Reference:** See `references/smartstack-frontend.md` section 9 "Compliance Gates" for all 5 mandatory checks:
+> See `references/smartstack-frontend.md` section 9 "Compliance Gates" for all 5 required checks:
 > 1. CSS Variables (theme system)
-> 2. Forms as Pages (ZERO modals/drawers/slide-overs)
+> 2. Forms as Pages (zero modals/drawers/slide-overs)
 > 3. I18n File Structure (4 languages, separate JSON files)
 > 4. Lazy Loading (React.lazy() — no static imports)
 > 5. useTranslation in Pages (all text translated)
 
-**BLOCKING:** Do NOT commit frontend changes until ALL 5 gates pass.
+Do not commit frontend changes until all 5 gates pass.
 
 When delegating to `/ui-components` skill, include explicit instructions:
 - "CSS: Use CSS variables ONLY — `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`."
@@ -510,7 +531,7 @@ When delegating to `/ui-components` skill, include explicit instructions:
 npm run typecheck
 ```
 
-**MUST PASS before commit.**
+Must pass before commit.
 
 TaskUpdate(taskId: layer3_task_id, status: "completed",
   metadata: { build_gate: "pass" })
@@ -595,6 +616,40 @@ Layer 4: feat({module}): [devdata] test data for development  # if applicable
 
 ---
 
+## State Auto-Save (after each layer)
+
+> **Automatic** — not dependent on `-s` flag. Enables reliable resume after context loss.
+
+After each layer's build gate passes, write state to `.claude/output/apex/{task_id}/state.json`:
+
+```json
+{
+  "step": 3,
+  "layer": 2,
+  "completed_layers": [0, 1, 2],
+  "completed_entities": ["Employee", "Department"],
+  "files_created": ["Employee.cs", "EmployeeConfiguration.cs", "..."],
+  "build_gates": { "layer0": "pass", "layer1": "pass", "layer2": "pass" },
+  "commits": ["abc1234", "def5678", "ghi9012"],
+  "timestamp": "2026-03-06T14:30:00Z"
+}
+```
+
+```
+IF .claude/output/apex/{task_id}/ does not exist:
+  Generate {task_id} from timestamp (e.g., "20260306-143000")
+  Create directory
+
+After EACH layer build gate passes:
+  Read existing state.json (or create new)
+  Update: layer, completed_layers, completed_entities, files_created, build_gates, commits
+  Write back to state.json
+```
+
+This file is consumed by resume mode (`-r`) to skip completed layers instead of re-deriving from git.
+
+---
+
 ## Save Output (if save_mode)
 
 Write to `{output_dir}/03-execute.md` with execution log per layer.