@atlashub/smartstack-cli 3.8.0 → 3.9.0

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

@@ -0,0 +1,160 @@
+---
+name: step-02-plan
+description: Create layer-by-layer execution plan with skill/MCP mapping per file
+model: opus
+prev_step: steps/step-01-analyze.md
+next_step: steps/step-03-execute.md
+---
+
+# Step 2: Plan
+
+**Goal:** Create a precise, file-by-file plan. Each file mapped to a SKILL or MCP tool.
+
+## LOAD CONDITIONALLY
+
+Read `references/smartstack-layers.md` for layer execution rules and skill/MCP mapping.
+
+---
+
+## 1. Map Changes to Layers
+
+For each element identified in step-01 (create or modify), assign to a SmartStack layer:
+
+| Layer | Category | Order |
+|-------|----------|-------|
+| 0 | Domain (entities, enums, exceptions) | Sequential |
+| 0 | Infrastructure - EF Configs | Sequential |
+| 0 | Infrastructure - Migration (BLOCKING) | Sequential |
+| 1 | Application (services, DTOs, validators) | Parallel |
+| 1 | API (controllers) | Parallel |
+| 1 | Infrastructure - Seed Data | Parallel |
+| 2 | Frontend (pages, components) | Parallel |
+| 2 | I18n (translations) | Parallel |
+| 3 | Tests | Sequential |
+
+---
+
+## 2. Assign Skill/MCP per File
+
+For EACH file in the plan, specify HOW it will be created/modified:
+
+```markdown
+### Layer 0 — Domain + Infrastructure (sequential)
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 1 | Domain/Entities/.../MyEntity.cs | create | MCP scaffold_extension |
+| 2 | Infrastructure/.../MyEntityConfiguration.cs | create | MCP scaffold_extension |
+| 3 | Migration | create | MCP suggest_migration + dotnet ef |
+
+### Layer 1 — Application + API (parallel)
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 4 | Application/Services/.../MyService.cs | create | MCP scaffold_extension |
+| 5 | Application/DTOs/.../MyDto.cs | create | MCP scaffold_extension |
+| 6 | Api/Controllers/.../MyController.cs | create | /controller skill |
+| 7 | Seeding/Data/.../NavigationModuleSeedData.cs | create | MCP generate_permissions |
+| 8 | Seeding/Data/.../PermissionsSeedData.cs | create | MCP generate_permissions |
+| 9 | Seeding/Data/.../RolesSeedData.cs | create | ref smartstack-layers.md |
+
+### Layer 2 — Frontend + I18n (parallel)
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 10 | src/pages/{Ctx}/{App}/{Mod}/ListPage.tsx | create | /ui-components skill |
+| 11 | src/services/api/{module}Api.ts | create | MCP scaffold_api_client |
+| 12 | src/routes/{module}.tsx | create | MCP scaffold_routes |
+| 13 | src/locales/fr/{module}.json | create | manual (4 languages) |
+
+### Layer 3 — Tests (sequential, if -t)
+
+| # | File | Action | Tool |
+|---|------|--------|------|
+| 14 | tests/.../MyEntityTests.cs | create | MCP scaffold_tests |
+| 15 | tests/.../MyServiceTests.cs | create | MCP scaffold_tests |
+```
+
+---
+
+## 3. Identify Parallelization (Agent Teams)
+
+If NOT economy_mode AND Layer 1 has both backend and frontend work:
+
+```
+Layer 0: SEQUENTIAL (agent principal)
+  → domain + infra + migration
+  → dotnet build --no-restore (BLOCKING)
+
+Layer 1: PARALLEL (Agent Teams)
+  → exec-backend: application + api + seed data
+  → exec-frontend: frontend + i18n
+
+Layer 2: SEQUENTIAL (agent principal)
+  → final validation + tests
+```
+
+If economy_mode: ALL layers sequential, agent principal only.
+
+---
+
+## 4. Dependency Validation
+
+Verify the plan respects dependencies:
+
+```
+- Migration AFTER EF configs (always)
+- Application services AFTER domain entities (always)
+- Controllers AFTER application services (always)
+- Frontend AFTER API controllers (API contract needed)
+- Seed data AFTER navigation module exists
+- Tests AFTER all code layers complete
+- Build check between Layer 0 and Layer 1 (BLOCKING)
+```
+
+---
+
+## 5. Estimated Commits
+
+```
+feat({module}): [domain+infra] {description}
+feat({module}): [app+api] {description}
+feat({module}): [frontend] {description}
+feat({module}): [seed] {description}
+feat({module}): [tests] {description}    # if -t
+```
+
+---
+
+## 6. User Checkpoint (if NOT auto_mode)
+
+Present the plan and ask for validation:
+
+```yaml
+questions:
+  - header: "Plan"
+    question: "Does this execution plan look correct?"
+    options:
+      - label: "Approve and execute (Recommended)"
+        description: "Proceed with the plan as described"
+      - label: "Modify plan"
+        description: "I want to adjust some items"
+      - label: "Cancel"
+        description: "Abort the workflow"
+    multiSelect: false
+```
+
+If "Modify plan": ask what to change, update plan, re-present.
+If "Cancel": abort workflow.
+
+---
+
+## 7. Save Output (if save_mode)
+
+Write to `{output_dir}/02-plan.md` with the complete plan.
+
+---
+
+## NEXT STEP
+
+Load `steps/step-03-execute.md`

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

