--- name: acli description: "OBLIGATOIRE pour TOUTE interaction avec Jira ou Confluence. Utiliser ce skill AVANT d'exécuter toute commande acli. Couvre : créer/modifier/commenter des tickets, ajouter des commentaires (format ADF obligatoire sur Jira Cloud), rechercher des work items, gérer les sprints/boards, gérer les espaces Confluence. TRIGGER : dès que le message mentionne 'Jira', 'ticket', 'Confluence', 'acli', 'Atlassian', 'sprint', 'backlog', 'epic', 'work item', 'issue', ou contient une clé de ticket (ex: PROJ-123). Ne JAMAIS exécuter acli en Bash sans charger ce skill d'abord." allowed-tools: ["Bash", "Read", "Write", "Glob", "Grep"] model: sonnet --- # Atlassian CLI (acli) Skill pour construire et exécuter des commandes `acli` (Atlassian CLI v1.3+). ## Quick Start ```bash # Vérifier l'authentification acli jira auth status # Chercher des work items acli jira workitem search --jql "project = TEAM AND status = 'In Progress'" --limit 10 # Créer un work item acli jira workitem create --summary "Fix login bug" --project TEAM --type Bug # Voir un work item acli jira workitem view KEY-123 ``` ## Syntaxe générale ``` acli [flags] ``` - **product** : `jira`, `confluence`, `admin`, `auth`, `config`, `rovodev` - **resource** : `workitem`, `project`, `board`, `sprint`, `filter`, `dashboard`, `field`, `space`, `user`, `auth` - **action** : `create`, `search`, `view`, `edit`, `delete`, `transition`, `list`, etc. ## Produits et commandes disponibles ### Jira (`acli jira`) | Ressource | Actions | |--------------|-------------------------------------------------------------------------------------------| | `workitem` | create, create-bulk, search, view, edit, delete, transition, assign, clone, archive, unarchive | | `workitem comment` | create, list, update, delete, visibility | | `workitem link` | create, delete, list, type | | `workitem attachment` | list, delete | | `workitem watcher` | list, remove | | `project` | create, list, view, update, delete, archive, restore | | `board` | create, search, get, delete, list-sprints, list-projects | | `sprint` | create, update, view, delete, list-workitems | | `filter` | search, list, get, update, get-columns, reset-columns, add-favourite, change-owner | | `dashboard` | search | | `field` | create, delete, cancel-delete | ### Confluence (`acli confluence`) | Ressource | Actions | |-----------|-----------------------------------------------| | `space` | create, list, view, update, archive, restore | ### Admin (`acli admin`) | Ressource | Actions | |-----------|-------------------------------------------| | `user` | activate, deactivate, delete, cancel-delete | ### Authentification | Commande | Description | |------------------------|--------------------------------------| | `acli auth login` | OAuth global | | `acli jira auth login` | Auth Jira (--web, --token, --email, --site) | | `acli confluence auth login` | Auth Confluence (memes flags) | | `acli admin auth login`| Auth Admin (--email, --token) | | `acli * auth status` | Vérifier le statut | | `acli * auth switch` | Basculer entre comptes | | `acli * auth logout` | Se déconnecter | ## Flags communs | Flag | Description | |-------------------|----------------------------------------------------| | `--json` | Sortie JSON | | `--csv` | Sortie CSV | | `--limit N` | Limiter le nombre de résultats | | `--paginate` | Récupérer tous les résultats (ignore --limit) | | `--yes` / `-y` | Confirmer sans prompt | | `--ignore-errors` | Continuer en cas d'erreur | | `--web` / `-w` | Ouvrir dans le navigateur | | `--fields` | Sélectionner les champs affichés | | `-h, --help` | Afficher l'aide d'une commande | ## Sélection de work items (multi-targeting) Plusieurs commandes (edit, transition, assign, delete, archive, comment create) supportent 3 modes de sélection : | Flag | Description | Exemple | |------------------|--------------------------------------|-----------------------------------------| | `--key` | Par clé(s), séparées par virgule | `--key "KEY-1,KEY-2"` | | `--jql` | Par requête JQL | `--jql "project = TEAM"` | | `--filter` | Par ID de filtre sauvegardé | `--filter 10001` | | `--from-file` | Depuis un fichier (clés/IDs) | `--from-file "issues.txt"` | ## Commentaires Jira : formatage riche via ADF **IMPORTANT** : `comment create` n'a PAS de flag `--body-adf`. Seul `comment update` le supporte. ### Workflow pour un commentaire bien formaté ```bash # 1. Créer un placeholder acli jira workitem comment create --key KEY-123 --body "(mise en forme en cours...)" # 2. Récupérer l'ID du commentaire acli jira workitem comment list --key KEY-123 --json | \ python3 -c "import json,sys; cs=json.load(sys.stdin)['comments']; print(cs[-1]['id'])" # 3. Mettre à jour avec ADF (Atlassian Document Format) acli jira workitem comment update --key KEY-123 --id COMMENT_ID --body-adf /tmp/comment.json ``` ### Structure ADF Le fichier JSON doit contenir un document ADF (sans wrapper `{"body": ...}`) : ```json { "version": 1, "type": "doc", "content": [ {"type": "heading", "attrs": {"level": 2}, "content": [ {"type": "text", "text": "Titre"} ]}, {"type": "paragraph", "content": [ {"type": "text", "text": "texte normal "}, {"type": "text", "text": "gras", "marks": [{"type": "strong"}]}, {"type": "text", "text": " et "}, {"type": "text", "text": "code", "marks": [{"type": "code"}]} ]}, {"type": "bulletList", "content": [ {"type": "listItem", "content": [ {"type": "paragraph", "content": [{"type": "text", "text": "item"}]} ]} ]}, {"type": "table", "content": [ {"type": "tableRow", "content": [ {"type": "tableHeader", "content": [ {"type": "paragraph", "content": [{"type": "text", "text": "Colonne"}]} ]} ]}, {"type": "tableRow", "content": [ {"type": "tableCell", "content": [ {"type": "paragraph", "content": [{"type": "text", "text": "Valeur"}]} ]} ]} ]}, {"type": "panel", "attrs": {"panelType": "note"}, "content": [ {"type": "paragraph", "content": [{"type": "text", "text": "Note importante"}]} ]}, {"type": "rule"} ] } ``` ### Nœuds ADF disponibles | Nœud | Usage | Attributs | |------|-------|-----------| | `heading` | Titres | `attrs.level` (1-6) | | `paragraph` | Paragraphe | — | | `bulletList` / `orderedList` | Listes | contient `listItem` | | `table` | Tableau | contient `tableRow` → `tableHeader` / `tableCell` | | `codeBlock` | Bloc de code | `attrs.language` | | `blockquote` | Citation | — | | `panel` | Encadré | `attrs.panelType` : `info`, `note`, `warning`, `error`, `success` | | `rule` | Séparateur horizontal | — | | `hardBreak` | Retour à la ligne (inline) | — | ### Marks (formatage inline) | Mark | Rendu | |------|-------| | `{"type": "strong"}` | **gras** | | `{"type": "em"}` | *italique* | | `{"type": "code"}` | `code` | | `{"type": "underline"}` | souligné | | `{"type": "strike"}` | barré | | `{"type": "link", "attrs": {"href": "url"}}` | lien | ### Commentaire simple (texte brut) Pour un commentaire sans formatage, `--body` ou `--body-file` suffisent : ```bash acli jira workitem comment create --key KEY-123 --body "Commentaire simple" acli jira workitem comment create --key KEY-123 --body-file /tmp/comment.txt ``` ## Analyse complète d'un ticket **RÈGLE** : Lors de l'analyse d'un ticket Jira, toujours récupérer en parallèle : ```bash # 1. Description complète acli jira workitem view KEY-123 --fields '*all' # 2. Commentaires acli jira workitem comment list --key KEY-123 # 3. Pièces jointes acli jira workitem attachment list --key KEY-123 ``` **Pièces jointes** : `acli` ne permet PAS de télécharger les attachments. Workaround : - Chercher localement : `find ~/projets -name "nom-du-fichier"` - Les études et analyses sont souvent dans `TravailAFaire/` du projet - Ne pas télécharger les fichiers sensibles/binaires (SQL, dumps, credentials, keystores, images) ### Patterns `--fields` pour `view` ```bash # Tous les champs (priorité, URL, projet, labels, etc.) acli jira workitem view KEY-123 --fields '*all' # Champs spécifiques (ex: summary + commentaires) acli jira workitem view KEY-123 --fields 'summary,comment' # Exclure un champ (ex: tout sauf description) acli jira workitem view KEY-123 --fields '-description' # Champs spéciaux : '*all', '*navigable', 'comment', 'attachment' ``` ## Erreurs fréquentes (flags inexistants) | Erreur | Correction | |--------|------------| | `--action` | Utiliser les sous-commandes (`create`, `view`, etc.) | | `--outputFormat` | `--json` | | `--comments` | `--fields 'comment'` | | `--output json` | `--json` | | `search --project` | `--jql "project = INDELINE"` | | `attachment download` | N'existe pas — chercher le fichier localement | ## Création de work items — pièges connus ### Types de tickets : noms en français obligatoires Les noms de types dans `--type` dépendent de la **langue du projet Jira**. Pour le projet INDELINE, les types sont en français : - `Epic` (identique en français/anglais) - `Développement` (PAS "Task") — **ATTENTION : c'est un type subtask**, n'apparaît PAS dans le backlog Scrum - `Sous-tâche` (PAS "Sub-task") — type subtask, n'apparaît PAS dans le backlog - `Story`, `Problème`, `Recette`, `Spécifications`, `Fiche recette`, `Documentation`, `Validation juridique`, `MEP Extranet`, `MEP Intranet` **ERREUR FRÉQUENTE** : `--type "Task"` est **silencieusement rejeté** (pas de ticket créé, pas d'erreur visible avec `--json`). Utiliser un type non-subtask. **Comment découvrir les types autorisés** : provoquer une erreur avec un type invalide : ```bash acli jira workitem create --project INDELINE --type "INVALID" --summary "test" # → Error: Allowed issue types for project are : Tâche, Sous-tâche, Story, ... ``` ### Backlog Scrum : types subtask vs non-subtask **RÈGLE CRITIQUE** : les types marqués `subtask: true` (comme `Développement`, `Sous-tâche`) n'apparaissent **PAS** dans le backlog Scrum. Ils sont imbriqués sous leur parent et invisibles dans la vue backlog. Pour créer des tickets visibles dans le backlog et rattachés à un Epic, utiliser un **type non-subtask** avec `--parent` : - `Story` — pour les fonctionnalités - `Problème` — pour les bugs/correctifs ### `--parent` : comportement selon le type - `--parent "EPIC-KEY"` fonctionne pour rattacher un ticket enfant à un Epic - Le type enfant doit être compatible (ex: `Story`, `Problème`) - **PIÈGE** : si le type n'est pas compatible avec `--parent`, la commande échoue **silencieusement** (exit code 0, pas de ticket créé, pas de JSON en sortie) - **Vérification obligatoire** : toujours capturer le JSON de sortie et vérifier que le `key` est présent ### Ne pas affecter les tickets automatiquement **RÈGLE** : ne jamais utiliser `--assignee` lors de la création. Les tickets doivent être créés **non assignés** et apparaître dans le backlog pour que l'équipe les prenne en charge. ### Vérification post-création Toujours vérifier que les tickets ont été créés : ```bash # Vérifier les enfants d'un Epic acli jira workitem search --jql "parent = INDELINE-XXXX" --fields "key,issuetype,summary" ``` ### Suppression de tickets `acli jira workitem delete` demande une confirmation interactive. Utiliser : ```bash echo "y" | acli jira workitem delete --key KEY-123 ``` ### Liens entre tickets ```bash # Lister les types de liens disponibles acli jira workitem link type # Créer un lien (ex: "Blocks") acli jira workitem link create --out KEY-123 --in KEY-456 --type Blocks # Créer un lien "Relates" acli jira workitem link create --out KEY-123 --in KEY-456 --type Relates ``` ### Recherche : pas de `--project` La commande `search` n'a pas de flag `--project`. Utiliser `--jql` : ```bash acli jira workitem search --jql "project = INDELINE AND ..." --fields "key,summary" ``` ### Champs non disponibles selon le type Certains types de tickets n'exposent pas tous les champs. Erreur typique : ``` Error: Field 'description' cannot be set. It is not on the appropriate screen, or unknown. ``` **PIÈGE** : Le champ `description` peut être absent de l'écran de création ET d'édition pour certains types (Story, Problème). Cela dépend de la configuration Jira du projet, pas du type lui-même. **Workaround si description indisponible** : Ajouter le contenu en **commentaire ADF** : ```bash # 1. Créer un placeholder acli jira workitem comment create --key KEY-123 --body "(description détaillée)" # 2. Récupérer l'ID du commentaire acli jira workitem comment list --key KEY-123 --json | \ python3 -c "import json,sys; cs=json.load(sys.stdin)['comments']; print(cs[-1]['id'])" # 3. Mettre à jour avec ADF formaté acli jira workitem comment update --key KEY-123 --id COMMENT_ID --body-adf /tmp/comment.json ``` ### Champs custom obligatoires Certains types (Story, Problème) exigent des champs custom avec des valeurs de **select list**. Ces champs doivent être passés via `additionalAttributes` dans `--from-json`. **IMPORTANT** : Les select lists exigent le format `{"value": "..."}` ou `{"id": "..."}`, pas une string brute. **Comment découvrir les valeurs valides** : Inspecter un ticket existant du même type : ```bash acli jira workitem view KEY-123 --fields '*all' --json | python3 -c " import json, sys data = json.load(sys.stdin) for k, v in sorted(data['fields'].items()): if 'customfield' in k and v and isinstance(v, dict) and 'value' in v: print(f'{k}: {json.dumps(v, ensure_ascii=False)[:150]}') " ``` **RÈGLE** : Avant de créer un ticket d'un type jamais utilisé, toujours inspecter un ticket existant du même type pour découvrir les champs obligatoires et leurs valeurs valides. Sauvegarder ces infos en mémoire projet. ### Descriptions en ADF (Atlassian Document Format) **RÈGLE** : Pour les descriptions de work items avec formatage riche, toujours utiliser `--from-json` (jamais `--description-file` qui échoue en ADF, ni le wiki markup `h2.` qui ne rend pas en Jira Cloud). ### `--from-json` : différences create vs edit - **create** : supporte `additionalAttributes` pour les champs custom (select lists, Epic Link, etc.) - **edit** : ne supporte **PAS** `additionalAttributes` — seuls `summary`, `description`, `assignee`, `type`, `labels` sont éditables - Pour modifier un champ custom après création, il faut **supprimer et recréer** le ticket, ou passer par l'API REST Jira directement ### Epic Link via `--from-json` Pour rattacher un ticket à un Epic lors de la création, inclure l'Epic Link dans `additionalAttributes` : ```json { "projectKey": "PROJ", "type": "Story", "summary": "...", "additionalAttributes": { "customfield_10014": "EPIC-KEY" } } ``` **Note** : Le champ Epic Link est souvent `customfield_10014` mais peut varier selon le projet. Vérifier via un ticket existant. Workflow : ```bash # 1. Générer le template JSON acli jira workitem edit --generate-json # 2. Créer le fichier JSON avec ADF dans le champ "description" + "issues" pour cibler # 3. Appliquer acli jira workitem edit --from-json /tmp/edit.json --yes ``` Le champ `description` dans le JSON doit contenir un document ADF (même structure que pour les commentaires, voir section ADF ci-dessus). Le champ `issues` contient la liste des clés à modifier. ## Comportement attendu 1. **Toujours vérifier l'auth en premier** : exécuter `acli jira auth status` ou `acli confluence auth status` avant toute opération si doute. 2. **Préférer --json pour le parsing** : quand le résultat doit être traité programmatiquement, utiliser `--json` et parser avec `jq` ou `python3 -c`. 3. **Confirmer les actions destructives** : ne jamais ajouter `--yes` automatiquement sur delete, transition de masse, ou archive. Demander confirmation à l'utilisateur. 4. **Utiliser --limit pour les grosses recherches** : éviter `--paginate` sans besoin, préférer `--limit` raisonnable. 5. **JQL entre guillemets** : toujours entourer la requête JQL de guillemets doubles. 6. **Fichiers d'entrée** : pour les opérations bulk, préférer `--from-json` ou `--from-csv` avec des fichiers temporaires générés par Write. 7. **Ne jamais stocker de tokens en clair** : utiliser `--token < fichier` ou `echo $TOKEN | acli ... --token`. 8. **Vérifier les créations** : après `workitem create`, toujours vérifier la sortie JSON pour confirmer que le ticket a bien été créé (présence du champ `key`). 9. **Types en français** : pour le projet INDELINE, utiliser les noms de types en français (`Développement`, pas `Task`). ## Référence complète Pour la référence détaillée de chaque commande avec tous les flags : voir [reference.md](reference.md).