@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/apex/references/domain-events-pattern.md

@@ -1,45 +0,0 @@
-# Domain Events (lightweight pub-sub)
-
-> Extracted from `smartstack-api.md` for clarity. Loaded only when generating code that needs events.
-
-SmartStack uses a minimal domain event pattern in `SmartStack.Domain.Support.Events`.
-
-## Interface + base class
-
-```csharp
-public interface IDomainEvent
-{
-    DateTime OccurredAt { get; }
-}
-
-public abstract class DomainEvent : IDomainEvent
-{
-    public DateTime OccurredAt { get; } = DateTime.UtcNow;
-}
-```
-
-## When to raise an event vs use a hook
-
-| Use case | Mechanism |
-|---|---|
-| Cross-cutting side effect tied to entity lifecycle (Create/Update/Delete) | Entity hook (`IAfterCreate<T>`, …) — see [entity-hooks-pattern.md](entity-hooks-pattern.md) |
-| Business event independent of CRUD (e.g. `WorkflowExecuted`, `LicenseRenewed`) | Domain event |
-| Need to handle multiple unrelated reactions to the same business fact | Domain event |
-| Reaction must be transactional with the entity write | Neither — code it inline in the handler |
-
-## Convention
-
-- One event class per business fact, named `{PastTense}Event` (e.g. `EmployeeOnboardedEvent`, `WorkflowExecutedEvent`).
-- Place events in `Domain/{Aggregate}/Events/`.
-- Inherit `DomainEvent` (gets `OccurredAt` for free).
-- Dispatched by handlers (no automatic publication from `SaveChangesAsync` in v3.46) — keep dispatch explicit so the handler controls timing.
-
-## Example dispatch (handler)
-
-```csharp
-await _mediator.Publish(new EmployeeOnboardedEvent(employee.Id, employee.TenantId), ct);
-```
-
-## Source
-
-- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Support/Events/IDomainEvent.cs`

package/templates/skills/apex/references/entity-hooks-pattern.md

@@ -1,68 +0,0 @@
-# Entity Lifecycle Hooks (v3.46+)
-
-> Extracted from `smartstack-api.md` for clarity. Loaded only when generating code that needs hooks.
-
-SmartStack exposes 6 typed hook interfaces + 1 executor in `SmartStack.Application.Common.Interfaces.Hooks`.
-
-## Interfaces
-
-```csharp
-public interface IBeforeCreate<in T>  where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
-public interface IAfterCreate<in T>   where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
-public interface IBeforeUpdate<in T>  where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
-public interface IAfterUpdate<in T>   where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
-public interface IBeforeDelete<in T>  where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
-public interface IAfterDelete<in T>   where T : class { int Order => 0; Task ExecuteAsync(T entity, CancellationToken ct = default); }
-
-public interface IHookExecutor
-{
-    Task ExecuteBeforeCreateAsync<T>(T entity, CancellationToken ct = default) where T : class;
-    Task ExecuteAfterCreateAsync<T>(T entity,  CancellationToken ct = default) where T : class;
-    Task ExecuteBeforeUpdateAsync<T>(T entity, CancellationToken ct = default) where T : class;
-    Task ExecuteAfterUpdateAsync<T>(T entity,  CancellationToken ct = default) where T : class;
-    Task ExecuteBeforeDeleteAsync<T>(T entity, CancellationToken ct = default) where T : class;
-    Task ExecuteAfterDeleteAsync<T>(T entity,  CancellationToken ct = default) where T : class;
-}
-```
-
-## Semantics
-
-- **`IBefore*`** runs **before** the entity is persisted. May transform the entity. May `throw` to cancel the operation (the calling handler does NOT call `SaveChangesAsync`).
-- **`IAfter*`** runs **after** `SaveChangesAsync` completes. Side-effects only (notifications, indexing, caches, integrations). Throwing here does NOT roll back the DB write — wrap risky calls.
-- **`Order`** (default 0) — lower runs earlier. Use `Order = -100` to pre-empt validation, `Order = 100` to run last.
-
-## DI registration (Infrastructure DependencyInjection.cs)
-
-```csharp
-services.AddScoped<IHookExecutor, HookExecutor>();
-services.AddScoped<IBeforeCreate<Employee>,  EmployeeValidationHook>();
-services.AddScoped<IAfterCreate<Employee>,   EmployeeWelcomeNotificationHook>();
-services.AddScoped<IAfterUpdate<Employee>,   EmployeeUpdatedAuditHook>();
-```
-
-## Usage in service / handler
-
-```csharp
-public async Task<EmployeeDto> CreateAsync(CreateEmployeeDto dto, CancellationToken ct)
-{
-    var entity = Employee.Create(dto.TenantId, dto.Code, dto.Name);
-    await _hooks.ExecuteBeforeCreateAsync(entity, ct);   // may throw → cancel
-    _db.Employees.Add(entity);
-    await _db.SaveChangesAsync(ct);
-    await _hooks.ExecuteAfterCreateAsync(entity, ct);    // post-commit side effects
-    return _mapper.Map<EmployeeDto>(entity);
-}
-```
-
-## DO / DON'T
-
-- DO use hooks for cross-cutting concerns (notifications, audit beyond `IAuditableEntity`, cache invalidation)
-- DO keep hooks small and idempotent — `IAfter*` runs without DB transaction
-- DON'T use hooks for business validation that varies per command — keep that in the handler / FluentValidation
-- DON'T register the same hook twice — DI picks all of them, and they all execute
-
-## Sources
-
-- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Interfaces/Hooks/IBeforeCreate.cs`
-- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Interfaces/Hooks/IAfterCreate.cs`
-- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Interfaces/Hooks/IHookExecutor.cs` (and 4 more)