@@ -0,0 +1,166 @@
+---
+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
+---
+
+# Step 3: Execute
+
+**CRITICAL PRINCIPLE: /apex ORCHESTRATES. It NEVER writes SmartStack code directly.**
+All code goes through skills (/controller, /application, /ui-components, /efcore) or MCP tools.
+
+## LOAD CONDITIONALLY
+
+- Read `references/smartstack-layers.md` for execution rules per layer
+- If NOT `{economy_mode}` AND Layer 1 has parallel work: read `references/agent-teams-protocol.md`
+
+---
+
+## Layer 0 — Domain + Infrastructure (sequential, agent principal)
+
+### Domain Entities
+
+```
+For each entity to create/modify:
+  → MCP scaffold_extension (type: "entity", target: entity_name)
+  → Verify: inherits AuditableEntity, has IHasData if multi-tenant
+```
+
+### EF Core Configurations
+
+```
+For each entity:
+  → MCP scaffold_extension (type: "configuration", target: entity_name)
+  → Verify: table name, relationships, indexes
+  → Register DbSet in ExtensionsDbContext if new entity
+```
+
+### Migration (BLOCKING)
+
+```
+1. MCP suggest_migration → get standardized name
+2. dotnet ef migrations add {Name} --project src/{Infra}.csproj --startup-project src/{Api}.csproj -o Persistence/Migrations
+3. dotnet ef database update (if local DB)
+4. dotnet build --no-restore → MUST PASS
+```
+
+**BLOCKING:** If build fails after migration, fix EF configs before proceeding.
+
+### Post-Layer 0 Build Gate
+
+```bash
+dotnet build --no-restore
+```
+
+**MUST PASS before Layer 1. If failure, fix and retry.**
+
+---
+
+## Layer 1 — Application + API + Seed Data
+
+### If economy_mode: Sequential execution
+
+Execute each item from the plan sequentially using skills and MCP.
+
+### If NOT economy_mode: Agent Teams (parallel)
+
+> **Protocol:** See `references/agent-teams-protocol.md`
+
+```
+TeamCreate("apex-exec", description: "Execute Layer 1 in parallel")
+
+Spawn 2 teammates (Opus, full tools):
+
+1. exec-backend (team_name: "apex-exec", name: "exec-backend"):
+   "Execute these Layer 1 backend tasks for module {module_code}:
+    {list of application + api + seed data tasks from plan}
+
+    For each task:
+    - Application services/DTOs: MCP scaffold_extension
+    - Controllers: use /controller skill for complex, MCP scaffold_extension for simple
+    - Seed data: MCP generate_permissions, then follow smartstack-layers.md templates
+
+    After ALL tasks done:
+    SendMessage(type:'message', recipient:'team-lead', content:'BACKEND_COMPLETE', summary:'Backend layer done')"
+
+2. exec-frontend (team_name: "apex-exec", name: "exec-frontend"):
+   "Execute these Layer 1 frontend tasks for module {module_code}:
+    {list of frontend + i18n tasks from plan}
+
+    For each task:
+    - API client: MCP scaffold_api_client
+    - Routes: MCP scaffold_routes
+    - Pages: use /ui-components skill
+    - I18n: 4 languages (fr, en, it, de)
+    - MUST use src/pages/{Context}/{App}/{Module}/ hierarchy (NOT flat)
+
+    After ALL tasks done:
+    SendMessage(type:'message', recipient:'team-lead', content:'FRONTEND_COMPLETE', summary:'Frontend layer done')"
+
+Wait for both teammates to report completion.
+
+Build verification:
+  dotnet build --no-restore  (backend)
+  npm run typecheck           (frontend, if applicable)
+
+shutdown_request → shutdown_response → TeamDelete("apex-exec")
+```
+
+---
+
+## Layer 1 — Skill Delegation
+
+| Skill | When | Context to provide |
+|-------|------|--------------------|
+| /controller | Custom routes, complex auth, file upload | entity, CRUD actions, permissions, routes |
+| /application | Full context/app/module from scratch | context, app, module names |
+| /ui-components | Complex pages (tables, grids, dashboards) | entity, fields, page type |
+| /efcore | Complex EF configs, inheritance | relationships, indexes |
+| /notification | In-app or email notifications | trigger, recipients, template |
+| /workflow | Automated workflows | trigger, steps, conditions |
+
+---
+
+## Layer 2 — Final Seed Data + Validation (sequential)
+
+After Layer 1 completes:
+
+```
+1. Verify seed data completeness:
+   - NavigationModuleSeedData.cs with 4 languages
+   - PermissionsSeedData.cs with deterministic GUIDs
+   - RolesSeedData.cs with context-based role mapping
+   - IClientSeedDataProvider updated
+   - DI registration added
+
+2. Build gate:
+   dotnet build --no-restore → MUST PASS
+   npm run typecheck → MUST PASS (if frontend)
+```
+
+---
+
+## Commits Per Layer
+
+After each layer completes and builds pass:
+
+```
+Layer 0: feat({module}): [domain+infra] {short description}
+Layer 1: feat({module}): [app+api] {short description}
+Layer 1: feat({module}): [frontend] {short description}  # if applicable
+Layer 2: feat({module}): [seed] {short description}       # if applicable
+```
+
+---
+
+## Save Output (if save_mode)
+
+Write to `{output_dir}/03-execute.md` with execution log per layer.
+
+---
+
+## NEXT STEP
+
+Load `steps/step-04-validate.md`

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

