🚀 Spec-Kit MCP Server

Plateforme d'orchestration automatisée pour le développement piloté par les spécifications (Spec-Driven Development) via GitHub Copilot et MCP (Model Context Protocol).

📚 Table of Contents

• ✨ Fonctionnalités
• ⚡ Installation Rapide
• 📁 Structure du Projet
• 🎮 Commandes Disponibles
• 🚀 Workflow Recommandé
• 🔧 Personnalisation
• ❓ Obtenir de l'Aide
• 🔗 Intégration Azure DevOps
• �️ Troubleshooting
• �📖 Documentation Complète
• 🧪 Développement
• 📄 License

✨ Fonctionnalités

• 🤖 Commandes Naturelles: Utilisez speckit: spec, speckit: plan, etc. directement dans Copilot Chat
• 📝 Prompts Versionnés: Prompts personnalisables et versionnables dans .spec-kit/prompts/
• 🔄 Workflows YAML: Processus personnalisables étape par étape
• 📋 Templates Complets: Specs, plans, data-model, API contracts (OpenAPI), quickstart, research
• 🛡️ Gouvernance Intégrée: Constitution projet, Phase -1 Gates, principes de développement
• ✅ Checklists de Qualité: "Unit tests for English" pour valider vos requirements
• 🔍 Analyse de Traçabilité: Vérification de cohérence entre specs, plans et tâches
• 🔗 Azure DevOps: Intégration native via MCP
• ❓ Aide Contextuelle: Demandez de l'aide sur Spec-Kit directement dans Copilot

🆕 VS Code 1.109+ (Février 2026)

• 🧑‍💼 Agents Natifs (.agent.md): 6 agents Copilot dédiés (Spec, Plan, Governance, Test, Conductor, Implement)
• 🧠 Agent Skills GA: 3 compétences partagées (spec-driven-dev, security-validation, api-design)
• 🎭 Orchestration par Subagents: Conductor délègue aux agents spécialisés en parallèle
• ❓ askQuestions: UX interactive structurée pour la clarification et la constitution
• 📊 MCP Apps: Dashboards interactifs (workflow progress, matrice de traçabilité)
• 💾 Copilot Memory: Mémoire duale (native cross-session + projet partagé en git)
• 🔎 Search Subagent: Exploration du codebase en contexte isolé pour préserver le contexte principal

🏆 Pourquoi Smart Spec-Kit vs GitHub Spec-Kit ?

| Aspect | GitHub Spec-Kit | Smart Spec-Kit | |--------|-----------------|--------------------| | Installation | Copier manuellement les fichiers | npx smart-spec-kit-mcp setup ✨ | | Distribution | Dossier à cloner | Package npm installable | | Mise à jour | Copier à nouveau | npx smart-spec-kit-mcp@latest setup | | Personnalisation | Éditer les fichiers sources | Override dans .spec-kit/ (non-destructif) | | Workflows | Manuel (copier les commandes) | Automatisé avec YAML + approval gates | | Agents | Prompts fixes | Agents personnalisables (.spec-kit/agents/) | | Validation | Manuelle | Automatique (sécurité, RGPD, schéma) | | Phase -1 Gates | Dans les templates | Intégré dans le workflow | | Supporting Docs | Templates séparés | Génération automatique (data-model, contracts, quickstart) | | Mémoire Projet | Non inclus | Auto-enrichissement des décisions/learnings | | Multi-langue | Anglais | Français + Anglais | | MCP Server | ❌ Non | ✅ Oui - communication native avec Copilot |

🎯 Smart Spec-Kit = GitHub Spec-Kit + Automatisation + MCP

Smart Spec-Kit implémente 100% de la méthodologie GitHub Spec-Kit (spec-driven.md) avec :

1. 📦 Distribution packagée - Un seul npx pour tout installer
2. 🔄 Workflows automatisés - Enchaînement des étapes sans intervention
3. 📝 Documents de support auto-générés - data-model.md, contracts/, quickstart.md
4. 🚦 Phase -1 Gates intégrées - Validation architecturale avant implémentation
5. 🧠 Mémoire projet - Enrichissement automatique des décisions et conventions
6. 🔌 Serveur MCP natif - Communication directe avec GitHub Copilot
7. 🎨 Personnalisation non-destructive - Vos overrides dans .spec-kit/ survivent aux mises à jour

⚡ Installation Rapide

