## Guide Projet : quoi utiliser et quand ? Project Guide: what to use and when?

Choisissez votre situation pour decouvrir le parcours recommande. Choose your situation to discover the recommended path.

### 🏠 Scenario 1 — Nouveau projet, partir de zero 🏠 Scenario 1 — New project, starting from scratch

💬

« On demarre un nouveau projet de gestion RH, je veux tout faire dans les regles. »

« We're starting a new HR management project, I want to do it by the book. »

1. ##### `/gitflow init` + `/gitflow -f my-project`

   Initialiser le repository GitFlow et creer la branche feature.

   Initialize GitFlow repository and create the feature branch.

2. ##### `/business-analyse` steps 00-04

   Analyser le besoin : cadrage, structure App/Module/Section/Resource, specification par module, consolidation cross-module.

   Analyze requirements: framing, App/Module/Section/Resource structure, per-module specification, cross-module consolidation.

3. ##### `/ba-design-ui` → `/business-analyse-html` → `/ba-review`

   Designer les ecrans, generer le livrable HTML interactif, iterer avec le client jusqu'a validation.

   Design screens, generate interactive HTML deliverable, iterate with client until validation.

4. ##### `/derive-prd`

   Transformer la BA validee en PRD (Product Requirement Documents) pour le developpement.

   Transform validated BA into PRD (Product Requirement Documents) for development.

5. ##### `/ralph-loop`

   Lancer la boucle de developpement autonome : lit les PRDs, orchestre les taches, genere tout le code (entites, migrations, API, frontend).

   Launch autonomous development loop: reads PRDs, orchestrates tasks, generates all code (entities, migrations, API, frontend).

6. ##### `/validate-feature` + `/review-code`

   Valider la compilation, les tests, le smoke test API. Puis revue de code securite/architecture.

   Validate compilation, tests, API smoke test. Then security/architecture code review.

7. ##### `/gitflow commit` → `/gitflow pr` → `/gitflow merge`

   Commiter, creer la PR, merger apres review.

   Commit, create PR, merge after review.

### ⚙ Scenario 2 — Ajouter une feature a un projet existant ⚙ Scenario 2 — Add a feature to an existing project

💬

« J'ai deja un module RH, je veux ajouter la gestion des absences. »

« I already have an HR module, I want to add absence management. »

1. ##### `/gitflow -f add-absences`

   Creer la branche feature dans un worktree isole.

   Create the feature branch in an isolated worktree.

2. ##### `/apex`

   Developpement incremental : analyse le code existant, planifie les fichiers, genere couche par couche (domain, seed, backend, frontend, devdata).

   Incremental development: analyze existing code, plan files, generate layer by layer (domain, seed, backend, frontend, devdata).

3. ##### `/validate-feature`

   Verifier que tout compile, que les tests passent et que l'API repond.

   Verify compilation, passing tests, and API responses.

4. ##### `/gitflow commit` → `/gitflow pr`

   Commiter et creer la PR.

   Commit and create the PR.

### 📦 Scenario 3 — Creer un module complet rapidement 📦 Scenario 3 — Create a complete module quickly

💬

« Je connais deja le besoin, je veux generer le module Produits avec navigation, permissions, API et pages React. »

« I already know the requirements, I want to generate the Products module with navigation, permissions, API and React pages. »

1. ##### `/application`

   Genere tout le module full-stack : navigation, permissions, roles, entity, service, controller, DTOs, pages React, routes, migration, tests, i18n (4 langues).

   Generates the complete full-stack module: navigation, permissions, roles, entity, service, controller, DTOs, React pages, routes, migration, tests, i18n (4 languages).

2. ##### `/efcore db-deploy`

   Appliquer la migration generee en base de donnees.

   Apply the generated migration to the database.

3. ##### `/validate-feature`

   Verifier que le module fonctionne de bout en bout.

   Verify the module works end-to-end.

### 🐛 Scenario 4 — Corriger un bug 🐛 Scenario 4 — Fix a bug

💬

« L'API des commandes retourne une erreur 500 quand on filtre par date. »

« The orders API returns a 500 error when filtering by date. »

1. ##### `/gitflow -h fix-order-filter`

   Creer une branche hotfix (ou `-f` pour feature si non-urgent).

   Create a hotfix branch (or `-f` for feature if non-urgent).

2. ##### `/debug`

   Investigation systematique : analyse les logs, le code, les tests. Propose et applique le correctif.

   Systematic investigation: analyze logs, code, tests. Proposes and applies the fix.

