# Reference Documentation

Documentation complète des agents, workflows, composants et standards.

## 📑 Table des matières

1. [Agents disponibles](#agents-disponibles)
   - [Backend](#backend)
   - [Frontend](#frontend)
2. [Workflows disponibles](#workflows-disponibles)
   - [Backend](#backend-1)
   - [Frontend](#frontend-1)
3. [Registre de composants](#registre-de-composants)
   - [Authentification](#authentification)
   - [Base de données](#base-de-données)
   - [Frontend](#frontend-2)
   - [Infrastructure](#infrastructure)
4. [Versions des frameworks](#versions-des-frameworks)
5. [Standards et Best Practices](#standards-et-best-practices)
   - [RFC pour APIs RESTful](#rfc-pour-apis-restful)
   - [Standards Frontend](#standards-frontend)
   - [Best Practices par langage](#best-practices-par-langage)
6. [Contextes supportés](#contextes-supportés)
7. [Environnement Cloud](#environnement-cloud)

---

## Agents disponibles

### Backend

| Agent | Rôle |
|-------|------|
| `@architect` | Design, Clean Architecture, SOLID |
| `@developer` | Implémentation, Best Practices |
| `@unit-tester` | Tests unitaires (Domain, Application) |
| `@integration-tester` | Tests d'intégration (API, Database) |
| `@reviewer` | Code review, sécurité |
| `@docwriter` | Documentation API |
| `@token-optimizer` | Optimisation tokens, skip agents inutiles |

### Frontend (React/Next.js)

| Agent | Rôle |
|-------|------|
| `@frontend-developer` | Développement React/Next.js |
| `@api-integrator` | Intégration API .NET → TypeScript |
| `@component-builder` | Composants UI accessibles |
| `@frontend-tester` | Tests React (Vitest, RTL, MSW) |

---

## Workflows disponibles

### Backend

| Commande | Séquence | Usage |
|----------|----------|-------|
| `@chain:backend-feature` | arch → dev → test → review → doc | Nouvelles features backend |
| `@chain:bugfix` | dev → test → review | Corrections de bugs |
| `@chain:quickfix` | dev → test | Corrections rapides |
| `@chain:refactor` | arch → dev → test → review | Refactoring |
| `@chain:optimized-feature` | token-optimizer → (agents conditionnels) | Feature optimisée en tokens |

### Frontend (React/Next.js)

| Commande | Séquence | Usage |
|-------|----------|-------|
| `@chain:frontend-feature` | api-integrator → frontend-dev → tester → review → doc | Feature avec API |
| `@chain:api-integration` | api-integrator → mocks → validation | Intégration API .NET |
| `@chain:component` | component-builder → tester | Composant UI |
| `@chain:adaptive` | Automatique selon complexité | Workflow intelligent |

---

## Registre de composants

Le registre permet d'assembler des applications modulaires. Fichier : `.claude-portable/registry/components.registry.yaml`

### Authentification

| Composant | Description | Stacks |
|-----------|-------------|--------|
| `jwt` | JSON Web Tokens | .NET, Node.js, Python |
| `oauth` | OAuth 2.0 / OpenID | .NET, Node.js |
| `auth0` | Auth0 managé | .NET, Node.js, React |
| `keycloak` | IAM open source | .NET, Node.js |

### Base de données

| Composant | Description | ORM par défaut |
|-----------|-------------|----------------|
| `postgres` | PostgreSQL 17 | EF Core / Prisma / SQLAlchemy |
| `mongodb` | MongoDB 8.0 | MongoDB.Driver / Mongoose |
| `redis` | Cache & Pub/Sub | StackExchange.Redis / ioredis |

### Frontend

| Composant | Description |
|-----------|-------------|
| `tanstack-query` | Gestion d'état serveur |
| `zustand` | State management léger |
| `shadcn` | Composants UI (Radix + Tailwind) |
| `tailwind` | CSS utility-first |

### Infrastructure

| Composant | Description |
|-----------|-------------|
| `docker` | Dockerfile + docker-compose |
| `ci-github` | GitHub Actions |
| `ci-gitlab` | GitLab CI |
| `kubernetes` | Manifests K8s |

---

## Versions des frameworks

Les versions sont mises à jour automatiquement. Fichier : `.claude-portable/versions/latest.versions.yaml`

| Framework | Version actuelle | LTS |
|-----------|-----------------|-----|
| .NET | 10 | 8 |
| Node.js | 25 | 24 |
| Python | 3.13 | 3.12 |
| React | 19 | - |
| Angular | 19 | 18 |
| PostgreSQL | 17 | - |

**Mise à jour manuelle** :
```bash
./scripts/update-versions.sh
```

---

## Standards et Best Practices

Chaque contexte inclut une section `standards` avec:

### RFC pour APIs RESTful

| RFC | Nom | Priorité |
|-----|-----|----------|
| RFC 7231 | HTTP/1.1 Semantics | Mandatory |
| RFC 8259 | JSON | Mandatory |
| RFC 7807 | Problem Details | Mandatory |
| RFC 3986 | URI | Recommended |
| RFC 7234 | HTTP Caching | Recommended |

### Standards Frontend

| Standard | Nom | Priorité |
|----------|-----|----------|
| WCAG 2.1 | Accessibility | Mandatory |
| Core Web Vitals | Performance | Recommended |

### Best Practices par langage

Chaque contexte documente les best practices pour:
- **Code style**: Conventions et formatage
- **Architecture**: Patterns recommandés
- **Testing**: Stratégie de test
- **Security**: Bonnes pratiques de sécurité
- **Performance**: Optimisations

---

## Contextes supportés

| Langage | Fichier | Framework | Standards |
|---------|---------|-----------|-----------|
| .NET/C# | `dotnet.context.yaml` | ASP.NET Core | RFC + .NET Best Practices |
| Node.js | `nodejs.context.yaml` | Express | RFC + TypeScript Best Practices |
| Python | `python.context.yaml` | FastAPI | RFC + PEP + Python Best Practices |
| React | `react.context.yaml` | Next.js | WCAG + Web Vitals + React Best Practices |

#### Ajouter un nouveau langage

1. Copier `.claude-portable/contexts/_template.context.yaml`
2. Adapter au nouveau langage/framework
3. Compléter la section `standards` obligatoire
4. Mettre à jour ce README

Voir `.claude-portable/contexts/CONTRIBUTING.md` pour le guide complet.

---

## Environnement Cloud

Ce repository est configuré pour **Claude Code sur le web** ([claude.ai/code](https://claude.ai/code)).

### Configuration automatique

Quand vous lancez une session cloud, le kit s'initialise automatiquement via :
- `.claude/settings.json` : Hook SessionStart
- `scripts/cloud-setup.sh` : Script d'initialisation

### Utiliser Claude Code sur le web

1. Allez sur [claude.ai/code](https://claude.ai/code)
2. Connectez votre compte GitHub
3. Sélectionnez ce repository
4. Configurez votre environnement :
   - Cliquez sur l'environnement actuel → "Add environment"
   - **Nom** : ex. "AI Agent Kit"
   - **Réseau** : "Limited" (défaut) ou "Full"
   - **Variables** : optionnel (format `.env`)

### Envoyer des tâches depuis le terminal

Depuis Claude Code CLI, préfixez avec `&` pour exécuter dans le cloud :

```bash
& @chain:backend-feature "Add user authentication"
```

Ou directement :

```bash
claude --remote "Fix the bug in auth module"
```

### Structure cloud

```
.claude/
├── settings.json      # Hooks SessionStart
└── commands/          # Slash commands (/feature, /bugfix, etc.)
scripts/
└── cloud-setup.sh     # Script d'initialisation cloud
AGENTS.md              # Instructions universelles (tous LLM)
CLAUDE.md              # Point d'entrée Claude Code
```

---

## Documentation supplémentaire

- [Getting Started](getting-started.md) — Installation et configuration initiale
- [Usage Guide](usage-guide.md) — Exemples pratiques et workflows
- [Project Structure](project-structure.md) — Maintenance et support