# Skills SmartStack - Shared Functions

> **SmartStack CLI** v{{SMARTSTACK_VERSION}}

## Model Strategy

| Task | Model | Reason |
|------|-------|--------|
| Code generation | **Sonnet** | Optimal quality/cost ratio |
| Security audit | **Opus** | Critical analysis required |
| Final validation | **Opus** | Architectural decisions |

## SmartStack Architecture

```
Domain → Application → Infrastructure → API → Web
```

### Layers
| Layer | Responsibility | Namespace | Folder Hierarchy |
|-------|-----------------|-----------|------------------|
| Domain | Entities, ValueObjects | `SmartStack.Domain.{App}.{Module}` | `Domain/{App}/{Module}/` |
| Application | Interfaces (Common), DTOs | `SmartStack.Application.Common.Interfaces` / `.{App}.{Module}.DTOs` | `Application/Common/Interfaces/` + `Application/{App}/{Module}/DTOs/` |
| Infrastructure | Service Impl, EF Core | `SmartStack.Infrastructure.Services.{App}.{Module}` | `Infrastructure/Services/{App}/{Module}/` + `Persistence/Configurations/{App}/{Module}/` |
| API | Controllers, Middleware | `SmartStack.Api.Controllers` | `Api/Controllers/` |
| Web | React components, pages | N/A | `pages/{app}/{module}/` + `components/{module}/` |

## Permissions (2 mandatory files)

### 1. Permissions.cs (Application layer)
```csharp
public static class {Module}
{
    public const string View = "{app}.{module}.view";
    public const string Create = "{app}.{module}.create";
    public const string Update = "{app}.{module}.update";
    public const string Delete = "{app}.{module}.delete";
}
```

### 2. PermissionConfiguration.cs (Infrastructure layer)
```csharp
builder.HasData(
    new { Id = nextId++, Path = Permissions.{Module}.View, ... },
    new { Id = nextId++, Path = Permissions.{Module}.Create, ... },
    ...
);
```

## i18n (4 mandatory languages)

| Language | File | Code |
|----------|------|------|
| French | `fr.json` | `fr` |
| English | `en.json` | `en` |
| Italian | `it.json` | `it` |
| German | `de.json` | `de` |

### i18n Structure
```json
{
  "{application}": {
    "{module}": {
      "title": "...",
      "fields": { ... },
      "actions": { ... },
      "messages": { ... }
    }
  }
}
```

## Common Services to Inject

| Service | Usage |
|---------|-------|
| `IApplicationDbContext` | DB access |
| `ICurrentUserService` | Current user |
| `ILogger<T>` | Logging |
| `IMapper` | AutoMapper |
| `IPermissionService` | Permission cache |

## Security Validation

### Critical Logs
| Event | Level |
|-------|-------|
| Failed login | `Critical` |
| Permission denied | `Critical` |
| Account locked | `Critical` |
| Password change | `Warning` |
| Deletion | `Warning` |

### System Account Protection
```csharp
if (entity.UserType == UserType.System || entity.UserType == UserType.LocalAdmin)
    return BadRequest(new { message = "Cannot modify system accounts" });
```

## FORBIDDEN: Temporary Files and Scripts (ALL SKILLS)

> **ABSOLUTE PROHIBITION: NEVER create temporary files, scripts, or helper files.**

This includes but is not limited to:
- `.ps1`, `.sh`, `.bat`, `.cmd` scripts
- `temp-*`, `tmp-*`, `helper-*` files
- Any file created solely to discover types, scan DLLs, or read metadata

**How to discover .NET types WITHOUT scripts:**
| Need | Tool to Use |
|------|-------------|
| Find a class/entity | `Grep` for `class {Name}` in `*.cs` files |
| Find services/interfaces | `Glob` for `**/I*Service.cs` in Application layer |
| Find NuGet packages | `Read` the `.csproj` file directly |
| Find existing entities | `Glob` for `**/*.cs` in Domain layer |
| Validate conventions | MCP `validate_conventions` tool |
| Cannot find after 2 tries | **ASK the user** |

**If you catch yourself about to create a script file: STOP. Use the tools above instead.**

## Common Validation Checklist

```
□ Permissions created (Permissions.cs + PermissionConfiguration.cs)
□ EF Core migration created
□ i18n 4 languages (fr, en, it, de)
□ Unit tests
□ API documentation (ProducesResponseType)
```

## MCP Prerequisite Guard (BLOCKING)

