@atlashub/smartstack-cli 3.8.0 → 3.10.0

package/templates/skills/apex/SKILL.md

@@ -0,0 +1,120 @@
+---
+name: apex
+description: |
+  SmartStack incremental development using APEX methodology (Analyze-Plan-Execute-eXamine).
+  Use this skill when:
+  - Adding a new section/resource to an existing module
+  - Developing feature by feature without /business-analyse
+  - Fixing or extending code generated by /ralph-loop
+  - Any incremental SmartStack development task
+argument-hint: "[-a] [-x] [-s] [-t] [-e] [-r] [-pr] <task description>"
+---
+
+<objective>
+Execute incremental SmartStack development using the APEX methodology. This skill knows the SmartStack hierarchy (context/application/module/section/resource), delegates code creation to existing skills (/controller, /application, /ui-components, /efcore, /notification, /workflow) and MCP tools, and validates via MCP conventions.
+
+**Key principle:** /apex ORCHESTRATES — it never generates SmartStack code directly. All generation goes through skills and MCP tools.
+</objective>
+
+<quick_start>
+
+```bash
+/apex add absence management to HR module           # Add section to module
+/apex -a fix the leave request controller            # Auto fix
+/apex -a -x -s -t -pr add PDF export to Orders      # Full workflow
+/apex -e add status field to Project entity          # Economy (no agents)
+/apex -r                                             # Resume previous
+```
+
+</quick_start>
+
+<parameters>
+
+| Flag | Description |
+|------|-------------|
+| `-a` | Auto mode: skip confirmations |
+| `-x` | Examine mode: adversarial code review |
+| `-s` | Save mode: output to `.claude/output/apex/` |
+| `-t` | Test mode: scaffold + run tests via MCP |
+| `-e` | Economy mode: no subagents |
+| `-r` | Resume: continue from previous state |
+| `-pr` | PR mode: create pull request at end |
+
+</parameters>
+
+<state_variables>
+
+| Variable | Type | Description |
+|----------|------|-------------|
+| `{task_description}` | string | What to implement (flags removed) |
+| `{task_id}` | string | Kebab-case identifier |
+| `{auto_mode}` | boolean | Skip confirmations |
+| `{examine_mode}` | boolean | Adversarial review |
+| `{save_mode}` | boolean | Save outputs to `.claude/output/apex/{task-id}/` |
+| `{test_mode}` | boolean | Include test steps (07-08) |
+| `{economy_mode}` | boolean | No subagents |
+| `{pr_mode}` | boolean | Create PR at end |
+| `{context_code}` | string | "business", "platform", "personal" |
+| `{app_name}` | string | Application name |
+| `{module_code}` | string | Module code |
+| `{sections}` | string[] | Sections being added/modified |
+| `{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 |
+</state_variables>
+
+<entry_point>
+
+**FIRST ACTION:** Load `steps/step-00-init.md`
+
+</entry_point>
+
+<step_files>
+**Progressive loading - only load current step:**
+
+| Step | File | Model | Purpose |
+|------|------|-------|---------|
+| 00 | `steps/step-00-init.md` | Sonnet | Parse flags, detect SmartStack context, verify MCP |
+| 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) |
+| 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>
+
+<reference_files>
+**Loaded conditionally by steps that need them:**
+
+| File | Purpose | Loaded by |
+|------|---------|-----------|
+| `references/smartstack-layers.md` | Layer execution rules, skill/MCP mapping, seed data | step-02, step-03 |
+| `references/agent-teams-protocol.md` | TeamCreate, coordination, shutdown protocol | step-01, step-03 |
+</reference_files>
+
+<execution_rules>
+
+- **Load one step at a time** - Progressive loading to manage context
+- **ORCHESTRATE, never generate** - All SmartStack code via skills (/controller, /application, etc.) or MCP tools
+- **MCP-first** - Use MCP scaffold/validate tools before manual approaches
+- **Verify MCP at startup** - step-00 checks MCP availability
+- **Layer order** - domain -> infra -> migration(BLOCKING) -> app -> api -> frontend -> i18n -> tests
+- **Agent Teams** - Parallel execution for scan (step-01) and Layer 1 (step-03), unless economy_mode
+- **Save outputs** if `{save_mode}` = true
+- **Commits per layer** - Atomic commits after each execution layer
+
+</execution_rules>
+
+<success_criteria>
+- SmartStack context detected (context/app/module)
+- Plan validated with skill/MCP mapped for each file
+- Code created/corrected via existing skills and MCP (no direct generation)
+- MCP validate_conventions: 0 errors
+- Build: dotnet build PASS + npm run typecheck PASS (if frontend)
+- Seed data complete (navigation, permissions, roles, provider) if required
+- Tests: 100% pass, >= 80% coverage (if -t)
+- Commits atomic per layer
+</success_criteria>

package/templates/skills/apex/_shared.md

@@ -0,0 +1,86 @@
+# APEX Shared — SmartStack Detection & MCP References
+
+> **Loaded by:** step-00-init (always), other steps as needed
+
+---
+
+## SmartStack Project Detection
+
+### Scan Pattern
+
+1. `*.sln` → .NET backend confirmed
+2. `docs/business/` → BA artifacts exist
+3. `.ralph/prd-*.json` → PRDs exist
+4. `src/pages/` → React frontend exists
+
+### Context-to-Folder Mapping
+
+| Context | Backend | Controller | Frontend Layout |
+|---------|---------|------------|----------------|
+| `business` | `Business` | `Business` | `BusinessLayout` |
+| `platform.administration` | `Platform/Administration` | `Admin` | `AdminLayout` |
+| `platform.support` | `Platform/Support` | `Support` | `AdminLayout` |
+| `personal` | `Personal` | `User` | `UserLayout` |
+
+---
+
+## MCP Tools Reference
+
+### Mandatory (every execution)
+
+| Tool | Purpose | Step |
+|------|---------|------|
+| `validate_conventions` | Validate SmartStack conventions | 00 (check), 04 (validate) |
+
+### Generation (step-03)
+
+| Tool | Purpose | Condition |
+|------|---------|-----------|
+| `scaffold_extension` | Generate entities, services, controllers | New code creation |
+| `suggest_migration` | Get standardized migration name | EF Core changes |
+| `generate_permissions` | Generate RBAC permissions + seed data | New module/section |
+| `scaffold_api_client` | Generate TypeScript API client | Frontend changes |
+| `scaffold_routes` | Generate React Router routes | Frontend changes |
+
+### Validation (step-04)
+
+| Tool | Purpose | Condition |
+|------|---------|-----------|
+| `check_migrations` | Validate EF Core migrations | Migration created |
+| `validate_frontend_routes` | Validate route/layout alignment | Frontend changes |
+| `validate_security` | Check security patterns | API changes |
+
+### Analysis (step-01)
+
+| Tool | Purpose |
+|------|---------|
+| `api_docs` | Existing API documentation |
+| `analyze_extension_points` | React extension points |
+
+### Tests (step-07, if -t)
+
+| Tool | Purpose |
+|------|---------|
+| `scaffold_tests` | Generate tests (domain, app, api, security) |
+| `suggest_test_scenarios` | Suggest test scenarios |
+| `analyze_test_coverage` | Check coverage percentage |
+
+### Review (step-05, if -x)
+
+| Tool | Purpose |
+|------|---------|
+| `review_code` | Adversarial code review |
+| `analyze_code_quality` | Code quality metrics |
+
+---
+
+## Existing Skills Delegation
+
+| Skill | When to delegate |
+|-------|-----------------|
+| `/controller` | Complex controller with custom routes |
+| `/application` | New context/application/module structure |
+| `/ui-components` | Complex React pages (tables, grids, dashboards) |
+| `/efcore` | Complex EF Core configurations |
+| `/notification` | In-app or email notifications |
+| `/workflow` | Automated workflow triggers |

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

@@ -0,0 +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: "general-purpose"
+  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 Assignment (T02/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 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/smartstack-layers.md

@@ -0,0 +1,173 @@
+# SmartStack Layers — Execution Rules & Skill/MCP Mapping
+
+> **Loaded by:** step-02 (planning) and step-03 (execution)
+> **Purpose:** Defines per-layer folder conventions, skill/MCP tools, and verification rules.
+
+---
+
+## Layer 0 — Domain (sequential)
+
+**Entities:** `Domain/Entities/{ContextPascal}/{App}/{Module}/`
+**Enums:** `Domain/Enums/{ContextPascal}/{App}/{Module}/`
+**Exceptions:** `Domain/Exceptions/{ContextPascal}/{App}/{Module}/`
+
+| Action | Tool |
+|--------|------|
+| Create entity | MCP `scaffold_extension` (type: entity) |
+| Validate | MCP `validate_conventions` |
+
+**Rules:**
+- Inherit `AuditableEntity`, implement `IHasData` for multi-tenant
+- Audit fields: CreatedAt, CreatedBy, ModifiedAt, ModifiedBy
+- Domain events for state changes
+- Value objects for composite values
+
+---
+
+## Layer 0 — Infrastructure: EF Core (sequential)
+
+**Configs:** `Infrastructure/Persistence/Configurations/{ContextPascal}/{App}/{Module}/`
+**Migrations:** `Infrastructure/Persistence/Migrations/` (NEVER subdirectories)
+
+| Action | Tool |
+|--------|------|
+| Create config | MCP `scaffold_extension` (type: configuration) |
+| Create migration | MCP `suggest_migration` → `dotnet ef migrations add` |
+| Validate | MCP `check_migrations` |
+
+**Rules:**
+- One config per entity, table name = plural
+- All relationships explicitly configured
+- Indexes on FKs and frequent queries
+- Register DbSet in ExtensionsDbContext
+- Migration name ALWAYS from MCP `suggest_migration`
+- Migration flag: `-o Persistence/Migrations`
+
+**BLOCKING:** `dotnet build --no-restore` MUST pass after migration.
+
+---
+
+## Layer 1 — Application (parallel with API)
+
+**Services:** `Application/Services/{ContextPascal}/{App}/{Module}/`
+**DTOs:** `Application/DTOs/{ContextPascal}/{App}/{Module}/`
+**Validators:** `Application/Validators/{ContextPascal}/{App}/{Module}/`
+
+| Action | Tool |
+|--------|------|
+| Create service/DTO | MCP `scaffold_extension` |
+| Complex service logic | /application skill |
+| Validate | MCP `validate_conventions` |
+
+**Rules:**
+- CQRS with MediatR
+- FluentValidation for all commands
+- DTOs separate from domain entities
+- Service interfaces in Application, implementations in Infrastructure
+
+---
+
+## Layer 1 — API (parallel with Application)
+
+**Controllers:** `Api/Controllers/{ContextShort}/{App}/{Entity}Controller.cs`
+
+| Context | Controller Folder |
+|---------|-------------------|
+| `platform.administration` | `Admin` |
+| `platform.support` | `Support` |
+| `business.*` | `Business` |
+| `personal.*` | `User` |
+
+| Action | Tool |
+|--------|------|
+| Simple CRUD controller | MCP `scaffold_extension` |
+| Complex controller | /controller skill |
+| Validate | MCP `validate_security` |
+
+**Rules:**
+- `[RequirePermission(Permissions.{Module}.{Action})]` on EVERY endpoint
+- NEVER use `[Authorize]` without specific permission
+- Swagger XML documentation
+- Return DTOs, never domain entities
+
+---
+
+## Layer 1 — Seed Data (parallel)
+
+**Folder:** `Infrastructure/Persistence/Seeding/Data/{ModulePascal}/`
+
+| Action | Tool |
+|--------|------|
+| Generate permissions | MCP `generate_permissions` (PRIMARY) |
+| Navigation seed | Template below |
+| Roles seed | Template below |
+| Provider | Template below |
+
+### Seed Data Chain (5 files)
+
+1. **NavigationModuleSeedData.cs** — Deterministic GUIDs (SHA256), 4 languages
+2. **PermissionsSeedData.cs** — MCP `generate_permissions` first, fallback template
+3. **RolesSeedData.cs** — Context-based: Admin=CRUD, Manager=CRU, Contributor=CR, Viewer=R
+4. **SeedConstants.cs** — Shared deterministic GUIDs
+5. **{App}SeedDataProvider.cs** — Implements IClientSeedDataProvider
+   - SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
+   - DI: `services.AddScoped<IClientSeedDataProvider, {App}SeedDataProvider>()`
+
+**FORBIDDEN:**
+- `Guid.NewGuid()` → use deterministic GUIDs (SHA256)
+- Missing translations (must have fr, en, it, de)
+- Empty seed classes with no seeding logic
+
+---
+
+## Layer 2 — Frontend (parallel with I18n)
+
+**Pages:** `src/pages/{ContextPascal}/{AppPascal}/{Module}/`
+**Components:** `src/components/{Module}/`
+
+| Action | Tool |
+|--------|------|
+| API client | MCP `scaffold_api_client` |
+| Routes | MCP `scaffold_routes` |
+| Complex pages | /ui-components skill |
+| Validate routes | MCP `validate_frontend_routes` |
+
+**Layout mapping:**
+
+| Context | Layout | Route prefix |
+|---------|--------|-------------|
+| `platform.*` | `AdminLayout` | `/platform` |
+| `business.*` | `BusinessLayout` | `/business` |
+| `personal.*` | `UserLayout` | `/personal/myspace` |
+
+**Components:** SmartTable, SmartFilter, EntityCard, SmartForm, StatCard (NEVER raw HTML)
+**CSS:** Variables only → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
+
+**FORBIDDEN:**
+- `src/pages/{Module}/` (flat, missing Context/App)
+- `import axios` → use `@/services/api/apiClient`
+- `<table>` → use SmartTable
+- Hardcoded colors → use CSS variables
+- Only fr/en → MUST have 4 languages
+
+---
+
+## Layer 2 — I18n
+
+4 JSON files: fr, en, it, de — identical key structures.
+
+---
+
+## Layer 3 — Tests (sequential, if -t)
+
+| Action | Tool |
+|--------|------|
+| Unit tests (domain) | MCP `scaffold_tests` (target_layer: domain) |
+| Unit tests (app) | MCP `scaffold_tests` (target_layer: application) |
+| Integration tests (api) | MCP `scaffold_tests` (target_layer: api, type: integration) |
+| Security tests | MCP `scaffold_tests` (type: security) |
+| Coverage check | MCP `analyze_test_coverage` |
+| Scenarios | MCP `suggest_test_scenarios` |
+
+**Target:** >= 80% coverage, 100% pass rate.
+**Fix CODE, not tests.**

package/templates/skills/apex/steps/step-00-init.md

@@ -0,0 +1,156 @@
+---
+name: step-00-init
+description: Parse flags, detect SmartStack context, verify MCP availability
+model: sonnet
+next_step: steps/step-01-analyze.md
+---
+
+# Step 0: Initialize
+
+## LOAD SHARED
+
+Read `_shared.md` for SmartStack detection patterns and MCP tools reference.
+
+---
+
+## 1. Parse Flags
+
+Extract flags from the raw input:
+
+```
+Input: "{raw_input}"
+
+Flags to detect: -a, -x, -s, -t, -e, -r, -pr
+Remaining text after flag removal = {task_description}
+```
+
+**Defaults:**
+
+```yaml
+auto_mode: false
+examine_mode: false
+save_mode: false
+test_mode: false
+economy_mode: false
+pr_mode: false
+resume_mode: false
+```
+
+---
+
+## 2. Detect SmartStack Context
+
+Scan the project to identify the SmartStack hierarchy:
+
+```
+1. Glob("*.sln") → confirm .NET project
+2. Glob("docs/business/**/*") → list existing BA artifacts
+3. Glob(".ralph/prd-*.json") → list existing PRDs
+4. Glob("src/pages/**/*.tsx") → confirm frontend exists
+```
+
+**From task description, infer:**
+- `{context_code}`: business (default), platform, personal
+- `{app_name}`: application name
+- `{module_code}`: target module
+- `{sections}`: sections being added/modified
+
+**From existing artifacts:**
+- `{prd_path}`: `.ralph/prd-{module_code}.json` if exists
+- `{feature_path}`: `docs/business/{app}/{module}/business-analyse/*/feature.json` if exists
+
+**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
+```
+
+---
+
+## 3. Verify MCP Availability
+
+```
+Call: mcp__smartstack__validate_conventions (quick connectivity test)
+
+IF success → MCP available, proceed normally
+IF failure → warn user, continue in degraded mode (manual tools only)
+```
+
+---
+
+## 4. Determine Needs
+
+```
+needs_seed_data = true IF:
+  - New module or new section with navigation entries
+  - Task mentions "navigation", "permissions", "roles", "seed"
+
+needs_migration = true IF:
+  - New entities or entity modifications detected
+  - Task mentions "entity", "field", "table", "column", "migration"
+```
+
+---
+
+## 5. Resume Mode (if -r)
+
+```
+IF resume_mode:
+  1. Read .claude/output/apex/ → find latest task folder
+  2. Read 00-context.md → restore state variables
+  3. Find last completed step file
+  4. Route to next step directly
+  → SKIP to identified next step
+```
+
+---
+
+## 6. Save Mode Setup (if -s)
+
+```
+IF save_mode:
+  1. Generate task_id: NN-kebab-case from task_description
+  2. Create .claude/output/apex/{task_id}/
+  3. Write 00-context.md with:
+     - Timestamp
+     - All state variables (generic + SmartStack)
+     - Flags
+     - Detected hierarchy
+```
+
+---
+
+## 7. Display Context Summary
+
+```
+**APEX SmartStack - Initialization Complete**
+
+**Task:** {task_description}
+**Context:** {context_code} / {app_name} / {module_code}
+**Sections:** {sections}
+
+**Sources:**
+- PRD: {prd_path || "none"}
+- Feature: {feature_path || "none"}
+
+**Flags:** {active_flags}
+**MCP:** {available|degraded}
+**Needs migration:** {yes|no}
+**Needs seed data:** {yes|no}
+```
+
+---
+
+## NEXT STEP
+
+Load `steps/step-01-analyze.md`