package/templates/skills/apex/references/error-classification.md

@@ -1,168 +0,0 @@
-# Error Classification Reference
-
-> **Loaded by:** apex step-03-execute (build failure) and step-04-examine (validation)
-> **Purpose:** Classify build and runtime errors to apply the correct fix strategy.
-> **Key insight:** Not all errors are code errors. Package/config errors require different fixes than code errors.
-> **Moved from:** `business-analyse-develop/references/error-classification.md` (delegation refactoring)
-
----
-
-## Error Categories
-
-### Category A: Missing NuGet Package (FIX = `dotnet add package`)
-
-> **These errors CANNOT be fixed by editing source code. Do NOT waste iterations trying.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `FileNotFoundException: Could not load file or assembly '{Name}, Version={V}'` | `Could not load file or assembly 'Microsoft.Extensions.Http.Resilience, Version=10.2.0.0'` | `dotnet add package {Name} --version {V.Major}.{V.Minor}.{V.Patch}` |
-| `error CS0246: The type or namespace name '{Type}' could not be found` (after restore) | `The type or namespace name 'Polly' could not be found` | `dotnet add package {PackageName}` |
-| `error NU1101: Unable to find package {Name}` | Package source misconfigured | Check `nuget.config` sources |
-
-**Detection heuristic:** If `dotnet build` fails with CS0246 and the missing type is NOT in any project file (grep across `src/`), it is a missing package, not a missing `using` statement.
-
-**Fix procedure:**
-1. Extract package name from error message
-2. Run `dotnet add {TargetProject} package {PackageName}`
-3. Run `dotnet restore`
-4. Rebuild -- if still failing, the version may need to be pinned
-
----
-
-### Category B: Version Mismatch (FIX = update package version)
-
-> **These errors CANNOT be fixed by editing source code.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `TypeLoadException: Could not load type '{Type}' from assembly '{Asm}'` | Type exists in different version | `dotnet add package {Asm} --version {CorrectVersion}` |
-| `MissingMethodException: Method not found: '{Method}'` | Method signature changed between versions | Update to version that has the method |
-| `NU1605: Detected package downgrade` | Version conflict in dependency tree | Align all references to same version |
-| `FileLoadException: Could not load file or assembly '{Name}'. The located assembly's manifest definition does not match the assembly reference.` | Wrong version loaded | Pin correct version in .csproj |
-
-**Fix procedure:**
-1. Identify the assembly/package name
-2. Run `dotnet list package --include-transitive` to see actual resolved version
-3. If conflict: add explicit `<PackageReference>` with correct version
-4. Rebuild
-
----
-
-### Category C: Missing DI Registration (FIX = edit DI configuration)
-
-> **These errors require editing `DependencyInjection.cs` or `Program.cs`, NOT the service/interface code.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `InvalidOperationException: Unable to resolve service for type '{Interface}'` | Missing `services.AddScoped<IFoo, Foo>()` | Add DI registration |
-| `InvalidOperationException: No service for type '{Type}' has been registered` | Same as above | Same |
-| `InvalidOperationException: Unable to resolve service for type '{Type}' while attempting to activate '{Consumer}'` | Consumer's dependency not registered | Register the missing dependency |
-
-**Fix procedure:**
-1. Extract the interface/type name from error
-2. Find the implementation class (grep for `class.*: {Interface}`)
-3. Add `services.AddScoped<{Interface}, {Implementation}>()` to appropriate DI file
-4. Rebuild
-
----
-
-### Category D: Database/Migration (FIX = run migration commands)
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `SqlException: Invalid object name '{TableName}'` | Table does not exist | `dotnet ef database update` |
-| `SqlException: Invalid column name '{Column}'` | Column not in schema | Create and apply migration |
-| `RelationalEventId.PendingModelChangesWarning` | Model changed, no migration | `dotnet ef migrations add {Name}` |
-
----
-
-### Category E: Configuration (FIX = edit appsettings.json)
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `InvalidOperationException: The ConnectionString property has not been initialized` | Missing connection string | Add to `appsettings.json` |
-| `ArgumentNullException: Value cannot be null. (Parameter 'connectionString')` | Same | Same |
-| `OptionsValidationException: Validation failed for '{Section}'` | Missing required config section | Add section to `appsettings.json` |
-
----
-
-### Category F: Code Error (FIX = edit source code)
-
-> **Only this category should trigger code editing in business-analyse-develop iterations.**
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `error CS0246` + type IS in a project file | Missing `using` statement | Add `using {Namespace};` |
-| `error CS1061` | Method does not exist on type | Fix method call or add method |
-| `error CS0103` | Name does not exist in current context | Fix variable/method reference |
-| `error CS0029` | Cannot implicitly convert type | Fix type mismatch |
-| Test assertion failures | `Assert.Equal` fails | Fix source code (not tests) |
-
----
-
-### Category G: PRD Quality Error (FIX = fix PRD or re-run handoff)
-
-> **These errors are NOT caused by code generation — they originate from invalid PRD data.**
-> The handoff generated file paths with illegal characters (spaces, apostrophes, accents in entity names).
-> Code generation faithfully reproduced the invalid paths → build failure.
-
-| Error Pattern | Example | Fix |
-|--------------|---------|-----|
-| `error CS1001: Identifier expected` with file name containing spaces | `Type d'absence.cs` → CS1001 | Re-run `/business-analyse-handoff` with entity canonicalization |
-| `error CS1513/CS1514` with file name containing apostrophes | `Congé.cs` → accent in identifier | Fix entity name in BA or re-run handoff |
-| Path contains non-ASCII characters in `.cs` file names | `Département.cs` | Canonicalize: strip diacritics, PascalCase |
-
-**Detection heuristic:** If the error file path contains spaces, apostrophes, or accented characters, it is a PRD quality error, not a code error. Do NOT attempt to fix the generated code — fix the PRD source.
-
-**Fix procedure:**
-1. Identify the invalid entity name from the error file path
-2. Report to user: "PRD quality error — entity name '{name}' is not a valid C# identifier"
-3. Either: manually canonicalize in the PRD file, or re-run `/business-analyse-handoff` (which now includes canonicalization)
-4. Re-run `/apex -d` with the corrected PRD
-
----
-
-## Decision Tree
-
-When a build or runtime error occurs, follow this tree:
-
-```
-BUILD/RUNTIME ERROR
-  |
-  +-- Contains "Could not load file or assembly" ?
-  |     YES -> Category A or B (NEVER edit source code)
-  |     Extract package name -> dotnet add package -> rebuild
-  |
-  +-- Contains "Unable to resolve service" ?
-  |     YES -> Category C (edit DI config ONLY)
-  |     Find implementation -> add registration -> rebuild
-  |
-  +-- Contains "SqlException" or "Invalid object name" ?
-  |     YES -> Category D (run migrations)
-  |     dotnet ef migrations add / database update
-  |
-  +-- Contains "ConnectionString" or "OptionsValidation" ?
-  |     YES -> Category E (edit config files)
-  |
-  +-- error CS#### (C# compiler error) ?
-  |     YES -> Does the error file path contain spaces, apostrophes, or accents?
-  |           YES -> Category G (PRD quality error — fix handoff, not code)
-  |           NO  -> Is the missing type in ANY project file?
-  |                 NO  -> Category A (missing package)
-  |                 YES -> Category F (fix source code)
-  |
-  +-- Test failure (Assert/Expected) ?
-        YES -> Category F (fix source code, NOT tests)
-```
-
----
-
-## Ralph-Loop Integration Rules
-
-1. **Before ANY code fix attempt:** Classify the error using the decision tree above
-2. **Categories A, B:** Run package commands IMMEDIATELY. Do NOT count as a "fix iteration"
-3. **Category C:** Edit DI file only. One targeted fix, rebuild, verify
-4. **Category D:** Run migration commands. Do NOT edit code
-5. **Category E:** Edit config file only
-6. **Category F:** Normal business-analyse-develop code fix iteration
-7. **If 2+ consecutive iterations fail on same error after code fixes -> re-classify** (likely wrong category)

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

