@atlashub/smartstack-cli 4.18.0 → 4.19.0

package/templates/skills/apex/references/smartstack-layers.md

@@ -17,17 +17,17 @@ Api            → Application, Infrastructure
 Web            → Application (via API clients)
 ```
 
-### FORBIDDEN Patterns
-
-| Layer | FORBIDDEN import | Why |
-|-------|-----------------|-----|
-| Domain | Application, Infrastructure, Api | Domain is the core, depends on nothing |
-| Application | Infrastructure, Api | Application defines interfaces, Infrastructure implements them |
-| Controller | DbContext (direct injection) | Controllers use Application services, not database directly |
-| Controller | IRepository (direct injection) | Controllers use Application services, not repositories |
-| Domain | EF Core attributes (`[Table]`, `[Column]`, `[Index]`) | Domain must be persistence-ignorant; use `IEntityTypeConfiguration<T>` in Infrastructure |
-| Domain | `using Microsoft.EntityFrameworkCore` | Infrastructure concern leaking into Domain |
-| API response | Domain entity (e.g., `ActionResult<Employee>`) | Return DTOs (`EmployeeResponseDto`), never Domain entities |
+### Forbidden Patterns
+
+| Layer | Do not | Why |
+|-------|--------|-----|
+| Domain | import Application, Infrastructure, Api | Domain is the core, depends on nothing |
+| Application | import Infrastructure, Api | Application defines interfaces, Infrastructure implements them |
+| Controller | inject DbContext directly | Controllers use Application services, not database directly |
+| Controller | inject IRepository directly | Controllers use Application services, not repositories |
+| Domain | use EF Core attributes (`[Table]`, `[Column]`, `[Index]`) | Domain must be persistence-ignorant; use `IEntityTypeConfiguration<T>` in Infrastructure |
+| Domain | use `using Microsoft.EntityFrameworkCore` | Infrastructure concern leaking into Domain |
+| API response | return Domain entity (e.g., `ActionResult<Employee>`) | Return DTOs (`EmployeeResponseDto`), never Domain entities |
 
 ### Enforcement
 
@@ -50,10 +50,10 @@ Web            → Application (via API clients)
 
 **Rules:**
 - Inherit `BaseEntity`, choose tenant interface based on data isolation requirements:
-  - **`ITenantEntity`** (strict mode, default): User can only access their tenant's data. Implement `Guid TenantId { get; set; }`. Service MUST filter by `_currentTenant.TenantId` with guard clause.
-  - **`IOptionalTenantEntity`** (optional mode): Cross-tenant data (shared lookup tables, public content). Implement `Guid? TenantId { get; set; }`. Service MAY accept null TenantId. EF global filter handles both shared (null) and tenant-scoped (TenantId == current) rows automatically.
-  - **`IScopedTenantEntity`** (scoped mode): Data scoped by Scope + TenantId combination. Validate both match current context in service layer.
-  - **No tenant interface** (none mode): Cross-tenant system data (no isolation). No TenantId property, no filtering needed.
+  - `ITenantEntity` (strict mode, default): User can only access their tenant's data. Implement `Guid TenantId { get; set; }`. Service must filter by `_currentTenant.TenantId` with guard clause.
+  - `IOptionalTenantEntity` (optional mode): Cross-tenant data (shared lookup tables, public content). Implement `Guid? TenantId { get; set; }`. Service may accept null TenantId. EF global filter handles both shared (null) and tenant-scoped (TenantId == current) rows automatically.
+  - `IScopedTenantEntity` (scoped mode): Data scoped by Scope + TenantId combination. Validate both match current context in service layer.
+  - No tenant interface (none mode): Cross-tenant system data (no isolation). No TenantId property, no filtering needed.
 - Also implement `IAuditableEntity` for CreatedBy/UpdatedBy tracking
 - See `references/smartstack-api.md` for exact BaseEntity API (Id, CreatedAt, UpdatedAt only)
 - No Code/IsDeleted/RowVersion in BaseEntity — add business properties yourself
@@ -61,8 +61,8 @@ Web            → Application (via API clients)
 - Value objects for composite values
 - **Person Extension Pattern:** If entity has `personRoleConfig` (from PRD or feature.json):
   - Load `references/person-extension-pattern.md` for full patterns
-  - **Mandatory** (`userLinkMode: 'mandatory'`): `Guid UserId` (non-nullable), ZERO person fields (`FirstName`, `LastName`, `Email`), unique index `(TenantId, UserId)`
-  - **Optional** (`userLinkMode: 'optional'`): `Guid? UserId` (nullable), own person fields + computed `Display*` properties, filtered unique index `(TenantId, UserId) WHERE UserId IS NOT NULL`
+  - Mandatory variant (`userLinkMode: 'mandatory'`): `Guid UserId` (non-nullable), ZERO person fields (`FirstName`, `LastName`, `Email`), unique index `(TenantId, UserId)`
+  - Optional variant (`userLinkMode: 'optional'`): `Guid? UserId` (nullable), own person fields + computed `Display*` properties, filtered unique index `(TenantId, UserId) WHERE UserId IS NOT NULL`
   - EF Config: `builder.Ignore()` on computed `Display*` properties (optional variant only)
 
 ---
@@ -70,11 +70,11 @@ Web            → Application (via API clients)
 ## Layer 0 — Infrastructure: EF Core (sequential)
 
 **Configs:** `Infrastructure/Persistence/Configurations/{App}/{Module}/`
-**Migrations:** `Infrastructure/Persistence/Migrations/` (NEVER subdirectories)
+**Migrations:** `Infrastructure/Persistence/Migrations/` (not in subdirectories)
 
 | Action | Tool |
 |--------|------|
-| Create config | MCP `scaffold_extension` (type: configuration) |
+| Create config | Manual: `IEntityTypeConfiguration<T>` per `smartstack-api.md` patterns |
 | Create migration | MCP `suggest_migration` → `dotnet ef migrations add` |
 | Validate | MCP `check_migrations` |
 
@@ -86,9 +86,9 @@ Web            → Application (via API clients)
 - Migration name ALWAYS from MCP `suggest_migration`
 - Migration flag: `-o Persistence/Migrations`
 
-**BLOCKING:** `dotnet build --no-restore` MUST pass after migration.
+Build requirement: `dotnet build --no-restore` must pass after migration.
 
-> **CRITICAL — Migration must cover ALL entities (POST-CHECK 36, 40):**
+> **Migration must cover ALL entities (POST-CHECK C38, C42):**
 > Create/update migration AFTER ALL entities and EF configs are registered in DbContext.
 > Verify with `dotnet ef migrations has-pending-model-changes` — must report NO pending changes.
 > If entities are added incrementally across modules, create a NEW migration for each batch.
@@ -100,7 +100,7 @@ Web            → Application (via API clients)
 **Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`
 
 > **Detailed templates:** See `references/core-seed-data.md` for complete C# code templates.