3. ##### `/review-code`

   Verifier que le fix n'introduit pas de regression ou de faille de securite.

   Verify the fix doesn't introduce regressions or security vulnerabilities.

4. ##### `/gitflow commit` → `/gitflow pr` → `/gitflow finish`

   Commiter, PR, puis finaliser le hotfix (tag + merge dans main + develop).

   Commit, PR, then finalize the hotfix (tag + merge into main + develop).

### 🚀 Scenario 5 — Preparer une release 🚀 Scenario 5 — Prepare a release

💬

« On est prets pour la v2.0.0, je veux tout valider et publier. »

« We're ready for v2.0.0, I want to validate everything and publish. »

1. ##### `/gitflow -r 2.0.0`

   Creer la branche release avec bump de version.

   Create the release branch with version bump.

2. ##### `/validate-feature` + `/review-code`

   Validation complete et revue de securite avant release.

   Full validation and security review before release.

3. ##### `/efcore squash`

   Consolider les migrations de la feature en une seule migration propre (si necessaire).

   Consolidate feature migrations into a single clean migration (if needed).

4. ##### `/gitflow finish`

   Finaliser : merge dans main, tag, merge-back dans develop, cleanup.

   Finalize: merge into main, tag, merge-back into develop, cleanup.

### 🗄 Scenario 6 — Gerer la base de donnees 🗄 Scenario 6 — Manage the database

💬

« J'ai modifie une entite, je veux creer la migration et l'appliquer. »

« I modified an entity, I want to create the migration and apply it. »

1. ##### `/efcore migration`

   Creer la migration avec nommage automatique via MCP (convention respectee).

   Create the migration with automatic naming via MCP (convention enforced).

2. ##### `/efcore db-deploy`

   Appliquer les migrations en attente sur la base locale.

   Apply pending migrations to the local database.

⚠

Conflits de migrations ? Utilisez `/efcore scan` pour detecter les conflits cross-branches, puis `/efcore rebase-snapshot` pour resynchroniser.

Migration conflicts? Use `/efcore scan` to detect cross-branch conflicts, then `/efcore rebase-snapshot` to resync.

### ▶ Scenario 7 — Lancer ou arreter l'application ▶ Scenario 7 — Run or stop the application

💬

« Je veux lancer le backend et le frontend pour tester en local. »

« I want to launch the backend and frontend to test locally. »

Commande Command | Description Description
--- | ---
`/dev-start` | Lancer tout (backend + frontend). Idempotent : detecte les processus deja en cours. Launch everything (backend + frontend). Idempotent: detects already-running processes.
`/dev-start --stop` | Arreter le backend et le frontend. Stop backend and frontend.
`/dev-start --backend-only` | Lancer uniquement le backend (.NET). Launch only the backend (.NET).
`/dev-start --frontend-only` | Lancer uniquement le frontend (Vite/React). Launch only the frontend (Vite/React).
`/dev-start --reset` | Forcer le reset du mot de passe admin. Force admin password reset.

💡

`/dev-start` detecte automatiquement le profil (Local ou Development), valide la coherence des ports entre backend et frontend, et affiche les credentials admin.

`/dev-start` automatically detects the profile (Local or Development), validates port coherence between backend and frontend, and displays admin credentials.

### 🔎 Scenario 8 — Comprendre le code existant 🔎 Scenario 8 — Understand existing code

💬

« Je debarque sur le projet, comment fonctionne le systeme de permissions ? »

« I'm new to the project, how does the permission system work? »

🔍

#### `/quick-search`

Question simple, reponse rapide. « Ou est defini le PermissionService ? »

Simple question, fast answer. « Where is PermissionService defined? »

🔬

#### `/explore`

Analyse approfondie d'un mecanisme. « Comment fonctionne l'isolation multi-tenant ? »

Deep analysis of a mechanism. « How does multi-tenant isolation work? »

📊

#### `/documentation`

Generer la doc technique d'un module existant (ERD, guides, schemas).

Generate technical docs for an existing module (ERD, guides, schemas).