Option 1: Installation Automatique (Recommandé)

npx smart-spec-kit-mcp setup

Cette commande configure automatiquement:

• ✅ VS Code settings.json (MCP server)
• ✅ Tous les profils VS Code (Windows, macOS, Linux)
• ✅ .github/copilot-instructions.md (guide Copilot)
• ✅ .github/agents/ (agents natifs VS Code 1.109+)
• ✅ .github/skills/ (compétences agents)
• ✅ .spec-kit/ avec prompts, templates et workflows

Note macOS: Si vous avez une erreur command not found, assurez-vous que npm/npx est à jour: npm install -g npm@latest

Option 2: Configuration Manuelle

Ajoutez dans .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "spec-kit": {
        "command": "npx",
        "args": ["-y", "smart-spec-kit-mcp"]
      }
    }
  },
  "chat.agentFilesLocations": [".github/agents"],
  "chat.agentSkillsLocations": [".github/skills"],
  "github.copilot.chat.copilotMemory.enabled": true
}

Puis rechargez VS Code: Ctrl+Shift+P → "Developer: Reload Window"

📁 Structure du Projet

Structure interne du package Spec-Kit

smart-spec-kit-mcp/
├── starter-kit/                  # Source unique de la configuration
│   ├── prompts/                  # Prompts MCP (specify, plan, implement, etc.)
│   │   ├── specify.md
│   │   ├── plan.md
│   │   ├── tasks.md
│   │   ├── implement.md
│   │   ├── clarify.md
│   │   ├── validate.md
│   │   ├── memory.md
│   │   ├── constitution.md       # Configuration de la constitution projet
│   │   ├── analyze.md            # Analyse de traçabilité
│   │   └── checklist.md          # Checklist de qualité des requirements
│   ├── templates/                # Templates de documents
│   │   ├── functional-spec.md    # Spécification fonctionnelle
│   │   ├── plan-template.md      # Plan avec Phase -1 Gates
│   │   ├── tasks-template.md     # Liste de tâches
│   │   ├── data-model.md         # Entités et relations
│   │   ├── quickstart.md         # Scénarios de validation
│   │   ├── research.md           # Recherche technique
│   │   ├── checklist-template.md
│   │   ├── bugfix-report.md
│   │   └── contracts/            # Contrats API
│   │       ├── api-template.yaml # OpenAPI 3.0
│   │       └── events-template.md # WebSocket/SSE
│   ├── workflows/                # Workflows YAML prédéfinis
│   │   ├── feature-quick.yaml    # 2-step (spécification rapide)
│   │   ├── feature-standard.yaml # 5-step (spec → plan → tasks → analyze → implement)
│   │   ├── feature-full.yaml     # 7-step (avec validations sécurité/RGPD)
│   │   ├── bugfix-quick.yaml     # 2-step (bugfix rapide)
│   │   └── bugfix.yaml
│   ├── agents/                   # Agents IA customisables (system prompts)
│   │   ├── SpecAgent.md          # Rédacteur de spécifications
│   │   ├── PlanAgent.md          # Planificateur technique
│   │   ├── GovAgent.md           # Validateur gouvernance
│   │   ├── TestAgent.md          # Stratège de tests
│   │   └── _CustomAgent.template.md
│   ├── github-agents/            # 🆕 Agents VS Code natifs (.agent.md)
│   │   ├── speckit-spec.agent.md
│   │   ├── speckit-plan.agent.md
│   │   ├── speckit-governance.agent.md
│   │   ├── speckit-test.agent.md
│   │   ├── speckit-conductor.agent.md  # Orchestrateur
│   │   └── speckit-implement.agent.md
│   ├── github-skills/            # 🆕 Compétences agents (SKILL.md)
│   │   ├── spec-driven-dev/SKILL.md
│   │   ├── security-validation/SKILL.md
│   │   └── api-design/SKILL.md
│   ├── rules/                    # Règles de validation
│   │   ├── security-rules.md     # Règles OWASP
│   │   └── rgpd-rules.md         # Conformité GDPR
│   ├── memory/                   # Contexte projet
│   │   └── constitution.md       # Template de constitution (avec [PLACEHOLDER])
│   ├── github-prompts/           # Slash commands pour Copilot
│   │   └── speckit.*.prompt.md
│   └── copilot-instructions.md   # Guide Copilot

Structure après installation dans votre projet