-> Navigation hierarchy: Application → Module → Section → Resource (ALL levels need seed data).
+> Navigation hierarchy: Application → Module → Section → Resource (all levels need seed data).
 
 | Action | Tool |
 |--------|------|
@@ -121,7 +121,7 @@ Web            → Application (via API clients)
 5. **NavigationResourceSeedData.cs** — Resource-level navigation (if resources defined)
 6. **Permissions.cs** — Static permission constants: `public static class {Module} { public const string Read = "..."; }`. Referenced by `[RequirePermission(Permissions.{Module}.Read)]`.
 7. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
-8. **RolesSeedData.cs** — Code-based role mapping: Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R. **NEVER use deterministic GUIDs for roles** — look up by Code at runtime.
+8. **RolesSeedData.cs** — Code-based role mapping: Admin=wildcard(*), Manager=CRU, Contributor=CR, Viewer=R. Do not use deterministic GUIDs for roles — look up by Code at runtime.
 
 **Infrastructure (created ONCE per application):**
 9. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
@@ -133,17 +133,13 @@ Web            → Application (via API clients)
 
 ### GUID Generation Rule
 
-```csharp
-// ALWAYS use Guid.NewGuid() for ALL seed data IDs
-// Avoids conflicts between projects/tenants/environments
-// Idempotence is handled by Code-based lookups at runtime
-public static readonly Guid ModuleId = Guid.NewGuid();
-```
+All seed data IDs MUST use `Guid.NewGuid()` — NEVER deterministic/sequential/fixed GUIDs.
+> See `references/core-seed-data.md` section 1b for the complete GUID rule and template.
 
-### Route Convention (CRITICAL — Full Paths Required)
+### Route Convention (Full Paths Required)
 
 > **Routes stored in DB drive the platform menu AND application-tracking.**
-> Short routes (e.g., `humanresources`) cause **400 Bad Request** on every page navigation.
+> Short routes (e.g., `humanresources`) cause errors on every page navigation.
 
 **Route format: `/{app-kebab}/{module-kebab}/{section-kebab}`**
 
