Initialiser les issues et le projet d'un dépôt
Met en place les conventions supposées par les autres compétences issue-*. Tout ici écrit sur GitHub
(labels, un projet, un lien de dépôt) : indiquez ce que vous allez créer et obtenez d'abord l'accord de l'utilisateur.
Rien n'est poussé vers git.
Prérequis : gh auth status montre les scopes repo et project (sinon
gh auth refresh -s project) ; jq est installé.
1. Inspection (lecture seule)
REPO=$(gh repo view --json nameWithOwner -q .nameWithOwner); OWNER=${REPO%%/*}
gh label list --repo "$REPO" --limit 100
gh project list --owner "$OWNER"
2. Labels
Créez les labels standards ci-dessous (nom|description|couleur). Ajoutez les labels composant
propres au dépôt (par défaut backend, frontend ; supprimez ou ajoutez selon le besoin). Laissez les labels par défaut de GitHub
(enhancement, documentation, ...) tranquilles sauf demande contraire.
while IFS='|' read -r n d c; do
gh label create "$n" --repo "$REPO" --description "$d" --color "$c" --force
done <<'EOF'
bug|Quelque chose ne fonctionne pas|d73a4a
feature|Nouvelle fonctionnalité pour l'utilisateur|a2eeef
tech-debt|Dette technique suivie|fbca04
epic|Effort multi-issues|5319e7
backend|Backend / services|0e8a16
frontend|Frontend / application web|1d76db
performance|Performance|fef2c0
security|Sécurité|d93f0b
testing|Tests / CI / E2E|c5def5
privacy|Vie privée / RGPD|bfdadc
ai|Accessible par un agent IA sans intervention humaine|7057ff
needs-context|Accessible par IA après une vérification ou décision rapide (porte aussi ai)|fbca04
needs-human|Nécessite un appareil, une décision juridique/propriétaire, un accès externe ou un choix de roadmap|d93f0b
wontfix|Ne sera pas traité|ffffff
EOF
gh label list --repo "$REPO" # create est silencieux en cas de succès : vérifiez
3. Board
A. Copier un board de référence (champs et vues, pas les éléments) :
gh project copy <numéro-source> --source-owner <propriétaire> --target-owner "$OWNER" --title "<Nom du dépôt>"
B. Depuis zéro :
gh project create --owner "$OWNER" --title "<Nom du dépôt>" --format json -q '.number' # notez-le comme $N
for f in Portée Impact "Confidence (%)" "Effort (jours)" RICE; do
gh project field-create "$N" --owner "$OWNER" --name "$f" --data-type NUMBER
done
Un nouveau board a déjà un champ Statut avec Todo, In Progress, Done ; cela suffit
(une option Defer peut être ajoutée dans l'interface du board).
Ensuite, liez-le et vérifiez :
gh project link "$N" --owner "$OWNER" --repo "$REPO"
# puis suivez "Résoudre d'abord les IDs" dans issue-project-fields : il doit trouver le board et tous ses champs
4. Documentez-le dans le dépôt
Ajoutez cette section aux instructions de l'agent du dépôt (AGENTS.md, CLAUDE.md, ou les deux), en remplissant
les placeholders <...> (dépôt, URL du board, et les labels composant que vous avez créés à l'étape 2 ; si les
compétences proviennent d'un plugin, dites-le et nommez-le). Commitez sur une branche, pas la branche par défaut.
## Suivi du travail (GitHub Issues)
Le backlog se trouve dans les **GitHub Issues** (`<propriétaire/dépôt>`), suivi dans le projet **<titre du board>**
(<URL du board>). L'issue est la source de vérité pour le contexte *et* le statut ; référez-vous au travail par numéro
d'issue (`#123`) et par labels. Compétences de workflow : `issue-search`, `issue-file`, `issue-start`,
`issue-pr-refs`, `issue-close-out`, `issue-project-fields`, `issue-score`, `issue-link`,
`issue-plan-doc`, `issue-file-found`, `issue-audit-scores`, `issue-project-init` (<d'où elles viennent>).
### Labels
| Groupe | Labels | Règle |
|---|---|---|
| Type | `bug`, `feature`, `tech-debt`, `epic` | Exactement un par issue |
| Composant | <p. ex. `backend`, `frontend`> | Autant que nécessaire |
| Sujet | `performance`, `security`, `testing`, `privacy` | Optionnel |
| Routage agent | `ai`, `needs-context`, `needs-human` | Optionnel. `ai` = un agent peut le faire sans surveillance ; `needs-context` = un agent peut le faire une fois qu'une question rapide a été répondue (porte aussi `ai`) ; `needs-human` = nécessite un appareil, un accès externe ou une décision du propriétaire |
### Champs du projet
| Champ | Valeurs | Notes |
|---|---|---|
| Statut | Todo / In Progress / Done | Défini uniquement par l'agent orchestrateur |
| Portée | 1–5 | Combien d'utilisateurs cela touche |
| Impact | 0.5–3 | Taille de l'effet |
| Confiance (%) | pourcentage entier, ex. `70` | |
| Effort (jours) | nombre | |
| RICE | `(Portée × Impact × Confiance) / Effort` | Également écrit dans le corps comme `**Score:** RICE x = (P × I × C%) / Ed` pour que l'issue soit autonome |
### Corps de l'issue et workflow
**Le corps de l'issue** contient tout l'enregistrement : Description, État actuel, Ce qui doit être fait, Pourquoi c'est
important, Fichiers liés, estimation. Liez le travail connexe avec `#n` ; exprimez l'ordonnancement avec "bloqué par"
(texte du corps et API des dépendances, voir `issue-link`). Un gros travail est une `epic` dont le plan se trouve dans
le corps de l'issue et dont les morceaux sont des sous-issues.
- **Avant de commencer :** cherchez d'abord (`issue-search`) ; réutilisez ou étendez plutôt que de créer des doublons.
- **Pendant le travail :** mettez l'élément en In Progress et assignez-le (`issue-start`) ; les noms de branche portent le
numéro d'issue (`feat/123-short-desc`). Les bugs et la dette technique commencent par un test qui échoue. Déposez les
découvertes non liées comme de nouvelles issues au lieu d'étendre le périmètre (`issue-file-found`).
- **En terminant :** chaque PR référence ses issues (`Closes #n` par issue, `Part of #n` pour l'epic ;
`issue-pr-refs`) ; après la fusion, mettez Statut = Done et mettez à jour les issues liées (`issue-close-out`).
- `gh` nécessite le scope `project` (`gh auth refresh -s project`). Seul l'agent orchestrateur
modifie le statut des issues/projet ; les sous-agents délégués ne créent, ne modifient ni ne ferment d'issues.
5. Optionnel : amorcer une epic
issue-file (type epic) → issue-plan-doc → par morceau issue-file + issue-link +
issue-project-fields + issue-score.
Pièges
gh label create,gh project copy|link|item-editsont silencieux en cas de succès : vérifiez toujours.- Un board copié commence vide ;
item-addest idempotent. - Les appels REST pour les sous-issues et dépendances utilisent l'ID numérique de base de données de l'issue (voir
issue-link). - La confiance est un pourcentage entier (
70) ; les IDs diffèrent selon les boards, donc redécouvrez-les toujours (issue-project-fields).