## Introduction

APEX (Analyze-Plan-Execute-eXamine) est une methodologie systematique pour l'implementation de features complexes. Elle garantit une approche structuree avec une comprehension complete du contexte avant d'ecrire du code.

APEX (Analyze-Plan-Execute-eXamine) is a systematic methodology for implementing complex features. It ensures a structured approach with complete context understanding before writing code.

🎯

##### Principe fondamental

##### Core Principle

Context depth > Speed. Une analyse incomplete mene a des implementations defaillantes.

Context depth > Speed. Incomplete analysis leads to failed implementations.

## Workflow

Chaque phase produit un artefact qui sert d'input a la phase suivante :

Each phase produces an artifact that serves as input for the next phase:

Phase | Commande Command | Artefact Artifact
--- | --- | ---
Analyze | `/apex 1-analyze` | `analyze.md`
Plan | `/apex 2-plan` | `plan.md`
Execute | `/apex 3-execute` | `implementation.md`
eXamine | `/apex 4-examine` | `validation.md`
Tasks | `/apex 5-tasks` | `task-*.md`

## 1. Analyze

La phase d'analyse collecte tout le contexte necessaire avant l'implementation. Elle utilise des agents paralleles pour explorer le codebase, la documentation et le web.

The analysis phase collects all necessary context before implementation. It uses parallel agents to explore the codebase, documentation, and web.

`/apex 1-analyze` Analysis

    /apex 1-analyze Add user authentication with JWT tokens

#### Template Prompt Prompt Template

1-analyze.md

`templates/commands/apex/1-analyze.md`

    ---
    description: Analyze phase - gather all context and create analysis report
    argument-hint: <task-description>
    ---

    You are an analysis specialist. Your mission is to gather ALL relevant context before implementation.

    **You need to ULTRA THINK before launching agents.**

    ## Workflow

    1. **SETUP TASK FOLDER**: Create organized workspace in .claude/tasks
       - Find next task number: Check `.claude/tasks/` for existing folders
       - Parse task description to create kebab-case name
       - Create `.claude/tasks/nn-task-name/` folder structure
       - **EXAMPLE**: "Add user authentication" → `.claude/tasks/01-add-user-authentication/`

    2. **ULTRA THINK**: Plan analysis strategy
       - **CRITICAL**: Know EXACTLY what to search for before launching agents
       - Identify key concepts, files, patterns to find
       - Determine which sources need analysis (codebase/docs/web)

    3. **LAUNCH PARALLEL ANALYSIS**: Gather context from all sources
       - **Codebase exploration** (`explore-codebase` agent)
       - **Documentation exploration** (`explore-docs` agent)
       - **Web research** (`websearch` agent)
       - **CRITICAL**: Launch ALL agents in parallel

    4. **SYNTHESIZE FINDINGS**: Create comprehensive analysis report

    5. **SAVE ANALYSIS**: Write to `analyze.md`
       ```markdown
       # Task: [Description]

       ## Codebase Context
       [Findings from codebase exploration]

       ## Documentation Insights
       [Key information from docs]

       ## Key Files
       - `path/to/file.ts:line` - Purpose

       ## Patterns to Follow
       [Existing conventions]
       ```

    ## Priority
    Context depth > Speed. Missing context causes failed implementations.

### Agents utilises

### Agents used

🔍
explore-codebase

Explore le codebase pour trouver des implementations similaires, patterns et conventions.

Explores codebase to find similar implementations, patterns and conventions.

📖
explore-docs

Recherche dans la documentation des librairies pour les APIs et best practices.

Searches library documentation for APIs and best practices.

🌐
websearch

Recherche sur le web les dernieres approches et solutions.

Searches the web for latest approaches and solutions.

## 2. Plan

La phase de planification transforme l'analyse en un plan d'implementation detaille, organise par fichier.

The planning phase transforms the analysis into a detailed implementation plan, organized by file.

`/apex 2-plan` Planning

    /apex 2-plan 01-add-user-authentication

#### Template Prompt Prompt Template

2-plan.md