@@ -1,91 +0,0 @@
-# Frontend: Route Registration with PageRegistry + DynamicRouter
-
-> **v3.7+** — Replaces the legacy Pattern A (mergeRoutes) and Pattern B (JSX routes) patterns.
-
----
-
-## How It Works
-
-1. **Backend seed data** defines navigation entries with `ComponentKey` values
-   (e.g., `administration.users`, `support.tickets.list`)
-2. **`componentRegistry.generated.ts`** registers all page components into `PageRegistry`
-   via `PageRegistry.register('key', lazy(() => import(...)))`
-3. **DynamicRouter** fetches the menu API, matches each entry's `componentKey` to a
-   `PageRegistry` entry, and generates `<Route>` elements at runtime
-4. **Implicit routes** (detail, create, edit) are resolved by convention:
-   - `*.detail` → `.../:id`
-   - `*.create` → `.../create`
-   - `*.edit` → `.../:id/edit`
-
-No manual App.tsx wiring is needed.
-
----
-
-## For SmartStack Core Pages
-
-`componentRegistry.generated.ts` is auto-generated by MCP `scaffold_routes`:
-
-```tsx
-// Auto-generated — DO NOT EDIT
-import { lazy } from 'react';
-import { PageRegistry } from '@/extensions/PageRegistry';
-
-PageRegistry.register('administration.users', lazy(() =>
-  import('@/pages/platform/administration/users/UsersPage').then(m => ({ default: m.UsersPage }))
-));
-PageRegistry.register('administration.users.detail', lazy(() =>
-  import('@/pages/platform/administration/users/UserDetailPage').then(m => ({ default: m.UserDetailPage }))
-));
-// ... ~100 registrations
-```
-
-Imported once in `main.tsx`:
-```tsx
-import './extensions/componentRegistry.generated';
-```
-
----
-
-## For Client SDK Pages
-
-> **CRITICAL:** Keys use DOT notation (`rh.employes.list`), NEVER hyphens (`rh-employes-list`).
-> Dots are hierarchy separators matching `NavigationService.ComponentKey` computation at runtime.
-
-Clients register their own pages directly:
-
-```tsx
-import { PageRegistry } from '@atlashub/smartstack';
-import { lazy } from 'react';
-
-PageRegistry.register('rh.time.dashboard', lazy(() => import('./pages/TimeDashboard')));
-PageRegistry.register('rh.time.list', lazy(() => import('./pages/TimeList')));
-PageRegistry.register('rh.time.detail', lazy(() => import('./pages/TimeDetail')));
-```
-
-Navigation entries are created in DB (via admin UI or seed data).
-DynamicRouter does the junction automatically.
-
----
-
-## Verification
-
-```
-Tool: mcp__smartstack__validate_frontend_routes
-Args:
-  scope: "routes"
-```
-
-Checks:
-- `componentRegistry.generated.ts` exists
-- Each backend NavRoute has a `PageRegistry.register()` call
-- `main.tsx` imports the generated file
-- Implicit route keys (*.detail, *.create, *.edit) exist for CRUD pages
-
----
-
-## Legacy Patterns (DEPRECATED)
-
-> The Pattern A (`mergeRoutes(clientRoutes, applicationRoutes)`) and Pattern B
-> (JSX `<Route>` in App.tsx) patterns are deprecated since v3.7.
-> They still work but are not recommended for new development.
-> See git history for the legacy documentation.