@@ -178,21 +174,21 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 // → "/human-resources/employees/departments"
 ```
 
-**ROUTE SPECIAL CASES (list and detail sections):**
+**Route special cases (list and detail sections):**
 > `list` and `detail` 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: `/employees/list`, `/employees/detail/:id`
+> - Do not use: `/employees/list`, `/employees/detail/:id`
 > - Other sections (dashboard, approve, import) = module route + `/{section-kebab}` (normal)
 
-**FORBIDDEN:**
-- Deterministic/sequential/fixed GUIDs → ALWAYS use `Guid.NewGuid()`
-- Missing translations (must have fr, en, it, de)
-- Empty seed classes with no seeding logic
-- PascalCase in route URLs → always kebab-case
-- Missing NavigationApplicationSeedData → menu invisible
-- **Short routes without `/` prefix** → `"humanresources"` must be `"/human-resources"`
-- **Routes without parent hierarchy** → `"employees"` must be `"/human-resources/employees"`
+**Do not:**
+- Use deterministic/sequential/fixed GUIDs — always use `Guid.NewGuid()`
+- Skip translations (must have fr, en, it, de)
+- Create empty seed classes with no seeding logic
+- Use PascalCase in route URLs — always kebab-case
+- Omit NavigationApplicationSeedData — menu becomes invisible
+- Use short routes without `/` prefix — `"humanresources"` must be `"/human-resources"`
+- Create routes without parent hierarchy — `"employees"` must be `"/human-resources/employees"`
 
 ---
 
@@ -211,24 +207,24 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 
 **Rules:**
 - **Tenant injection depends on entity tenant mode** (see entity rules below):
-  - **strict mode (default):** Inject `ICurrentTenantService` + guard clause: `var tenantId = _currentTenant.TenantId ?? throw new TenantContextRequiredException();` (mandatory, returns 400)
-  - **optional mode:** Inject `ICurrentTenantService`, no guard: `var tenantId = _currentTenant.TenantId;` (nullable). EF global filter handles shared+tenant data.
-  - **scoped mode:** Inject `ICurrentTenantService`, validate Scope + TenantId consistency. Tenant scope requires TenantId.
-  - **none mode:** No `ICurrentTenantService` injection needed (cross-tenant data, no filtering)
-- **ALL services MUST inject `ICurrentUserService`** for audit trails
-- **ALL services MUST inject `ILogger<T>`** for production diagnostics
+  - strict mode (default): Inject `ICurrentTenantService` + guard clause: `var tenantId = _currentTenant.TenantId ?? throw new TenantContextRequiredException();` (returns 400 if missing)
+  - optional mode: Inject `ICurrentTenantService`, no guard: `var tenantId = _currentTenant.TenantId;` (nullable). EF global filter handles shared+tenant data.
+  - scoped mode: Inject `ICurrentTenantService`, validate Scope + TenantId consistency. Tenant scope requires TenantId.
+  - none mode: No `ICurrentTenantService` injection needed (cross-tenant data, no filtering)
+- All services must inject `ICurrentUserService` for audit trails
+- All services must inject `ILogger<T>` for production diagnostics
 - CQRS with MediatR
-- FluentValidation for all commands — **MUST register validators via DI:**
+- FluentValidation for all commands — must register validators via DI:
   `services.AddValidatorsFromAssemblyContaining<Create{Entity}DtoValidator>();`
-  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK 38)
-- **Date fields in DTOs MUST use `DateOnly`**, not `string` (POST-CHECK 39). See `smartstack-api.md` DTO Type Mapping.
+  Without DI registration, `[FromBody]` DTOs are never validated (POST-CHECK C40)
+- Date fields in DTOs must use `DateOnly`, not `string` (POST-CHECK C41). See `smartstack-api.md` DTO Type Mapping.
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
-- **FORBIDDEN:** `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
+- Do not use: `tenantId: Guid.Empty`, `TenantId!.Value`, queries without TenantId filter, `ICurrentUser` (does not exist — use `ICurrentUserService` + `ICurrentTenantService`), `string` type for date fields
 - **Person Extension services:** If entity has `personRoleConfig`:
-  - `Include(x => x.User)` on ALL queries (mandatory)
+  - `Include(x => x.User)` on all queries (required)
   - Inject `ICoreDbContext` for User existence checks
-  - Mandatory: search on `User.FirstName`, `User.LastName`, `User.Email`
+  - Required: search on `User.FirstName`, `User.LastName`, `User.Email`
   - Optional: search fallback `User.FirstName ?? x.FirstName`
   - CreateAsync: verify User exists + no duplicate `(TenantId, UserId)`
   - ResponseDto: include `Display*` fields resolved from User join
@@ -246,25 +242,25 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 | Validate | MCP `validate_security` |
 
 **Rules:**