`templates/commands/apex/2-plan.md`

    ---
    description: Planning phase - create detailed implementation strategy from analysis
    argument-hint: <task-folder-path>
    ---

    You are a strategic planning specialist. Transform analysis findings into executable plans.

    **You need to ULTRA THINK about the complete implementation strategy.**

    ## Workflow

    1. **VALIDATE INPUT**: Verify task folder exists
       - Check that `.claude/tasks/<task-folder>/` exists
       - Verify `analyze.md` file is present

    2. **READ ANALYSIS**: Load all context

    3. **ULTRA THINK PLANNING**: Design comprehensive strategy
       - **CRITICAL**: Think through ENTIRE implementation before writing
       - Consider all edge cases and dependencies
       - Plan file changes in logical dependency order

    4. **ASK FOR CLARITY**: Resolve ambiguities
       - **STOP**: If anything is unclear about requirements
       - **NEVER ASSUME**: Always clarify before planning

    5. **CREATE DETAILED PLAN**: Write file-by-file implementation guide
       - **Structure**: Group by file, NOT by feature
       - **Format**: Action-oriented, no code snippets

    ## Plan Quality Guidelines

    ### Good Plan Entry
    ```markdown
    ### `src/auth/middleware.ts`
    - Add validateToken function that checks JWT expiration
    - Extract token from Authorization header (follow pattern in `src/api/auth.ts:45`)
    - Return 401 if token invalid or expired
    ```

    ### Bad Plan Entry
    ```markdown
    ### `src/auth/middleware.ts`
    - Add authentication
    - Fix security issues
    ```

    ## Priority
    Clarity > Completeness. Every step must be unambiguous and executable.

⚠

##### Pas de code dans le plan

##### No code in the plan

Le plan decrit les actions, pas les implementations. Chaque item doit etre clair et executable sans montrer de code.

The plan describes actions, not implementations. Each item must be clear and executable without showing code.

## 3. Execute

La phase d'execution implemente le plan etape par etape, en suivant les patterns identifies lors de l'analyse.

The execution phase implements the plan step by step, following patterns identified during analysis.

`/apex 3-execute` Implementation

    /apex 3-execute 01-add-user-authentication

#### Template Prompt Prompt Template

3-execute.md

`templates/commands/apex/3-execute.md`

    ---
    description: Execution phase - implement the plan step by step with ultra thinking
    argument-hint: <task-folder-path>
    ---

    You are an implementation specialist. Execute plans precisely while maintaining code quality.

    **You need to ULTRA THINK at every step.**

    ## Workflow

    1. **VALIDATE INPUT**: Verify task folder is ready
    2. **LOAD CONTEXT**: Read analyze.md and plan.md

    3. **CREATE TODO LIST**: Track implementation progress
       - **CRITICAL**: Use TodoWrite to create todos from plan
       - Break down each file change into separate todo items

    4. **ULTRA THINK BEFORE EACH CHANGE**: Plan every modification
       - **BEFORE** editing any file:
         - Think through the exact changes needed
         - Review analysis findings for patterns to follow
       - **NEVER** make changes without thinking first

    5. **IMPLEMENT STEP BY STEP**: Execute plan methodically
       - **ONE TODO AT A TIME**: Mark in_progress, complete, then move to next
       - **Follow existing patterns**
       - **Stay strictly in scope**

    6. **FORMAT AND LINT**: Clean up code
    7. **TEST PHASE**: Verify implementation works

    ## Implementation Quality Rules

    ### Code Style
    - **NO COMMENTS**: Use clear names instead
    - **MATCH PATTERNS**: Follow existing codebase conventions exactly
    - **MINIMAL CHANGES**: Only touch what's needed

    ### Scope Management
    - **STRICTLY IN SCOPE**: Implement only what's in the plan
    - **NO REFACTORING**: Don't improve unrelated code
    - **NO EXTRAS**: Don't add unrequested features

    ## Priority
    Correctness > Completeness > Speed

### Regles d'implementation

### Implementation Rules

#### ✅ Ultra Think avant chaque modification Ultra Think before each modification

Avant d'editer un fichier, reflechir aux changements exacts necessaires, revoir les patterns de l'analyse, et considerer l'impact sur les autres fichiers.

Before editing a file, think through the exact changes needed, review patterns from analysis, and consider impact on other files.

#### ✅ Un todo a la fois One todo at a time

Marquer le todo comme `in_progress`, completer la tache, puis marquer comme `completed` avant de passer au suivant.

Mark the todo as `in_progress`, complete the task, then mark as `completed` before moving to the next.

#### ✅ Rester dans le scope Stay in scope

Implementer uniquement ce qui est dans le plan. Pas de refactoring non demande, pas de features supplementaires.

Implement only what's in the plan. No unrequested refactoring, no extra features.

## 4. eXamine

La phase d'examination valide l'implementation et s'assure que tout fonctionne correctement.

The examination phase validates the implementation and ensures everything works correctly.

`/apex 4-examine` Validation

    /apex 4-examine 01-add-user-authentication

#### Template Prompt Prompt Template

4-examine.md

