mirror of
https://github.com/MaksTinyWorkshop/_Assistant_Lead_Tech
synced 2026-04-07 05:51:41 +02:00
mcp: consolidate lot 1 metadata and planning
This commit is contained in:
MaksTinyWorkshop
144
mcp/leadtech_bmad_mcp/docs/implementation_plan.md
Normal file
144
mcp/leadtech_bmad_mcp/docs/implementation_plan.md
Normal file
@@ -0,0 +1,144 @@
|
||||
# leadtech-bmad-mcp — Plan d'implementation
|
||||
|
||||
Ce document sert de **plan de chantier vivant** pour transformer le prototype actuel en MCP propre, stable et exploitable dans BMAD.
|
||||
|
||||
Mode d'usage :
|
||||
|
||||
- cocher les taches terminees
|
||||
- mettre a jour le statut des lots en debut/fin de session
|
||||
- ajouter les decisions structurantes dans `40_decisions_et_archi.md` si besoin
|
||||
- garder ici le suivi operationnel, pas les longues explications
|
||||
|
||||
---
|
||||
|
||||
## Vue d'ensemble
|
||||
|
||||
| Lot | Objectif | Statut |
|
||||
| --- | --- | --- |
|
||||
| Lot 1 | Contrat MCP v1 + metadonnees `knowledge` + compatibilite loader | En cours avance |
|
||||
| Lot 2 | Index compile local + branchement de la recherche MCP dessus | A faire |
|
||||
| Lot 3 | Gates configurables + packaging + rollout BMAD | A faire |
|
||||
|
||||
---
|
||||
|
||||
## Lot 1 — Contrat v1 et base structuree
|
||||
|
||||
### Objectif
|
||||
|
||||
Stabiliser le contrat du MCP et preparer un corpus `knowledge/` assez structure pour servir de base au futur index.
|
||||
|
||||
### Livrables
|
||||
|
||||
- [x] Documenter le contrat MCP v1
|
||||
- [x] Documenter le format de front matter `knowledge/`
|
||||
- [x] Ajouter la lecture du front matter dans le loader
|
||||
- [x] Exposer un champ structure `matched_docs` dans `get_guidance`
|
||||
- [x] Ajouter des tests sur le parsing des metadonnees
|
||||
- [x] Annoter un premier noyau de documents critiques
|
||||
|
||||
### Noyau pilote vise
|
||||
|
||||
- [x] `knowledge/backend/patterns/auth.md`
|
||||
- [x] `knowledge/backend/patterns/contracts.md`
|
||||
- [x] `knowledge/backend/patterns/nestjs.md`
|
||||
- [x] `knowledge/backend/risques/auth.md`
|
||||
- [x] `knowledge/backend/risques/contracts.md`
|
||||
- [x] `knowledge/backend/risques/nestjs.md`
|
||||
- [x] `knowledge/backend/risques/prisma.md`
|
||||
- [x] `knowledge/frontend/patterns/navigation.md`
|
||||
- [x] `knowledge/frontend/patterns/tests.md`
|
||||
- [x] `knowledge/frontend/risques/navigation.md`
|
||||
- [x] `knowledge/workflow/risques/story-tracking.md`
|
||||
|
||||
### Reste a faire avant cloture complete du lot
|
||||
|
||||
- [ ] Verifier si `knowledge/backend/patterns/prisma.md` doit aussi entrer dans le noyau pilote
|
||||
- [ ] Verifier si `knowledge/frontend/risques/tests.md` doit aussi entrer dans le noyau pilote
|
||||
- [ ] Faire un commit de cloture explicite du Lot 1
|
||||
|
||||
### Critere de fin
|
||||
|
||||
- le contrat v1 est stable
|
||||
- un noyau representatif de docs critiques est structure
|
||||
- la recherche MCP sait exploiter les metadonnees sans casser le comportement existant
|
||||
|
||||
---
|
||||
|
||||
## Lot 2 — Index compile local
|
||||
|
||||
### Objectif
|
||||
|
||||
Remplacer le scan Markdown a la volee par un index local plus rapide, plus fiable et plus facile a faire evoluer.
|
||||
|
||||
### Taches
|
||||
|
||||
- [ ] Definir le format de l'index (JSON d'abord)
|
||||
- [ ] Creer un script de build d'index
|
||||
- [ ] Indexer les docs `knowledge/*`
|
||||
- [ ] Indexer les docs globaux `10_*`, `40_*`, `90_*`
|
||||
- [ ] Prevoir un mode fallback si l'index n'existe pas
|
||||
- [ ] Rebrancher `search_knowledge()` sur l'index
|
||||
- [ ] Rebrancher `search_global_docs()` sur l'index
|
||||
- [ ] Ajouter des tests d'integration sur un mini corpus indexe
|
||||
|
||||
### Livrables attendus
|
||||
|
||||
- `src/leadtech_bmad_mcp/indexer.py`
|
||||
- un artefact d'index local versionnable ou regenerable
|
||||
- documentation de rebuild
|
||||
|
||||
### Critere de fin
|
||||
|
||||
- les tools de recherche utilisent d'abord l'index
|
||||
- le fallback texte brut reste disponible pour ne pas bloquer le dev
|
||||
|
||||
---
|
||||
|
||||
## Lot 3 — Gates configurables et industrialisation
|
||||
|
||||
### Objectif
|
||||
|
||||
Sortir les regles du code dur, rendre l'installation reproductible, puis cabler proprement le rollout BMAD.
|
||||
|
||||
### Taches
|
||||
|
||||
- [ ] Extraire les gates dans une config versionnee
|
||||
- [ ] Distinguer advisory et blocking dans la config
|
||||
- [ ] Ajouter des tests sur les faux positifs/faux negatifs des gates
|
||||
- [ ] Stabiliser l'installation `pip install -e ".[dev]"`
|
||||
- [ ] Ajouter une doc machine vierge / quickstart
|
||||
- [ ] Preparer un rollout BMAD advisory
|
||||
- [ ] Definir 2-3 blocages stricts seulement apres validation
|
||||
|
||||
### Livrables attendus
|
||||
|
||||
- `config/gates.yaml`
|
||||
- quickstart dev local
|
||||
- procedure de rollout BMAD
|
||||
|
||||
### Critere de fin
|
||||
|
||||
- modifier une regle ne demande plus un patch Python
|
||||
- une autre machine peut installer et lancer le serveur sans bricolage
|
||||
- BMAD sait quand appeler quels tools et comment interpreter leur sortie
|
||||
|
||||
---
|
||||
|
||||
## Journal de progression
|
||||
|
||||
### 2026-03-31
|
||||
|
||||
- Lot 1 demarre
|
||||
- contrat `mcp_v1.md` ajoute
|
||||
- convention `knowledge_metadata.md` ajoutee
|
||||
- loader front matter ajoute
|
||||
- `matched_docs` ajoute a `get_guidance`
|
||||
- noyau pilote annote sur backend, frontend et workflow
|
||||
|
||||
---
|
||||
|
||||
## Regles de maintenance de ce plan
|
||||
|
||||
- un lot passe a `Termine` uniquement quand son critere de fin est satisfait
|
||||
- une case ne se coche pas si le code est seulement commence
|
||||
- si un arbitrage durable apparait, l'inscrire aussi dans `40_decisions_et_archi.md`
|
||||
108
mcp/leadtech_bmad_mcp/docs/knowledge_metadata.md
Normal file
108
mcp/leadtech_bmad_mcp/docs/knowledge_metadata.md
Normal file
@@ -0,0 +1,108 @@
|
||||
# leadtech-bmad-mcp — Métadonnées `knowledge/`
|
||||
|
||||
Ce document définit le **front matter minimal** attendu pour rendre la base `knowledge/` mieux exploitable par le MCP.
|
||||
|
||||
## Objectif
|
||||
|
||||
- améliorer le ranking de recherche
|
||||
- permettre des filtres structurés
|
||||
- préparer un futur index compilé
|
||||
|
||||
## Format retenu
|
||||
|
||||
Chaque document `knowledge/*/*.md` peut commencer par :
|
||||
|
||||
```md
|
||||
---
|
||||
title: Backend — Patterns : NestJS
|
||||
domain: backend
|
||||
bucket: patterns
|
||||
tags: [nestjs, guards, auth, redis]
|
||||
applies_to: [analysis, implementation, review, debug]
|
||||
severity: medium
|
||||
validated_on: 2026-03-07
|
||||
source_projects: [app-alexandrie]
|
||||
---
|
||||
```
|
||||
|
||||
Le front matter est **optionnel** dans la phase 1.
|
||||
|
||||
Le loader doit :
|
||||
|
||||
- fonctionner avec ou sans front matter
|
||||
- ignorer proprement les champs inconnus
|
||||
- continuer à servir le markdown brut si demandé en resource
|
||||
|
||||
## Champs v1
|
||||
|
||||
### `title`
|
||||
|
||||
- titre logique du document
|
||||
- type : `string`
|
||||
|
||||
### `domain`
|
||||
|
||||
- domaine principal
|
||||
- type : `backend | frontend | ux | n8n | product | workflow`
|
||||
|
||||
### `bucket`
|
||||
|
||||
- type de document
|
||||
- type : `patterns | risques`
|
||||
|
||||
### `tags`
|
||||
|
||||
- mots-clés de recherche
|
||||
- type : `string[]`
|
||||
|
||||
### `applies_to`
|
||||
|
||||
- moments du workflow où le document est pertinent
|
||||
- type : `analysis | implementation | review | debug | architecture`
|
||||
- type de stockage : `string[]`
|
||||
|
||||
### `severity`
|
||||
|
||||
- niveau de criticité métier ou technique du document
|
||||
- type : `low | medium | high`
|
||||
|
||||
### `validated_on`
|
||||
|
||||
- date de validation terrain
|
||||
- type : `YYYY-MM-DD`
|
||||
|
||||
### `source_projects`
|
||||
|
||||
- projets ayant validé le pattern ou révélé le risque
|
||||
- type : `string[]`
|
||||
|
||||
## Règles de gouvernance
|
||||
|
||||
- les README d'index n'ont pas besoin de front matter dans la phase 1
|
||||
- priorité aux documents les plus consultés ou les plus critiques
|
||||
- ne pas bloquer une capitalisation parce que le front matter n'existe pas encore
|
||||
|
||||
## Politique de migration
|
||||
|
||||
Phase 1 :
|
||||
- ajouter le front matter à un petit noyau de documents pilotes
|
||||
|
||||
Noyau pilote actuellement couvert :
|
||||
|
||||
- `knowledge/backend/patterns/auth.md`
|
||||
- `knowledge/backend/patterns/contracts.md`
|
||||
- `knowledge/backend/patterns/nestjs.md`
|
||||
- `knowledge/backend/risques/auth.md`
|
||||
- `knowledge/backend/risques/contracts.md`
|
||||
- `knowledge/backend/risques/nestjs.md`
|
||||
- `knowledge/backend/risques/prisma.md`
|
||||
- `knowledge/frontend/patterns/navigation.md`
|
||||
- `knowledge/frontend/patterns/tests.md`
|
||||
- `knowledge/frontend/risques/navigation.md`
|
||||
- `knowledge/workflow/risques/story-tracking.md`
|
||||
|
||||
Phase 2 :
|
||||
- généraliser aux documents backend, frontend et workflow les plus actifs
|
||||
|
||||
Phase 3 :
|
||||
- exiger ces métadonnées pour l'index compilé
|
||||
209
mcp/leadtech_bmad_mcp/docs/mcp_v1.md
Normal file
209
mcp/leadtech_bmad_mcp/docs/mcp_v1.md
Normal file
@@ -0,0 +1,209 @@
|
||||
# leadtech-bmad-mcp — Contrat v1
|
||||
|
||||
Ce document fige le **contrat fonctionnel v1** du sidecar MCP Lead_tech.
|
||||
|
||||
Objectif :
|
||||
|
||||
- stabiliser ce que le serveur promet aux agents BMAD
|
||||
- éviter les changements de payload implicites
|
||||
- préparer les itérations suivantes (index compilé, gates configurables) sans casser les prompts existants
|
||||
|
||||
## Positionnement
|
||||
|
||||
- BMAD garde l'orchestration
|
||||
- Lead_tech garde la doctrine et la validation humaine
|
||||
- le MCP sidecar fournit une couche outillée de lecture, guidance, gate qualité, et capitalisation
|
||||
|
||||
## Version fonctionnelle
|
||||
|
||||
- Nom logique : `leadtech-bmad-mcp`
|
||||
- Version de contrat : `v1`
|
||||
- Statut : advisory-first
|
||||
|
||||
## Outils v1
|
||||
|
||||
### `get_guidance(domain, task_type, story_text?, keywords?, max_items?)`
|
||||
|
||||
Rôle :
|
||||
- retrouver les patterns, risques et docs globaux pertinents pour une story
|
||||
|
||||
Entrées :
|
||||
- `domain` : `backend | frontend | ux | n8n | product | workflow`
|
||||
- `task_type` : `analysis | implementation | review | debug | architecture`
|
||||
- `story_text` : texte libre
|
||||
- `keywords` : liste de mots-clés optionnelle
|
||||
- `max_items` : entier optionnel
|
||||
|
||||
Sortie :
|
||||
- `must_do[]`
|
||||
- `should_do[]`
|
||||
- `red_flags[]`
|
||||
- `blocking_issues[]`
|
||||
- `references[]`
|
||||
- `confidence`
|
||||
- `gates[]`
|
||||
|
||||
Règle :
|
||||
- advisory par défaut
|
||||
- pas d'écriture
|
||||
|
||||
### `validate_plan(domain, plan_text, agent_role?, strict?)`
|
||||
|
||||
Rôle :
|
||||
- vérifier qu'un plan BMAD couvre les gates Lead_tech les plus importantes
|
||||
|
||||
Règle :
|
||||
- `strict=true` peut produire des `blocking_issues`
|
||||
- `strict=false` reste advisory
|
||||
|
||||
### `validate_patch(domain, diff_text, changed_files?, strict?)`
|
||||
|
||||
Rôle :
|
||||
- contrôler un diff par rapport à des gates Lead_tech
|
||||
|
||||
Règle :
|
||||
- détecte les signaux faibles, pas une preuve formelle de conformité
|
||||
- un résultat vide ne remplace jamais une review humaine
|
||||
|
||||
### `emit_checklist(agent_role, domain, story_text?)`
|
||||
|
||||
Rôle :
|
||||
- produire une checklist opérationnelle par rôle BMAD
|
||||
|
||||
### `propose_capitalization(project_name, target_file, why, proposal, dry_run?)`
|
||||
|
||||
Rôle :
|
||||
- préparer une entrée `FILE_UPDATE_PROPOSAL` pour `95_a_capitaliser.md`
|
||||
|
||||
Règle :
|
||||
- `dry_run=true` par défaut
|
||||
- écriture réelle uniquement si `LEADTECH_MCP_ALLOW_WRITE=1`
|
||||
|
||||
### `triage_capitalization(project_filter?, max_entries?)`
|
||||
|
||||
Rôle :
|
||||
- analyser les entrées du buffer de capitalisation
|
||||
|
||||
Statut :
|
||||
- heuristique, non décisionnaire
|
||||
|
||||
### `route_to_project_memory(project_name, section, content, dry_run?)`
|
||||
|
||||
Rôle :
|
||||
- router un apprentissage de portée projet vers le `CLAUDE.md` du projet
|
||||
|
||||
Règle :
|
||||
- écriture réelle uniquement si `LEADTECH_MCP_ALLOW_WRITE=1`
|
||||
|
||||
## Resources v1
|
||||
|
||||
- `leadtech://index`
|
||||
- `leadtech://capitalisation/pending`
|
||||
- `leadtech://projects/conf`
|
||||
- `leadtech://knowledge/{domain}/{bucket}/{slug}`
|
||||
- `leadtech://global/architecture`
|
||||
- `leadtech://global/debug`
|
||||
- `leadtech://global/conventions`
|
||||
|
||||
## Payload commun
|
||||
|
||||
Les tools de guidance et de validation retournent un payload homogène :
|
||||
|
||||
```json
|
||||
{
|
||||
"must_do": [],
|
||||
"should_do": [],
|
||||
"red_flags": [],
|
||||
"blocking_issues": [],
|
||||
"confidence": "MEDIUM",
|
||||
"references": [],
|
||||
"matched_docs": [],
|
||||
"gates": []
|
||||
}
|
||||
```
|
||||
|
||||
## Niveaux de sévérité
|
||||
|
||||
- `must_do` : action attendue fortement recommandée
|
||||
- `should_do` : amélioration ou vérification utile
|
||||
- `red_flags` : signal de risque ou d'incertitude
|
||||
- `blocking_issues` : empêche la progression en mode strict
|
||||
|
||||
## Confiance
|
||||
|
||||
- `HIGH`
|
||||
- `MEDIUM`
|
||||
- `LOW`
|
||||
|
||||
Règle :
|
||||
- la confiance exprime la qualité du matching heuristique, pas la vérité terrain
|
||||
|
||||
## Références
|
||||
|
||||
`references[]` contient :
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/abs/path/doc.md",
|
||||
"reason": "Match patterns score=7"
|
||||
}
|
||||
```
|
||||
|
||||
Règle :
|
||||
- toujours renvoyer des chemins absolus si possible
|
||||
- référencer la source, pas uniquement un résumé
|
||||
|
||||
## Matched docs
|
||||
|
||||
`matched_docs[]` expose les meilleurs documents remontés par le moteur de guidance.
|
||||
|
||||
Structure cible v1 :
|
||||
|
||||
```json
|
||||
{
|
||||
"path": "/abs/path/doc.md",
|
||||
"bucket": "patterns",
|
||||
"title": "Backend — Patterns : NestJS",
|
||||
"score": "12",
|
||||
"severity": "medium",
|
||||
"applies_to": "analysis, implementation, review, debug",
|
||||
"tags": "nestjs, guards, auth, redis, quota",
|
||||
"read_uri": "leadtech://knowledge/backend/patterns/nestjs"
|
||||
}
|
||||
```
|
||||
|
||||
Règle :
|
||||
- champ informatif, non bloquant
|
||||
- utile pour les agents qui veulent afficher ou prioriser explicitement les docs remontés
|
||||
|
||||
## Erreurs
|
||||
|
||||
Conventions v1 :
|
||||
|
||||
- tool de lecture : lever une erreur explicite si ressource introuvable
|
||||
- tool d'écriture : retourner un objet `{ "error": "..." }` si écriture désactivée ou cible introuvable
|
||||
- ne jamais écrire dans `knowledge/*`
|
||||
|
||||
## Sécurité d'écriture
|
||||
|
||||
Écritures autorisées uniquement vers :
|
||||
|
||||
- `95_a_capitaliser.md`
|
||||
- `CLAUDE.md` projet
|
||||
|
||||
Écritures interdites :
|
||||
|
||||
- `knowledge/*`
|
||||
- `10_*`
|
||||
- `40_*`
|
||||
- `90_*`
|
||||
|
||||
## Compatibilité BMAD
|
||||
|
||||
Ce contrat v1 est pensé pour :
|
||||
|
||||
- enrichir une story à l'entrée
|
||||
- bloquer certains cas en pre-implémentation ou post-patch
|
||||
- tracer la décision humaine dans la story
|
||||
|
||||
Les prompts BMAD doivent considérer ce contrat comme stable tant qu'un document `v2` n'existe pas.
|
||||
Reference in New Issue
Block a user