-- `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
-- **NavRoute minimum 2 segments** (application.module):
+- `[RequirePermission(Permissions.{Module}.{Action})]` on every endpoint
+- NavRoute minimum 2 segments (application.module):
   - `[NavRoute("human-resources.employees")]` (CORRECT — module-level, 2 segments)
   - `[NavRoute("human-resources.employees.departments")]` (CORRECT — section-level, 3 segments)
   - `[NavRoute("administration.ai", Suffix = "prompts")]` (CORRECT — sub-resource with Suffix)
-- **NavRoute values MUST use kebab-case for ALL multi-word segments:**
+- NavRoute values must use kebab-case for all multi-word segments:
   - `[NavRoute("human-resources.employees")]` (CORRECT)
   - `[NavRoute("humanresources.employees")]` (WRONG — missing hyphens)
   - `[NavRoute("project-management.projects")]` (CORRECT)
   - `[NavRoute("projectmanagement.projects")]` (WRONG)
-- Permission paths MUST use kebab-case matching NavRoute codes (e.g., `human-resources.employees.read`)
-- FORBIDDEN: concatenated segments like `humanresources` — must be `human-resources`
-- POST-CHECK 32 detects non-kebab-case NavRoute values. POST-CHECK 33 detects non-kebab-case permissions
-- **FORBIDDEN:** `[Route("api/...")]` alongside `[NavRoute]` — causes 404s (POST-CHECK 41)
-- `[NavRoute]` is the ONLY route attribute needed — resolves routes from DB at startup
-- NEVER use `[Authorize]` without specific permission
+- Permission paths must use kebab-case matching NavRoute codes (e.g., `human-resources.employees.read`)
+- Do not use concatenated segments like `humanresources` — must be `human-resources`
+- POST-CHECK C34 detects non-kebab-case NavRoute values. POST-CHECK C35 detects non-kebab-case permissions
+- Do not combine `[Route("api/...")]` with `[NavRoute]` — causes 404s (POST-CHECK C43)
+- `[NavRoute]` is the only route attribute needed — resolves routes from DB at startup
+- Do not use `[Authorize]` without specific permission
 - Swagger XML documentation
 - Return DTOs, never domain entities
-- **Person Extension DTOs:** ResponseDto MUST include `Display*` fields (`DisplayFirstName`, `DisplayLastName`, `DisplayEmail`) resolved from User join. Mandatory CreateDto: `Guid UserId` only. Optional CreateDto: `Guid? UserId` + person fields.
+- **Person Extension DTOs:** ResponseDto must include `Display*` fields (`DisplayFirstName`, `DisplayLastName`, `DisplayEmail`) resolved from User join. Required CreateDto: `Guid UserId` only. Optional CreateDto: `Guid? UserId` + person fields.
 
 ---
 
@@ -284,19 +280,9 @@ var sectionRoute = $"{moduleRoute}/{ToKebabCase(sectionCode)}";
 
 **Layout mapping:** Configured per application in the routing configuration.
 
-### Lazy Loading (MANDATORY)
+### Lazy Loading (Required)
 
-ALL page components MUST be lazy-loaded using `React.lazy()`:
-
-```tsx
-const EmployeesPage = lazy(() =>
-  import('@/pages/HumanResources/Employees/EmployeesPage')
-    .then(m => ({ default: m.EmployeesPage }))
-);
-
-// Route element — ALWAYS wrap with Suspense
-element: <Suspense fallback={<PageLoader />}><EmployeesPage /></Suspense>
-```
+> See `references/smartstack-frontend.md` section 1 for complete patterns (React.lazy + Suspense + named export wrapping).
 
 ### Page Structure Pattern
 
@@ -315,19 +301,9 @@ const [loading, setLoading] = useState(true);
 
 ### Components & CSS
 
-**Components:** DataTable, EntityCard, EntityLookup (NEVER raw HTML `<table>`)
-**CSS:** Variables ONLY — hardcoded Tailwind colors are **BLOCKING** in POST-CHECK 9:
-
-| Instead of | Use |
-|-----------|-----|
-| `bg-white` | `bg-[var(--bg-card)]` |
-| `bg-gray-50` | `bg-[var(--bg-primary)]` |
-| `text-gray-900` | `text-[var(--text-primary)]` |
-| `text-gray-500` | `text-[var(--text-secondary)]` |
-| `border-gray-200` | `border-[var(--border-color)]` |
-| `bg-blue-600` | `bg-[var(--color-accent-500)]` |
-| `hover:bg-blue-700` | `hover:bg-[var(--color-accent-600)]` |
-| `text-red-500` | `text-[var(--error-text)]` |
+**Components:** DataTable, EntityCard, EntityLookup (do not use raw HTML `<table>`)
+**CSS:** Variables only — hardcoded Tailwind colors cause failures in POST-CHECK C9.
+> See `references/smartstack-frontend.md` section 4 for the full CSS variable mapping table.
 
 **Loader:** `Loader2` from `lucide-react` for spinners, `PageLoader` for Suspense fallback
 
@@ -345,48 +321,25 @@ If the module defines `{sections}`, generate frontend routes for EACH section as
 
 Section pages live in `src/pages/{AppPascal}/{Module}/{Section}/`.
 
-### FK Fields in Forms (CRITICAL)
-
-Any entity property that is a FK Guid (e.g., `EmployeeId`, `DepartmentId`) MUST use the `EntityLookup` component — NEVER a `<select>` dropdown, NEVER a `<input type="text">`. Users cannot type GUIDs manually, and `<select>` fails at scale (no search, loads all options).
-
-```tsx
-// CORRECT — EntityLookup for FK field (ONLY acceptable pattern)
-<EntityLookup
-  apiEndpoint="/api/human-resources/employees"
-  value={formData.employeeId}
-  onChange={(id) => handleChange('employeeId', id)}
-  label={t('module:form.employee', 'Employee')}
-  mapOption={(item) => ({ id: item.id, label: item.name, sublabel: item.code })}
-  required
-/>
-
-// WRONG — plain text input for FK GUID
-<input type="text" value={formData.employeeId} placeholder="Enter employee ID" />
-
-// WRONG — <select> dropdown for FK field (even with API-loaded options)
-<select value={formData.departmentId} onChange={(e) => setFormData({...formData, departmentId: e.target.value})}>
-  <option value="">Select...</option>
-  {departments.map(d => <option key={d.id} value={d.id}>{d.name}</option>)}
-</select>
-```
-
-**Backend requirement:** Each target entity's GetAll endpoint MUST accept `?search=` parameter. See `smartstack-api.md` Service Pattern.
-
-See `references/smartstack-frontend.md` section 6 for the full `EntityLookup` component definition and usage patterns.
-
-**FORBIDDEN:**
-- `src/pages/{Module}/` (flat, missing App)
-- `import axios` → use `@/services/api/apiClient`
-- `<table>` → use DataTable
-- `<input type="text">` for FK Guid fields → use `EntityLookup`
-- `<select>` for FK Guid fields → use `EntityLookup` (even with API-loaded options)
-- Placeholder "Enter ID" or "Enter GUID" → use `EntityLookup`
-- Hardcoded Tailwind colors (`bg-white`, `text-gray-900`) → use CSS variables
-- Static page imports in route files → use `React.lazy()`
-- `<Suspense>` without `fallback` prop
-- Only fr/en → MUST have 4 languages
-- `t('key')` without namespace prefix → use `t('ns:key', 'fallback')`
-- Hardcoded user-facing strings in JSX → use `t()`
+### FK Fields in Forms
+
+FK Guid fields (e.g., `EmployeeId`) must use `EntityLookup` — do not use `<select>` or `<input>`.
+Backend: GetAll endpoint must accept `?search=` parameter.
+> See `references/smartstack-frontend.md` section 6 for the full EntityLookup component, code examples, and usage patterns.
+
+**Do not:**
+- Use `src/pages/{Module}/` structure (flat, missing App)
+- Import axios directly — use `@/services/api/apiClient`
+- Use raw `<table>` element — use DataTable
+- Use `<input type="text">` for FK Guid fields — use `EntityLookup`
+- Use `<select>` for FK Guid fields — use `EntityLookup` (even with API-loaded options)
+- Add placeholders like "Enter ID" or "Enter GUID" — use `EntityLookup`
+- Hardcode Tailwind colors (`bg-white`, `text-gray-900`) — use CSS variables
+- Import pages statically in route files — use `React.lazy()`
+- Create `<Suspense>` without `fallback` prop
+- Support only fr/en — must have 4 languages
+- Use `t('key')` without namespace prefix — use `t('ns:key', 'fallback')`
+- Hardcode user-facing strings in JSX — use `t()`
 
 ---
 
@@ -416,14 +369,14 @@ t('{module}:actions.create', 'Create entity') // ALWAYS with namespace prefix
 | Action | Tool |
 |--------|------|
 | Generate doc-data.ts + page wrapper | `/documentation` skill (type: user) |
-| Verify DocToggleButton in pages | POST-CHECK 24 |
+| Verify DocToggleButton in pages | POST-CHECK C26 |
 
 **Output files:**
 - `src/pages/docs/business/{app}/{module}/doc-data.ts` — data-driven documentation
 - `src/pages/docs/business/{app}/{module}/index.tsx` — page wrapper using `DocRenderer`
 - `src/i18n/locales/fr/docs-{app}-{module}.json` — French doc translations
 
-**DocToggleButton (MANDATORY):** Every list/detail page must include `DocToggleButton` in its header.
+**DocToggleButton (Required):** Every list/detail page must include `DocToggleButton` in its header.
 See `references/smartstack-frontend.md` section 7 for the component pattern.
 
 ---
@@ -438,7 +391,7 @@ See `references/smartstack-frontend.md` section 7 for the component pattern.
 
 **Rules:**
 - Business test data for development/demo environments
-- ALL DevData entities MUST include `TenantId`
+- All DevData entities must include `TenantId`
 - DevData depends on seed data (navigation, permissions) being in place
 - Optional — skip if no meaningful test data needed
 
@@ -504,27 +457,27 @@ For EACH file in the plan, specify HOW it will be created/modified:
 
 ---
 
-## Parallelization Strategy (Agent Teams)
+## Parallelization Strategy (Agent tool)
 
-> **Cross-layer parallelism is FORBIDDEN.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
-> Agent teams are used **within** a layer to parallelize multi-entity work.
+> **Do not parallelize across layers.** Layers execute sequentially: 0 → 1 → 2 → 3 → 4.
+> The Agent tool is used **within** a layer to parallelize multi-entity work.
 
 If NOT economy_mode AND a layer has multiple entities to process:
 
-**Create agent teams WITHIN the layer to parallelize multi-entity work.**
+**Launch parallel Agent subagents WITHIN the layer for multi-entity work.**
 
-- **Layer 2 (Backend):** If multiple entities, spawn entity-specific teammates (each handles service + controller for one entity)
-- **Layer 3 (Frontend):** If multiple entities, spawn entity-specific teammates (each handles pages + i18n for one entity)
+- **Layer 2 (Backend):** If multiple entities, launch one Snipper agent per entity (each handles service + controller for one entity)
+- **Layer 3 (Frontend):** If multiple entities, launch one Snipper agent per entity (each handles pages + i18n for one entity)
 
 | Condition | Action |
 |-----------|--------|
-| economy_mode = true | NO teams, all sequential |
-| Single entity | NO teams, agent principal handles all layers |
-| Multiple entities, Layer 2 | Teams: one teammate per entity (service + controller) |
-| Multiple entities, Layer 3 | Teams: one teammate per entity (pages + i18n) |
-| Analysis phase (step-01) | Teams: scan-backend + scan-frontend + scan-context |
+| economy_mode = true | NO parallel agents, all sequential |
+| Single entity | NO parallel agents, agent principal handles all layers |
+| Multiple entities, Layer 2 | Parallel: one Snipper agent per entity (service + controller) |
+| Multiple entities, Layer 3 | Parallel: one Snipper agent per entity (pages + i18n) |
+| Analysis phase (step-01) | Parallel: 2-3 Explore agents (backend + frontend + context) |
 
-See `references/agent-teams-protocol.md` for team creation, teammate spawning, task coordination, and shutdown.
+See `references/parallel-execution.md` for agent launch patterns, task coordination, and decision matrix.
 
 ---
 

package/templates/skills/apex/steps/step-00-init.md

@@ -206,7 +206,7 @@ These values are propagated to:
 
 ---
 
-## 5e. Scope Complexity Guard (BLOCKING)
+## 5e. Scope Complexity Guard
 
 > **Root cause (test-apex-007):** `/apex` was invoked with 3 applications and 7 entities.
 > The model's context window saturated, causing: incomplete migrations, lost conventions,
@@ -234,21 +234,32 @@ IF delegate_mode (-d flag):
   → SKIP guard (ralph-loop already handles scope per module)
 
 ELSE IF app_count > 1:
-  → BLOCKING: "Multiple applications detected ({app_count} apps, {entity_count} entities).
+  → Warning: "Multiple applications detected ({app_count} apps, {entity_count} entities).
      /apex handles 1 module at a time. For multi-module projects, use:
      - /ralph-loop (automated: reads PRD, generates all modules sequentially)
      - Multiple /apex calls (manual: one /apex per module)
 
-     To override this guard, split your request:
+     To proceed, split your request:
        /apex -e add HR employee management
        /apex -e add CRM client management
        /apex -e add Project management"
 
+ELSE IF entity_count > 6:
+  → BLOCKING: "Too many entities ({entity_count}) for a single /apex invocation.
+     Context window saturation causes: incomplete migrations, lost conventions,
+     missing pages, unregistered i18n, forgotten DI registrations.
+     Maximum: 6 entities without delegate mode (-d).
+
+     Solutions:
+       /ralph-loop (automated multi-module orchestration)
+       /apex -d {prd_path} (delegate mode, called per module by ralph-loop)
+       Split manually: /apex add {first 3-4 entities} → then /apex add {remaining}"
+  → STOP execution
+
 ELSE IF scope_score > 8:
   → WARNING: "Large scope detected ({entity_count} entities, {section_count} sections).
      /apex works best with ≤ 4 entities per invocation.
-     Consider splitting into smaller iterations.
-     Proceeding, but expect higher risk of omissions."
+     Consider splitting into smaller iterations."
 
   AskUserQuestion:
     header: "Scope"
@@ -294,7 +305,20 @@ needs_notification = {module_complexity} in ["crud-workflow","complex"] OR task
 
 ```
 IF resume_mode:
