@atlashub/smartstack-cli 3.24.0 → 3.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlashub/smartstack-cli",
-  "version": "3.24.0",
+  "version": "3.26.0",
   "description": "SmartStack Claude Code automation toolkit - GitFlow, EF Core migrations, prompts and more",
   "author": {
     "name": "SmartStack",

package/templates/skills/apex/SKILL.md

@@ -33,7 +33,7 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | Flag | Description |
 |------|-------------|
 | `-a` | Auto mode: skip confirmations |
-| `-x` | Examine mode: adversarial code review |
+| `-x` | Deep review: adversarial code review (beyond step-04 automated checks) |
 | `-s` | Save mode: output to `.claude/output/apex/` |
 | `-t` | Test mode: scaffold + run tests via MCP |
 | `-e` | Economy mode: no subagents |
@@ -57,11 +57,17 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 | `{context_code}` | string | "business", "platform", "personal" |
 | `{app_name}` | string | Application name |
 | `{module_code}` | string | Module code |
-| `{sections}` | string[] | Sections being added/modified |
+| `{sections}` | object[] | Sections (MANDATORY, min 1) with code/labels/icon/displayOrder |
+| `{entities}` | string[] | Main entities to manage (from need-challenge) |
+| `{module_complexity}` | string | "simple-crud", "crud-rules", "crud-workflow", "complex" |
+| `{has_dependencies}` | string | "none", "references", "unknown" |
+| `{key_properties}` | string[] | Key business properties mentioned by user |
 | `{prd_path}` | string? | `.ralph/prd-{module}.json` if exists |
 | `{feature_path}` | string? | `docs/business/.../feature.json` if exists |
 | `{needs_seed_data}` | boolean | Seed data creation required |
 | `{needs_migration}` | boolean | EF Core migration required |
+| `{needs_workflow}` | boolean | Workflow integration required |
+| `{needs_notification}` | boolean | Notification integration required |
 </state_variables>
 
 <entry_point>
@@ -75,17 +81,32 @@ Execute incremental SmartStack development using the APEX methodology. This skil
 
 | Step | File | Model | Purpose |
 |------|------|-------|---------|
-| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect SmartStack context, verify MCP |
+| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect context, verify MCP, define hierarchy (5 levels), challenge need |
 | 01 | `steps/step-01-analyze.md` | Opus | Explore existing code (Agent Teams or direct) |
 | 02 | `steps/step-02-plan.md` | Opus | Layer-by-layer plan with skill/MCP mapping |
 | 03 | `steps/step-03-execute.md` | Opus | Orchestrate execution via skills and MCP |
-| 04 | `steps/step-04-validate.md` | Opus | MCP validation, build, seed data check |
-| 05 | `steps/step-05-examine.md` | Opus | Adversarial review (if -x) |
+| 04 | `steps/step-04-examine.md` | Opus | eXamine: MCP validation, build, 21 POST-CHECKs, acceptance criteria |
+| 05 | `steps/step-05-deep-review.md` | Opus | Deep Review: adversarial code review (if -x) |
 | 06 | `steps/step-06-resolve.md` | Opus | Fix BLOCKING findings (if any) |
 | 07 | `steps/step-07-tests.md` | Opus | Scaffold tests via MCP (if -t) |
 | 08 | `steps/step-08-run-tests.md` | Opus | Run tests until 100% pass (if -t) |
 </step_files>
 
+<apex_phases>
+**APEX = Analyze → Plan → Execute → eXamine**
+
+| Phase | Step | Obligatory | Description |
+|-------|------|------------|-------------|
+| *Init* | 00 | Yes | Setup, hierarchy, challenge the need |
+| **A** — Analyze | 01 | Yes | Explore existing code |
+| **P** — Plan | 02 | Yes | File-by-file plan with skill/MCP mapping |
+| **E** — Execute | 03 | Yes | Orchestrate creation via skills and MCP |
+| **X** — eXamine | 04 | Yes | 21 POST-CHECKs, MCP validation, build, acceptance criteria |
+| *Deep Review* | 05 (if -x) | No | Adversarial code review beyond automated checks |
+| *Resolve* | 06 (if BLOCKING) | No | Fix BLOCKING findings |
+| *Tests* | 07-08 (if -t) | No | Scaffold and run tests |
+</apex_phases>
+
 <reference_files>
 **Loaded conditionally by steps that need them:**
 

package/templates/skills/apex/_shared.md

@@ -30,7 +30,7 @@
 
 | Tool | Purpose | Step |
 |------|---------|------|
-| `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (validate) |
+| `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (examine) |
 
 ### Generation (step-03)
 
@@ -42,7 +42,7 @@
 | `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
 | `scaffold_routes` | Generate React Router routes | Frontend changes |
 
-### Validation (step-04)
+### eXamine (step-04)
 
 | Tool | Purpose | Condition |
 |------|---------|-----------|
@@ -65,7 +65,7 @@
 | `suggest_test_scenarios` | Suggest test scenarios |
 | `analyze_test_coverage` | Check coverage percentage |
 
-### Review (step-05, if -x)
+### Deep Review (step-05, if -x)
 
 | Tool | Purpose |
 |------|---------|

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

@@ -22,7 +22,7 @@ Always provide both `team_name` and `description`.
 
 ```yaml
 Task:
-  subagent_type: "general-purpose"
+  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)
@@ -30,14 +30,14 @@ Task:
   prompt: "{detailed task prompt}"
 ```
 
-### Model Assignment (T02/T06)
+### Model & Agent Assignment (T02/T03/T06)
 
-| Task Type | Model | Justification |
-|-----------|-------|---------------|
-| Scan/read files | Sonnet | Read-only, no analysis needed |
-| Read context (PRD, feature.json) | Sonnet | Read-only extraction |
-| Code development | Opus | Complex generation via skills/MCP |
-| Fix/resolve | Opus | Requires reasoning |
+| 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 |
 
 ---
 

package/templates/skills/apex/references/challenge-questions.md

@@ -0,0 +1,165 @@
+# Challenge Questions — APEX
+
+> **Referenced by:** step-00-init.md
+> Question templates for context detection, hierarchy validation, and need challenging.
+
+---
+
+## Context Detection (section 2)
+
+If hierarchy cannot be inferred, ask the user:
+
+```yaml
+questions:
+  - header: "Context"
+    question: "What is the SmartStack context for this work?"
+    options:
+      - label: "Business (Recommended)"
+        description: "Business application module"
+      - label: "Platform"
+        description: "Platform administration or support"
+      - label: "Personal"
+        description: "Personal user space"
+    multiSelect: false
+```
+
+---
+
+## 4a. Application Validation
+
+If `{app_name}` was NOT clearly inferred from the task description:
+
+```yaml
+questions:
+  - header: "Application"
+    question: "Which application does this module belong to?"
+    options:
+      - label: "<best guess from task> (Recommended)"
+        description: "Inferred from your task description"
+      - label: "New application"
+        description: "Create a new application in the {context_code} context"
+      - label: "Existing application"
+        description: "Add to an existing application (specify in Other)"
+    multiSelect: false
+```
+
+If "New application": collect `{app_name}`, `{app_code}`, `{app_icon}`, `{app_labels}` (4 langs).
+If "Existing application": scan `**/Seeding/Data/**/NavigationApplicationSeedData.cs` and present discovered apps.
+
+---
+
+## 4b. Module Validation
+
+If `{module_code}` was NOT clearly inferred from the task description:
+
+```yaml
+questions:
+  - header: "Module"
+    question: "What is the module code? (kebab-case, e.g., 'order-management', 'employees')"
+    options:
+      - label: "<inferred module code> (Recommended)"
+        description: "Inferred from your task description"
+      - label: "<alternative suggestion>"
+        description: "Alternative based on keywords"
+    multiSelect: false
+```
+
+---
+
+## 4c. Section Selection
+
+> **BLOCKING:** This question MUST be asked. `{sections}` MUST contain at least one entry before proceeding.
+
+Infer section suggestions from:
+1. Task description (extract nouns/concepts that suggest functional sub-areas)
+2. PRD/feature.json if available (module.sections)
+3. Common patterns: "list" (default for simple CRUD), "dashboard", "settings", "reports"
+
+```yaml
+questions:
+  - header: "Sections"
+    question: "What sections should the module '{module_code}' contain? (Select at least one — use 'Other' to add custom sections)"
+    options:
+      - label: "<inferred section 1>"
+        description: "Primary functional area based on module purpose"
+      - label: "<inferred section 2>"
+        description: "Secondary functional area"
+      - label: "<inferred section 3>"
+        description: "Additional area inferred from context"
+    multiSelect: true
+```
+
+**Validation (BLOCKING):**
+```
+IF {sections}.length == 0:
+  DISPLAY: "Every module must have at least one section. Please select or define at least one."
+  → Re-ask the sections question
+  → DO NOT proceed to next step
+```
+
+**Store for each section:**
+```yaml
+sections:
+  - code: "section-kebab"
+    labels: { fr: "...", en: "...", it: "...", de: "..." }
+    icon: "LucideIconName"
+    displayOrder: 10
+```
+
+---
+
+## 5a. Entity Scope & Relationships
+
+```yaml
+questions:
+  - header: "Entities"
+    question: "What are the main entities this module manages? (e.g., 'Order, OrderLine, OrderStatus')"
+    options:
+      - label: "<inferred primary entity>"
+        description: "Main entity inferred from module name"
+      - label: "<inferred primary + secondary>"
+        description: "Primary entity plus related entities from context"
+      - label: "Only the primary entity"
+        description: "Simple module — single entity '{module_code}' with standard CRUD"
+    multiSelect: false
+  - header: "Complexity"
+    question: "What best describes this module's behavior?"
+    options:
+      - label: "Simple CRUD (Recommended)"
+        description: "Standard list/create/edit/delete — no special business logic"
+      - label: "CRUD + Business rules"
+        description: "CRUD with validations, computed fields, status transitions, or constraints"
+      - label: "CRUD + Workflow/Notifications"
+        description: "CRUD with automated actions (emails, approvals, webhooks)"
+      - label: "Complex module"
+        description: "Multiple interrelated entities with specific business logic"
+    multiSelect: false
+```
+
+---
+
+## 5b. Dependencies & Key Properties
+
+```yaml
+questions:
+  - header: "Dependencies"
+    question: "Does this module reference entities from other existing modules?"
+    options:
+      - label: "No dependencies"
+        description: "Standalone module — no FK relationships to other modules"
+      - label: "Yes, has FK references"
+        description: "References entities from other modules (specify in Other)"
+      - label: "Not sure yet"
+        description: "Will determine during analysis — may require EntityLookup components"
+    multiSelect: false
+  - header: "Key fields"
+    question: "Beyond standard fields (Id, TenantId, Audit), what are the key business properties of the main entity?"
+    options:
+      - label: "<inferred properties from context>"
+        description: "Properties inferred from module purpose"
+      - label: "Standard fields only"
+        description: "I'll define properties later during implementation"
+      - label: "I have specific requirements"
+        description: "Describe your fields in 'Other'"
+    multiSelect: false
+```