@@ -0,0 +1,138 @@
+---
+name: step-04-validate
+description: MCP validation, build verification, seed data check, acceptance criteria
+model: opus
+prev_step: steps/step-03-execute.md
+next_step: steps/step-05-examine.md
+---
+
+# Step 4: Validate
+
+**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
+# Backend
+dotnet clean && dotnet restore && dotnet build
+
+# Frontend (if applicable)
+npm run typecheck
+```
+
+**BLOCKING:** Both must pass. If failure, fix and retry.
+
+---
+
+## 5. Seed Data Completeness Check (if needs_seed_data)
+
+| File | Checks |
+|------|--------|
+| 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>()` |
+
+---
+
+## 6. 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.**
+
+---
+
+## 7. Validation Summary
+
+```
+**APEX SmartStack - Validation Complete**
+
+| Check | Status |
+|-------|--------|
+| MCP validate_conventions | PASS (0 errors) |
+| EF Core migrations | PASS / N/A |
+| Frontend routes | PASS / N/A |
+| dotnet build | PASS |
+| npm typecheck | PASS / N/A |
+| Seed data | PASS / N/A |
+| Acceptance criteria | {X}/{Y} PASS |
+```
+
+---
+
+## 8. Save Output (if save_mode)
+
+Write to `{output_dir}/04-validate.md` with validation results.
+
+---
+
+## 9. Route to Next Step
+
+```
+IF examine_mode = true:
+  → Load steps/step-05-examine.md
+
+ELSE IF test_mode = true:
+  → Load steps/step-07-tests.md
+
+ELSE IF pr_mode = true:
+  → Create PR and show final summary
+
+ELSE:
+  → Show final summary and exit
+```
+
+---
+
+## FINAL SUMMARY (if no more steps)
+
+Display: task, context, files created/modified, validation status, commits count, next steps (git diff, dotnet test, deploy).

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