-  Read .claude/output/apex/ → find latest task → restore state from 00-context.md → SKIP to next step
+  Read .claude/output/apex/ → find latest task directory (by timestamp)
+
+  IF state.json exists:
+    → Read state.json for precise layer-level resume:
+      completed_layers, completed_entities, files_created, build_gates, commits
+    → Resume step-03 at NEXT uncompleted layer (skip completed layers entirely)
+    → Re-derive remaining state variables from existing files + git log
+
+  ELSE IF 00-context.md exists:
+    → Restore state from 00-context.md (step-00 output only)
+    → Re-derive post-step-00 state from git history + existing files
+
+  ELSE:
+    → Full re-derive from git history + existing files (slowest path)
 ```
 
 ---

package/templates/skills/apex/steps/step-01-analyze.md

@@ -14,7 +14,7 @@ next_step: steps/step-02-plan.md
 
 - **ALWAYS** read `references/smartstack-api.md` — BaseEntity API, entity/config/controller patterns
   > **CONTEXT NOTE:** This file stays in context and is reused by step-03. Do NOT re-read it there.
-- If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
+- If NOT `{economy_mode}`: read `references/parallel-execution.md`
 
 ---
 
@@ -58,15 +58,21 @@ IF delegate_mode:
   4. Read feature.json for wireframes/componentMapping if {feature_path} exists:
      → enriches frontend generation in step-03
 
-  5. Perform LIGHTWEIGHT code exploration (verification only):
-     - Glob("**/Domain/Entities/**/{module_code}/**/*.cs") → what already exists?
-     - Glob("**/Infrastructure/Persistence/Seeding/Data/**/*SeedData*.cs") → existing seed data?
-     - Glob("src/pages/**/{module_code}/**/*.tsx") → existing pages?
-     → Only to determine create vs modify vs skip (NOT deep analysis)
+  5. Perform LIGHTWEIGHT code exploration (verification only — ONLY entities from PRD tasks):
+     For each entity_name in entities[]:
+       - Glob("**/Domain/Entities/**/{entity_name}.cs") → exists? (create vs modify)
+       - Glob("**/Infrastructure/Persistence/Configurations/**/{entity_name}Configuration.cs") → exists?
+       - Glob("**/Application/Services/**/*{entity_name}*Service.cs") → exists?
+       - Glob("**/Api/Controllers/**/*{entity_name}*Controller.cs") → exists?
+     Module-level checks (once):
+       - Glob("**/Infrastructure/Persistence/Seeding/Data/{module_code}/**/*SeedData*.cs") → existing seed data?
+       - Glob("src/pages/**/{module_code}/**/*.tsx") → existing pages?
+     Do NOT scan the full codebase — only verify files relevant to PRD tasks.
+     Result: mark each PRD task as "create" (file missing) or "modify" (file exists).
 
   6. Gap Analysis: Mark all PRD tasks as "create" unless existing code found
 
-  SKIP: Full Agent Teams exploration (section 2), challenge question follow-up
+  SKIP: Full Agent tool parallel exploration (section 2), challenge question follow-up
   Jump to section 5 (Gap Analysis summary) → section 7 (Analysis Summary)
 ```
 