### 🌳 Arbre de decision rapide 🌳 Quick decision tree

    Que voulez-vous faire ?
    │
    ├─ Nouveau projet complet
    │  └─ /business-analyse → /ba-design-ui → /business-analyse-html
    │     → /ba-review → /derive-prd → /ralph-loop
    │
    ├─ Ajouter une feature a un projet existant
    │  ├─ Feature simple (1 entite)  → /application
    │  ├─ Feature complexe (multi)   → /apex
    │  └─ Feature avec IA/notif/wf   → /apex (orchestre /ai-prompt, /notification, /workflow)
    │
    ├─ Generer du code specifique
    │  ├─ API controller + DTOs      → /controller
    │  ├─ Composants React           → /ui-components
    │  ├─ Notifications              → /notification
    │  ├─ Workflows automatises      → /workflow
    │  └─ Integration IA             → /ai-prompt
    │
    ├─ Base de donnees
    │  ├─ Creer une migration        → /efcore migration
    │  ├─ Appliquer les migrations   → /efcore db-deploy
    │  ├─ Reset complet              → /efcore db-reset
    │  └─ Conflits de migrations     → /efcore scan + /efcore rebase-snapshot
    │
    ├─ Qualite et validation
    │  ├─ Valider une feature E2E    → /validate-feature
    │  ├─ Revue de code/securite     → /review-code
    │  ├─ Valider les conventions    → /validate
    │  └─ Refactoring                → /refactor
    │
    ├─ Corriger un bug               → /debug
    │
    ├─ Lancer / arreter l'app
    │  ├─ Tout lancer                → /dev-start
    │  ├─ Tout arreter              → /dev-start --stop
    │  ├─ Backend seul               → /dev-start --backend-only
    │  └─ Frontend seul              → /dev-start --frontend-only
    │
    ├─ Comprendre le code
    │  ├─ Question rapide            → /quick-search
    │  └─ Analyse approfondie        → /explore
    │
    └─ Gestion des branches
       ├─ Nouvelle feature           → /gitflow -f <name>
       ├─ Release                    → /gitflow -r <version>
       ├─ Hotfix                     → /gitflow -h <name>
       ├─ Commit                     → /gitflow commit
       ├─ Pull Request               → /gitflow pr
       └─ Finaliser                  → /gitflow finishWhat do you want to do?
    │
    ├─ New complete project
    │  └─ /business-analyse → /ba-design-ui → /business-analyse-html
    │     → /ba-review → /derive-prd → /ralph-loop
    │
    ├─ Add a feature to an existing project
    │  ├─ Simple feature (1 entity)  → /application
    │  ├─ Complex feature (multi)    → /apex
    │  └─ Feature with AI/notif/wf   → /apex (orchestrates /ai-prompt, /notification, /workflow)
    │
    ├─ Generate specific code
    │  ├─ API controller + DTOs      → /controller
    │  ├─ React components           → /ui-components
    │  ├─ Notifications              → /notification
    │  ├─ Automated workflows        → /workflow
    │  └─ AI integration             → /ai-prompt
    │
    ├─ Database
    │  ├─ Create a migration         → /efcore migration
    │  ├─ Apply migrations           → /efcore db-deploy
    │  ├─ Full reset                 → /efcore db-reset
    │  └─ Migration conflicts        → /efcore scan + /efcore rebase-snapshot
    │
    ├─ Quality & validation
    │  ├─ Validate feature E2E       → /validate-feature
    │  ├─ Code/security review       → /review-code
    │  ├─ Validate conventions       → /validate
    │  └─ Refactoring                → /refactor
    │
    ├─ Fix a bug                     → /debug
    │
    ├─ Run / stop the app
    │  ├─ Launch all                 → /dev-start
    │  ├─ Stop all                   → /dev-start --stop
    │  ├─ Backend only               → /dev-start --backend-only
    │  └─ Frontend only              → /dev-start --frontend-only
    │
    ├─ Understand code
    │  ├─ Quick question             → /quick-search
    │  └─ Deep analysis              → /explore
    │
    └─ Branch management
       ├─ New feature                → /gitflow -f <name>
       ├─ Release                    → /gitflow -r <version>
       ├─ Hotfix                     → /gitflow -h <name>
       ├─ Commit                     → /gitflow commit
       ├─ Pull Request               → /gitflow pr
       └─ Finalize                   → /gitflow finish

## GitFlow Workflow