@@ -0,0 +1,124 @@
+---
+name: step-05-examine
+description: Adversarial code review of changes — find issues before they reach production
+model: opus
+prev_step: steps/step-04-validate.md
+next_step: steps/step-06-resolve.md
+---
+
+# Step 5: Examine (if -x)
+
+**Goal:** Review the code as an adversarial external reviewer. Find bugs, security issues, and convention violations that automated checks missed.
+
+---
+
+## 1. Gather Changed Files
+
+```bash
+git diff --name-only HEAD~{commit_count}
+```
+
+List all files modified during this APEX session.
+
+---
+
+## 2. MCP Code Review
+
+```
+Call: mcp__smartstack__review_code
+  scope: "changed"      # Only review files changed in this session
+
+Call: mcp__smartstack__analyze_code_quality
+  scope: "changed"
+```
+
+---
+
+## 3. Manual Adversarial Review
+
+For each changed file, check:
+
+**Security (OWASP):**
+- [ ] `[RequirePermission]` on every endpoint (not `[Authorize]`)
+- [ ] No SQL injection (parameterized queries, EF Core only)
+- [ ] No XSS (React auto-escapes, but check dangerouslySetInnerHTML)
+- [ ] Multi-tenant isolation (IHasData filter applied)
+- [ ] No secrets in code
+
+**Architecture:**
+- [ ] Entities in correct Domain folder
+- [ ] Configs in correct Infrastructure folder
+- [ ] Services follow CQRS pattern
+- [ ] DTOs separate from domain entities
+- [ ] Controllers return DTOs, not entities
+- [ ] Frontend in correct hierarchy (Context/App/Module)
+
+**SmartStack conventions:**
+- [ ] Deterministic GUIDs in seed data (not Guid.NewGuid())
+- [ ] 4 languages in translations
+- [ ] CSS variables (not hardcoded colors)
+- [ ] SmartTable/SmartForm (not raw HTML tables/forms)
+- [ ] Correct Layout wrapper per context
+
+---
+
+## 4. Produce Findings
+
+For each issue found, classify:
+
+```
+[BLOCKING] — Must fix before completion
+[SUGGESTION] — Should fix, quality improvement
+[NIT] — Minor style/preference issue
+```
+
+**Findings format:**
+
+```markdown
+### Finding F01 [BLOCKING]
+**File:** {path}:{line}
+**Issue:** {description}
+**Fix:** {recommended fix}
+
+### Finding F02 [SUGGESTION]
+**File:** {path}:{line}
+**Issue:** {description}
+**Fix:** {recommended fix}
+```
+
+---
+
+## 5. Summary
+
+```
+**APEX SmartStack - Examine Complete**
+
+**Files reviewed:** {count}
+**Findings:** {blocking} BLOCKING, {suggestions} SUGGESTION, {nits} NIT
+
+{findings table}
+```
+
+---
+
+## 6. Save Output (if save_mode)
+
+Write to `{output_dir}/05-examine.md` with all findings.
+
+---
+
+## 7. Route to Next Step
+
+```
+IF BLOCKING findings exist:
+  → Load steps/step-06-resolve.md
+
+ELSE IF test_mode = true:
+  → Load steps/step-07-tests.md
+
+ELSE IF pr_mode = true:
+  → Create PR and show final summary
+
+ELSE:
+  → Show final summary and exit
+```

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

@@ -0,0 +1,105 @@
+---
+name: step-06-resolve
+description: Fix BLOCKING findings from adversarial review
+model: opus
+prev_step: steps/step-05-examine.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.
+
+---
+
+## 1. Process BLOCKING Findings
+
+For each BLOCKING finding from step-05:
+
+```
+Finding: {F01, F02, ...}
+File: {path}
+Issue: {description}
+Fix approach: {use appropriate skill/MCP tool}
+```
+
+**Fixing rules:**
+- Use the SAME skill/MCP that created the original code
+- If the finding is in a controller → use /controller or MCP scaffold_extension
+- If the finding is in seed data → use MCP generate_permissions
+- If the finding is in frontend → use /ui-components or MCP scaffold_routes
+- NEVER fix by writing raw SmartStack code
+
+---
+
+## 2. Apply Fixes
+
+For each finding:
+
+```
+1. Read the file to understand current state
+2. Apply fix via appropriate skill/MCP
+3. Verify fix addresses the finding
+4. Mark finding as RESOLVED
+```
+
+---
+
+## 3. Re-Validate
+
+After all BLOCKING findings are fixed:
+
+```
+1. MCP validate_conventions → 0 errors
+2. dotnet build --no-restore → PASS
+3. npm run typecheck → PASS (if frontend)
+```
+
+---
+
+## 4. Commit Fixes
+
+```
+fix({module}): resolve review findings {F01, F02, ...}
+```
+
+---
+
+## 5. Resolution Summary
+
+```
+**APEX SmartStack - Resolve Complete**
+
+**BLOCKING findings:** {count}
+**Resolved:** {count}
+**Remaining:** {count} (should be 0)
+
+| Finding | Status | Fix Applied |
+|---------|--------|-------------|
+| F01 | RESOLVED | {description} |
+| F02 | RESOLVED | {description} |
+```
+
+---
+
+## 6. Save Output (if save_mode)
+
+Write to `{output_dir}/06-resolve.md` with resolution log.
+
+---
+
+## 7. Route to Next Step
+
+```
+IF remaining BLOCKING > 0:
+  → Loop: fix remaining, re-validate
+
+IF test_mode = true:
+  → Load steps/step-07-tests.md
+
+ELSE IF pr_mode = true:
+  → Create PR and show final summary
+
+ELSE:
+  → Show final summary and exit
+```