@@ -105,28 +111,26 @@ MCP:
 - mcp__smartstack__analyze_extension_points → React extension points
 ```
 
-### If NOT economy_mode: Agent Teams
+### If NOT economy_mode: Parallel Agent Exploration
 
-> **Protocol:** See `references/agent-teams-protocol.md`
+> **Protocol:** See `references/parallel-execution.md`
 
-```
-TeamCreate("apex-analyze", description: "Scan SmartStack project for existing code")
-
-Spawn 3 teammates (subagent_type: "Explore", model: "sonnet"):
+Launch 2-3 Explore agents in parallel (single message):
 
-1. scan-backend:
-   "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 backend for module {module_code}: entities, EF configs, services,
+   DTOs, validators, controllers in Domain/ + Infrastructure/ + Application/ + Api/')
 
-2. scan-frontend:
-   "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='Scan frontend for module {module_code}: pages, components, hooks,
+   i18n files, route definitions in src/pages/ + src/components/ + src/locales/')
 
-3. scan-context:
-   "Read context artifacts for module {module_code}: .ralph/prd-{module_code}.json,
-    docs/business/**/feature.json → extract sections, entities, rules, permissions, ACs"
+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')
 
-Wait for all 3 → aggregate results → shutdown → TeamDelete("apex-analyze")
+# All 3 launched in a single message → agent principal aggregates results
 ```
 
 ---

package/templates/skills/apex/steps/step-02-plan.md

@@ -61,26 +61,26 @@ IF delegate_mode:
 > - Skill/MCP assignment table (per file, per layer)
 > - Layer 0/1/2/3/4 file lists with tools (see "Planning Template" section)
 > - FK field guidance (EntityLookup + backend ?search= parameter)
-> - Parallelization strategy (Agent Teams within Layer 2/3 for multi-entity)
+> - Parallelization strategy (Agent tool within Layer 2/3 for multi-entity)
 > - Delegate mode fast path (PRD task mapping to layers)
 
 ```
 Layer 0: SEQUENTIAL (agent principal)
   → domain + infra + migration
