@atlashub/smartstack-cli 3.9.0 → 3.12.0

package/templates/skills/debug/references/team-protocol.md

@@ -0,0 +1,232 @@
+# Team Protocol — Debug Investigation
+
+> **Loaded by:** SKILL.md phase 2 (EXPLORE)
+> **Purpose:** Coordinate parallel investigation agents for bug diagnosis.
+> **Pattern:** APEX-style (single session, parallel scan, aggregated results)
+
+---
+
+## 1. Team Creation
+
+```yaml
+TeamCreate:
+  team_name: "debug-investigate"
+  description: "Parallel bug investigation team"
+```
+
+---
+
+## 2. Teammate Spawn
+
+Spawn all teammates **in a single message** (parallel Task calls):
+
+| Teammate | Model | Scope | Tools |
+|----------|-------|-------|-------|
+| `code-investigator` | haiku | Codebase search | Read, Glob, Grep, Bash |
+| `doc-researcher` | haiku | Documentation + web | Read, Glob, Grep, WebSearch, WebFetch |
+| `data-inspector` | haiku | Database READ-ONLY | Read, Glob, Grep, Bash |
+
+**`data-inspector`**: spawn ONLY if the bug involves data, persistence, or database operations. Otherwise spawn only 2 teammates.
+
+```yaml
+# For each teammate:
+Task:
+  subagent_type: "general-purpose"
+  team_name: "debug-investigate"
+  name: "{teammate-name}"
+  model: "haiku"
+  mode: "bypassPermissions"
+  prompt: "{TEAMMATE_PROMPT}"
+```
+
+---
+
+## 3. Communication Protocol
+
+### Messages from teammates → team-lead
+
+| Message | When | Format |
+|---------|------|--------|
+| `FINDING` | Significant discovery | `FINDING: {description with file paths and line numbers}` |
+| `INVESTIGATION_COMPLETE` | Agent finished all checks | `INVESTIGATION_COMPLETE: {summary of all findings}` |
+
+**Rules:**
+- Send `FINDING` as soon as a significant discovery is made (don't wait until the end)
+- Always include **file paths with line numbers** in findings
+- Send exactly ONE `INVESTIGATION_COMPLETE` when done
+
+### Messages from team-lead → teammates
+
+| Message | When | Format |
+|---------|------|--------|
+| `LEAD_HINT` | Lead wants to orient a search | `LEAD_HINT: {new direction to investigate}` |
+
+**Rules:**
+- Lead sends hints based on cross-agent findings (e.g., code-investigator found a file, ask data-inspector to check related records)
+- Hints are optional — only when findings from one agent inform another's search
+
+### Example Flow
+
+```
+code-investigator → lead:  FINDING: NullRef at OrderService.cs:45 — Customer lookup returns null
+lead → data-inspector:     LEAD_HINT: Check if Customer records exist for OrderId=123, verify FK integrity Orders→Customers
+data-inspector → lead:     FINDING: FK broken — Order.CustomerId=99 has no matching Customer record (deleted without cascade)
+doc-researcher → lead:     FINDING: EF Core docs warn about cascade delete config — OnDelete(DeleteBehavior.Restrict) may leave orphans
+code-investigator → lead:  INVESTIGATION_COMPLETE: Source at OrderService.cs:45, no null check before Customer access
+data-inspector → lead:     INVESTIGATION_COMPLETE: 3 orphaned Orders found, TenantId OK, audit fields present
+doc-researcher → lead:     INVESTIGATION_COMPLETE: EF Core cascade delete misconfiguration documented
+```
+
+---
+
+## 4. Teammate Prompts
+
+### code-investigator
+
+```
+You are a code investigator on the debug team.
+
+## Bug Context
+Error: {error_description}
+Stack trace: {stack_trace}
+
+## Your Mission
+1. Locate the error source in code (from stack trace)
+2. Find related error handling patterns
+3. Identify similar code that works correctly (for comparison)
+4. Check recent commits on affected files (git log --oneline -10, git blame)
+5. Search for similar error patterns elsewhere in codebase
+
+## Communication Protocol
+- Send FINDING messages to team-lead for each significant discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
+- When done, send:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Code investigation done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Tools
+- Read, Glob, Grep for code search
+- Bash ONLY for: git log, git blame, git diff (NEVER for code modification)
+
+## Output
+Report file paths with line numbers. Be precise and factual.
+```
+
+### doc-researcher
+
+```
+You are a documentation researcher on the debug team.
+
+## Bug Context
+Error: {error_description}
+Libraries/frameworks in stack trace: {libraries_in_stacktrace}
+
+## Your Mission
+1. Research documentation for libraries in the stack trace
+2. Find known issues or breaking changes
+3. Find correct usage patterns
+4. Search for similar issues reported by others online
+5. Look for migration guides if version issues suspected
+
+## Communication Protocol
+- Send FINDING messages to team-lead for each discovery:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Found {short}")
+- When done, send:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "Doc research done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Tools
+- Read, Glob, Grep for local documentation search
+- WebSearch, WebFetch for online documentation and issue trackers
+```
+
+### data-inspector
+
+```
+You are a READ-ONLY database inspector on the debug team.
+
+## Bug Context
+Error: {error_description}
+
+## ABSOLUTE RESTRICTIONS — READ BEFORE EVERY BASH COMMAND
+YOU MUST NEVER EXECUTE:
+- INSERT, UPDATE, DELETE, MERGE, TRUNCATE
+- DROP, ALTER, CREATE, RENAME
+- EXEC, EXECUTE (stored procedures)
+- dotnet ef database update, dotnet ef migrations
+- ANY command that writes, modifies, or deletes data or schema
+
+YOU MAY ONLY EXECUTE:
+- SELECT queries
+- INFORMATION_SCHEMA queries
+- sys.* catalog views
+- sp_help, sp_helptext, sp_columns
+
+## Your Mission
+1. Find the connection string (appsettings.json, appsettings.Development.json)
+2. Check record existence and field values for affected entities
+3. Verify foreign key integrity (orphaned records)
+4. Check tenant isolation (TenantId present on all records)
+5. Verify soft delete and audit field consistency
+6. Compare actual schema vs expected EF Core model
+
+## Communication Protocol
+- Send FINDING messages to team-lead for each data anomaly:
+  SendMessage(type: "message", recipient: "team-lead", content: "FINDING: {description}", summary: "Data issue {short}")
+- When done, send:
+  SendMessage(type: "message", recipient: "team-lead", content: "INVESTIGATION_COMPLETE: {summary}", summary: "DB inspection done")
+- If team-lead sends a LEAD_HINT, follow that direction
+
+## Tools
+- Read, Glob, Grep for connection string and config discovery
+- Bash ONLY for SELECT queries (NEVER modify data)
+
+## Output
+- Use markdown tables for query results
+- Mask sensitive data (passwords, tokens, PII)
+- Limit results with TOP/LIMIT to avoid overwhelming output
+- If a data fix is needed, DESCRIBE it — NEVER execute it
+```
+
+---
+
+## 5. Team Lead Aggregation
+
+After receiving all `INVESTIGATION_COMPLETE` messages:
+
+```
+1. Collect all FINDING messages from each agent
+2. Cross-reference findings (code issues ↔ data anomalies ↔ documentation)
+3. Build the root cause chain: symptom → immediate cause → root cause
+4. Shutdown teammates
+5. Proceed to ULTRA-THINK phase (inline)
+```
+
+---
+
+## 6. Graceful Shutdown
+
+After aggregation (or if investigation is sufficient before all complete):
+
+```yaml
+# For each teammate:
+SendMessage:
+  type: "shutdown_request"
+  recipient: "{teammate-name}"
+  content: "Investigation complete, shutting down"
+
+# Wait for shutdown_response from each, then:
+TeamDelete
+```
+
+---
+
+## 7. Decision Matrix
+
+| Condition | Action |
+|-----------|--------|
+| Simple error, obvious from stack trace | NO team — inline investigation |
+| Error involves code + data | Team: code-investigator + data-inspector |
+| Error involves unknown library | Team: code-investigator + doc-researcher |
+| Complex bug, multiple suspects | Full team: all 3 agents |
+| Performance issue (no error) | code-investigator only (profiling inline) |

package/templates/skills/ralph-loop/references/category-rules.md

@@ -75,10 +75,17 @@ Execution sequence:
 - IClientSeedDataProvider: SeedNavigationAsync + SeedPermissionsAsync + SeedRolePermissionsAsync
 - DI: `services.AddScoped<IClientSeedDataProvider, {AppPascalName}SeedDataProvider>()`
 
+**Business seed data (DevDataSeeder):**
+- ALL seeded business entities MUST include `TenantId = {tenantGuid}`
+- Reference entities (types, categories, statuses) MUST set TenantId
+- Use deterministic TenantId from SeedConstants (NEVER hardcoded inline)
+- DevDataSeeder MUST implement `IDevDataSeeder` with idempotent `SeedAsync()` method
+
 **FORBIDDEN:**
 - `Guid.NewGuid()` → use deterministic GUIDs
 - Empty seed data classes with only GUIDs and no seeding methods
 - Missing translations (must have all 4 languages)
+- Seeding business entities WITHOUT `TenantId`
 
 ---
 
@@ -118,6 +125,24 @@ Rules:
 - DTOs separate from domain entities
 - Service interfaces in Application, implementations in Infrastructure
 
+**Lifecycle-aware services:**
+- Services operating on entities with a `lifeCycle` (status field) MUST validate entity state before mutations
+- Example: `if (entity.Status == EmployeeStatus.Terminated) throw new BusinessException("Cannot update terminated employee")`
+- Guard checks MUST match the `allowedTransitions` from the entity's lifecycle definition
+- Delete/archive operations MUST respect terminal states (`isTerminal: true`)
+
+**Validator completeness (BLOCKING):**
+- For EVERY `Create{Entity}Validator`, a matching `Update{Entity}Validator` MUST exist
+- ALL validators MUST be registered in `Application/DependencyInjection.cs`:
+  `services.AddValidatorsFromAssemblyContaining<Create{Entity}Validator>()`
+- DependencyInjection.cs MUST NOT be empty or contain only TODO comments
+- After writing validators, VERIFY DI registration exists — if missing, add it immediately
+
+**FORBIDDEN:**
+- Empty DependencyInjection.cs with `// TODO` placeholder
+- CreateValidator without matching UpdateValidator
+- Validators not registered in DI container
+
 ---
 
 ## API
@@ -140,9 +165,15 @@ Rules:
 - Consistent route patterns: `api/{context}/{app}/{module}`
 - Return DTOs, never domain entities
 
+**Controller coverage (BLOCKING):**
+- EVERY entity in the module MUST have a controller with CRUD endpoints (GET list, GET by id, POST, PUT, DELETE)
+- Reference/lookup entities (types, categories, statuses) MUST also have controllers — they are needed for dropdowns and configuration
+- Count: `controllers created >= entities in module`. If fewer → FAIL
+
 **FORBIDDEN:**
 - `[Authorize]` without specific permission → use `[RequirePermission]`
 - Returning domain entities directly
+- Skipping controllers for reference/lookup entities
 
 ---
 
@@ -178,6 +209,18 @@ Rules:
 
 **CSS:** Variables ONLY → `bg-[var(--bg-card)]`, `text-[var(--text-primary)]`
 
+**Form error handling (MANDATORY):**
+- ALL SmartForm components MUST include `onError` callback for API errors
+- Validation errors MUST be displayed inline next to the relevant field
+- API errors (4xx, 5xx) MUST show a user-friendly error notification (toast/banner)
+- Forms MUST preserve user input on error (no data loss on failed submit)
+
+**Dependency verification (BLOCKING):**
+- BEFORE writing any import, verify the package exists in `package.json`
+- If package not present: run `npm install {package}` BEFORE writing the import
+- Common missing packages: @tanstack/react-query, recharts, date-fns, react-router-dom
+- After ALL frontend tasks: run `npm ls --depth=0` to detect any MISSING dependencies
+
 **FORBIDDEN patterns (any = FAIL):**
 ```
 import axios from 'axios'                    → use @/services/api/apiClient
@@ -186,6 +229,9 @@ import axios from 'axios'                    → use @/services/api/apiClient
 <Route path="/business/app/mod" />           → MUST be nested inside Layout
 Only fr/en translations                      → MUST have 4 languages
 src/pages/{Module}/                          → MUST be src/pages/{Context}/{App}/{Module}/
+'00000000-0000-0000-0000-000000000000'       → use dynamic ID from auth context or route params
+const api = axios.create(...)                → use @/services/api/apiClient (single instance)
+useXxx with raw axios inside hooks           → hooks MUST use the shared apiClient from @/services/api
 ```
 
 ---

package/templates/skills/ralph-loop/references/compact-loop.md

@@ -71,8 +71,25 @@ Batch: {batch.length} [{firstCategory}] → {batch.map(t => `[${t.id}] ${t.descr
    - Backend (domain/infra/app/api): `dotnet build --no-restore` → MUST exit 0
    - Frontend: `npm run typecheck` → MUST exit 0
 3. If build fails → read FULL error output → fix source code → rebuild → loop until pass
-4. Verify acceptance criteria
-5. If failed after 3 attempts: `task.status = 'failed'`, `task.error = reason`, continue to next in batch
+4. **ARTIFACT verification (BLOCKING per task):**
+   - `files_created` MUST NOT be empty for code-generating tasks
+   - Category-specific checks (see below)
+   - IF no artifacts produced → task.status = 'failed', task.error = 'No artifacts created'
+5. Verify acceptance criteria from task description
+6. If failed after 3 attempts: `task.status = 'failed'`, `task.error = reason`, continue to next in batch
+
+**Category-specific artifact checks (step 4 above):**
+
+| Category | Artifact Check | FAIL if |
+|----------|---------------|---------|
+| `domain` | Entity .cs files exist in Domain/ | 0 files created |
+| `infrastructure` with migration | `Migrations/` folder has .cs files | No migration files |
+| `infrastructure` with seed data | Seed data .cs files exist | 0 files created |
+| `application` | Service + DTO + Validator files exist | 0 files created |
+| `api` | Controller .cs files exist | 0 files created |
+| `frontend` | .tsx page files exist | 0 files created |
+| `test` | Test project dir exists AND contains test .cs files | No test project or 0 test files |
+| `validation` | `dotnet test` exit 0 AND `dotnet build` exit 0 | Either command fails |
 
 **Category-specific triggers:**
 
@@ -99,12 +116,25 @@ Batch: {batch.length} [{firstCategory}] → {batch.map(t => `[${t.id}] ${t.descr
    ```
    If FAIL → fix source code (NOT tests) → rebuild → retest → loop until 100% pass
 
+2bis. **DI completeness (if application tasks in batch):**
+   Verify `Application/DependencyInjection.cs` registers all validators and services:
+   - Count validators in `Validators/` folder
+   - Verify `AddValidatorsFromAssemblyContaining` is present
+   - If empty/TODO → FAIL → fix DI registration → rebuild
+
 3. **Frontend (if frontend/i18n tasks in batch):**
    ```bash
    npm run typecheck && npm run lint
    ```
    If FAIL → fix → re-check → loop until pass
 
+3bis. **Dependency audit (if frontend tasks in batch):**
+   ```bash
+   cd {frontend_dir}
+   npm ls --depth=0 2>&1 | grep "MISSING" && echo "FAIL: missing deps" && exit 1
+   ```
+   If FAIL → `npm install {missing_packages}` → re-check → loop until pass
+
 4. **MCP validation:**
    `mcp__smartstack__validate_conventions` ONCE for the whole batch