# APEX

APEX = Analyze → Plan → Execute → eXamine

APEX = Analyze → Plan → Execute → eXamine

APEX est la méthodologie SmartStack de développement incrémental. C'est un orchestrateur qui coordonne la génération de code via les skills existants (/controller, /application, /ui-components, /efcore) et les outils MCP.

APEX is the SmartStack incremental development methodology. It is an orchestrator that coordinates code generation through existing skills (/controller, /application, /ui-components, /efcore) and MCP tools.

💡

##### Principe clé

##### Key Principle

APEX orchestre — il ne génère jamais le code SmartStack directement. Toute génération passe par les skills et les outils MCP.

APEX orchestrates — it never generates SmartStack code directly. All generation goes through skills and MCP tools.

## Démarrage Rapide

## Quick Start

Commandes APEX
APEX Commands

    /apex add absence management to HR module           # Add section
    /apex -a fix the leave request controller            # Auto fix
    /apex -a -x -s -pr add PDF export to Orders          # Full workflow
    /apex -e add status field to Project entity          # Economy (no agents)
    /apex -r                                             # Resume previous
    /apex -d .ralph/prd.json                             # Delegate mode (from ralph-loop)

## Drapeaux

## Flags

Drapeau | Flag | Description | Description
--- | --- | --- | ---
`-a` |  | Mode auto: saute les confirmations | Auto mode: skip confirmations
`-x` |  | Revue approfondie: revue de code adversariale | Deep review: adversarial code review
`-s` |  | Mode sauvegarde: sortie vers `.claude/output/apex/` | Save mode: output to `.claude/output/apex/`
`-e` |  | Mode économie: pas de sous-agents | Economy mode: no subagents
`-r` |  | Reprendre l'état précédent | Resume: continue from previous state
`-pr` |  | Mode PR: créer une pull request à la fin | PR mode: create pull request at end
`-d {path}` |  | Mode délégué: lire le contexte d'un fichier PRD. Implique -a -e. Utilisé par /ralph-loop. | Delegate mode: read context from PRD file. Implies -a -e. Used by /ralph-loop.

## Architecture: 9 Étapes

## Architecture: 9 Steps

Étape | Step | Phase | Phase | Objectif | Purpose
--- | --- | --- | --- | --- | ---
00 |  | Init |  | Parser flags, détecter contexte, vérifier MCP, définir hiérarchie 4 niveaux, challenger besoin | Parse flags, detect context, verify MCP, define 4-level hierarchy, challenge need
01 |  | ANALYZE |  | Explorer le code existant (Agent Teams ou direct) | Explore existing code (Agent Teams or direct)
02 |  | PLAN |  | Plan par couche avec mapping skill/MCP | Layer-by-layer plan with skill/MCP mapping
03 |  | EXECUTE |  | Orchestrer exécution via skills et MCP | Orchestrate execution via skills and MCP
04 |  | EXAMINE |  | Validation MCP, build, 43 POST-CHECKs, critères acceptation | MCP validation, build, 43 POST-CHECKs, acceptance criteria
05 |  | Deep Review |  | Revue de code adversariale (si flag -x) | Adversarial code review (if -x flag)
06 |  | Resolve |  | Corriger les trouvailles BLOQUANTES | Fix BLOCKING findings
07 |  | Tests |  | Scaffolder tests via MCP | Scaffold tests via MCP
08 |  | Run Tests |  | Exécuter tests jusqu'à 100% réussi | Run tests until 100% pass

## 43 POST-CHECKs (Étape 04)

## 43 POST-CHECKs (Step 04)

Validation automatisée couvrant:

Automated validation covering:

