Contribuer au projet

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

Structure du projet

framework/
├── personas/          ← Rôles IA
├── 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 persona
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

Suivez le tutoriel correspondant :

• Créer un skill
• Créer un persona
• 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
Persona	Fichier .md avec identité, menu, contraintes
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-persona

# Commiter
/commit

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

Conventions de contribution

Nommage

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

Langue

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

Structure d'un skill

skills/{name}/
├── SKILL.md           ← Obligatoire, < 5000 tokens
├── REFERENCE.md       ← Optionnel, détails et templates
└── steps/             ← Optionnel, si > 5 steps
    ├── step-01-*.md
    └── step-02-*.md

Frontmatter obligatoire

Tout composant doit avoir un frontmatter YAML avec au minimum :

---
name: nom-unique
description: |
  Description claire de quand et pourquoi utiliser ce composant.
---

Que contribuer ?

Idées de skills

Skill	Description
/deploy	Pipeline de déploiement (build → test → deploy → healthcheck)
/db-migrate	Création + validation de migrations DB
/api-doc	Générer la documentation OpenAPI
/perf-audit	Audit de performance (lighthouse, k6, profiling)
/security-scan	Scan de sécurité (dépendances, secrets, OWASP)

Idées de personas

Persona	Rôle
dba	Expert base de données
devops	Expert CI/CD et infrastructure
ux-designer	Expert UX/UI
tech-writer	Rédacteur technique
qa-engineer	Expert qualité et tests

Idées de profiles

Profile	Stack
python-django	Django + DRF
python-fastapi	FastAPI + SQLAlchemy
java-spring	Spring Boot + JPA
typescript-nestjs	NestJS + TypeORM
go-gin	Gin + GORM
react-typescript	React + TypeScript + Zustand
svelte-kit	SvelteKit + TypeScript

Idées d'agents

Agent	Mission
dependency-auditor	Vérifier les dépendances obsolètes/vulnérables
api-tester	Tester les endpoints automatiquement
doc-linter	Vérifier la qualité de la documentation
config-validator	Valider les fichiers de configuration

Questions fréquentes

Mon skill est trop long, que faire ?

Découpez-le en step files séparés dans skills/{name}/steps/. Le SKILL.md ne doit contenir que le frontmatter, l'usage, les flags et la vue d'ensemble du pipeline.

Dois-je créer un persona ou un agent ?

• Persona : si le rôle dialogue avec l'utilisateur et opère dans le pipeline principal
• Agent : si la tâche est autonome, ciblée, et retourne un rapport

Comment savoir si mon profil est bien fait ?

Lancez /apex avec votre profil actif et vérifiez que :

• L'Architect propose des patterns spécifiques à votre stack
• Le Developer utilise les bonnes conventions
• Le Reviewer détecte les anti-patterns listés dans le profil

Puis-je modifier les personas de base ?

Oui, mais préférez les profiles pour ajouter du contexte technologique. Modifiez un persona de base uniquement si vous voulez changer son comportement fondamental (responsabilités, contraintes, menu).