votre-projet/
├── .github/
│   ├── agents/                   # 🆕 Agents natifs VS Code 1.109+
│   │   ├── speckit-spec.agent.md
│   │   ├── speckit-plan.agent.md
│   │   ├── speckit-conductor.agent.md
│   │   └── ...
│   ├── skills/                   # 🆕 Compétences agents
│   │   ├── spec-driven-dev/SKILL.md
│   │   ├── security-validation/SKILL.md
│   │   └── api-design/SKILL.md
│   ├── prompts/                  # Slash commands Copilot
│   └── copilot-instructions.md   # Copié lors du setup
├── .spec-kit/                    # Configuration locale (personnalisations)
│   ├── prompts/                  # Override les prompts par défaut
│   ├── templates/                # Override les templates par défaut
│   │   └── contracts/            # Contrats API personnalisés
│   ├── workflows/                # Vos workflows personnalisés
│   ├── agents/                   # Vos agents personnalisés (system prompts)
│   ├── rules/                    # Vos règles de validation
│   └── memory/
│       └── constitution.md       # Principes de votre projet
└── specs/                        # Spécifications générées
    ├── [feature-name]/           # Dossier par feature
    │   ├── spec.md               # Spécification fonctionnelle
    │   ├── plan.md               # Plan d'implémentation
    │   ├── data-model.md         # Entités et relations
    │   ├── quickstart.md         # Scénarios validation
    │   ├── tasks.md              # Liste des tâches
    │   ├── research.md           # Recherche technique (optionnel)
    │   └── contracts/            # Contrats API
    │       ├── api.yaml          # OpenAPI 3.0
    │       └── events.md         # Événements temps réel (optionnel)
    └── validations/              # Rapports de validation

Note: Les workflows, templates et agents par défaut viennent de starter-kit/ du package. Vous pouvez personnaliser en créant des fichiers dans .spec-kit/.

🎮 Commandes Disponibles

Slash Commands (Recommandé)

Tapez / dans Copilot Chat pour voir les slash commands disponibles:

| Slash Command | Description | |---------------|-------------| | /speckit.specify | Crée une spécification fonctionnelle | | /speckit.plan | Crée un plan d'implémentation | | /speckit.tasks | Génère la liste des tâches | | /speckit.implement | Exécute les tâches | | /speckit.clarify | Clarifie les requirements ambigus | | /speckit.validate | Valide la conformité (sécurité, RGPD, etc.) | | /speckit.memory | Gère la mémoire projet | | /speckit.workflow | Gère les workflows (list, start, status) | | /speckit.help | Obtient de l'aide sur Spec-Kit | | /speckit.constitution | Configure la constitution projet | | /speckit.analyze | Analyse la cohérence entre artifacts | | /speckit.checklist | Génère un checklist de qualité des requirements |

Commandes par mots-clés (Alternative)

Vous pouvez aussi utiliser ces phrases dans Copilot Chat:

| Commande | Alias | Description | |----------|-------|-------------| | speckit: spec | speckit: specify, créer une spec | Crée une spécification fonctionnelle | | speckit: plan | planifier, créer un plan | Crée un plan d'implémentation | | speckit: tasks | générer les tâches | Génère la liste des tâches | | speckit: implement | implémenter, coder | Exécute les tâches | | speckit: clarify | clarifier, préciser | Clarifie les requirements ambigus | | speckit: validate | valider, vérifier | Valide la conformité (sécurité, RGPD, etc.) | | speckit: workflow | démarrer un workflow, workflow list | Gère les workflows multi-étapes | | speckit: memory | enrichir la mémoire, ajouter au contexte | Gère la mémoire projet | | speckit: help | aide sur speckit | Obtient de l'aide sur Spec-Kit | | speckit: init | init | Initialise Spec-Kit (demande guidé vs auto par défaut) | | speckit: constitution | définir les principes | Configure la constitution projet | | speckit: analyze | analyser, vérifier cohérence | Analyse la cohérence entre artifacts | | speckit: checklist | générer checklist | Génère un checklist de qualité des requirements |

🚀 Workflow Recommandé

1. Établir les principes du projet

Utilisez /speckit.constitution pour définir les principes de votre projet:

/speckit.constitution monorepo TypeScript avec React et Node.js

Ou éditez directement .spec-kit/memory/constitution.md avec vos principes de développement.

