@atlashub/smartstack-cli 3.7.0 → 3.9.0

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`

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`