| name | import-external |
| description | Importe une doc externe (Spec Kit, BMAD-METHOD, GSD) vers `docs/story/NNN-<f|r|t>-<slug>/`. Détecte la source, mappe les sections vers `pitch.md`/`plan.md` avec validation, copie via `git mv` pour préserver l'historique. |
| user_invocable | true |
| disable-model-invocation | true |
| argument-hint | [spec-kit | bmad | gsd] |
| allowed-tools | ["Read","Write","Edit","Grep","Glob","Bash(ls:*)","Bash(find:*)","Bash(mkdir:*)","Bash(cp:*)","Bash(git mv:*)","Bash(git add:*)"] |
/import-external — Import depuis Spec Kit, BMAD-METHOD ou GSD
Ce skill fait passer un projet d'un autre framework spec-driven (Spec Kit, BMAD-METHOD, get-shit-done) vers le format forge : docs/story/NNN-<f|r|t>-<slug>/ avec pitch.md+plan.md pour une feature, plan.md seul pour un refacto ou une évolution tech.
C'est une opération d'import, pas un pont bidirectionnel. L'objectif : récupérer le contenu existant dans la nomenclature workflow pour pouvoir continuer avec /feature-implem, /refactor-implem, /tech-implem, etc. La doc d'origine est conservée (déplacée dans _archive/, pas supprimée) au cas où l'utilisateur veut comparer.
Périmètre
- Détection automatique de la source via la présence de répertoires/fichiers caractéristiques.
- Mapping fichier-à-fichier documenté pour chaque source (voir références).
- Choix du tag (
f/r/t) interactif, avec heuristique sur les mots-clés du titre.
- Compteur global : si certaines stories ont déjà un numéro (Spec Kit), on réutilise. Sinon (BMAD, GSD), on alloue séquentiellement.
- Pas de modification de contenu au-delà du strict minimum (renommage de sections type
## Spec → ## Spec reste tel quel ; le fichier renommé spec.md → pitch.md garde son texte intégral).
Sources supportées
Trois références détaillées, bundlées avec la skill — lis celle qui correspond à la source détectée via Read sur ${CLAUDE_SKILL_DIR}/references/<fichier> (jamais un chemin relatif au projet) :
| Source | Référence | Indice de détection |
|---|
| Spec Kit (GitHub) | spec-kit.md | specs/NNN-<slug>/ avec spec.md+plan.md ; ou .specify/ à la racine |
| BMAD-METHOD | bmad.md | docs/stories/<epic>.<story>*.md ; ou docs/prd.md+docs/architecture.md |
| GSD (get-shit-done) | gsd.md | .plans/<id>-<slug>.md (fichiers plats) ; ou .gsd/ |
Si la source ne matche aucune des trois : « Je ne reconnais pas le format source. Décris-moi la structure (tree -L 3 docs/ specs/ .plans/ 2>/dev/null) et on improvise un mapping manuel. »
Règles du mode interactif
- Lecture seule en phase de plan — n'écrire ni renommer aucun fichier avant validation explicite ("go", "exécute") du plan complet.
- Vérifier l'état du repo — abandonner si l'index n'est pas propre, pour que l'import soit un commit isolé.
- Une seule source à la fois — si plusieurs frameworks coexistent (rare), demander lequel migrer en premier. Mélanger casse les heuristiques.
- Préserver l'historique — utiliser
git mv quand c'est faisable pour qu'un git log --follow retrouve le contenu d'origine.
Déroulement
Phase 1 — Détection de la source
[ -d ".specify" ] || ls -d specs/[0-9][0-9][0-9]-* 2>/dev/null | head -1
[ -f "docs/prd.md" ] || ls docs/stories/*.story.md 2>/dev/null | head -1
[ -d ".gsd" ] || [ -d ".plans" ]
Annonce ce que tu as trouvé : « Source détectée : Spec Kit (8 dossiers sous specs/). Tu confirmes que c'est bien ça qu'on importe ? »
Charge la référence correspondante (${CLAUDE_SKILL_DIR}/references/<source>.md) et suis-la pour le mapping fichiers.
Phase 2 — Inventaire et tagging
Pour chaque story source, construis un enregistrement :
- source : specs/003-checkout-express/
- slug : checkout-express
- numéro source : 003
- titre détecté (depuis spec.md ou frontmatter) : "Express checkout"
- tag proposé : f (heuristique : mots-clés "feature", "user story", "checkout")
- destination : docs/story/003-f-checkout-express/
- mapping fichiers :
spec.md → pitch.md
plan.md → plan.md
tasks.md → _archive/tasks.md
Heuristique de tagging (le skill propose, l'utilisateur confirme/corrige) :
r (refacto) : titre/contenu mentionne refactor, refacto, cleanup, extract, split class, modernize, rename, dead code.t (tech) : titre/contenu mentionne cache, retry, circuit breaker, queue, async, index, migration, health check, latency, performance, observability, log, security, CSP, CVE.f (feature) : par défaut.
Présente un tableau récapitulatif :
| # | Source | Tag proposé | Destination |
|----|---------------------------------|-------------|------------------------------------|
| 1 | specs/001-user-login | f | docs/story/001-f-user-login |
| 2 | specs/002-extract-auth-service | r | docs/story/002-r-extract-auth-service |
| 3 | specs/003-redis-cache | t | docs/story/003-t-redis-cache |
Demande : « Les tags te paraissent corrects ? Tu peux corriger ligne par ligne (ex: "ligne 2 c'est plutôt un t"), ou valider le lot. »
Phase 3 — Allocation des numéros
Si la source utilise déjà un compteur (Spec Kit séquentiel) : on réutilise les numéros pour préserver les références dans les commits/branches existants. Vérifie qu'il n'y a pas de collision avec des dossiers docs/story/ existants — si oui, demande quelle politique appliquer (renuméroter les nouveaux ou les anciens).
Si la source n'a pas de compteur (BMAD avec format <epic>.<story>, GSD avec timestamps/issues) : alloue séquentiellement à partir de max(numéros existants dans docs/story/) + 1. L'ordre est dicté par la date de modification du fichier source (essaie git log --diff-filter=A --format=%ad --date=iso -- <source> pour récupérer la date de création ; à défaut, stat).
Phase 4 — Plan complet et validation
Récapitule tout :
Import depuis Spec Kit :
- 8 stories à importer
- Compteur source réutilisé (numéros 001-008)
- Tags : 6 × f, 1 × r, 1 × t (modifie si besoin)
- Fichiers d'origine déplacés vers
_archive/spec-kit/ (conservés)
tasks.md archivés (pas d'équivalent dans le format workflow)
Confirme pour exécuter ("go", "exécute", "c'est bon").
Phase 5 — Exécution
Pour chaque story :
- Crée le dossier de destination :
mkdir -p docs/story/<NNN>-<tag>-<slug>/
- Déplace les fichiers mappés via
git mv (préserve l'historique).
- Renomme selon le mapping (ex:
git mv specs/003-x/spec.md docs/story/003-f-x/pitch.md).
- Archive les fichiers non mappés :
git mv <fichier> _archive/<source>/<NNN>-<slug>/<fichier>.
- Si la source était un fichier plat (GSD
.plans/<id>-<slug>.md), le contenu va dans pitch.md ou plan.md selon le tag — voir ${CLAUDE_SKILL_DIR}/references/gsd.md.
À la fin :
ls -1 docs/story/ | head -20
Phase 6 — Bilan
Affiche :
Import terminé :
- 8 stories importées dans
docs/story/
- 1 dossier
_archive/spec-kit/ créé (à committer ou .gitignore selon ta préférence)
- Tu peux maintenant utiliser
/feature-implem, /refactor-implem, /tech-implem sur ces stories existantes
Recommandation : commit isolé chore(docs): import depuis Spec Kit. Je peux le faire si tu veux.
Ne commit pas sans validation explicite.
Pièges courants
- Numéros qui dépassent 999 : Spec Kit accepte des timestamps
20251225-143022-x comme numéros. Dans ce cas, demande à l'utilisateur s'il veut renuméroter séquentiellement (recommandé : 001-f-x, 002-f-y, …) ou tronquer à 3 chiffres (risqué : collisions possibles).
- Stories BMAD au format
<epic>.<story> : 1.1.story.md, 1.2.story.md, 2.1.story.md n'ont pas de compteur global. On alloue séquentiellement et on garde la trace de l'epic dans le slug (ex: 001-f-epic-1-user-login).
- GSD avec un seul fichier plat :
.plans/1755-install-audit-fix.md devient docs/story/<NNN>-<tag>-install-audit-fix/pitch.md ou plan.md. Le numéro 1755 (souvent un issue GitHub) est mentionné dans le header du fichier importé pour traçabilité, pas dans le nom du dossier.
- Conflit avec stories workflow déjà présentes : si
docs/story/ contient déjà du contenu workflow, l'import doit s'ajouter (suite logique de la numérotation), pas écraser. Vérifier collisions avant chaque git mv.
Substitutions disponibles
$ARGUMENTS — force la source si la détection est ambiguë (/import-external spec-kit, /import-external bmad, /import-external gsd).
