smart-spec-kit-mcp 2.0.4 → 2.0.5

package/docs/PACKAGING.md

@@ -0,0 +1,323 @@
+# 📦 Guide de Packaging et Distribution
+
+Ce guide explique comment Spec-Kit est conçu pour être utilisé dans n'importe quel projet.
+
+---
+
+## 🎯 Principe: Zero Config + Override Local
+
+Spec-Kit fonctionne **immédiatement** avec les workflows par défaut, mais permet aux équipes de **personnaliser** pour leur stack.
+
+```text
+┌─────────────────────────────────────────────────────────────┐
+│  Votre Projet                                               │
+│  ├── .spec-kit/          ← Overrides locaux (optionnel)     │
+│  │   ├── workflows/                                         │
+│  │   │   └── react-feature.yaml   ← Votre workflow custom   │
+│  │   └── templates/                                         │
+│  │       └── react-spec.md        ← Votre template custom   │
+│  └── src/                                                   │
+│      └── ...                                                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              │ utilise
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  Package spec-kit-mcp (npm)                                 │
+│  ├── workflows/          ← Workflows par défaut             │
+│  │   ├── feature-standard.yaml                              │
+│  │   ├── feature-full.yaml                                  │
+│  │   └── bugfix.yaml                                        │
+│  └── templates/          ← Templates par défaut             │
+│      ├── functional-spec.md                                 │
+│      └── bugfix-report.md                                   │
+└─────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📥 Installation pour l'Utilisateur Final
+
+### Option 1: NPX (Recommandé)
+
+Aucune installation nécessaire, toujours à jour:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "spec-kit": {
+        "command": "npx",
+        "args": ["-y", "spec-kit-mcp"]
+      }
+    }
+  }
+}
+```
+
+### Option 2: Installation Globale
+
+```bash
+npm install -g spec-kit-mcp
+```
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "spec-kit": {
+        "command": "spec-kit-mcp"
+      }
+    }
+  }
+}
+```
+
+---
+
+## 🔧 Personnalisation par Projet
+
+### Initialiser la config locale
+
+Dans Copilot Chat:
+
+```text
+@spec-kit init
+```
+
+Cela crée:
+
+```text
+.spec-kit/
+├── workflows/
+│   └── custom-feature.yaml  ← Exemple modifiable
+└── templates/
+    └── custom-spec.md       ← Exemple modifiable
+```
+
+### Ordre de résolution
+
+Quand vous appelez `start_workflow workflow_name="X"`:
+
+1. **D'abord**: `.spec-kit/workflows/X.yaml` (local)
+2. **Ensuite**: `workflows/X.yaml` (dans le projet)
+3. **Enfin**: Package defaults (feature-standard, etc.)
+
+> Le **premier trouvé gagne** - vous pouvez override les workflows par défaut!
+
+---
+
+## 📝 Créer un Workflow pour votre Stack
+
+### Exemple: React + TypeScript
+
+`.spec-kit/workflows/react-feature.yaml`:
+
+```yaml
+name: react-feature
+displayName: "React Feature Specification"
+description: "Workflow adapté pour les features React/TypeScript"
+template: react-spec.md
+defaultAgent: SpecAgent
+
+steps:
+  - id: fetch-requirements
+    name: "Fetch Requirements"
+    action: fetch_ado
+    description: "Récupère la User Story depuis Azure DevOps"
+    outputs:
+      - user_story
+
+  - id: generate-spec
+    name: "Generate Specification"
+    action: call_agent
+    agent: SpecAgent
+    description: |
+      Génère une spécification React avec:
+      - Structure des composants
+      - Props/State attendus
+      - Hooks nécessaires
+    inputs:
+      source: user_story
+
+  - id: component-plan
+    name: "Component Architecture"
+    action: call_agent
+    agent: PlanAgent
+    description: |
+      Planifie l'architecture des composants:
+      - Découpage en composants atomiques
+      - Shared state (Context/Redux)
+      - API calls (React Query)
+    inputs:
+      source: user_story
+
+  - id: review
+    name: "Technical Review"
+    action: review
+    agent: GovAgent
+    description: |
+      Valide les aspects techniques:
+      - Performance (memo, useMemo, useCallback)
+      - Accessibilité (ARIA, semantic HTML)
+      - Tests (Jest, Testing Library)
+
+  - id: create-output
+    name: "Create Output"
+    action: create_file
+    description: "Crée le fichier de spécification"
+    inputs:
+      filename: "specs/{contextId}-react-spec.md"
+```
+
+### Template associé
+
+`.spec-kit/templates/react-spec.md`:
+
+```markdown
+# {{title}} - React Specification
+
+## Context
+- **Work Item**: {{contextId}}
+- **Date**: {{date}}
+- **Stack**: React 18 + TypeScript
+
+## User Story
+{{description}}
+
+## Component Architecture
+
+### Components Tree
+<!-- À remplir par SpecAgent -->
+
+### Props & State
+<!-- À remplir par SpecAgent -->
+
+## Technical Considerations
+
+### Performance
+- [ ] Lazy loading si nécessaire
+- [ ] Memoization des composants lourds
+- [ ] Optimistic updates pour l'UX
+
+### Accessibility
+- [ ] ARIA labels
+- [ ] Keyboard navigation
+- [ ] Screen reader support
+
+### Testing
+- [ ] Unit tests (Jest)
+- [ ] Component tests (Testing Library)
+- [ ] E2E si applicable (Playwright)
+
+## Tasks
+<!-- À remplir par PlanAgent -->
+```
+
+---
+
+## 🚀 Publication sur NPM
+
+### Prérequis
+
+1. Compte npm
+2. `npm login`
+
+### Publish
+
+```bash
+npm run build
+npm publish
+```
+
+### Le package inclut
+
+Défini dans `package.json`:
+
+```json
+{
+  "files": [
+    "dist",
+    "workflows",
+    "templates",
+    "README.md"
+  ]
+}
+```
+
+---
+
+## 🏗️ Architecture pour Maintainers
+
+### Structure du package publié
+
+```text
+spec-kit-mcp/
+├── dist/                    ← Code compilé
+│   ├── index.js            ← Entry point
+│   ├── engine/
+│   ├── tools/
+│   ├── prompts/
+│   ├── schemas/
+│   └── utils/
+├── workflows/               ← Workflows par défaut
+│   ├── feature-standard.yaml
+│   ├── feature-full.yaml
+│   └── bugfix.yaml
+├── templates/               ← Templates par défaut
+│   ├── functional-spec.md
+│   └── bugfix-report.md
+├── package.json
+└── README.md
+```
+
+### Résolution des chemins
+
+Le `workflowLoader.ts` gère la résolution:
+
+```typescript
+// Ordre de recherche
+const searchPaths = [
+  // 1. Local override
+  path.join(process.cwd(), ".spec-kit", "workflows"),
+  // 2. Project root (pour projets dédiés)
+  path.join(process.cwd(), "workflows"),
+  // 3. Package defaults
+  path.join(__dirname, "..", "..", "workflows"),
+];
+```
+
+---
+
+## 📊 Commandes de Debug
+
+### Voir la configuration actuelle
+
+```text
+@spec-kit config
+```
+
+Affiche:
+- Chemins de recherche
+- Workflows disponibles (local vs package)
+- Projet courant vs package
+
+### Tester un workflow custom
+
+```text
+@spec-kit start_workflow workflow_name="custom-feature" context_id="TEST"
+```
+
+---
+
+## 🎁 Stacks Pré-configurées (Roadmap)
+
+Future versions pourraient inclure des presets:
+
+```bash
+npx spec-kit-mcp init --preset=react
+npx spec-kit-mcp init --preset=dotnet
+npx spec-kit-mcp init --preset=python
+```
+
+Chaque preset créerait `.spec-kit/` avec des workflows optimisés pour la stack.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "smart-spec-kit-mcp",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "description": "AI-driven specification platform using MCP (Model Context Protocol) for VS Code & GitHub Copilot",
   "main": "dist/index.js",
   "type": "module",
@@ -10,6 +10,7 @@
   },
   "files": [
     "dist",
+    "docs",
     "workflows",
     "templates",
     "starter-kit",

package/starter-kit/copilot-instructions.md

@@ -0,0 +1,96 @@
+# Copilot Instructions for Spec-Kit
+
+This project uses **Spec-Kit** for specification-driven development. Spec-Kit provides MCP tools to guide you through a structured workflow from requirements to implementation.
+
+## How to Use Spec-Kit
+
+When the user mentions **"speckit:"** followed by a command, or uses these keywords in French/English, call the corresponding MCP tool:
+
+| User Says | MCP Tool | Description |
+|-----------|----------|-------------|
+| `speckit: spec`, `speckit: specify`, `créer une spec` | `speckit_specify` | Create a functional specification |
+| `speckit: plan`, `planifier`, `créer un plan` | `speckit_plan` | Create an implementation plan |
+| `speckit: tasks`, `générer les tâches`, `créer les tâches` | `speckit_tasks` | Generate task breakdown |
+| `speckit: implement`, `implémenter`, `coder` | `speckit_implement` | Implement tasks |
+| `speckit: clarify`, `clarifier`, `préciser` | `speckit_clarify` | Clarify requirements |
+| `speckit: help`, `aide sur speckit`, questions about spec-kit | `speckit_help` | Get help and documentation |
+
+## Getting Help
+
+When the user asks questions about Spec-Kit (how to use it, how to customize, how to create workflows, troubleshooting), call `speckit_help` with the relevant topic:
+
+**Examples**:
+- "speckit: help comment créer un workflow ?" → `speckit_help` with topic: "workflows"
+- "Comment personnaliser les templates spec-kit ?" → `speckit_help` with topic: "templates"
+- "speckit aide" → `speckit_help` without topic (general help)
+
+## Workflow
+
+The typical spec-kit workflow is:
+
+```
+speckit_specify → speckit_plan → speckit_tasks → speckit_implement
+                      ↑
+               speckit_clarify (if needed)
+```
+
+1. **Specify**: Transform requirements into a structured specification
+2. **Plan**: Create a technical implementation plan from the spec
+3. **Tasks**: Break down the plan into atomic, actionable tasks  
+4. **Implement**: Execute tasks one by one
+5. **Clarify**: Resolve ambiguities at any point
+
+## Project Structure
+
+```
+.spec-kit/
+├── prompts/           # Prompt-as-code files (read by MCP tools)
+│   ├── specify.md
+│   ├── plan.md
+│   ├── tasks.md
+│   ├── implement.md
+│   └── clarify.md
+├── templates/         # Document templates
+│   ├── functional-spec.md
+│   ├── plan-template.md
+│   └── tasks-template.md
+├── memory/            # Project context
+│   └── constitution.md
+└── workflows/         # Automated workflows
+
+specs/                 # Generated specifications (output)
+```
+
+## Important Conventions
+
+When using spec-kit:
+
+1. **Always read the constitution** (`.spec-kit/memory/constitution.md`) for project principles
+2. **Follow the templates** in `.spec-kit/templates/`
+3. **Save outputs to `specs/`** directory
+4. **Suggest the next step** after each tool completes
+
+## Tool Response Format
+
+After calling a spec-kit tool, follow the instructions in the tool response. The response will include:
+- Context from prompts and templates
+- User input
+- Specific instructions for what to generate
+- Suggested next step
+
+## Example Interactions
+
+**User**: "speckit: créer une spec pour un système de notifications push"
+**Action**: Call `speckit_specify` with `requirements: "système de notifications push"`
+
+**User**: "speckit: planifier l'implémentation"  
+**Action**: Call `speckit_plan` (will find the most recent spec automatically)
+
+**User**: "speckit: implement task 3"
+**Action**: Call `speckit_implement` with `taskId: "3"`
+
+**User**: "speckit: help comment créer un nouveau workflow ?"
+**Action**: Call `speckit_help` with `topic: "workflows"`
+
+**User**: "Comment fonctionne spec-kit ?"
+**Action**: Call `speckit_help` without topic for general help

package/starter-kit/prompts/clarify.md

@@ -0,0 +1,73 @@
+# Clarify Prompt
+
+You are clarifying ambiguous requirements in a specification. Follow this structured approach:
+
+## 1. Find Ambiguities
+
+Scan the specification for:
+- `[NEEDS CLARIFICATION]` markers
+- Vague terms ("fast", "easy", "simple")
+- Missing details (undefined behaviors)
+- Conflicting requirements
+- Unstated assumptions
+
+## 2. Prioritize Clarifications
+
+Focus on ambiguities that:
+- Block implementation
+- Could lead to rework
+- Affect user experience significantly
+- Have security implications
+
+## 3. Ask Targeted Questions
+
+For each ambiguity:
+
+```markdown
+### Clarification Needed: {Topic}
+
+**Context**: {Where this appears in the spec}
+
+**Ambiguity**: {What's unclear}
+
+**Options**:
+1. {Option A} - {implication}
+2. {Option B} - {implication}
+3. {Option C} - {implication}
+
+**Recommendation**: {Your suggested choice and why}
+
+**Question**: {Specific question for stakeholder}
+```
+
+## 4. Question Guidelines
+
+Good questions are:
+- **Specific**: One topic per question
+- **Bounded**: Offer options when possible
+- **Contextual**: Explain why it matters
+- **Actionable**: Answer leads to decision
+
+Avoid:
+- Open-ended questions
+- Technical jargon (unless spec is technical)
+- Compound questions
+- Leading questions
+
+## 5. Update Specification
+
+After receiving answers:
+1. Update the relevant section
+2. Remove the `[NEEDS CLARIFICATION]` marker
+3. Add rationale for the decision
+4. Note any assumptions made
+
+## 6. Output
+
+Report:
+- Number of clarifications found
+- Questions asked
+- Answers received (if any)
+- Specification updates made
+- Remaining ambiguities (if any)
+- Next step: `speckit_plan` if all clarified

package/starter-kit/prompts/implement.md

@@ -0,0 +1,79 @@
+# Implement Prompt
+
+You are implementing tasks from the task breakdown. Follow this structured approach:
+
+## 1. Task Selection
+
+If no specific task ID provided:
+- Find the first task with status "Not Started"
+- Check dependencies are satisfied (all dependent tasks are "Done")
+- If dependencies not met, suggest which task to do instead
+
+## 2. Before Implementation
+
+Read and understand:
+- The task description and acceptance criteria
+- The original specification (for context)
+- The project constitution (for conventions)
+- Related code files
+
+## 3. Implementation Guidelines
+
+### Code Quality
+- Follow project conventions from constitution
+- Write clean, self-documenting code
+- Add comments for complex logic only
+- Follow existing patterns in the codebase
+
+### Testing
+- Write tests alongside implementation
+- Cover happy path and edge cases
+- Follow existing test patterns
+
+### Error Handling
+- Handle errors gracefully
+- Provide meaningful error messages
+- Log appropriately
+
+## 4. Implementation Process
+
+For each task:
+
+1. **Read** the task requirements
+2. **Identify** files to create/modify
+3. **Implement** the changes
+4. **Verify** acceptance criteria are met
+5. **Update** task status in tasks.md
+
+## 5. Status Updates
+
+After implementing, update the task in `specs/tasks.md`:
+- Change status from "Not Started" to "Done"
+- Add any notes about implementation decisions
+
+## 6. Commit Guidelines
+
+Suggest a commit message following format:
+```
+feat({scope}): {short description}
+
+- {detail 1}
+- {detail 2}
+
+Task: {task ID}
+```
+
+## 7. Output
+
+Report:
+- What was implemented
+- Files created/modified
+- Any deviations from plan
+- Next task to implement (if continuing)
+
+## 8. Iteration
+
+Ask the user:
+- "Task {ID} completed. Continue with {next task}? (yes/no)"
+- If yes, proceed with next task
+- If no, summarize progress made

package/starter-kit/prompts/plan.md

@@ -0,0 +1,69 @@
+# Plan Prompt
+
+You are creating a technical implementation plan from a specification. Follow this structured approach:
+
+## 1. Understand the Specification
+
+Read and analyze:
+- All functional requirements
+- Non-functional requirements
+- Technical constraints
+- Dependencies
+
+## 2. Architecture Analysis
+
+Identify:
+- **Components to create or modify**
+- **Integration points**
+- **Data flows**
+- **API contracts** (if applicable)
+
+## 3. Create Implementation Plan
+
+Structure the plan with:
+
+### Phases
+Break work into logical phases:
+1. **Foundation** - Core infrastructure, models, utilities
+2. **Core Features** - Main functionality
+3. **Integration** - Connecting components
+4. **Polish** - Error handling, edge cases, UX
+5. **Testing** - Unit, integration, E2E tests
+
+### For Each Phase
+
+Define:
+- **Objectives**: What this phase accomplishes
+- **Deliverables**: Concrete outputs
+- **Dependencies**: What must be done first
+- **Risks**: Potential blockers
+- **Estimated effort**: T-shirt size (S/M/L/XL)
+
+### Technical Decisions
+
+Document key decisions:
+- Patterns to use
+- Libraries to adopt
+- Trade-offs made
+
+## 4. Risk Assessment
+
+Identify and mitigate:
+- Technical risks
+- Dependency risks
+- Timeline risks
+
+## 5. Quality Gates
+
+Define checkpoints:
+- Code review requirements
+- Test coverage targets
+- Performance benchmarks
+
+## 6. Output
+
+Save to `specs/plan.md` and report:
+- Plan summary
+- Total phases count
+- Key risks identified
+- Next step: `speckit_tasks` to generate task breakdown