@atlashub/smartstack-cli 3.39.0 → 3.40.0

package/templates/skills/apex/references/agent-teams-protocol.md

@@ -1,164 +1,164 @@
-# Agent Teams Protocol — APEX
-
-> **Loaded by:** step-01 (analysis scan) and step-03 (parallel execution)
-> **Condition:** NOT economy_mode
-> **Purpose:** Reusable protocol for TeamCreate, coordination, and shutdown.
-
----
-
-## Team Creation (T08)
-
-```yaml
-TeamCreate:
-  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-exec"
-  description: "{phase purpose}"      # e.g., "Scan SmartStack project for existing code"
-```
-
-Always provide both `team_name` and `description`.
-
----
-
-## Teammate Spawning (T12)
-
-```yaml
-Task:
-  subagent_type: "Explore" | "general-purpose"  # See assignment table below
-  team_name: "apex-{phase}"          # Must match TeamCreate
-  name: "{teammate-name}"            # e.g., "scan-backend", "exec-frontend"
-  model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
-  mode: "bypassPermissions"
-  prompt: "{detailed task prompt}"
-```
-
-### Model & Agent Assignment (T02/T03/T06)
-
-| 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 | general-purpose | Opus | Full tools via skills/MCP |
-| Fix/resolve | general-purpose | Opus | Requires reasoning + editing |
-
----
-
-## Task List Coordination (T10)
-
-Team lead manages the task list:
-
-```
-1. TaskCreate: create task for each work item, assign owner
-2. Teammate: TaskUpdate(status: "in_progress") before starting
-3. Teammate: TaskUpdate(status: "completed") after finishing
-4. Lead: TaskList to monitor progress
-```
-
----
-
-## Communication (T09)
-
-**Default:** Direct messages (DM) between specific agents.
-
-```yaml
-SendMessage:
-  type: "message"                    # DM, not broadcast
-  recipient: "{teammate-name}"       # By name, not UUID
-  content: "{message}"
-  summary: "{5-10 word preview}"
-```
-
-**Broadcast:** ONLY for emergency (all-stop, critical blocker).
-
-```yaml
-SendMessage:
-  type: "broadcast"                  # Expensive: N teammates = N deliveries
-  content: "{urgent message}"
-  summary: "{critical issue summary}"
-```
-
----
-
-## Team Decomposition (C01)
-
-### Step-01 Analyze: Split by scan scope
-
-```
-scan-backend  : Domain/ + Infrastructure/ + Application/ + Api/
-scan-frontend : src/pages/ + src/components/ + src/locales/
-scan-context  : .ralph/ + docs/business/
-```
-
-### Step-03 Execute: Split by execution layer
-
-```
-exec-backend  : Application services + API controllers + Seed data
-exec-frontend : Pages + Components + Routes + I18n
-```
-
-Each teammate has an **isolated scope** (C02): backend never touches frontend.
-
----
-
-## Coordination (C03)
-
-### Step-01: Lead aggregates scan results
-
-```
-1. Spawn 3 scan teammates
-2. Each reports findings via DM to lead
-3. Lead merges into unified analysis
-```
-
-### Step-03: Lead verifies between layers
-
-```
-1. Layer 0: lead executes (domain + infra + migration)
-2. Build gate: dotnet build --no-restore → MUST PASS
-3. Layer 1: spawn exec-backend + exec-frontend
-4. Wait for both to complete
-5. Build gate: dotnet build + npm typecheck → MUST PASS
-6. Layer 2: lead executes final validation
-```
-
----
-
-## Idle Handling (T13)
-
-Teammates go idle after every turn — this is **normal**.
-- Idle does NOT mean done or unavailable
-- Sending a message to an idle teammate wakes them up
-- Do NOT treat idle as an error
-
----
-
-## Graceful Shutdown (T11)
-
-After phase completes:
-
-```yaml
-# For each teammate:
-SendMessage:
-  type: "shutdown_request"
-  recipient: "{teammate-name}"
-  content: "Phase complete, shutting down"
-
-# Teammate responds:
-SendMessage:
-  type: "shutdown_response"
-  request_id: "{from_request}"
-  approve: true
-
-# After all confirmations:
-TeamDelete
-```
-
----
-
-## Decision Matrix
-
-| Condition | Action |
-|-----------|--------|
-| economy_mode = true | NO teams, all sequential |
-| Only backend work | NO teams, agent principal |
-| Only frontend work | NO teams, agent principal |
-| Backend + Frontend | Teams: exec-backend + exec-frontend |
-| Analysis phase | Teams: scan-backend + scan-frontend + scan-context |
+# Agent Teams Protocol — APEX
+
+> **Loaded by:** step-01 (analysis scan) and step-03 (parallel execution)
+> **Condition:** NOT economy_mode
+> **Purpose:** Reusable protocol for TeamCreate, coordination, and shutdown.
+
+---
+
+## Team Creation (T08)
+
+```yaml
+TeamCreate:
+  team_name: "apex-{phase}"          # e.g., "apex-analyze", "apex-exec"
+  description: "{phase purpose}"      # e.g., "Scan SmartStack project for existing code"
+```
+
+Always provide both `team_name` and `description`.
+
+---
+
+## Teammate Spawning (T12)
+
+```yaml
+Task:
+  subagent_type: "Explore" | "general-purpose"  # See assignment table below
+  team_name: "apex-{phase}"          # Must match TeamCreate
+  name: "{teammate-name}"            # e.g., "scan-backend", "exec-frontend"
+  model: "sonnet" | "opus"           # sonnet for scan, opus for dev (T02/T06)
+  mode: "bypassPermissions"
+  prompt: "{detailed task prompt}"
+```
+
+### Model & Agent Assignment (T02/T03/T06)
+
+| 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 | general-purpose | Opus | Full tools via skills/MCP |
+| Fix/resolve | general-purpose | Opus | Requires reasoning + editing |
+
+---
+
+## Task List Coordination (T10)
+
+Team lead manages the task list:
+
+```
+1. TaskCreate: create task for each work item, assign owner
+2. Teammate: TaskUpdate(status: "in_progress") before starting
+3. Teammate: TaskUpdate(status: "completed") after finishing
+4. Lead: TaskList to monitor progress
+```
+
+---
+
+## Communication (T09)
+
+**Default:** Direct messages (DM) between specific agents.
+
+```yaml
+SendMessage:
+  type: "message"                    # DM, not broadcast
+  recipient: "{teammate-name}"       # By name, not UUID
+  content: "{message}"
+  summary: "{5-10 word preview}"
+```
+
+**Broadcast:** ONLY for emergency (all-stop, critical blocker).
+
+```yaml
+SendMessage:
+  type: "broadcast"                  # Expensive: N teammates = N deliveries
+  content: "{urgent message}"
+  summary: "{critical issue summary}"
+```
+
+---
+
+## Team Decomposition (C01)
+
+### Step-01 Analyze: Split by scan scope
+
+```
+scan-backend  : Domain/ + Infrastructure/ + Application/ + Api/
+scan-frontend : src/pages/ + src/components/ + src/locales/
+scan-context  : .ralph/ + docs/business/
+```
+
+### Step-03 Execute: Split by execution layer
+
+```
+exec-backend  : Application services + API controllers + Seed data
+exec-frontend : Pages + Components + Routes + I18n
+```
+
+Each teammate has an **isolated scope** (C02): backend never touches frontend.
+
+---
+
+## Coordination (C03)
+
+### Step-01: Lead aggregates scan results
+
+```
+1. Spawn 3 scan teammates
+2. Each reports findings via DM to lead
+3. Lead merges into unified analysis
+```
+
+### Step-03: Lead verifies between layers
+
+```
+1. Layer 0: lead executes (domain + infra + migration)
+2. Build gate: dotnet build --no-restore → MUST PASS
+3. Layer 1: spawn exec-backend + exec-frontend
+4. Wait for both to complete
+5. Build gate: dotnet build + npm typecheck → MUST PASS
+6. Layer 2: lead executes final validation
+```
+
+---
+
+## Idle Handling (T13)
+
+Teammates go idle after every turn — this is **normal**.
+- Idle does NOT mean done or unavailable
+- Sending a message to an idle teammate wakes them up
+- Do NOT treat idle as an error
+
+---
+
+## Graceful Shutdown (T11)
+
+After phase completes:
+
+```yaml
+# For each teammate:
+SendMessage:
+  type: "shutdown_request"
+  recipient: "{teammate-name}"
+  content: "Phase complete, shutting down"
+
+# Teammate responds:
+SendMessage:
+  type: "shutdown_response"
+  request_id: "{from_request}"
+  approve: true
+
+# After all confirmations:
+TeamDelete
+```
+
+---
+
+## Decision Matrix
+
+| Condition | Action |
+|-----------|--------|
+| economy_mode = true | NO teams, all sequential |
+| Only backend work | NO teams, agent principal |
+| Only frontend work | NO teams, agent principal |
+| Backend + Frontend | Teams: exec-backend + exec-frontend |
+| Analysis phase | Teams: scan-backend + scan-frontend + scan-context |