Commande Command | Description Description | Page
--- | --- | ---
`/gitflow` | Orchestrateur principal GitFlow Main GitFlow orchestrator | GitFlow
`/gitflow init` | Initialiser la structure GitFlow (bare clone + worktrees) Initialize GitFlow structure (bare clone + worktrees) | GitFlow
`/gitflow start` | Demarrer une branche + worktree (feature/release/hotfix) Start a branch + worktree (feature/release/hotfix) | GitFlow
`/gitflow commit` | Commit intelligent avec validation EF Core Smart commit with EF Core validation | GitFlow
`/gitflow sync` | Synchroniser et rebaser avec le distant Sync and rebase with remote | GitFlow
`/gitflow plan` | Creer un plan d'integration avec analyse EF Core Create integration plan with EF Core analysis | GitFlow
`/gitflow pr` | Creer une Pull Request avec description automatique Create Pull Request with auto-description | GitFlow
`/gitflow merge` | Merger la PR apres review Merge PR after review | GitFlow
`/gitflow finish` | Finaliser une branche (tag + cleanup) Finalize a branch (tag + cleanup) | GitFlow
`/gitflow status` | Afficher l'etat complet du repository Show complete repository state | GitFlow
`/gitflow abort` | Rollback et recuperation Rollback and recovery | GitFlow
`/gitflow cleanup` | Auditer et nettoyer les worktrees orphelins Audit and clean orphan worktrees | GitFlow

💡

Mode auto : Sans `-a`, chaque commande execute UNIQUEMENT son etape puis s'arrete. Avec `-a`, toutes les etapes s'enchainent automatiquement.

Auto mode: Without `-a`, each command executes ONLY its own step then stops. With `-a`, all steps chain automatically.

## Pipeline Business Analyse Business Analysis Pipeline

### Phase 1 - Macro (Identification + Challenge) Phase 1 - Macro (Identification + Challenge)

Commande Command | Modele Model | Description Description | Page
--- | --- | --- | ---
`/business-analyse` (step 00) | Sonnet | Initialisation : detection nouveau/existant, scan, creation index.json Init: detect new/existing, scan, create index.json | BA
`/business-analyse` (step 01) | Opus | Cadrage : contexte, parties prenantes, perimetre, risques (~40 questions) Framing: context, stakeholders, scope, risks (~40 questions) | BA
`/business-analyse` (step 02) | Opus | Structure : hierarchie App > Module > Section > Resource avec challenge Structure: App > Module > Section > Resource hierarchy with challenge | BA

### Phase 2 - Specification (Deep dive + Consolidation) Phase 2 - Specification (Deep dive + Consolidation)

Commande Command | Modele Model | Description Description | Page
--- | --- | --- | ---
`/business-analyse` (step 03) | Opus | Specification : entites, regles metier, cas d'usage, permissions par module Specification: entities, business rules, use cases, permissions per module | BA
`/business-analyse` (step 04) | Opus | Consolidation : validation cross-module, modele de donnees, coherence permissions Consolidation: cross-module validation, data model, permission coherence | BA

### Post-BA : Design, HTML, Review, PRD Post-BA: Design, HTML, Review, PRD

Commande Command | Description Description | Page
--- | --- | ---
`/ba-design-ui` | Designer les interfaces (ecrans, wireframes, arbre de navigation) Design interfaces (screens, wireframes, navigation tree) | BA
`/business-analyse-html` | Generer le document HTML interactif (mockups, ERD, permissions) Generate interactive HTML document (mockups, ERD, permissions) | BA
`/ba-review` | Appliquer les corrections client et regenerer le HTML Apply client corrections and regenerate HTML | BA
`/derive-prd` | Transformer la BA consolidee en PRD pour /ralph-loop Transform consolidated BA into PRD for /ralph-loop | BA

💡

Pipeline complet : /business-analyse (steps 00-04) → /ba-design-ui → /business-analyse-html → /ba-review → /derive-prd → /ralph-loop

Full pipeline: /business-analyse (steps 00-04) → /ba-design-ui → /business-analyse-html → /ba-review → /derive-prd → /ralph-loop

## Pipeline de developpement Development Pipeline

Commande Command | Description Description | Page
--- | --- | ---
`/ralph-loop` | Boucle de developpement iterative IA : lit les PRDs et orchestre les taches Iterative AI development loop: reads PRDs and orchestrates tasks | Ralph Loop
`/apex` | Developpement incremental APEX (Analyze-Plan-Execute-eXamine) APEX incremental development (Analyze-Plan-Execute-eXamine) | APEX
`/dev-start` | Lancer l'environnement de dev (backend + frontend + credentials admin) Launch dev environment (backend + frontend + admin credentials) | -
`/dev-start --stop` | Arreter le backend et le frontend Stop backend and frontend | -

## Generation de code Code Generation