`templates/commands/apex/4-examine.md`

    ---
    description: Examine phase - validate and test application for deployment readiness
    allowed-tools: Bash(npm :*), Bash(pnpm :*), Read, Task, Grep
    ---

    You are a validation specialist. Ensure implementation is complete and correct.

    ## Workflow

    1. **LOAD CONTEXT**: Read analyze.md, plan.md, and implementation.md

    2. **RUN VALIDATION SUITE**: Execute all checks
       - Type checking: npm run typecheck
       - Linting: npm run lint
       - Unit tests: npm run test
       - Build: npm run build
       - E2E tests: npm run test:e2e (if applicable)

    3. **VERIFY IMPLEMENTATION**: Cross-check against plan
       - Every plan item is implemented
       - No extra changes outside scope
       - Code follows identified patterns

    4. **CREATE VALIDATION REPORT**: Write to validation.md
       ```markdown
       # Validation Report

       ## Checks Passed
       - [x] Type checking
       - [x] Linting
       - [x] Unit tests
       - [x] Build

       ## Implementation Verification
       - [x] All plan items implemented
       - [x] No scope creep
       - [x] Patterns followed

       ## Issues Found
       [List any issues or "None"]

       ## Status: PASSED/FAILED
       ```

    5. **FIX ISSUES**: If validation fails, fix and re-run

    ## Priority
    Quality > Speed. Never approve a failing implementation.

### Checklist de validation

### Validation Checklist

Verification Check | Commande Command
--- | ---
Type checking Type checking | `npm run typecheck`
Linting | `npm run lint`
Tests unitaires Unit tests | `npm run test`
Build | `npm run build`
Tests E2E E2E tests | `npm run test:e2e`

## 5. Tasks

La phase Tasks divise le plan en fichiers de taches individuels, utiles pour les grandes implementations ou le travail en equipe.

The Tasks phase divides the plan into individual task files, useful for large implementations or team work.

`/apex 5-tasks` Division

    /apex 5-tasks 01-add-user-authentication

#### Template Prompt Prompt Template

5-tasks.md

`templates/commands/apex/5-tasks.md`

    ---
    description: Task creation - divide plan into small, actionable task files
    argument-hint: <task-folder-path>
    ---

    You are a task division specialist. Break down plans into executable task files.

    ## Workflow

    1. **LOAD CONTEXT**: Read analyze.md and plan.md

    2. **IDENTIFY TASK BOUNDARIES**: Group related changes
       - Each task should be independently testable
       - Tasks should follow dependency order
       - Target 15-30 minutes per task

    3. **CREATE TASK FILES**: For each logical unit
       ```markdown
       # Task: [Short Name]

       ## Context
       [Relevant context from analyze.md]

       ## Objective
       [Clear, single objective]

       ## Files to Modify
       - `path/to/file.ts` - [changes]

       ## Steps
       1. [Action 1]
       2. [Action 2]

       ## Acceptance Criteria
       - [ ] [Criterion 1]
       - [ ] [Criterion 2]

       ## Dependencies
       - Requires: [Previous tasks]
       - Enables: [Next tasks]
       ```

    4. **SAVE TASKS**: Write to task-NN-name.md files

    ## Task Naming
    - task-01-setup-config.md
    - task-02-create-types.md
    - task-03-implement-service.md

    ## Priority
    Clarity > Granularity. Each task must be self-contained.

Genere des fichiers de taches individuels :

Generates individual task files:

    .claude/tasks/01-add-user-authentication/
    ├── analyze.md
    ├── plan.md
    ├── task-01-setup-jwt-config.md
    ├── task-02-create-auth-middleware.md
    ├── task-03-implement-login-endpoint.md
    ├── task-04-add-token-refresh.md
    └── task-05-write-tests.md

## Bonnes pratiques Best Practices

#### ✅ Toujours commencer par /apex 1-analyze Always start with /apex 1-analyze

Ne jamais sauter l'analyse. Une comprehension incomplete du contexte mene a des implementations defaillantes.

Never skip analysis. Incomplete context understanding leads to failed implementations.

#### ✅ Utiliser /apex pour les taches complexes Use /apex for complex tasks

Pour les taches simples (renommer une variable, corriger un bug evident), utilisez directement la commande appropriee sans passer par APEX.

For simple tasks (renaming a variable, fixing an obvious bug), use the appropriate command directly without going through APEX.

#### ✅ Verifier les artefacts entre chaque phase Review artifacts between each phase

Avant de passer a la phase suivante, lire l'artefact genere pour s'assurer qu'il est complet et correct.

Before moving to the next phase, read the generated artifact to ensure it's complete and correct.

💡

##### Raccourci

##### Shortcut

Utilisez `/apex <description>` pour lancer le workflow complet en une seule commande. Claude executera automatiquement toutes les phases.

Use `/apex <description>` to launch the complete workflow in a single command. Claude will automatically execute all phases.