package/templates/skills/apex/references/licensing-enforcement.md

@@ -1,52 +0,0 @@
-# Licensing — `[RequiresLicense]` attribute (v3.46+)
-
-> Extracted from `smartstack-api.md` for clarity. Loaded only when generating code that needs license gating.
-
-Mark a Command or Query as requiring a valid license / feature / write capability.
-
-## Attribute definition
-
-```csharp
-namespace SmartStack.Application.Common.Licensing;
-
-[AttributeUsage(AttributeTargets.Class, AllowMultiple = true, Inherited = true)]
-public class RequiresLicenseAttribute : Attribute
-{
-    public string? Feature { get; }
-    public bool IsWriteOperation { get; }
-
-    public RequiresLicenseAttribute() { /* just needs valid license */ }
-    public RequiresLicenseAttribute(bool isWriteOperation) { /* blocked in read-only mode */ }
-    public RequiresLicenseAttribute(string feature, bool isWriteOperation = false) { /* both */ }
-}
-```
-
-## Usage on a Command
-
-```csharp
-[RequiresLicense(LicenseFeatures.AdvancedWorkflows, isWriteOperation: true)]
-public record CreateAdvancedWorkflowCommand(string Name, ...) : IRequest<WorkflowDto>;
-```
-
-## Behavior at runtime
-
-- A MediatR pipeline behavior reads the attribute on the request type.
-- `Feature` → checked against the cached `License.Features` (resolved per-tenant from JWT).
-- `IsWriteOperation = true` → blocked when the system is in read-only mode (license expired but in grace period, license downgraded, …).
-- Failures throw a typed exception → 403 Forbidden with a stable error code (`LICENSE_FEATURE_DISABLED`, `LICENSE_READ_ONLY`).
-
-## Where to read feature constants
-
-`SmartStack.Domain.Licensing.LicenseFeatures` (string consts — `Entra`, `AdvancedWorkflows`, `AiAdvanced`, …).
-
-## DO / DON'T
-
-- DO put `[RequiresLicense]` on the request (Command/Query), not on the handler
-- DO use `LicenseFeatures.X` constants — never magic strings
-- DON'T add `[RequiresLicense]` on `[AllowAnonymous]` endpoints — they bypass the pipeline
-- DON'T duplicate the check in the handler body — the pipeline already enforced it
-
-## Sources
-
-- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Application/Common/Licensing/RequiresLicenseAttribute.cs`
-- `D:/01 - projets/SmartStack.app/features/IA-Workflow/src/SmartStack.Domain/Licensing/LicenseFeatures.cs`

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

@@ -1,187 +0,0 @@
-# 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 BOUNDARY: Snipper agents do NOT have access to MCP tools.
-  # Services, DTOs, controllers MUST be scaffolded by the principal agent via MCP.
-  # Snipper agents handle ONLY: business logic, validators, code-gen wiring.
-
-  # PHASE A — Sequential: MCP scaffolding (principal agent)
-  For each entity:
-    mcp__smartstack__scaffold_extension(type: "dto", name: "{Entity}", options: { navRoute: "..." })
-    mcp__smartstack__scaffold_extension(type: "controller", name: "{Entity}", options: { navRoute: "..." })
-    Verify NavRoute on generated controller (bash)
-
-  # PHASE B — Parallel: post-scaffold adjustments (Snipper agents)
-  Agent(subagent_type='Snipper', model='opus',
-    prompt='Adjust Layer 2 backend for {Entity1}: service logic, validators, code-gen wiring.
-            DO NOT regenerate controller/DTO — already created by MCP.')
-  Agent(subagent_type='Snipper', model='opus',
-    prompt='Adjust Layer 2 backend for {Entity2}: service logic, validators, code-gen wiring.
-            DO NOT regenerate controller/DTO — already created by MCP.')
-  # Launched in parallel in a single message
-
-  # PHASE C — Sequential: DI registration (principal agent)
-  # Register all services + validators in DependencyInjection.cs (single pass, no conflicts)
-
-Layer 3 (Frontend) — if multiple entities:
-  # ⛔ AGENT BOUNDARY: Snipper agents do NOT have access to Skill().
-  # Pages (.tsx) MUST be generated by the principal agent via Skill("ui-components").
-  # Snipper agents handle ONLY: API clients, routes, wiring, i18n — NOT pages.
-
-  # PHASE A — Parallel: infrastructure (Snipper agents)
-  Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 3 INFRASTRUCTURE for {Entity1}: API client, routes, wiring, i18n.
-            DO NOT generate any .tsx page files — pages are handled by the principal agent.')
-  Agent(subagent_type='Snipper', model='opus',
-    prompt='Execute Layer 3 INFRASTRUCTURE for {Entity2}: API client, routes, wiring, i18n.
-            DO NOT generate any .tsx page files — pages are handled by the principal agent.')
-  # Launched in parallel in a single message
-
-  # PHASE B — Sequential: pages (principal agent only)
-  # After all Snipper agents complete, principal generates pages via Skill("ui-components").
-  # See step-03-execute.md Layer 3 HARD RULE for full protocol.
-```
-
-Each agent has an **isolated scope**: handles one entity end-to-end within the layer.
-**Exception:** Layer 3 pages are NOT delegated — see step-03 HARD RULE.
-
----
-
-## 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 Phase A: principal scaffolds ALL entities via MCP (dto + controller per entity)
-5b. Layer 2 Phase B: launch Snipper agents for post-scaffold adjustments (parallel)
-5c. Layer 2 Phase C: principal registers all DI in DependencyInjection.cs (single pass)
-6. Build gate: dotnet build → MUST PASS
-7. Backend tests inline (scaffold + run + fix max 3)
-8. Layer 3 Phase A: launch Snipper agents for infra (api-client, routes, i18n) — NOT pages
-9. Layer 3 Phase B: principal agent generates ALL pages via Skill("ui-components") — sequential
-10. Compliance gate: 6 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 | Phase A: principal scaffolds via MCP (sequential). Phase B: Snipper for business logic (parallel). Phase C: principal DI registration (sequential) |
-| Multiple entities, Layer 3 | Parallel: Snipper agents for infra (api-client, routes, i18n) — pages by principal via Skill("ui-components") |
-| Layer 0, Layer 1, Layer 4 | NO parallel agents (sequential by nature) |
-| Analysis phase (step-01) | Parallel: 2-3 Explore agents (backend + frontend + context) |