Skills that depend on SmartStack MCP **MUST** verify connectivity before proceeding. This check is **BLOCKING** - the skill cannot continue without MCP.

### Detection Method

At skill initialization (step-00-init), attempt a minimal MCP call:

```
mcp__smartstack__validate_conventions({ checks: ["tables"] })
```

### Decision Matrix

| Result | Action |
|--------|--------|
| Success response | Set `mcp_available = true`, continue workflow |
| Connection error / tool not found | **STOP EXECUTION** - display error below |

### Blocking Error (STOP)

If MCP is not available, display this message and **STOP the skill immediately**:

```
═══════════════════════════════════════════════════════════════
  MCP SMARTSTACK NOT AVAILABLE - SKILL BLOCKED
═══════════════════════════════════════════════════════════════

  The SmartStack MCP server is required for this skill but
  could not be reached.

  To install:
    claude mcp add smartstack -- npx --package @atlashub/smartstack-cli smartstack-mcp

  To verify:
    /mcp healthcheck

  After installation, restart Claude Code and retry.

═══════════════════════════════════════════════════════════════
```

**DO NOT** offer fallback modes, manual instructions, or degraded execution. The skill MUST stop.

### Skills Requiring MCP

| Skill | MCP Required | Reason |
|-------|:---:|--------|
| business-analyse | **YES** | Analysis, specification, validation |
| application | **YES** | Navigation + code generation |
| controller | **YES** | Controller scaffolding |
| business-analyse-develop | **YES** | Iterative code generation |
| validate | **YES** | Convention validation |
| efcore | **YES** | Migration management |
| review-code | **YES** | Code review |
| gitflow | NO | Git operations only |
| explore | NO | Code search only |
| mcp | NO | Self-check skill |

## MCP Tools References

### Outils Core

| Tool | Usage | Used By |
|------|-------|---------|
| `mcp__smartstack__validate_conventions` | Valider conventions SmartStack (tables, migrations, services, namespaces, entities, tenants, controllers) | application, controller, business-analyse-develop |
| `mcp__smartstack__scaffold_extension` | Génération code (feature, entity, service, controller, component, dto, validator, repository) | application, business-analyse-develop |
| `mcp__smartstack__check_migrations` | Analyser migrations EF Core (conflits, ordre, ModelSnapshot) | application, business-analyse-develop |
| `mcp__smartstack__api_docs` | Documentation API depuis Swagger/OpenAPI ou controllers | controller |
| `mcp__smartstack__suggest_migration` | Suggérer nom migration ({context}_v{version}_{sequence}_{Description}) | application, business-analyse-develop |
| `mcp__smartstack__generate_permissions` | Générer permissions RBAC depuis NavRoute | application, business-analyse-develop |

### Outils Tests

| Tool | Usage | Used By |
|------|-------|---------|
| `mcp__smartstack__scaffold_tests` | Générer tests unitaires/intégration/sécurité | application, business-analyse-develop |
| `mcp__smartstack__analyze_test_coverage` | Analyser couverture de tests du projet | business-analyse-develop |
| `mcp__smartstack__validate_test_conventions` | Valider conventions de nommage des tests | business-analyse-develop |
| `mcp__smartstack__suggest_test_scenarios` | Suggérer scénarios de test basés sur le code | business-analyse-develop |

### Outils Frontend

| Tool | Usage | Used By |
|------|-------|---------|
| `mcp__smartstack__scaffold_api_client` | Générer client TypeScript avec NavRoute | application, business-analyse-develop |
| `mcp__smartstack__scaffold_routes` | Générer React Router depuis NavRoute backend | application, business-analyse-develop |
| `mcp__smartstack__validate_frontend_routes` | Valider synchronisation routes frontend/backend | application, business-analyse-develop |
| `mcp__smartstack__scaffold_frontend_extension` | Générer infrastructure extension frontend | application |
| `mcp__smartstack__analyze_extension_points` | Analyser points d'extension dans les pages React | application |

### Outils Documentation

| Tool | Usage | Used By |
|------|-------|---------|
| `mcp__smartstack__validate_documentation` | Valider fraîcheur, complétude et exactitude de la documentation (FUTURE - voir `_resources/mcp-validate-documentation-spec.md`) | documentation |

> **Fallback** : En attendant l'implémentation MCP, utiliser l'agent `docs-sync-checker` pour la détection de drift et l'agent `docs-context-reader` pour l'injection de contexte documentation.
