flowdeck/docs/flowdeck-agents-skills-phase1-tickets.md

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.