-  → dotnet build --no-restore (BLOCKING)
+  → dotnet build --no-restore (must pass)
 
 Layer 1: SEQUENTIAL (agent principal)
   → seed data (navigation, permissions, roles)
-  → dotnet build (BLOCKING)
+  → dotnet build (must pass)
 
-Layer 2: PARALLEL WITHIN LAYER (Agent Teams if multi-entity)
+Layer 2: PARALLEL WITHIN LAYER (Agent tool if multi-entity)
   → services + controllers
-  → dotnet build (BLOCKING)
+  → dotnet build (must pass)
   → backend tests inline (scaffold + run + fix max 3)
 
-Layer 3: PARALLEL WITHIN LAYER (Agent Teams if multi-entity)
+Layer 3: PARALLEL WITHIN LAYER (Agent tool if multi-entity)
   → pages + i18n + documentation
-  → compliance gate (BLOCKING)
+  → compliance gate (must pass)
   → frontend tests inline (scaffold + run + fix max 3)
 
 Layer 4: OPTIONAL (agent principal)
@@ -105,7 +105,7 @@ Verify the plan respects dependencies:
 - Backend tests AFTER services + controllers (inline in Layer 2)
 - Frontend AFTER API controllers (API contract needed)
 - Frontend tests AFTER pages created (inline in Layer 3)
