@atlashub/smartstack-cli 3.25.0 → 3.27.0

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

@@ -38,26 +38,11 @@ This saves ~2 minutes of Glob searches on an empty project.
 
 Read available context (in order of priority):
 
-**A. PRD (if exists):**
-```
-Read {prd_path} → extract:
-- filesToCreate (7 categories)
-- brToCodeMapping
-- permissionMatrix
-- acceptance criteria
-```
-
-**B. Feature.json (if exists):**
-```
-Read {feature_path} → extract:
-- Module structure (sections, resources)
-- Business rules
-- Entity definitions
-- Permission structure
-```
-
-**C. Task description only:**
-If neither PRD nor feature.json exists, rely on task description and code exploration.
+| Source | Action |
+|--------|--------|
+| PRD (`{prd_path}`) | Extract: filesToCreate, brToCodeMapping, permissionMatrix, acceptance criteria |
+| Feature.json (`{feature_path}`) | Extract: module structure, business rules, entity definitions, permissions |
+| Task description only | Rely on task description and code exploration |
 
 ---
 
@@ -65,8 +50,6 @@ If neither PRD nor feature.json exists, rely on task description and code explor
 
 ### If economy_mode: Direct Tools
 
-Use Glob, Grep, Read, and MCP tools directly:
-
 ```
 Backend:
 - Glob("**/Domain/Entities/**/{module_code}/**/*.cs")
@@ -91,116 +74,119 @@ MCP:
 ```
 TeamCreate("apex-analyze", description: "Scan SmartStack project for existing code")
 
-Spawn 3 teammates (Sonnet, read-only tools: Glob, Grep, Read):
+Spawn 3 teammates (subagent_type: "Explore", model: "sonnet"):
 
 1. scan-backend:
-   "Scan backend code for module {module_code} in app {app_name}.
-    Find: entities, EF configs, services, DTOs, validators, controllers.
-    Report: file paths, class names, key patterns found.
-    Folders: Domain/, Infrastructure/, Application/, Api/"
+   "Scan backend for module {module_code}: entities, EF configs, services,
+    DTOs, validators, controllers in Domain/ + Infrastructure/ + Application/ + Api/"
 
 2. scan-frontend:
-   "Scan frontend code for module {module_code} in app {app_name}.
-    Find: pages, components, hooks, i18n files, route definitions.
-    Report: file paths, component names, route patterns.
-    Folders: src/pages/, src/components/, src/locales/"
+   "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} in app {app_name}.
-    Read: .ralph/prd-{module_code}.json, docs/business/**/feature.json.
-    Report: sections, entities, business rules, permissions, acceptance criteria."
+   "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 teammates to report via SendMessage (DM to lead).
-Aggregate results.
-
-Shutdown teammates → TeamDelete("apex-analyze")
+Wait for all 3 → aggregate results → shutdown → TeamDelete("apex-analyze")
 ```
 
 ---
 
 ## 3. Seed Data Inventory
 
-Check existing seed data:
-
 ```
 Glob("**/Seeding/Data/{module_code}/*SeedData.cs")
 Glob("**/Seeding/*SeedDataProvider.cs")
 ```
 
-Identify:
-- NavigationModuleSeedData: exists? complete?
-- PermissionsSeedData: exists? complete?
-- RolesSeedData: exists? complete?
-- SeedConstants: exists?
-- IClientSeedDataProvider: exists? registered in DI?
+Identify: NavigationModuleSeedData, PermissionsSeedData, RolesSeedData, SeedConstants, IClientSeedDataProvider (+ DI registration).
 
 ---
 
 ## 4. 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 plain text for GUIDs)
+2. **Backend:** Each target entity's GetAll MUST support `?search=`
+
+---
+
+## 5. Gap Analysis
+
+Compare what EXISTS vs what the TASK REQUIRES:
 
 ```
-For each entity in analysis results:
-  - List properties ending in "Id" with a matching navigation property (e.g., EmployeeId + Employee)
-  - Record: { fkProperty, targetEntity, isRequired }
-
-Output:
-  fkFields: [
-    { entity: "TimeEntry", fkProperty: "EmployeeId", targetEntity: "Employee", isRequired: true },
-    { entity: "TimeEntry", fkProperty: "ProjectId", targetEntity: "Project", isRequired: true }
-  ]
+For each element: EXISTS+COMPLETE → "skip" | EXISTS+INCOMPLETE → "modify" | MISSING → "create"
 ```
 
-**Why:** FK fields drive two critical downstream requirements:
-1. **Frontend:** Each FK field MUST use `EntityLookup` component (NEVER plain text input for GUIDs)
-2. **Backend:** Each target entity's GetAll endpoint MUST support `?search=` query parameter
-
-These are propagated to step-02 (plan) and step-03 (execute).
+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
 
 ---
 
-## 5. Gap Analysis
+## 6. Analysis Validation (User Checkpoint)
 
-Compare what EXISTS vs what the TASK REQUIRES:
+> **Objective:** Present findings and validate scope with the user BEFORE planning.
+
+### 6a. Present Findings
 
 ```