package/templates/skills/apex/references/analysis-methods.md

@@ -1,141 +1,141 @@
-# Analysis Methods — FK Detection, Tenant Modes, Code Patterns, Gap Analysis
-
-> **Loaded by:** step-01-analyze.md (sections 4-7)
-> **Purpose:** Detailed methods for analyzing existing code and planning entity-level requirements.
-
----
-
-## FK Field Detection
-
-For each entity found (or to be created), identify FK relationships:
-- Properties ending in "Id" with matching navigation property
-- Record: `{ entity, fkProperty, targetEntity, isRequired }`
-
-**Why:** FK fields drive two critical requirements:
-1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>`)
-2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
-
-See `references/execution-frontend-patterns.md` for EntityLookup patterns.
-
----
-
-## Tenant Mode Decision
-
-For each entity found (or to be created), determine the `tenantMode`:
-
-| Mode | Meaning | Examples | EF Filter |
-|------|---------|----------|-----------|
-| `strict` | Data belongs to one tenant | Employee, Order, Invoice | `TenantId == current` |
-| `optional` | Can be shared or tenant-specific | Department, Currency, JobTitle | `TenantId == current OR TenantId == null` |
-| `scoped` | Explicit scope rules | Settings, Workflow, EmailTemplate | `TenantId == current AND Scope == current` |
-| `none` | Platform-wide (never filtered) | Navigation, Permission, User | No TenantId |
-
-**Why:** Tenant mode drives EF query filters, seed data generation, and API access control.
-
-**Reference:** See `references/smartstack-api.md` for TenantId handling patterns and `smartstack-layers.md` for seed data strategies per tenant mode.
-
----
-
-## Code Pattern Detection
-
-For each entity found (or to be created), identify code generation needs:
-
-```
-IF feature.json exists AND entity has codePattern:
-  → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
-  → Record in analysis: entity has auto-generated code
-
-ELSE IF feature.json exists BUT entity has NO codePattern:
-  → Record: entity needs codePattern decision in step-02
-  → Apply heuristic default based on entity name:
-    Invoice/Order/Receipt → timestamp-daily
-    Ticket/Incident → timestamp-minute
-    Contract/Policy → year-sequential
-    Reference/Category → uuid-short
-    Employee/Customer/Project → sequential
-
-ELSE (no feature.json):
-  → Propose codePattern during step-02 planning based on task description
-```
-
-**Why:** Code generation strategy drives CreateDto structure, service injection (ICodeGenerator<T>), and DI registration.
-
-**Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
-
----
-
-## Gap Analysis
-
-Compare what EXISTS vs what the TASK REQUIRES:
-
-```
-For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
-```
-
-Cross-reference with step-00 challenge responses:
-- Each entity: entity, EF config, service, controller, frontend pages → exists/missing
-- Each section: NavigationSectionSeedData, frontend route → exists/missing
-- If dependencies: verify FK target entities and their `?search=` support
-
----
-
-## Scope Re-Check (after exploration)
-
-**Re-validate scope after code exploration reveals the true entity count.**
-Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
-
-```
-IF NOT delegate_mode:
-  actual_entities = count of entities marked "create" in gap analysis
-  actual_sections = count of sections marked "create"
-
-  IF actual_entities > 6:
-    WARNING: "Code exploration reveals {actual_entities} entities.
-     This exceeds the recommended maximum (4) for a single /apex invocation.
-     Risk: incomplete migrations, lost conventions, missing pages.
-     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
-
-    Ask user to confirm or re-scope.
-```
-
----
-
-## Analysis Validation — User Checkpoint
-
-**Objective:** Present findings and validate scope BEFORE planning.
-
-### Present Findings
-
-```
-ANALYSIS FINDINGS
-═══════════════════════════════════════════════════════════════
-
-Entities expected / found / to create: {summary}
-Sections expected / found / to create: {summary}
-FK Relationships: {fkFields summary}
-Dependencies: {cross-module refs or "none"}
-Complexity: {module_complexity}
-```
-
-### Validate with User (if NOT auto_mode)
-
-Question template (same as step-01 section 6b):
-- "Scope is correct" (Recommended)
-- "Add elements" → update entities/sections, re-run gap analysis
-- "Reduce scope" → update accordingly
-- "Change approach" → potentially restart from step-00
-
----
-
-## Analysis Summary Output
-
-```
-**APEX SmartStack - Analysis Complete**
-
-Navigation: {app_name} → {module_code} → {sections[].code}
-Entities: {entity_name → create | modify | skip}
-Existing: entities, configs, services, controllers, pages, seed data, tests (with paths)
-Required: create / modify / skip lists
-Profile: complexity, dependencies, FK fields, workflow, notifications
-ACs: AC1..ACn (inferred from PRD/feature/task/challenge)
-```
+# Analysis Methods — FK Detection, Tenant Modes, Code Patterns, Gap Analysis
+
+> **Loaded by:** step-01-analyze.md (sections 4-7)
+> **Purpose:** Detailed methods for analyzing existing code and planning entity-level requirements.
+
+---
+
+## FK Field Detection
+
+For each entity found (or to be created), identify FK relationships:
+- Properties ending in "Id" with matching navigation property
+- Record: `{ entity, fkProperty, targetEntity, isRequired }`
+
+**Why:** FK fields drive two critical requirements:
+1. **Frontend:** Each FK field MUST use `<EntityLookup />` (NEVER `<input>`, NEVER `<select>`)
+2. **Backend:** Each target entity's GetAll MUST support `?search=` parameter + return `PaginatedResult<T>`
+
+See `references/execution-frontend-patterns.md` for EntityLookup patterns.
+
+---
+
+## Tenant Mode Decision
+
+For each entity found (or to be created), determine the `tenantMode`:
+
+| Mode | Meaning | Examples | EF Filter |
+|------|---------|----------|-----------|
+| `strict` | Data belongs to one tenant | Employee, Order, Invoice | `TenantId == current` |
+| `optional` | Can be shared or tenant-specific | Department, Currency, JobTitle | `TenantId == current OR TenantId == null` |
+| `scoped` | Explicit scope rules | Settings, Workflow, EmailTemplate | `TenantId == current AND Scope == current` |
+| `none` | Platform-wide (never filtered) | Navigation, Permission, User | No TenantId |
+
+**Why:** Tenant mode drives EF query filters, seed data generation, and API access control.
+
+**Reference:** See `references/smartstack-api.md` for TenantId handling patterns and `smartstack-layers.md` for seed data strategies per tenant mode.
+
+---
+
+## Code Pattern Detection
+
+For each entity found (or to be created), identify code generation needs:
+
+```
+IF feature.json exists AND entity has codePattern:
+  → Use codePattern config from feature.json (strategy, prefix, digits, etc.)
+  → Record in analysis: entity has auto-generated code
+
+ELSE IF feature.json exists BUT entity has NO codePattern:
+  → Record: entity needs codePattern decision in step-02
+  → Apply heuristic default based on entity name:
+    Invoice/Order/Receipt → timestamp-daily
+    Ticket/Incident → timestamp-minute
+    Contract/Policy → year-sequential
+    Reference/Category → uuid-short
+    Employee/Customer/Project → sequential
+
+ELSE (no feature.json):
+  → Propose codePattern during step-02 planning based on task description
+```
+
+**Why:** Code generation strategy drives CreateDto structure, service injection (ICodeGenerator<T>), and DI registration.
+
+**Reference:** See `references/code-generation.md` for strategy table, volume-to-digits calculation, and backend patterns.
+
+---
+
+## Gap Analysis
+
+Compare what EXISTS vs what the TASK REQUIRES:
+
+```
+For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
+```
+
+Cross-reference with step-00 challenge responses:
+- Each entity: entity, EF config, service, controller, frontend pages → exists/missing
+- Each section: NavigationSectionSeedData, frontend route → exists/missing
+- If dependencies: verify FK target entities and their `?search=` support
+
+---
+
+## Scope Re-Check (after exploration)
+
+**Re-validate scope after code exploration reveals the true entity count.**
+Step-00 guard uses the user's description (may undercount). Now we know the actual entities.
+
+```
+IF NOT delegate_mode:
+  actual_entities = count of entities marked "create" in gap analysis
+  actual_sections = count of sections marked "create"
+
+  IF actual_entities > 6:
+    WARNING: "Code exploration reveals {actual_entities} entities.
+     This exceeds the recommended maximum (4) for a single /apex invocation.
+     Risk: incomplete migrations, lost conventions, missing pages.
+     Consider: split into {ceil(actual_entities/4)} iterations of ~4 entities each."
+
+    Ask user to confirm or re-scope.
+```
+
+---
+
+## Analysis Validation — User Checkpoint
+
+**Objective:** Present findings and validate scope BEFORE planning.
+
+### Present Findings
+
+```
+ANALYSIS FINDINGS
+═══════════════════════════════════════════════════════════════
+
+Entities expected / found / to create: {summary}
+Sections expected / found / to create: {summary}
+FK Relationships: {fkFields summary}
+Dependencies: {cross-module refs or "none"}
+Complexity: {module_complexity}
+```
+
+### Validate with User (if NOT auto_mode)
+
+Question template (same as step-01 section 6b):
+- "Scope is correct" (Recommended)
+- "Add elements" → update entities/sections, re-run gap analysis
+- "Reduce scope" → update accordingly
+- "Change approach" → potentially restart from step-00
+
+---
+
+## Analysis Summary Output
+
+```
+**APEX SmartStack - Analysis Complete**
+
+Navigation: {app_name} → {module_code} → {sections[].code}
+Entities: {entity_name → create | modify | skip}
+Existing: entities, configs, services, controllers, pages, seed data, tests (with paths)
+Required: create / modify / skip lists
+Profile: complexity, dependencies, FK fields, workflow, notifications
+ACs: AC1..ACn (inferred from PRD/feature/task/challenge)
+```