Contribuer au projet

Ce guide explique comment contribuer au framework : ajouter des skills, agents, profiles, et les partager avec l'équipe.

Structure du projet

framework/

├── skills/            ← Commandes /slash
├── agents/            ← Workers autonomes
├── profiles/          ← Contexte technologique
├── workflows/         ← Pipelines visuels
├── templates/         ← Documents standardisés
└── scripts/           ← Hooks d'automatisation

Processus de contribution

1. Identifier le besoin

Ce que vous voulez	Créez
Un nouveau workflow réutilisable	Un skill
Un rôle IA spécialisé	Un agent
Une tâche autonome déléguable	Un agent
Des conventions pour une stack	Un profile
Un diagramme de pipeline	Un workflow

2. Créer le composant

Utilisez le template correspondant ci-dessous, ou suivez le tutoriel détaillé :

• Créer un skill
• Créer un agent

3. Tester localement

Avant de partager :

• [ ] Invoquer le skill/agent au moins 3 fois sur des cas différents
• [ ] Vérifier que les gates fonctionnent
• [ ] Vérifier que les outputs sont cohérents
• [ ] Demander à un collègue de tester sans explication (si c'est intuitif, c'est bon)

4. Documenter

Chaque contribution doit inclure :

Composant	Documentation requise
Skill	SKILL.md avec usage, flags, pipeline
Agent	Fichier .md avec mission, format de sortie
Profile	Fichier .md avec conventions, patterns, anti-patterns

5. Soumettre

# Créer une branche
git checkout -b feat/add-dba-agent

# Commiter
/commit

# Pousser + MR
git push -u origin feat/add-dba-agent

Conventions de contribution

Nommage

Composant	Convention	Exemple
Skill	kebab-case	api-endpoint, db-migrate
Agent	kebab-case	dba, devops, ux-designer
Profile	kebab-case	python-fastapi, java-spring

Langue

• Fichiers et code : noms en anglais
• Documentation interne (descriptions, instructions) : français
• Commit messages : français

---

Templates

Template de skill

Créez framework/skills/{name}/SKILL.md :

---
name: mon-skill
description: |
  Description claire du skill.
  Utiliser quand : [contexte d'utilisation].
allowed-tools: Read, Write, Edit, Bash, Glob, Grep
---

# /mon-skill

Description courte.

## Usage

/mon-skill [arguments]
/mon-skill --flag [arguments]

## Flags

| Flag | Description |
|------|-------------|
| `--flag` | Ce que fait le flag |

## Pipeline

### Step 01 — Analyser le contexte

<agent>architect</agent>

1. Explorer le code existant
2. Identifier les patterns et conventions
3. Lister les dépendances

<gate>Analyse terminée → type `next`</gate>

### Step 02 — Implémenter

<agent>executor</agent>

1. Créer les fichiers nécessaires
2. Suivre les conventions détectées au step 01
3. Gérer les erreurs

<gate>Code compile sans erreur → type `next`</gate>

### Step 03 — Vérifier

<agent>code-reviewer</agent>

1. Relire le code produit
2. Vérifier la conformité aux patterns
3. Proposer des corrections si nécessaire

Si le skill dépasse 5000 tokens, découpez les steps dans des fichiers séparés :

skills/{name}/
├── SKILL.md              ← Frontmatter + usage + flags + vue d'ensemble
├── REFERENCE.md          ← Optionnel : templates de sortie, edge cases
└── steps/
    ├── step-01-analyze.md
    ├── step-02-implement.md
    └── step-03-verify.md

Template d'agent

Créez framework/agents/{name}.md :

---
name: mon-agent
role: Description courte du rôle
model: sonnet
color: blue
description: |
  Description détaillée de la mission de l'agent.
  Utiliser quand : [contexte d'utilisation].
allowed-tools: Read, Glob, Grep, Bash
---

## Identité

Tu es un agent spécialisé dans [domaine]. Tu [mission principale].

## Responsabilités

1. [Responsabilité 1]
2. [Responsabilité 2]
3. [Responsabilité 3]
4. Produire un rapport structuré

## Contraintes

- **Read-only** : ne modifie aucun fichier (si applicable)
- **Facts only** : rapporter ce qui est, pas ce qui devrait être
- **Scope strict** : uniquement [périmètre]

## Format de sortie

\`\`\`markdown
# [Nom] Report

## Résumé
- Éléments analysés : {n}
- ✅ Conformes : {n}
- ❌ Non conformes : {n}

## Détails

### ✅ [élément conforme]
Conforme. [raison].

### ❌ [élément non conforme]
- 🔴 [problème critique]
- 🟡 [problème mineur]

## Recommandations
1. [action corrective]
\`\`\`

Template de profile

Créez framework/profiles/{name}.md :

---
name: ma-stack
description: |
  Conventions et patterns pour [nom de la stack].
  Utiliser quand : projet utilisant [technologies].
---

## Stack

- **Langage** : [langage + version]
- **Framework** : [framework + version]
- **ORM/DB** : [ORM + base de données]
- **Tests** : [framework de tests]

## Conventions

### Structure de fichiers

\`\`\`
src/
├── models/        ← [description]
├── services/      ← [description]
├── routes/        ← [description]
└── utils/         ← [description]
\`\`\`

### Nommage

| Élément | Convention | Exemple |
|---------|-----------|---------|
| Fichiers | [convention] | `user-service.ts` |
| Classes | [convention] | `UserService` |
| Fonctions | [convention] | `getUserById` |
| Variables | [convention] | `userName` |

## Patterns à suivre

- [Pattern 1 avec exemple de code court]
- [Pattern 2 avec exemple de code court]

## Anti-patterns à éviter

- ❌ [Anti-pattern 1 — pourquoi c'est mauvais]
- ❌ [Anti-pattern 2 — pourquoi c'est mauvais]

## Dépendances recommandées

| Besoin | Package |
|--------|---------|
| [besoin] | `package-name` |