@atlashub/smartstack-cli 4.17.1 → 4.19.0

package/templates/skills/apex/references/core-seed-data.md

@@ -62,9 +62,9 @@ if (!navRoute) {
 
 **File:** `Infrastructure/Persistence/Seeding/Data/NavigationApplicationSeedData.cs`
 
-> **MANDATORY:** This file MUST be created BEFORE any module seed data.
+> Create this file BEFORE any module seed data.
 > Without it, modules have no parent ApplicationId and ApplicationRolesSeedData has no GUID reference.
-> This file is created **ONCE per application** (not per module).
+> This file is created once per application (not per module).
 
 ### Data Source
 
@@ -220,10 +220,30 @@ public class NavigationApplicationSeedEntry
 ### GUID Generation Rule
 
 ```csharp
-// ALWAYS use Guid.NewGuid() — avoids conflicts between projects/tenants/environments
+// Use Guid.NewGuid() — avoids conflicts between projects/tenants/environments
 public static readonly Guid ModuleId = Guid.NewGuid();
 ```
 
+### FK Resolution Safety Rule
+
+When seed data references a parent entity (e.g., Module references Application, Section references Module), use `FirstOrDefaultAsync` with a null-guard that gives a clear diagnostic:
+
+```csharp
+// CORRECT: null-guard with clear error message
+var parentModule = await context.NavigationModules
+    .FirstOrDefaultAsync(m => m.Code == "target-module" && m.ApplicationId == app.Id, ct)
+    ?? throw new InvalidOperationException(
+        $"Seed data dependency missing: NavigationModule 'target-module' not found. " +
+        $"Run the target module's seed data provider first.");
+
+// WRONG: FirstAsync with generic error
+var parentModule = await context.NavigationModules
+    .FirstAsync(m => m.Code == "target-module", ct);
+// → Throws "Sequence contains no elements" — hard to debug
+```
+
+This applies to ALL cross-entity FK lookups in seed data: modules, sections, resources, roles, permissions.
+
 ### Template
 
 ```csharp
@@ -386,7 +406,7 @@ public static readonly Guid {ResourcePascal}ResourceId = Guid.NewGuid();
 > The `list` and `detail` sections are view modes of the module, NOT functional sub-areas.
 > - `list` section route = module route (e.g., `/human-resources/employees`) — NO `/list` suffix
 > - `detail` section route = module route + `/:id` (e.g., `/human-resources/employees/:id`) — NOT `/detail/:id`
-> - FORBIDDEN: `/{module}/list`, `/{module}/detail/:id`
+> - Do not use: `/{module}/list`, `/{module}/detail/:id`
 > - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
 
 ```csharp
@@ -416,7 +436,7 @@ public static IEnumerable<NavigationSectionSeedEntry> GetSectionEntries(Guid mod
             // - "list" section → same as module route (no extra segment)
             // - "detail" section → module route + "/:id"
             // - Other sections → module route + "/{section-kebab}"
-            // FORBIDDEN: "/employees/list", "/employees/detail/:id"
+            // Do not use: "/employees/list", "/employees/detail/:id"
             Route = "{section_route}",  // From seedDataCore.navigationSections[].route
             DisplayOrder = {section1_sort},
             IsActive = true
@@ -579,9 +599,9 @@ public class NavigationResourceSeedEntry
 
 ## 3. PermissionsSeedData.cs — MCP-First
 
-### CRITICAL: PermissionAction Safety Rules
+### PermissionAction Safety Rules
 
-> **NEVER use `Enum.Parse<PermissionAction>("...")` — this causes runtime crashes if the string is invalid.**
+> Do not use `Enum.Parse<PermissionAction>("...")` — this causes runtime crashes if the string is invalid.
 > The error only manifests at application startup, not at compile time.
 
 **Valid PermissionAction values (from SmartStack.Domain.Authorization):**
@@ -600,18 +620,18 @@ public class NavigationResourceSeedEntry
 | `PermissionAction.Assign` | 9 | Assign items to users |
 | `PermissionAction.Execute` | 10 | Execute actions (sync, run, etc.) |
 
-**Anti-patterns (FORBIDDEN):**
+**Anti-patterns:**
 
 ```csharp
-// FORBIDDEN — Runtime crash if string is not a valid enum value
+// Runtime crash if string is not a valid enum value
 Enum.Parse<PermissionAction>("Validate");          // ArgumentException at startup
 (PermissionAction)Enum.Parse(typeof(PermissionAction), "Validate"); // Same crash
 
-// FORBIDDEN — String-based action in anonymous objects
+// String-based action in anonymous objects
 new { Action = "read" };  // Not type-safe, silent mismatch possible
 ```
 
-**Correct patterns (MANDATORY):**
+**Correct patterns:**
 
 ```csharp
 // ALWAYS use the typed enum directly — compile-time safe
@@ -641,10 +661,10 @@ MCP returns:
 
 ### Step B: Write Permissions.cs (Application layer)
 
-> **CRITICAL — Permission paths use the SAME kebab-case as NavRoute codes.**
+> Permission paths use the SAME kebab-case as NavRoute codes.
 > `{navRoute}` is already kebab-case (e.g., `human-resources.employees`).
-> NEVER strip hyphens or derive codes from C# class names.
-> FORBIDDEN: `humanresources.employees.read` → CORRECT: `human-resources.employees.read`
+> Do not strip hyphens or derive codes from C# class names.
+> Use `human-resources.employees.read` not `humanresources.employees.read`.
 > SmartStack.app reference: `support-client.my-tickets.read`
 
 ```csharp
@@ -769,14 +789,14 @@ If MCP `generate_permissions` fails, use the template above directly with values
 
 Creates the 4 standard application-scoped roles: Admin, Manager, Contributor, Viewer.
 
-> **CRITICAL — SmartStack core MAY already provide system roles (admin, manager, contributor, viewer).**
-> If system roles already exist in `auth_Roles`, do NOT create duplicates.
-> `SeedRolesAsync()` MUST check existence by Code, not just by ApplicationId.
-> **For RolePermission mappings:** ALWAYS look up roles by Code at runtime (in `SeedRolePermissionsAsync()`).
-> **FORBIDDEN:** Using `GenerateRoleGuid()`, `DeterministicGuid("role:admin")`, or any hardcoded role GUID
+> SmartStack core MAY already provide system roles (admin, manager, contributor, viewer).
+> If system roles already exist in `auth_Roles`, do not create duplicates.
+> `SeedRolesAsync()` must check existence by Code, not just by ApplicationId.
+> For RolePermission mappings: always look up roles by Code at runtime (in `SeedRolePermissionsAsync()`).
+> Do not use `GenerateRoleGuid()`, `DeterministicGuid("role:admin")`, or any hardcoded role GUID
 > when creating RolePermission entries. The role GUIDs may differ from what's in the database.
 
-**CRITICAL:** This file is created **ONCE per application** (not per module).
+This file is created once per application (not per module).
 
 ### GUID Generation Rule
 
@@ -784,9 +804,9 @@ Creates the 4 standard application-scoped roles: Admin, Manager, Contributor, Vi
 > RolePermission mapping MUST look up roles by Code, not by GUID.
 
 ```csharp
-// All role GUIDs are random — ALWAYS resolve roles by Code at runtime
-// FORBIDDEN in RolePermission mapping: hardcoded GUIDs of any kind
-// CORRECT: var role = roles.FirstOrDefault(r => r.Code == "admin");
+// All role GUIDs are random — always resolve roles by Code at runtime
+// Do not use hardcoded GUIDs in RolePermission mapping
+var role = roles.FirstOrDefault(r => r.Code == "admin");
 ```
 
 ### Template
@@ -887,10 +907,10 @@ public class ApplicationRoleSeedEntry
 
 **File:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/RolesSeedData.cs`
 
-> **CRITICAL:** This file uses `RoleCode` (string), NOT role GUIDs.
+> This file uses `RoleCode` (string), not role GUIDs.
 > Roles are resolved by Code at runtime in `SeedRolePermissionsAsync()`.
-> **FORBIDDEN:** `DeterministicGuid("role:admin")`, `GenerateRoleGuid("admin")`, or any hardcoded Guid for roles.
-> SmartStack core pre-seeds system roles — their IDs are NOT deterministic from the client perspective.
+> Do not use `DeterministicGuid("role:admin")`, `GenerateRoleGuid("admin")`, or any hardcoded Guid for roles.
+> SmartStack core pre-seeds system roles — their IDs are not deterministic from the client perspective.
 
 ### Context-Based Role Mapping
 
@@ -967,7 +987,7 @@ public class RolePermissionSeedEntry
 
 | Rule | Description |
 |------|-------------|
-| Factory methods | `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — NEVER `new Entity()` |
+| Factory methods | `NavigationModule.Create(...)`, `Role.Create(...)`, `Permission.CreateForModule(...)`, `RolePermission.Create(...)` — do not use `new Entity()` |
 | Idempotence | Each Seed method checks existence before inserting |
 | Execution order | Navigation → Roles → Permissions → RolePermissions (roles MUST exist before mapping) |
 | SaveChanges per group | Navigation -> save -> Roles -> save -> Permissions -> save -> RolePermissions -> save |
@@ -1048,11 +1068,14 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
 
         // Resolve module entities for section/resource seeding (works for both new AND existing modules)
         var mod1Entity = await context.NavigationModules
-            .FirstAsync(m => m.Code == "{module1Code}" && m.ApplicationId == app.Id, ct);
+            .FirstOrDefaultAsync(m => m.Code == "{module1Code}" && m.ApplicationId == app.Id, ct)
+            ?? throw new InvalidOperationException(
+                $"Seed data dependency missing: NavigationModule '{"{module1Code}"}' not found for app '{app.Code}'. " +
+                $"Ensure the module was created in the navigation seeding step above.");
         // Repeat for each module...
 
         // --- Module translations (idempotent — unique index IX_nav_Translations_EntityType_EntityId_LanguageCode) ---
-        // CRITICAL: Always check existence before inserting translations to avoid duplicate key errors
+        // Always check existence before inserting translations to avoid duplicate key errors
         // on re-runs, partial failures, or DB reset scenarios.
         if (!await context.NavigationTranslations.AnyAsync(
             t => t.EntityId == {Module1Pascal}NavigationSeedData.{Module1Pascal}ModuleId
@@ -1103,9 +1126,9 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
         await ((DbContext)context).SaveChangesAsync(ct);
 
         // --- Resources (idempotent — use ACTUAL section IDs from DB, not deterministic seed IDs) ---
-        // CRITICAL: NavigationSection.Create() generates its own ID in DB.
-        // The GUID from GetSectionEntries() is NOT the actual SectionId in DB.
-        // We MUST query the real section by Code+ModuleId to get the actual DB ID,
+        // NavigationSection.Create() generates its own ID in DB.
+        // The GUID from GetSectionEntries() is not the actual SectionId in DB.
+        // Query the real section by Code+ModuleId to get the actual DB ID,
         // otherwise FK_nav_Resources_nav_Sections_SectionId will fail.
         foreach (var secEntry in {Module1Pascal}NavigationSeedData.GetSectionEntries(mod1Entity.Id))
         {
@@ -1186,9 +1209,9 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
             .AnyAsync(rp => rp.Permission!.Path.StartsWith("{appCode}."), ct);
         if (exists) return;
 
-        // CRITICAL: Resolve roles by Code from DB — NEVER use hardcoded GUIDs.
+        // Resolve roles by Code from DB — do not use hardcoded GUIDs.
         // Application-scoped roles (admin, manager, contributor, viewer) are created by
-        // SeedRolesAsync() above. System roles use their own IDs that do NOT match
+        // SeedRolesAsync() above. System roles use their own IDs that do not match
         // DeterministicGuid("role:admin").
         var roles = await context.Roles
             .Where(r => r.ApplicationId != null || r.IsSystem)
@@ -1211,7 +1234,7 @@ public class {AppPascalName}SeedDataProvider : IClientSeedDataProvider
 
             if (role == null)
             {
-                // CRITICAL: Role not found — SeedRolesAsync() may not have run.
+                // Role not found — SeedRolesAsync() may not have run.
                 // This causes silent permission failure → 401 on protected pages.
                 Console.WriteLine($"[SEED WARNING] Role '{mapping.RoleCode}' not found. Role-permission mapping skipped for '{mapping.PermissionPath}'.");
                 continue;
@@ -1281,7 +1304,7 @@ Sections and resources are **optional per module**. When processing a module's f
 
 ---
 
-## 8. Verification Checklist (BLOCKING)
+## 8. Verification Checklist
 
 Before marking the task as completed, verify ALL:
 
@@ -1302,12 +1325,12 @@ Before marking the task as completed, verify ALL:
 - [ ] `Permissions.cs` constants match seed data paths
 - [ ] MCP `generate_permissions` called (or fallback used)
 - [ ] Role-permission mappings assigned (Admin, Manager, Contributor, Viewer)
-- [ ] **RolePermission mappings use Code-based lookup** — NEVER `DeterministicGuid("role:admin")` or `GenerateRoleGuid()`
-- [ ] **SeedRolesAsync checks existence by Code** — SmartStack core may pre-seed system roles
+- [ ] RolePermission mappings use Code-based lookup (no `DeterministicGuid("role:admin")` or `GenerateRoleGuid()`)
+- [ ] SeedRolesAsync checks existence by Code (SmartStack core may pre-seed system roles)
 - [ ] `IClientSeedDataProvider` generated with 4 methods (Navigation, Roles, Permissions, RolePermissions)
 - [ ] Execution order: Navigation (application → modules → sections → resources) → Roles → Permissions → RolePermissions
 - [ ] Each Seed method is idempotent (checks existence before inserting)
-- [ ] Factory methods used throughout (NEVER `new Entity()`)
+- [ ] Factory methods used throughout (no `new Entity()`)
 - [ ] `SaveChangesAsync` called per group (Navigation → Roles → Permissions → RolePermissions)
 - [ ] DI registration added: `services.AddScoped<IClientSeedDataProvider, ...>()`
 - [ ] NavigationSections seeded (if `seedDataCore.navigationSections` present in feature.json)
@@ -1317,7 +1340,7 @@ Before marking the task as completed, verify ALL:
 - [ ] NO `Enum.Parse<PermissionAction>` usage anywhere in seeding code (use typed enum directly)
 - [ ] ALL PermissionAction values are from the valid enum: Access, Read, Create, Update, Delete, Export, Import, Approve, Reject, Assign, Execute
 
-**Seed Data Integrity (BLOCKING — run AFTER `dotnet build`):**
+**Seed Data Integrity (run AFTER `dotnet build`):**
 - [ ] Application startup test: `dotnet run --urls http://localhost:0 --environment Development` exits without seed data exceptions
 - [ ] Verify `nav_Applications` has entry for `{appCode}` (query or startup log)
 - [ ] Verify `nav_Modules` has entries for each module (count matches feature.json modules)
@@ -1337,8 +1360,8 @@ Before marking the task as completed, verify ALL:
 
 | Rule | Description |
 |------|-------------|
-| TenantId MANDATORY | ALL business seed entities MUST set `TenantId` |
-| Deterministic TenantId | Use `SeedConstants.DefaultTenantId` (NEVER inline GUID) |
+| TenantId required | All business seed entities must set `TenantId` |
+| Deterministic TenantId | Use `SeedConstants.DefaultTenantId` (do not inline GUID) |
 | DevDataSeeder pattern | Implement `IDevDataSeeder` with `SeedAsync()` method |
 | Idempotency | Each seeder MUST check `AnyAsync()` before inserting |
 | Order | DevDataSeeder `Order >= 200` (after core seed data at Order 100) |
@@ -1361,7 +1384,7 @@ public class {Module}DevDataSeeder : IDevDataSeeder
                 Id = Guid.NewGuid(),
                 Code = "{code}",
                 Name = "{name}",
-                TenantId = SeedConstants.DefaultTenantId,  // MANDATORY
+                TenantId = SeedConstants.DefaultTenantId,  // Required for multi-tenant isolation
                 IsActive = true
             }
         };
@@ -1374,9 +1397,9 @@ public class {Module}DevDataSeeder : IDevDataSeeder
 }
 ```
 
-### FORBIDDEN
+### Anti-patterns
 
-- Seeding business entities WITHOUT `TenantId`
+- Seeding business entities without `TenantId`
 - Using `Guid.NewGuid()` for TenantId
 - Omitting idempotency check (`AnyAsync`)
 - Hardcoding TenantId inline (use `SeedConstants.DefaultTenantId`)

package/templates/skills/apex/references/frontend-route-wiring-app-tsx.md

@@ -4,22 +4,27 @@
 
 ---
 
-## Step 4: Wire Routes to App.tsx (BLOCKING)
+## Step 4: Wire Routes to App.tsx
 
-**CRITICAL:** This step is MANDATORY. Without it, routes exist as files but are invisible to the React Router. The page will be BLANK.
+**Important:** This step is required. Without it, routes exist as files but are invisible to the React Router. The page will be blank.
 
 After `scaffold_routes` generates the route files, you MUST manually insert the routes into `App.tsx`.
 
 ---
 
-## Step 4a: Import Page Components
+## Step 4a: Import Page Components (Lazy Loading ONLY)
 
-At the top of App.tsx:
+At the top of App.tsx, ALL page imports MUST use `React.lazy()`:
 
 ```tsx
-import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
-// Or lazy-loaded:
-const {EntityName}Page = lazy(() => import('@/pages/{Application}/{Module}/{EntityName}Page'));
+// CORRECT — Lazy loading (MANDATORY per POST-CHECK S6)
+const {EntityName}Page = lazy(() =>
+  import('@/pages/{Application}/{Module}/{EntityName}Page')
+    .then(m => ({ default: m.{EntityName}Page }))
+);
+
+// WRONG — Static import is BLOCKING per POST-CHECK S6
+// import { {EntityName}Page } from '@/pages/{Application}/{Module}/{EntityName}Page';
 ```
 
 ---
@@ -98,9 +103,9 @@ Find `<Route path="/t/:slug">` and add the **same route entries** there.
 
 ---
 
-## Step 4b.5: Verify mergeRoutes() Call (BLOCKING)
+## Step 4b.5: Verify mergeRoutes() Call
 
-**BEFORE modifying routes, READ App.tsx and verify the `mergeRoutes()` call has 2 parameters.**
+**Before modifying routes, READ App.tsx and verify the `mergeRoutes()` call has 2 parameters.**
 
 ✅ Correct:
 ```tsx
@@ -113,9 +118,9 @@ const routes = mergeRoutes(clientRoutes);
 ```
 
 → Add the `applicationRoutes` object and pass it as 2nd parameter.
-Without it, ALL application routes are silently ignored → blank page or /login redirect.
+Without it, all application routes are silently ignored → blank page or /login redirect.
 
-**NEVER remove the `applicationRoutes` parameter or the `ApplicationRouteExtensions` import.**
+**Do not remove the `applicationRoutes` parameter or the `ApplicationRouteExtensions` import.**
 
 ---
 
@@ -141,11 +146,11 @@ If `appWiring.issues` is not empty, fix the wiring before proceeding.
 
 ---
 
-## Step 4e: Parent Redirect Routes (MANDATORY)
+## Step 4e: Parent Redirect Routes
 
-**CRITICAL:** Without parent redirects, navigating to an application or module URL (e.g., `/human-resources` or `/human-resources/employees`) will cause a redirect to `/login` because no route matches.
+**Important:** Without parent redirects, navigating to an application or module URL (e.g., `/human-resources` or `/human-resources/employees`) will cause a redirect to `/login` because no route matches.
 
-For each application, you MUST add:
+For each application, add:
 
 1. **Application root redirect** — redirects `/{application}` to the first module/section:
    ```tsx
@@ -169,19 +174,19 @@ The `to` prop is resolved relative to the **parent route** (`/{application}`), s
 
 ---
 
-## Forbidden Patterns (BOTH patterns)
+## Patterns to Avoid (BOTH patterns)
 
-- Adding application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is ONLY for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
-- Adding routes OUTSIDE the Layout wrapper (shell will not render)
-- Using `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
-- Adding custom application routes to `clientRoutes[]` with absolute paths:
+- Do not add application routes to `clientRoutes[]` with absolute paths — `clientRoutes` is only for routes outside SmartStack applications (e.g., `/about`, `/pricing`)
+- Do not add routes outside the Layout wrapper (shell will not render)
+- Do not use `createBrowserRouter` (SmartStack uses `useRoutes()` + `mergeRoutes()`)
+- Do not add custom application routes to `clientRoutes[]` with absolute paths:
   ```tsx
   // ❌ WRONG — bypasses RouteGuard + TenantLayout + AppLayout → /login redirect
   const clientRoutes: RouteConfig[] = [
     { path: '/human-resources/employees/management', element: <EmployeePage /> },
   ];
   ```
-  Custom application routes MUST go in `applicationRoutes` with RELATIVE paths:
+  Custom application routes go in `applicationRoutes` with RELATIVE paths:
   ```tsx
   // ✅ CORRECT
   const applicationRoutes: ApplicationRouteExtensions = {
@@ -190,7 +195,7 @@ The `to` prop is resolved relative to the **parent route** (`/{application}`), s
     ],
   };
   ```
-- Removing the `applicationRoutes` 2nd parameter from `mergeRoutes()` — this silently breaks ALL custom routes
+- Do not remove the `applicationRoutes` 2nd parameter from `mergeRoutes()` — this silently breaks all custom routes
 
 ---
 

package/templates/skills/apex/references/parallel-execution.md

@@ -0,0 +1,156 @@
+# Parallel Execution Protocol — APEX
+
+> **Loaded by:** step-01 (analysis scan) and step-03 (parallel execution)
+> **Condition:** NOT economy_mode
+> **Purpose:** Reusable protocol for launching parallel Agent subagents.
+
+---
+
+## Agent Tool Usage
+
+APEX uses the `Agent` tool from Claude Code to parallelize work. Agents are launched in a single message to run concurrently.
+
+```yaml
+Agent:
+  subagent_type: "Explore" | "Snipper"   # See assignment table below
+  model: "sonnet" | "opus"               # sonnet for scan, opus for dev
+  prompt: "{detailed task prompt}"
+```
+
+### Model & Agent Assignment
+
+| Task Type | subagent_type | Model | Justification |
+|-----------|---------------|-------|---------------|
+| Scan/read files | Explore | Sonnet | Read-only (Glob, Grep, Read) |
+| Read context (PRD, feature.json) | Explore | Sonnet | Read-only extraction |
+| Code development (Layer 2/3) | Snipper | Opus | Fast code editing (Read, Edit, Write, Glob, Grep) |
+
+---
+
+## Task List Coordination
+
+### Task Creation (by agent principal, BEFORE launching subagents)
+
+Tasks MUST be created upfront for the full layer scope:
+
+```
+FOR EACH entity in layer:
+  TaskCreate(
+    subject: "Layer {N}: {Entity} {layer_type}",
+    description: "{detailed scope: files, skills, MCP tools}",
+    activeForm: "{Building/Creating} {Entity} {layer_type}"
+  )
+```
+
+### Task Assignment (via prompt)
+
+Include task ID and context in the Agent prompt:
+
+```
+"Your assigned task ID is {task_id}.
+ Call TaskUpdate(taskId: '{task_id}', status: 'in_progress') before starting.
+ Call TaskUpdate(taskId: '{task_id}', status: 'completed', metadata: { files_created: [...] }) when done."
+```
+
+### Task Monitoring (by agent principal)
+
+```
+1. Agent results are returned when each subagent completes
+2. Agent principal updates TaskList after each result
+3. All tasks completed → proceed to build gate
+```
+
+---
+
+## Team Decomposition
+
+### Step-01 Analyze: Split by scan scope
+
+Launch 2-3 `Explore` agents in parallel (single message):
+
+```
+Agent(subagent_type='Explore', model='sonnet',
+  prompt='Scan backend for module {module_code}: entities, EF configs, services,
+   DTOs, validators, controllers in Domain/ + Infrastructure/ + Application/ + Api/')
+
+Agent(subagent_type='Explore', model='sonnet',
+  prompt='Scan frontend for module {module_code}: pages, components, hooks,
+   i18n files, route definitions in src/pages/ + src/components/ + src/locales/')
+
+Agent(subagent_type='Explore', model='sonnet',
+  prompt='Read context artifacts for module {module_code}: .ralph/prd-{module_code}.json,
+   docs/business/**/feature.json → extract sections, entities, rules, permissions, ACs')
+```
+
+Agent principal aggregates all results after all agents complete.
+
+### Step-03 Execute: Split by entity WITHIN a layer
+
+> **Cross-layer parallelism is FORBIDDEN.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
+> Parallel agents handle **multi-entity work within a single layer.**
+
+```
+Layer 2 (Backend) — if multiple entities:
+  Agent(subagent_type='Snipper', model='opus',
+    prompt='Execute Layer 2 backend for {Entity1}: service, DTO, controller, validators...')
+  Agent(subagent_type='Snipper', model='opus',
+    prompt='Execute Layer 2 backend for {Entity2}: service, DTO, controller, validators...')
+  # Launched in parallel in a single message
+
+Layer 3 (Frontend) — if multiple entities:
+  Agent(subagent_type='Snipper', model='opus',
+    prompt='Execute Layer 3 frontend for {Entity1}: pages, i18n, routes...')
+  Agent(subagent_type='Snipper', model='opus',
+    prompt='Execute Layer 3 frontend for {Entity2}: pages, i18n, routes...')
+  # Launched in parallel in a single message
+```
+
+Each agent has an **isolated scope**: handles one entity end-to-end within the layer.
+
+---
+
+## Coordination
+
+### Step-01: Agent principal aggregates scan results
+
+```
+1. Launch 2-3 Explore agents in parallel
+2. Each returns findings when complete
+3. Agent principal merges into unified analysis
+```
+
+### Step-03: Agent principal verifies between ALL 5 layers
+
+```
+1. Layer 0: agent principal executes (domain + infra + migration)
+2. Build gate: dotnet build → MUST PASS
+3. Layer 1: agent principal executes (seed data — sequential, no parallel agents)
+4. Build gate: dotnet build → MUST PASS
+5. Layer 2: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
+6. Build gate: dotnet build → MUST PASS
+7. Backend tests inline (scaffold + run + fix max 3)
+8. Layer 3: launch Snipper agents per entity (if multi-entity) OR agent principal (if single)
+9. Compliance gate: 5 frontend checks → MUST PASS
+10. Frontend tests inline (scaffold + run + fix max 3)
+11. Layer 4 (optional): agent principal executes DevData
+```
+
+---
+
+## Idle Handling
+
+Agents launched via the Agent tool return their results when complete.
+There is no idle state to manage — the agent principal simply waits for results.
+
+---
+
+## Decision Matrix
+
+| Condition | Action |
+|-----------|--------|
+| economy_mode = true | NO parallel agents, all sequential |
+| Single entity (any layer) | NO parallel agents, agent principal handles all |
+| Multiple entities, Layer 2 | Parallel: one Snipper agent per entity (service + controller) |
+| Multiple entities, Layer 3 | Parallel: one Snipper agent per entity (pages + i18n) |
+| Layer 0, Layer 1, Layer 4 | NO parallel agents (sequential by nature) |
+| Analysis phase (step-01) | Parallel: 2-3 Explore agents (backend + frontend + context) |

package/templates/skills/apex/references/person-extension-pattern.md

@@ -38,7 +38,7 @@ public class Employee : BaseEntity, ITenantEntity, IAuditableEntity
     public string? CreatedBy { get; set; }
     public string? UpdatedBy { get; set; }
 
-    // === USER LINK (Person Extension — mandatory) ===
+    // === USER LINK (Person Extension — required) ===
     public Guid UserId { get; private set; }
     public User? User { get; private set; }
 
@@ -167,7 +167,7 @@ public class EmployeeConfiguration : IEntityTypeConfiguration<Employee>
         builder.HasIndex(x => x.TenantId)
             .HasDatabaseName("IX_{prefix}Employees_TenantId");
 
-        // User link (mandatory)
+        // User link (required)
         builder.Property(x => x.UserId).IsRequired();
         builder.HasOne(e => e.User)
             .WithMany()
@@ -251,8 +251,8 @@ public class CustomerConfiguration : IEntityTypeConfiguration<Customer>
 ```
 
 **Key differences:**
-- Mandatory: `.IsRequired()` on UserId, plain `IsUnique()` on `(TenantId, UserId)`
-- Optional: `.IsRequired(false)` on UserId, `IsUnique().HasFilter("[UserId] IS NOT NULL")` on `(TenantId, UserId)`
+- Required variant: `.IsRequired()` on UserId, plain `IsUnique()` on `(TenantId, UserId)`
+- Optional variant: `.IsRequired(false)` on UserId, `IsUnique().HasFilter("[UserId] IS NOT NULL")` on `(TenantId, UserId)`
 - Optional: `builder.Ignore()` on computed `Display*` properties (not persisted)
 
 ---
@@ -277,7 +277,7 @@ public class EmployeeService : IEmployeeService
             ?? throw new TenantContextRequiredException();
 
         var query = _db.Employees
-            .Include(x => x.User)  // MANDATORY — always load User for display
+            .Include(x => x.User)  // Always load User for display
             .Where(x => x.TenantId == tenantId)
             .AsNoTracking();
 
@@ -350,7 +350,7 @@ public class CustomerService : ICustomerService
             ?? throw new TenantContextRequiredException();
 
         var query = _db.Customers
-            .Include(x => x.User)  // MANDATORY — load User for Display* resolution
+            .Include(x => x.User)  // Load User for Display* resolution
             .Where(x => x.TenantId == tenantId)
             .AsNoTracking();
 
@@ -409,8 +409,8 @@ public class CustomerService : ICustomerService
 **Key service rules:**
 - Both variants: `Include(x => x.User)` on ALL queries
 - Both variants: inject `ICoreDbContext` for User reads (User is in the core schema)
-- Mandatory: search on `User.FirstName`, `User.LastName`, `User.Email` directly
-- Optional: search fallback `User.FirstName ?? x.FirstName`
+- Mandatory variant: search on `User.FirstName`, `User.LastName`, `User.Email` directly
+- Optional variant: search fallback `User.FirstName ?? x.FirstName`
 - Both: CreateAsync verifies User exists + no duplicate `(TenantId, UserId)`
 
 ---
@@ -422,7 +422,7 @@ public class CustomerService : ICustomerService
 ```csharp
 // CreateDto — only UserId + business fields (no person fields)
 public record CreateEmployeeDto(
-    Guid UserId,        // mandatory — links to existing User
+    Guid UserId,        // required — links to existing User
     string Code,
     DateOnly HireDate
 );
@@ -481,8 +481,8 @@ public record CustomerResponseDto(
 ```
 
 **Key DTO rules:**
-- Mandatory CreateDto: `Guid UserId` + business fields only (no name/email)
-- Optional CreateDto: `Guid? UserId` + person fields (FirstName, LastName, Email)
+- Mandatory variant CreateDto: `Guid UserId` + business fields only (no name/email)
+- Optional variant CreateDto: `Guid? UserId` + person fields (FirstName, LastName, Email)
 - ResponseDto (both): includes `Display*` fields resolved from User or own fields
 - UserId is NOT in UpdateDto — the person link is set at creation time
 
@@ -493,7 +493,7 @@ public record CustomerResponseDto(
 ### Mandatory — CreatePage
 
 ```tsx
-// EntityLookup for User selection (mandatory)
+// EntityLookup for User selection (required)
 <EntityLookup
   apiEndpoint="/api/administration/users"
   value={formData.userId}