Astuce: lancez speckit: init avec guided: true pour un mode questions/réponses (sinon init vous demandera le mode). En mode auto, la constitution est remplie depuis la stack détectée.

2. Créer une spécification

/speckit.specify pour un système de notifications push

Ou avec la commande par mots-clés:

speckit: spec pour un système de notifications push

3. Vérifier la qualité des specs (optionnel)

/speckit.checklist

Cette commande génère un checklist de qualité des requirements - "unit tests for English".

4. Planifier l'implémentation

/speckit.plan

5. Générer les tâches

/speckit.tasks

6. Analyser la cohérence (recommandé)

/speckit.analyze

Vérifie la traçabilité entre specs → plan → tasks et identifie les gaps.

7. Implémenter

/speckit.implement

🔧 Personnalisation

Modifier les Prompts

Les prompts dans .spec-kit/prompts/ définissent le comportement de chaque commande:

# .spec-kit/prompts/specify.md

## Analyse Requirements
- Identifier les besoins utilisateur
- Lister les contraintes techniques
- Définir les critères d'acceptation
...

Personnaliser les Templates

Modifiez les templates dans .spec-kit/templates/ pour adapter le format de vos documents.

Créer un Workflow Personnalisé

Créez un fichier YAML dans .spec-kit/workflows/:

name: mon-workflow
displayName: "Mon Workflow Personnalisé"
description: "Description de ce que fait le workflow"
template: mon-template.md
defaultAgent: SpecAgent

steps:
  - id: analyze
    name: "Analyse"
    action: call_agent
    agent: SpecAgent
    description: "Analyse les requirements"
    
  - id: generate
    name: "Génération"
    action: call_agent
    agent: PlanAgent
    description: "Génère le plan"
    # Demande approbation avant l'étape suivante
    requiresApproval: true
    approvalMessage: "⚠️ Vérifiez le plan avant l'implémentation"

  - id: security-review
    name: "Revue Sécurité"
    action: review
    agent: GovAgent
    # Exécute dans un contexte isolé
    useSubagent: true
    description: "Analyse de sécurité approfondie"

Propriétés des Étapes

| Propriété | Type | Description | |-----------|------|-------------| | id | string | Identifiant unique de l'étape | | name | string | Nom affiché | | action | string | call_agent, review, fetch_ado, create_file | | agent | string | Agent à utiliser | | requiresApproval | boolean | ⏸️ Pause pour validation utilisateur | | approvalMessage | string | Message personnalisé à l'approbation | | useSubagent | boolean | 🔄 Exécution en contexte isolé |

Points de Validation (Approval Gates)

Utilisez requiresApproval: true pour créer des checkpoints :

steps:
  - id: generate-tasks
    name: "Générer les tâches"
    action: call_agent
    outputs: [tasks_document]
    requiresApproval: true  # ⏸️ Pause ici
    approvalMessage: "Vérifiez les tâches avant implémentation"

  - id: implement
    name: "Implémenter"
    action: call_agent

Quand utiliser les approval gates :

• Avant les phases d'implémentation
• Après les revues sécurité/compliance
• Aux transitions de phase (spec → plan → tasks → implement)

Exécution en Subagent

Utilisez useSubagent: true pour les analyses approfondies :

steps:
  - id: security-review
    action: review
    agent: GovAgent
    useSubagent: true  # 🔄 Contexte isolé

Avantages :

• Contexte isolé (ne pollue pas la conversation principale)
• Analyse approfondie sans encombrer le chat
• Seul le résultat final rejoint le contexte principal

À propos des "Agents"

⚠️ Important : Les agents Spec-Kit (SpecAgent, PlanAgent, GovAgent, TestAgent) ne sont PAS des agents GitHub Copilot.

Ce sont des system prompts prédéfinis qui guident le comportement de Copilot :

| Agent | Rôle | Fichier | |-------|------|---------| | SpecAgent | Rédacteur de spécifications | SpecAgent.md | | PlanAgent | Planificateur technique | PlanAgent.md | | GovAgent | Validateur de gouvernance | GovAgent.md | | TestAgent | Stratège de tests | TestAgent.md |

🆕 Agents Natifs VS Code (1.109+)

En plus des agents MCP (system prompts), Spec-Kit installe désormais des agents natifs VS Code dans .github/agents/ :

