# Flowdeck Agents & Skills — Phase 1 : découpage en tickets prêts à développer

_Dérivé du document d'architecture v1.0 (`architecture-agents-skills-notion-flowdeck.md`, §20 Phase 1). Chaque ticket cite la section source. Estimations relatives (S/M/L), pas des engagements. Périmètre strict de la Phase 1 : « le skill devient une page » (écarts E1, E3, E4 côté modèle). Le routeur automatique (§13.2), `agent_runs` (migration 40) et la personnalisation de l'Agent personnel sont en Phase 2 et ne sont **pas** dans ce découpage._

## Critère de sortie de la phase (§20)

UC-02 (skill manuel dans le chat : `/` → choisir un skill → résultat au format du skill) et UC-04 (skill dans l'éditeur, sur sélection ou bloc) fonctionnent entièrement sur des pages ; un playbook existant devient un skill sans copier-coller.

## Avant de coder : 1 spike de décision

- **SPIKE-A — Skills intégrés et AI Writing** (§23 Q3) : les prompts des 6 actions d'`ai_writing.py` deviennent-ils littéralement les pages des skills intégrés (éditables par l'admin), le service restant seulement pour l'autocomplétion inline (latence) ? C'est la voie proposée par le document pour les quatre skills d'édition. _Sortie : une page de décision qui conditionne A1-13, pas du code._

## Modèle de données — migration 41 (§10.3, §10.4)

- **A1-1 (M)** Migration 41 — skills (§10.3) : `collections.is_skills_db` + correspondance des propriétés dans `collections.schema_json` (`Description` / `Files` / `Tags`) ; recréation `agent_skills` → `agent_skills_v2` par copie (`page_id` unique, `name_cached`, `description`, `files_json`, `tools_json`, `is_builtin`, `auto_use_default`, `editor_menu_default`, `status`, `source`). _Acceptation : migration transactionnelle ; aucun drapeau `is_skill` sur `pages` — être un skill = avoir une ligne `agent_skills` (décision §10.3 n°1)._
- **A1-2 (S)** Activation par utilisateur (§10.4) : table `user_skill_enablements` (`enabled`, `auto_use` et `editor_menu` en NULL = suit le réglage du skill). _Acceptation : désactiver pour soi ne modifie ni la page ni les réglages des autres utilisateurs._
- **A1-3 (M)** Migration du contenu existant (§10.3 n°3, §22) : chaque skill `agent_skills` sans page reçoit une page générée conservant le prompt d'origine à l'identique (`source='legacy'`) ; les 17 presets de la galerie deviennent des pages dans la base de skills privée de l'utilisateur à l'installation. _Acceptation : vérification par comptage et échantillon avant bascule (§22, risque n°1) ; aucun skill ne survit hors du modèle page._
- **A1-4 (S)** Indexation (§10.3 n°4) : titre + `description` indexés dans `semantic_embeddings` avec `resource_type='skill'` par le moteur d'indexation incrémental existant. _Acceptation : créer/modifier un skill met à jour son index sans réindexation globale — c'est l'index que lira le routeur en Phase 2._

## Page, base et bannière (§7.5, §13.1)

- **A1-5 (M)** Marquer / démarquer une page (§7.5, §13.1) : entrée `•••` → *Use as a skill* ; marquer = insérer la ligne `agent_skills`, décocher = la supprimer, le contenu de la page ne bouge jamais. Créateur activé automatiquement (`Enable for me` implicite).
- **A1-6 (M)** Bannière de skill (§7.5, maquette §7A.2) : nom, base, état activé pour moi, interrupteurs *Use automatically* / *Add to text editor menu*, bouton *Download for local agents*, rappel qu'un skill partagé en édition est mutable par ses éditeurs pour tous. Aucun nouvel éditeur : on écrit un skill comme une page.
- **A1-7 (M)** Base de skills (§7.5) : conversion d'une collection ordinaire via le dialogue de correspondance `Description` / `Files` / `Tags` (créer ou mapper), case « activer les pages existantes comme skills pour moi » ; gabarit *Database → Skills* à la création ; badge « Skills » sur la collection. Dans une base, le skill est la page-ombre de la ligne (`pages.collection_row_id`), `Description`/`Files` relues depuis `property_values_json`.

## Library (§7.4)

- **A1-8 (M)** Onglet Skills de la Library : table des skills activés/créés (Nom, Base, Description tronquée, *Use automatically*, *Menu éditeur*, Propriétaire, Dernière utilisation), actions *New skill*, ouvrir, désactiver pour soi ; recherche/filtres par nom, description, base, propriétaire, `Tags`.
- **A1-9 (S)** Sous-vue Discover (§7.4, §13.5) : skills accessibles en lecture mais non activés ; bouton **Enable for me** par ligne, confirmation immédiate. `Discover` = accès lecture sans ligne `user_skill_enablements` active ; le partage reste celui de la page/base, aucun nouveau droit.