-For each element in the task description:
-  - EXISTS and COMPLETE → mark as "skip"
-  - EXISTS but INCOMPLETE → mark as "modify"
-  - DOES NOT EXIST → mark as "create"
+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}
+```
+
+### 6b. Validate with User (if NOT auto_mode)
+
+```yaml
+questions:
+  - header: "Scope"
+    question: "Based on the analysis above, is the scope accurate?"
+    options:
+      - label: "Scope is correct (Recommended)"
+        description: "Proceed to planning with the identified elements"
+      - label: "Add elements"
+        description: "I need to add entities, properties, or sections"
+      - label: "Reduce scope"
+        description: "Remove some elements — smaller first iteration"
+      - label: "Change approach"
+        description: "The analysis reveals issues — let's adjust"
+    multiSelect: false
 ```
 
+If "Add elements": update `{entities}`, `{sections}`, `{key_properties}`, re-run gap analysis.
+If "Reduce scope": update variables accordingly.
+If "Change approach": discuss with user, potentially restart from step-00.
+
 ---
 
-## 6. Analysis Summary
+## 7. Analysis Summary
 
 ```
 **APEX SmartStack - Analysis Complete**
-
-**Existing Code:**
-- Entities: {list with paths}
-- EF Configs: {list with paths}
-- Services: {list with paths}
-- Controllers: {list with paths}
-- Frontend pages: {list with paths}
-- Seed data: {status per type}
-- Tests: {list with paths}
-
-**Required Changes:**
-- Create: {list of new files/elements}
-- Modify: {list of files to change}
-- Skip: {list of existing complete elements}
-
-**Acceptance Criteria:** (inferred from PRD/feature/task)
-- AC1: {criterion}
-- AC2: {criterion}
-...
+Navigation: {context_code} → {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)
 ```
 
 ---
 
-## 7. Save Output (if save_mode)
+## 8. Save Output (if save_mode)
 
 Write to `{output_dir}/01-analyze.md` with analysis results.
 

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

@@ -3,7 +3,7 @@ name: step-03-execute
 description: Orchestrate code creation via existing skills and MCP tools
 model: opus
 prev_step: steps/step-02-plan.md
-next_step: steps/step-04-validate.md
+next_step: steps/step-04-examine.md
 ---
 
 # Step 3: Execute
@@ -207,4 +207,4 @@ Write to `{output_dir}/03-execute.md` with execution log per layer.
 
 ## NEXT STEP
 
-Load `steps/step-04-validate.md`
+Load `steps/step-04-examine.md`

package/templates/skills/apex/steps/step-04-examine.md

@@ -0,0 +1,198 @@
+---
+name: step-04-examine
+description: MCP validation, build verification, seed data check, acceptance criteria
+model: opus
+prev_step: steps/step-03-execute.md
+next_step: steps/step-05-deep-review.md
+---
+
+# Step 4: eXamine
+
+> **This is the X in APEX.** Mandatory automated examination of all generated code.
+
+**Goal:** Verify everything works. MCP conventions, build, seed data, acceptance criteria.
+
+---
+
+## 1. MCP Convention Validation
+
+```
+Call: mcp__smartstack__validate_conventions
+
+Expected: 0 errors
+If errors found:
+  → Fix each error (use appropriate skill/MCP)
+  → Re-validate until 0 errors
+```
+
+---
+
+## 2. EF Core Migration Check (if needs_migration)
+
+```
+Call: mcp__smartstack__check_migrations
+
+Verify:
+- Migration exists and is applied
+- No pending model changes
+- ModelSnapshot matches
+```
+
+---
+
+## 3. Frontend Route Validation (if frontend modified)
+
+```
+Call: mcp__smartstack__validate_frontend_routes
+
+Verify:
+- Routes nested inside correct Layout wrapper
+- Route paths match controller patterns
+- No orphan routes
+```
+
+---
+
+## 4. Build Verification
+
+```bash
+# Cleanup corrupted EF Core design-time artifacts (Roslyn BuildHost bug on Windows)
+for d in src/*/bin?Debug; do [ -d "$d" ] && echo "Removing corrupted artifact: $d" && rm -rf "$d"; done
+
+# Backend
+dotnet clean && dotnet restore && dotnet build
+
+# Frontend (if applicable)
+npm run typecheck
+```
+
+**BLOCKING:** Both must pass. If failure, fix and retry.
+
+---
+
+## 5. Database & Migration Validation (if needs_migration)
+
+### 5a. Pending Model Changes Check
+
+```bash
+INFRA_PROJECT=$(ls src/*Infrastructure*/*.csproj 2>/dev/null | head -1)
+API_PROJECT=$(ls src/*Api*/*.csproj 2>/dev/null | head -1)
+
+dotnet ef migrations has-pending-model-changes \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**BLOCKING** if pending changes detected → migration is missing.
+
+### 5b. Migration Application Test (SQL Server LocalDB)
+
+```bash
+DB_NAME="SmartStack_Apex_Examine_$(date +%s)"
+CONN_STRING="Server=(localdb)\\MSSQLLocalDB;Database=$DB_NAME;Integrated Security=true;TrustServerCertificate=true;Connect Timeout=120;"
+
+dotnet ef database update \
+  --connection "$CONN_STRING" \
+  --project "$INFRA_PROJECT" \
+  --startup-project "$API_PROJECT"
+```
+
+**BLOCKING** if migration fails on SQL Server. Common issues:
+- SQLite-only syntax in migrations (fix: regenerate migration)
+- Column type mismatches (fix: update EF configuration)
+- Missing foreign key targets (fix: reorder migrations)
+
+### 5c. Integration Tests on Real SQL Server
+
+```bash
+# Integration tests use DatabaseFixture → real SQL Server LocalDB
+# This validates: LINQ→SQL, multi-tenant isolation, soft delete, EF configs
+INT_TEST_PROJECT=$(ls tests/*Tests.Integration*/*.csproj 2>/dev/null | head -1)
+if [ -n "$INT_TEST_PROJECT" ]; then
+  dotnet test "$INT_TEST_PROJECT" --no-build --verbosity normal
+fi
+```
+
+Tests running against SQL Server catch issues that SQLite misses:
+- Case sensitivity in string comparisons
+- Date/time function differences
+- IDENTITY vs AUTOINCREMENT behavior
+- Global query filter translation to T-SQL
+
+### 5d. Cleanup
+
+```bash
+sqlcmd -S "(localdb)\MSSQLLocalDB" -Q "IF DB_ID('$DB_NAME') IS NOT NULL BEGIN ALTER DATABASE [$DB_NAME] SET SINGLE_USER WITH ROLLBACK IMMEDIATE; DROP DATABASE [$DB_NAME]; END" 2>/dev/null
+```
+
+---
+
+## 6. Seed Data Completeness Check (if needs_seed_data)
+
+| File | Checks |
+|------|--------|
+| NavigationApplicationSeedData | MUST be first, deterministic GUID for application (NOT for context — context is looked up by code), 4 lang translations |
+| NavigationModuleSeedData | Deterministic GUIDs (SHA256), 4 languages, GetModuleEntry + GetTranslationEntries |
+| PermissionsSeedData | MCP generate_permissions used, paths match Permissions.cs, wildcard + CRUD |
+| RolesSeedData | Admin=wildcard, Manager=CRU, Contributor=CR, Viewer=R |
+| IClientSeedDataProvider | 3 Seed methods, idempotent, factory methods, SaveChanges per group |
+| DI Registration | `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()` |
+
+---
+
+## 6b. BLOCKING POST-CHECKs
+
+Load and execute all checks from `references/post-checks.md`.
+
+**If ANY POST-CHECK fails → fix in step-03, re-validate.**
+
+---
+
+## 7. Acceptance Criteria POST-CHECK
+
+For each AC inferred in step-01:
+
+```
+AC1: {criterion} → PASS / FAIL (evidence: {file:line or test})
+AC2: {criterion} → PASS / FAIL (evidence: {file:line or test})
+...
+```
+
+**All ACs must PASS. If any FAIL, go back to step-03 to fix.**
+
+---
+
+## 8. eXamine Summary
+
+```
+**APEX SmartStack - eXamine Complete**
+
+| Category | Checks | Status |
+|----------|--------|--------|
+| MCP conventions | validate_conventions | PASS (0 errors) |
+| Build | dotnet build + npm typecheck | PASS |
+| EF Core | migrations, pending changes, SQL Server apply | PASS / N/A |
+| DB tests | Integration tests on SQL Server | PASS / N/A |
+| Frontend | routes, lazy loading, forms as pages, i18n (4 langs + keys) | PASS / N/A |
+| Security | TenantId filter, RequirePermission, no Guid.Empty, no !.Value | PASS / N/A |
+| Seed data | completeness, deterministic GUIDs, no ContextId/RoleId constants | PASS / N/A |
+| Code quality | PaginatedResult, EntityLookup, CSS vars, search param | PASS / N/A |
+| POST-CHECKs | 21 checks from references/post-checks.md | PASS / N/A |
+| Acceptance criteria | AC1..ACn | {X}/{Y} PASS |
+```
+
+---
+
+## 9. Save Output (if save_mode)
+
+Write to `{output_dir}/04-examine.md` with validation results.
+
+---
+
+## 10. Route to Next Step
+
+```
+examine_mode → step-05-deep-review | test_mode → step-07-tests | pr_mode → create PR | else → final summary
+```
+
+**FINAL SUMMARY (if no more steps):** task, context, files created/modified, validation status, commits count, next steps.