| Agent | Invocation | Description | |-------|-----------|-------------| | SpecKit-Conductor | @SpecKit-Conductor | Orchestrateur — délègue aux agents spécialistes | | SpecKit-Spec | @SpecKit-Spec | Rédaction de spécifications fonctionnelles | | SpecKit-Plan | @SpecKit-Plan | Planning technique avec diagrammes Mermaid | | SpecKit-Governance | @SpecKit-Governance | Revue sécurité, RGPD, conformité | | SpecKit-Test | @SpecKit-Test | Stratégie de tests et couverture | | SpecKit-Implement | @SpecKit-Implement | Implémentation de tâches |

Usage : Tapez @SpecKit-Conductor dans Copilot Chat pour démarrer un workflow orchestré.

🆕 Agent Skills (1.109+)

Compétences partagées entre agents dans .github/skills/ :

| Skill | Description | |-------|-------------| | spec-driven-dev | Méthodologie spec-driven complète | | security-validation | Framework de validation sécurité (OWASP) | | api-design | Patterns de conception REST API et data model | Quand vous mettez agent: SpecAgent dans une étape, Spec-Kit envoie le system prompt de SpecAgent à Copilot.

Créer un Agent Personnalisé

Les agents sont maintenant entièrement customisables depuis .spec-kit/agents/ :

# .spec-kit/agents/SecurityAgent.md

---
name: SecurityAgent
displayName: "Security Review Agent"
description: "Expert en sécurité applicative"
capabilities:
  - Identifier les vulnérabilités
  - Recommander les bonnes pratiques
---

## System Prompt

Tu es SecurityAgent, un expert en sécurité applicative...

Puis utilisez dans vos workflows :

steps:
  - id: security-review
    agent: SecurityAgent  # Votre agent custom !
    action: call_agent

Pour plus de détails : Understanding Spec-Kit Agents

Validation du Schéma de Workflow

Chaque workflow YAML est validé automatiquement contre un schéma Zod. Les champs obligatoires sont :

• name - Identifiant unique
• displayName - Nom visible
• description - Description
• template - Fichier template
• steps - Au moins une étape

Erreur si validation échoue :

Error: Invalid workflow "mon-workflow":
  - steps.0.action: Invalid enum value
  - name: Required

Pour plus de détails sur le schéma, voir Workflow Validation Schema.

❓ Obtenir de l'Aide

Demandez de l'aide directement dans Copilot Chat:

/speckit.help comment créer un nouveau workflow ?

/speckit.help comment personnaliser les templates ?

/speckit.help quels sont les agents disponibles ?

🔗 Intégration Azure DevOps

Pour récupérer automatiquement les work items:

{
  "mcp": {
    "servers": {
      "spec-kit": {
        "command": "npx",
        "args": ["-y", "smart-spec-kit-mcp"]
      },
      "azure-devops": {
        "command": "npx",
        "args": [
        "-y",
        "@azure-devops/mcp",
        "your-org",
      ],
        "env": {
          "AZURE_DEVOPS_PAT": "your-token"
        }
      }
    }
  }
}

Puis utilisez:

/speckit.specify pour le work item #12345

�️ Troubleshooting

Pour résoudre les problèmes courants:

• macOS: command not found: smart-spec-kit-mcp

  • Essayez: npm install -g npm@latest puis npx smart-spec-kit-mcp setup
  • Consultez TROUBLESHOOTING.md pour plus de solutions

• VS Code: Les outils Spec-Kit n'apparaissent pas

  • Relancez VS Code (Ctrl+Shift+P → "Reload Window")
  • Consultez TROUBLESHOOTING.md

• Autres problèmes: Voir TROUBLESHOOTING.md complet

📖 Documentation Complète

Pour une documentation détaillée sur tous les outils et fonctionnalités:

• QUICK-START.md - Guide de démarrage rapide (2 minutes)
• docs/DOCUMENTATION.md - Documentation complète des outils MCP et workflows
• docs/PACKAGING.md - Guide de packaging et distribution
• PROJECT_CONTEXT.md - Contexte du projet Spec-Kit
• TODO.md - Tâches en cours et prévues
• TROUBLESHOOTING.md - Guide de dépannage complet

🧪 Développement

git clone https://github.com/fazzani/smart-spec-kit.git
cd smart-spec-kit
npm install
npm run build

Tester localement

node dist/cli.js setup --project ./mon-projet --dry-run

📄 License

MIT