@atlashub/smartstack-cli 3.8.0 → 3.10.0

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

@@ -0,0 +1,169 @@
+---
+name: step-01-analyze
+description: Explore existing code to understand what exists — do NOT plan yet
+model: opus
+prev_step: steps/step-00-init.md
+next_step: steps/step-02-plan.md
+---
+
+# Step 1: Analyze
+
+**Goal:** Understand what EXISTS in the codebase. Pure exploration, NO planning.
+
+## LOAD CONDITIONALLY
+
+- If NOT `{economy_mode}`: read `references/agent-teams-protocol.md`
+
+---
+
+## 1. Context Sources
+
+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.
+
+---
+
+## 2. Code Exploration
+
+### If economy_mode: Direct Tools
+
+Use Glob, Grep, Read, and MCP tools directly:
+
+```
+Backend:
+- Glob("**/Domain/Entities/**/{module_code}/**/*.cs")
+- Glob("**/Infrastructure/Persistence/Configurations/**/{module_code}/**/*.cs")
+- Glob("**/Application/Services/**/{module_code}/**/*.cs")
+- Glob("**/Api/Controllers/**/*{module_code}*Controller.cs")
+- Glob("**/Infrastructure/Persistence/Seeding/Data/{module_code}/**/*.cs")
+
+Frontend:
+- Glob("src/pages/**/{module_code}/**/*.tsx")
+- Glob("src/components/**/{module_code}/**/*.tsx")
+
+MCP:
+- mcp__smartstack__api_docs → existing API surface
+- mcp__smartstack__analyze_extension_points → React extension points
+```
+
+### If NOT economy_mode: Agent Teams
+
+> **Protocol:** See `references/agent-teams-protocol.md`
+
+```
+TeamCreate("apex-analyze", description: "Scan SmartStack project for existing code")
+
+Spawn 3 teammates (Sonnet, read-only tools: Glob, Grep, Read):
+
+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/"
+
+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/"
+
+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."
+
+Wait for all 3 teammates to report via SendMessage (DM to lead).
+Aggregate results.
+
+Shutdown teammates → 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?
+
+---
+
+## 4. Gap Analysis
+
+Compare what EXISTS vs what the TASK REQUIRES:
+
+```
+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"
+```
+
+---
+
+## 5. 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}
+...
+```
+
+---
+
+## 6. Save Output (if save_mode)
+
+Write to `{output_dir}/01-analyze.md` with analysis results.
+
+---
+
+## NEXT STEP
+
+Load `steps/step-02-plan.md`

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).