Commande Command | Description Description
--- | ---
`/application` | Creer une application/module full-stack (Application → Module → Section → Resource) Create full-stack application/module (Application → Module → Section → Resource)
`/controller` | Generer un controleur API avec CRUD, DTOs, permissions et tests Postman Generate API controller with CRUD, DTOs, permissions and Postman tests
`/ui-components` | Generer des composants UI standardises (EntityCard, DataTable, Kanban, Dashboard, Charts) Generate standardized UI components (EntityCard, DataTable, Kanban, Dashboard, Charts)
`/ai-prompt` | Integrer des capacites IA dans une feature (prompts, schemas, providers) Integrate AI capabilities into a feature (prompts, schemas, providers)
`/notification` | Integrer le systeme de notifications (in-app DB + SignalR, email via workflows) Integrate notification system (in-app DB + SignalR, email via workflows)
`/workflow` | Creer des workflows automatises (SendEmail, Wait, Condition, Webhook) Create automated workflows (SendEmail, Wait, Condition, Webhook)
`/documentation` | Generer la documentation technique (guides, ERD, outils dev) Generate technical documentation (guides, ERD, dev tools)

## Qualite et analyse Quality & Analysis

Commande Command | Description Description
--- | ---
`/review-code` | Revue de code experte : securite (OWASP), architecture, clean code (SOLID), performance Expert code review: security (OWASP), architecture, clean code (SOLID), performance
`/validate` | Valider les conventions SmartStack via MCP (tables, migrations, services, namespaces) Validate SmartStack conventions via MCP (tables, migrations, services, namespaces)
`/validate-feature` | Valider une feature de bout en bout (compile, test, API smoke test, DB) Validate a feature end-to-end (compile, test, API smoke test, DB)
`/debug` | Debugging systematique avec analyse approfondie et resolution Systematic debugging with deep analysis and resolution
`/explore` | Exploration profonde du codebase pour repondre a des questions specifiques Deep codebase exploration to answer specific questions
`/quick-search` | Recherche ultra-rapide optimisee pour la vitesse Lightning-fast search optimized for speed
`/refactor` | Refactoring de code avec agents paralleles pour la vitesse Code refactoring with parallel agents for speed

## EF Core

Commande Command | Description Description | Page
--- | --- | ---
`/efcore db-status` | Verification rapide de l'etat des migrations Fast migration state check | EF Core
`/efcore db-deploy` | Appliquer les migrations en attente Apply pending migrations | EF Core
`/efcore db-reset` | Supprimer et recreer la base de donnees Drop and recreate database | EF Core
`/efcore db-seed` | Peupler la base avec des donnees de test Populate with test data | EF Core
`/efcore migration` | Creer/recreer une migration (nommage via MCP) Create/recreate a migration (naming via MCP) | EF Core
`/efcore squash` | Consolider les migrations en une seule Consolidate migrations into one | EF Core
`/efcore rebase-snapshot` | Synchroniser le snapshot avec la branche parente Sync snapshot with parent branch | EF Core
`/efcore scan` | Scanner les conflits de migrations cross-branches Scan cross-branch migration conflicts | EF Core
`/efcore conflicts` | Analyser les conflits de migrations (bloquant si detecte) Analyze migration conflicts (blocking if detected) | EF Core

## Infrastructure et outils Infrastructure & Tools

Commande Command | Description Description
--- | ---
`/mcp` | Gestion du serveur MCP : healthcheck et liste des outils MCP server management: healthcheck and tools list
`/utils` | Utilitaires SmartStack (test-web, test-web-config) SmartStack utilities (test-web, test-web-config)
`/check-version` | Verifier l'alignement des versions (package.json vs documentation) Verify version alignment (package.json vs documentation)
`/cli-app-sync` | Detecter et corriger le drift entre SmartStack.app et les templates CLI Detect and fix drift between SmartStack.app and CLI templates

## CLI (smartstack)

Commande Command | Alias | Description Description
--- | --- | ---
`smartstack activate <key>` | `a` | Activer la licence Activate license
`smartstack install` | `i` | Installer les commandes et agents Install commands and agents
`smartstack uninstall` | `u` | Desinstaller les commandes et agents Uninstall commands and agents
`smartstack status` | `s` | Afficher le statut d'installation Show installation status
`smartstack update` | - | Mettre a jour les commandes Update commands
`smartstack docs [page]` | `d` | Ouvrir la documentation dans le navigateur Open documentation in browser

### Options d'installation

### Installation Options

    # Installer tous les composants (defaut)
    smartstack install

    # Installer des composants specifiques
    smartstack install --commands-only
    smartstack install --agents-only
    smartstack install --hooks-only

    # Installer dans le projet (au lieu de ~/.claude)
    smartstack install --local

    # Forcer la reecriture des fichiers existants
    smartstack install --force

    # Ignorer la creation du fichier config
    smartstack install --no-config