- Conventions namespace, usage BaseEntity, ITenantEntity
- Namespace conventions, BaseEntity usage, ITenantEntity
- Filtrage TenantId dans les services (clause de garde obligatoire)
- TenantId filtering in services (guard clause mandatory)
- [RequirePermission] sur contrôleurs (pas seulement [Authorize])
- [RequirePermission] on controllers (not just [Authorize])
- Routes chemin complet, permissions en kebab-case
- Full-path routes, kebab-case permissions
- Complétude données seed (navigation, permissions, rôles, traductions)
- Seed data completeness (navigation, permissions, roles, translations)
- Idempotence traductions (gardes AnyAsync)
- Translation idempotency (AnyAsync guards)
- Sécurité données seed FK (requête IDs réels de DB)
- FK seed data safety (query actual IDs from DB)
- Frontend: i18n 4 langues, pas imports statiques en routes, pas couleurs en dur
- Frontend: i18n 4 languages, no static imports in routes, no hardcoded colors
- Pas de modaux pour formulaires, pages create/edit existent, fichiers test existent
- No modals for forms, create/edit pages exist, test files exist
- EntityLookup pour champs FK, param search sur GetAll
- EntityLookup for FK fields, search param on GetAll
- Complétude sous-ressources, onglets page détail état local
- Sub-resource completeness, detail page tabs local state

## Gestion des Erreurs

## Error Handling

Erreur | Error | Action | Action
--- | --- | --- | ---
`dotnet build` échoue fails |  | Corriger via skill/MCP, rebuilder (max 3) | Fix via skill/MCP, rebuild (max 3)
`npm run typecheck` échoue fails |  | Corriger erreur TypeScript (max 3) | Fix TypeScript error (max 3)
MCP indisponible | MCP unavailable |  | Mode dégradé avec smartstack-api.md | Degraded mode with smartstack-api.md
POST-CHECK échoue | POST-CHECK fails |  | Retourner execute, corriger, re-valider (max 2) | Return to execute, fix, re-validate (max 2)

## Critères de Succès

## Success Criteria

✓

- `validate_conventions` MCP: 0 erreurs
- `validate_conventions` MCP: 0 errors
- `dotnet build` PASS + `npm run typecheck` PASS
- `dotnet build` PASS + `npm run typecheck` PASS
- Données seed complètes (navigation, permissions, rôles)
- Seed data complete (navigation, permissions, roles)
- Tests: 100% réussi, >= 80% couverture
- Tests: 100% pass, >= 80% coverage
- Commits atomiques par couche
- Commits atomic per layer

## Mode Délégué (ralph-loop)

## Delegate Mode (ralph-loop)

Quand ralph-loop invoque APEX avec `-d .ralph/prd.json`, APEX lit le contexte PRD et exécute le workflow complet en mode autonome.

When ralph-loop invokes APEX with `-d .ralph/prd.json`, APEX reads PRD context and executes the full workflow in autonomous mode.

Structure PRD
PRD Structure

    {
      "version": "1.0",
      "metadata": {
        "name": "Feature Name",
        "domain": "module-path",
        "category": "feature|bugfix|refactor"
      },
      "context": {
        "domain": {...},
        "infrastructure": {...},
        "application": {...},
        "api": {...},
        "seedData": {...},
        "frontend": {...}
      },
      "tasks": [
        {
          "id": "entity",
          "category": "domain",
          "status": "pending",
          "completed_at": null,
          "commit_hash": null,
          "files_changed": []
        }
      ]
    }

APEX met à jour `task.status`, `completed_at`, `commit_hash`, et `files_changed` au fur et à mesure. Ralph lit le fichier PRD mis à jour après que APEX retourne.

APEX updates `task.status`, `completed_at`, `commit_hash`, and `files_changed` as it progresses. Ralph reads the updated PRD file after APEX returns.

## Points d'Intégration

## Integration Points

APEX intègre:

APEX integrates:

🛠 Skills: /controller, /application, /ui-components, /efcore Skills: /controller, /application, /ui-components, /efcore
📍 MCP: validate_conventions, scaffold_*, generate_*, suggest_* MCP: validate_conventions, scaffold_*, generate_*, suggest_*
📉 Agents: explore-codebase, code-reviewer (si -x) Agents: explore-codebase, code-reviewer (if -x)
🔁 GitFlow: commits atomiques, PR creation (si -pr) GitFlow: atomic commits, PR creation (if -pr)

## Référence

## Reference

`templates/skills/apex/`

💡

Pour une documentation complète des étapes APEX, références, et patterns: consultez les fichiers de la skill APEX dans `templates/skills/apex/`.

For complete APEX step documentation, references, and patterns: see APEX skill files in `templates/skills/apex/`.