package/templates/skills/apex/steps/{step-05-examine.md → step-05-deep-review.md}

@@ -1,14 +1,14 @@
 ---
-name: step-05-examine
+name: step-05-deep-review
 description: Adversarial code review of changes — find issues before they reach production
 model: opus
-prev_step: steps/step-04-validate.md
+prev_step: steps/step-04-examine.md
 next_step: steps/step-06-resolve.md
 ---
 
-# Step 5: Examine (if -x)
+# Step 5: Deep Review (if -x)
 
-**Goal:** Review the code as an adversarial external reviewer. Find bugs, security issues, and convention violations that automated checks missed.
+**Goal:** Review the code as an adversarial external reviewer. Find bugs, security issues, and convention violations that the automated eXamine checks (step-04) missed.
 
 ---
 
@@ -98,7 +98,7 @@ For each issue found, classify:
 ## 5. Summary
 
 ```
-**APEX SmartStack - Examine Complete**
+**APEX SmartStack - Deep Review Complete**
 
 **Files reviewed:** {count}
 **Findings:** {blocking} BLOCKING, {suggestions} SUGGESTION, {nits} NIT
@@ -110,7 +110,7 @@ For each issue found, classify:
 
 ## 6. Save Output (if save_mode)
 
-Write to `{output_dir}/05-examine.md` with all findings.
+Write to `{output_dir}/05-deep-review.md` with all findings.
 
 ---
 

package/templates/skills/apex/steps/step-06-resolve.md

@@ -2,13 +2,13 @@
 name: step-06-resolve
 description: Fix BLOCKING findings from adversarial review
 model: opus
-prev_step: steps/step-05-examine.md
+prev_step: steps/step-05-deep-review.md
 next_step: steps/step-07-tests.md
 ---
 
 # Step 6: Resolve (if BLOCKING findings)
 
-**Goal:** Fix all BLOCKING findings from step-05. Re-validate after fixes.
+**Goal:** Fix all BLOCKING findings from Deep Review (step-05). Re-validate after fixes.
 
 ---
 

package/templates/skills/business-analyse/SKILL.md

@@ -271,8 +271,36 @@ Load ONLY relevant categories based on feature type:
 - **Follow next_step directive** at end of each step
 - **Context: business only** - Reject platform/personal/system contexts
 - **Use parallel agents** for codebase exploration
+- **Team mode** (2+ modules): After step-02, load `references/team-orchestration.md` and follow team protocol
+- **Inline mode** (1 module): Classic sequential execution, no team
 </execution_rules>
 
+<team_mode>
+**Automatic team activation for multi-module applications:**
+
+| Condition | Mode |
+|-----------|------|
+| 1 module | Inline (classic, no team) |
+| 2+ modules | Team mode (Propose & Review) |
+
+**Team mode workflow (Propose & Review):**
+1. Steps 00-02 execute inline in the main conversation (interactive with user)
+2. After step-02 decomposition: `TeamCreate({ team_name: "ba-{appName}" })`
+3. For each module: spawn autonomous agent, agent proposes complete specification, team lead presents to user for validation
+4. After all modules specified: spawn consolidation agent (steps 04a + 04b), present report for user approval (04c)
+5. After consolidation approved: spawn handoff agent (steps 05a + 05b + 05c)
+6. `TeamDelete()` cleanup
+
+**Why team mode:**
+- Each module agent gets a **fresh context window** (zero accumulation)
+- The team lead stays lightweight (< 30% context even with 10+ modules)
+- Module agents work **autonomously** (no AskUserQuestion — they PROPOSE, user REVIEWS)
+- Error recovery: if an agent crashes, respawn with same module context from feature.json
+
+**Reference:** `references/team-orchestration.md` (loaded by step-02 after decomposition)
+**Agent prompt template:** `references/agent-module-prompt.md`
+</team_mode>
+
 <success_criteria>
 
 - Master feature.json created and enriched progressively through all steps