-- Build gate between EVERY layer (BLOCKING): Layer 0 → 1 → 2 → 3 → 4
+- Build gate between EVERY layer (must pass): Layer 0 → 1 → 2 → 3 → 4
 ```
 
 ---
@@ -155,7 +155,7 @@ Write to `{output_dir}/02-plan.md` with the complete plan.
 
 ---
 
-## 8. Create Task List (MANDATORY)
+## 8. Create Task List
 
 > **Visibility:** TaskCreate generates the grouped progress UI with checkboxes.
 > This makes APEX execution trackable and predictable for the user.
@@ -207,7 +207,7 @@ TaskCreate(subject: "APEX Progress",
 TaskCreate(subject: "Layer 0: Domain + Infrastructure",
   description: "Entities: {entity1} ({tenantMode}), {entity2} ({tenantMode}).
 Files: Domain/Entities/*.cs, Infrastructure/Persistence/Configs/*.cs, Migration.
-Tools: MCP scaffold_extension (type: entity, configuration). MCP suggest_migration.
+Tools: MCP scaffold_extension (type: entity). EF config: manual per smartstack-api.md. MCP suggest_migration.
 Gate: dotnet build --no-restore. ACs: {relevant ACs}.",
   activeForm: "Creating domain entities",
   metadata: { layer: 0, entities: [...], tools: ["scaffold_extension", "suggest_migration"], build_gate: "pending", files_created: [] })
@@ -271,7 +271,7 @@ Gate: dotnet build.",
 
 # Post-execution
 TaskCreate(subject: "eXamine: Validation + POST-CHECKs",
-  description: "MCP validate_conventions, build, 50 POST-CHECKs, acceptance criteria.
+  description: "MCP validate_conventions, build, POST-CHECKs (see post-checks.md), acceptance criteria.
 Tools: MCP validate_conventions, validate_security, validate_frontend_routes.",
   activeForm: "Validating conventions",
   metadata: { tools: ["validate_conventions", "validate_security", "validate_frontend_routes"] })
@@ -279,7 +279,7 @@ Tools: MCP validate_conventions, validate_security, validate_frontend_routes.",
 
 ### Economy Mode
 
-IF economy_mode: Create the SAME tasks (for visibility), but no Agent Teams — agent principal executes sequentially.
+IF economy_mode: Create the SAME tasks (for visibility), but no parallel agents — agent principal executes sequentially.
 
 ### Delegate Mode