## Exécution manuelle — Skill Runner minimal (§13.3, §11.3)

- **A1-10 (L)** Skill Runner, invocation manuelle seulement : construction de la consigne depuis la page rendue en Markdown (blocs éligibles §13.4, contenu imbriqué inclus) + extraits des fichiers de support `shareable` dans le budget + entrée du run ; contrainte d'outils en **intersection seulement** (§13.7 : un skill n'élargit jamais les outils, ne modifie pas les consignes système, ses fichiers sont des données, pas des instructions). La réponse nomme le skill utilisé.
- **A1-11 (M)** Surface chat — UC-02 (§9.2 pour l'éditeur, §11.3) : `POST /api/agent/skills/{id}/run-chat`, menu `/` alimenté par `GET /api/agent/skills/menu` (activés d'abord). _Acceptation UC-02 : `/` → Project Brief Writer → brief au format d'équipe, entièrement depuis la page du skill._
- **A1-12 (M)** Surface éditeur — UC-04 (§7.2, §13.4) : `POST /api/agent/skills/{id}/run-editor`, résultat en diff ou insertion ; éligibilité déclarée par type de bloc (`skill_eligible: bool` dans le registre des types) : texte, H1–H3, citation, callout, listes, toggle, image, bloc synchronisé. _Acceptation UC-04 : les skills personnels d'abord, puis les intégrés, dans le menu de sélection et le menu de bloc._

## Skills intégrés (§20, annexe C) — dépend de SPIKE-A

- **A1-13 (M)** Les 6 actions AI Writing exposées comme skills intégrés (`is_builtin=1`, seed, non supprimables mais désactivables) : Améliorer l'écriture · Corriger · Expliquer · Reformater · Traduire · Résumer ; unification des trois points d'entrée éditeur existants sur le Skill Runner (A1-10).

## Export / import `SKILL.md` (§13.6, §11.3)

- **A1-14 (M)** Export : sérialisation `SKILL.md` (front matter `name` + `description`, corps de page en Markdown) + bundle avec les fichiers de support `shareable=1` ; `GET /api/agent/skills/{id}/download`. Le format `flowdeck-skill` v1 (JSON) reste le format d'échange Flowdeck ↔ Flowdeck (ADR-08).
- **A1-15 (S)** Import : `POST /api/agent/skills/import` accepte `SKILL.md` externe et v1 ; un `SKILL.md` importé devient une page-skill dans la base privée de l'importateur, ses fichiers joints deviennent la propriété `Files`. Suivi de version : ligne `skill_local_downloads` (§10.4) à chaque téléchargement, badge « copie locale périmée » quand l'empreinte de page a changé. _Note : l'écriture directe chez les agents locaux est la question ouverte Q4 (§23) — la Phase 1 livre le téléchargement seul, pas d'utilitaire compagnon._

## API (§11.3) — récapitulatif des routes nouvelles livrées par les tickets ci-dessus

`POST|DELETE /api/agent/pages/{id}/skill` · `POST /api/agent/skills/from-page` · `GET /api/agent/skills/menu` · `PUT /api/agent/skills/{id}/enablement` · `POST …/run-chat` · `POST …/run-editor` · `GET …/download` · `POST /api/agent/skills/import` · `PUT /db/{id}/skills-db` · v2 : `GET /api/v2/skills` expose `page_id`, `description` et la sérialisation `SKILL.md` (`Accept: text/markdown`).

## Ordre conseillé

`SPIKE-A → A1-1 → A1-3 → A1-2/A1-4 → A1-5 → A1-6/A1-7 → A1-8/A1-9 → A1-10 → A1-11/A1-12 → A1-13 → A1-14/A1-15`

## Hors Phase 1 (ne pas ouvrir maintenant)

Routeur automatique et journal de décision (§13.2, Phase 2), migration 40 / `agent_runs` (Phase 2 limitée, Phase 3 complète), page « Mon Flowdeck AI » et instructions-page de l'Agent personnel (Phase 2), déclencheurs événementiels et Custom Agents autonomes (Phase 3), crédits / `ai_usage_ledger` migration 42 et espace fichiers migration 43 (Phase 4). Les questions Q1 (crédits), Q2 (modèle par défaut), Q5 (Slack vs messagerie existante) et Q6 (rétention des runs) ne bloquent **pas** la Phase 1.