@dev-kosaly/kagents 0.1.0 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dev-kosaly/kagents",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Kit d'agents IA d'ingénierie installable dans un projet (Claude Code, Cursor, AGENTS.md)",
   "bin": {
     "kagents": "bin/kagents.js"
@@ -10,10 +10,12 @@
     "agents",
     "skills",
     "commands",
+    "rules",
     "templates",
     "checklists",
     "workflows",
-    "governance"
+    "governance",
+    "docs"
   ],
   "engines": {
     "node": ">=18"

package/rules/domains/architect-chat.md

@@ -0,0 +1,61 @@
+# Contrat de sortie chat — Architect
+
+Reference adaptative — omettre les sections sans contenu utile.
+
+Priorite : **Clarte > Pertinence > Structure > Concision > Esthetique**.
+
+```markdown
+# Architect — [titre]
+
+**Mode :** Architecture | Impact
+**Niveau :** L0 | L1 | L2 | L3
+**Statut :** ETABLI | A VALIDER | BLOQUANT (selon le cas)
+
+## Synthese
+
+Quelques paragraphes : conclusion immediate, ce qui a ete analyse, proposition retenue.
+
+## Constats principaux
+
+Tableau ou liste (elements importants seulement).
+
+## Impact architectural
+
+Tableau MVC si mode Impact (ou « Pas d'impact identifie » par couche).
+
+| Couche | Impact | Element cle |
+|--------|--------|-------------|
+| Modele | | |
+| Controleur | | |
+| Vue | | |
+
+## Architecture concernee
+
+Diagramme Mermaid ou schema **uniquement** si cela clarifie flux ou composants.
+
+## Points a decider
+
+Decisions humaines importantes (pas les propositions de l'agent presentees comme decidees).
+
+## Incertitudes / points bloquants
+
+Ce qui influence la suite (max 5 questions bloquantes).
+
+## Handoff
+
+### Base (Database Expert)
+Si BDD / donnees concernees : ce que Base doit analyser dans `base-docs/`.
+
+### Suite du travail
+Validation humaine, Base, puis implementation (Developer hors scope de ce role).
+
+## Prochaine etape
+
+Action concrete.
+
+## Livrable
+
+Chemin exact : `.kagents/docs/architect-docs/outputs/...`
+```
+
+Le chat **n'est pas** une copie du fichier persistant. Ne pas lister tous les fichiers du repo.

package/rules/domains/architect-invariants.md

@@ -0,0 +1,22 @@
+# Invariants — Architect / Spec
+
+## Non-negociable
+
+- Ne pas modifier le code applicatif, migrations, modeles, ni `base-docs/`.
+- Ne pas ecrire SQL ni imposer un schema BDD.
+- Ne pas modifier les commandes, agents ou skills Base.
+- Ne pas lire ni recopier secrets (`.env`, credentials, tokens).
+- Ne pas ecraser un livrable dans `architect-docs/outputs/` sans suffixe version explicite.
+- Ne pas transformer PROPOSITION / DEDUIT en ETABLI sans source.
+
+## Qualification
+
+Chaque affirmation importante porte un statut : ETABLI, DEDUIT, PROPOSITION, A VALIDER, INCONNU, BLOQUANT.
+
+## Repository vs documentation
+
+Le code prevaut en cas de divergence avec une doc obsolete ; signaler l'ecart, ne pas trancher silencieusement.
+
+## knowledge/context.md
+
+Lecture autorisee. Ecriture automatique interdite sauf instruction explicite utilisateur ou politique projet documentee.

package/skills/README.md

@@ -1,31 +1,28 @@
 # Skills
 
-Une procedure = un dossier avec `SKILL.md` (frontmatter `name`, `description`).
+## Architect / Spec (internes — pas des commandes publiques)
 
-## Architect / Spec (implementees)
+| Skill | Commande publique typique |
+|-------|---------------------------|
+| `architect-discovery/` | `kagents architect` |
+| `architect-audit/` | `kagents architect:audit`, `:impact`, `:spec` |
+| `architect-impact/` | `kagents architect:impact`, partie `:spec` |
+| `architect-write-output/` | toutes commandes avec livrable |
+| `architect-index/` | livrables + registre decisions |
+| `architect-status/` | `kagents architect:status` (read-only) |
+| `architect-decision/` | `kagents architect:decision` |
 
-| Skill | Role |
-|-------|------|
-| `feature-analysis/` | Demande feature ou modification fonctionnelle |
-| `audit-repository/` | Cartographie projet existant |
-| `architecture-impact/` | Impacts et niveau L0–L3 |
-| `write-change-brief/` | Change Brief dans le repo projet |
+Contrat commandes : `docs/architect-commands.md` — fichiers `commands/architect*.md`.
 
-Role canonique : `agents/architect.md`.
+Role : `agents/architect.md`.
 
-## Base / base de donnees (implementees)
+## Base (base de données)
 
-| Skill | Role |
+| Skill | Rôle |
 |-------|------|
-| `schema-exploration/` | Explorer le repo et reconstruire le modele |
+| `schema-exploration/` | Explorer le repo et reconstruire le modèle |
 | `catalyst-export/` | Exploiter l'export JSON Catalyst |
-| `db-analysis/` | Grille d'analyse et severites |
-| `db-docs/` | Modeles des fichiers de `base-docs/db/` |
+| `db-analysis/` | Grille d'analyse et sévérités |
+| `db-docs/` | Modèles des fichiers de `base-docs/db/` |
 
 Agent : `agents/database_expert.md`.
-
-## A venir (hors perimetre actuel)
-
-- `write-adr/`
-- `catalyst-impact/` (analyse detaillee)
-- `init-project-artifacts/`

package/skills/architect-audit/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: architect-audit
+description: >-
+  Audit cible du repository avant analyse d'impact : stack, composants, ADR,
+  zones sensibles. Alimente Constats et Elements etablis du livrable.
+---
+
+# Architect audit
+
+## Quand utiliser
+
+- Mode Impact sur repo ou domaine peu connu.
+- Etape 3–4 de `architect-impact` si les constats sont insuffisants.
+
+## Lecture
+
+Ordre (aligne `agents/architect.md`) : decisions validees ; docs metier projet si presentes ; livrables Architect + `INDEX.md` ; `base-docs/` lecture seule ; `knowledge/context.md` ; code cible ; config non sensible ; standards harness si besoin.
+
+Signaler absences (STATE, schema, etc.) — ne pas creer.
+
+## Etapes
+
+1. Stack et decoupage (synthese actionnable).
+2. Composants et fichiers **directement** lies a la demande.
+3. Dependances et flux pertinents.
+4. Documentation architecturale existante : coherence avec code.
+5. Renseigner sections Constats / Architecture actuelle du template.
+
+## Limites
+
+Pas de refactoring propose. Pas d'ecriture base-docs.

package/skills/architect-decision/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: architect-decision
+description: >-
+  Interne — kagents architect:decision. Enregistre decision humaine dans
+  decisions/DEC-XXX-slug.md, met a jour INDEX, lie propositions/livrables.
+---
+
+# Architect decision
+
+## Quand utiliser
+
+- **`kagents architect:decision "<texte>"`** — le texte est la decision a enregistrer (VALIDEE par acte humain de commande).
+
+## Interdictions
+
+- Ne pas marquer VALIDEE une simple recommandation agent non confirmee par cette commande.
+- Ne pas ecraser un fichier DEC existant ; ne pas reutiliser un ID.
+- Ne pas supprimer propositions ni outputs ; ne pas ecrire base-docs ; pas de SQL/migrations.
+
+## Etapes
+
+1. Interpreter `$ARGUMENTS` comme **Decision** (pas une question).
+2. Detecter intent special dans le texte :
+   - « remplace DEC-00N » / « remplacement DEC-00N » → creer nouvelle DEC VALIDEE, mettre DEC-00N en **REMPLACEE** + lien.
+   - « rejet » / « REJETEE » → statut **REJETEE** si l'utilisateur enregistre un rejet explicite.
+3. **Prochain ID** : lister `decisions/DEC-*.md`, prendre max(N)+1 → `DEC-001`, etc.
+4. **Slug** : kebab-case court depuis le sujet (ex. `finance-marge-source`).
+5. Creer `decisions/DEC-XXX-<slug>.md` depuis `templates/architect-decision/template.md`.
+6. Renseigner metadonnees ; **Decideur : Humain** ; Statut **VALIDEE** par defaut.
+7. Lier **proposition d'origine** : chercher dans INDEX / dernier livrable pertinent (ex. finance marge v3) — ne pas modifier le livrable sauf ajout optionnel en **References** d'une ligne « Decision : DEC-XXX » en fin de fichier si deja ouvert pour edition ; preferer lien depuis decision vers output.
+8. Mettre a jour INDEX section **## Decisions (registre)** (ajouter ligne, ne pas reconstruire tout le fichier).
+9. Chat synthese : ID, statut, domaine, chemin, suite.
+
+## Propositions
+
+Conserver fichiers dans `proposals/` et contenu PROPOSITION dans outputs — ajouter dans decision le lien PROPOSITION → DECISION.
+
+## Remplacement
+
+Editer l'ancien fichier : Statut **REMPLACEE**, `Remplace par : DEC-YYY`. Creer DEC-YYY **VALIDEE**.

package/skills/architect-discovery/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: architect-discovery
+description: >-
+  Interne — commande publique kagents architect. Cartographie l'architecture observee
+  du projet : modules, flux, couches, dependances. Livrable dans outputs/architecture/.
+---
+
+# Architect discovery
+
+## Quand utiliser
+
+- Commande **`kagents architect`** ou demande « explique l'architecture », « comment est organise le projet ».
+- Avant une grosse evolution si aucune doc architecture fiable n'existe.
+
+## Prerequis
+
+- Racine repo projet.
+
+## Lecture (ciblee)
+
+1. `INDEX.md` et livrables Architect existants
+2. `knowledge/context.md` (sans modifier)
+3. `base-docs/` en lecture si deja present
+4. Manifestes stack, README, arborescence haute
+5. Code : entrees (routes, handlers), modules metier nommes, data layer visible
+
+Interdit : secrets, lecture exhaustive du repo.
+
+## Etapes
+
+1. Decrire structure **observee** (pas ideale).
+2. Modules, responsabilites, flux principaux, entrees/sorties.
+3. Backend, frontend, APIs, stockage **tels qu'observes**.
+4. Conventions reperees ; divergences doc vs code → **ETABLI** (code) + note d'ecart.
+5. Qualifier chaque bloc (ETABLI / DEDUIT / INCONNU).
+6. Niveau L0 sauf demande implicite de changement.
+7. `architect-write-output` → `outputs/architecture/`, type `architecture`.
+8. `architect-index`.
+9. Chat : `rules/domains/architect-chat.md`.
+
+## Resultat
+
+Livrable architecture + INDEX a jour.

package/skills/architect-impact/SKILL.md

@@ -0,0 +1,32 @@
+---
+name: architect-impact
+description: >-
+  Interne — commande publique kagents architect:impact. Procedure complete : perimetre,
+  MVC, L0-L3, risques, handoff Base, livrable persistant.
+---
+
+# Architect impact
+
+## Quand utiliser
+
+- **`kagents architect:impact "<demande>"`** ou formulations naturelles d'evolution.
+
+## Procedure
+
+Suivre `workflows/architect-impact.md`. Etapes cles (detail dans le workflow) :
+
+1. Objectif, perimetre, `architect-audit` si besoin.
+2. Qualifier ETABLI / DEDUIT / PROPOSITION / INCONNU / A VALIDER / BLOQUANT.
+3. Niveau L0–L3 via `workflows/architect-impact-levels.yaml` + justification.
+4. MVC ; autres axes si pertinents.
+5. Proposition, risques, decisions humaines, handoff Base (sans DDL).
+6. `architect-write-output` : `features/` si demande fonctionnelle, sinon `impacts/`.
+7. `architect-index` puis chat : `rules/domains/architect-chat.md`.
+
+## Questions
+
+Maximum 5 bloquantes ; autres → hypotheses qualifiees.
+
+## BDD
+
+Detecter impact ; preparer handoff ; **ne pas** decider schema, migrations, SQL.

package/skills/architect-index/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: architect-index
+description: >-
+  Met a jour .kagents/docs/architect-docs/INDEX.md apres un livrable Architect
+  (registre navigation, pas rapport).
+---
+
+# Architect index
+
+## Fichier
+
+`.kagents/docs/architect-docs/INDEX.md`
+
+Creer depuis `templates/architect-index/INDEX.template.md` si absent.
+
+## Apres chaque livrable
+
+1. Ajouter une ligne dans le tableau appropriate (Architecture / Impacts / Audits).
+2. Colonnes : Date, Fichier (lien relatif), Sujet, Niveau, Statut si impact.
+3. Mettre a jour **Decisions ouvertes** / **Travaux en cours** si pertinent (listes courtes).
+4. Ne pas dupliquer le contenu du livrable dans INDEX.
+
+## Apres chaque decision (`architect-decision`)
+
+1. Ajouter une ligne dans **## Decisions (registre)** : ID, Titre, Statut, Date, Domaine, Lien vers `decisions/DEC-XXX-*.md`.
+2. Retirer ou ajuster **Decisions ouvertes** si la decision tranche une question listee.
+3. Ne pas reconstruire tout INDEX.md.
+
+## Limites
+
+Ne pas modifier INDEX d'autres domaines (base-docs).

package/skills/architect-status/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: architect-status
+description: >-
+  Interne — kagents architect:status. Lecture INDEX, decisions/, proposals/,
+  synthese read-only. Pas d'audit repository complet.
+---
+
+# Architect status
+
+## Quand utiliser
+
+- Commande **`kagents architect:status`**.
+
+## Interdictions
+
+- Pas de modification de fichiers (read-only).
+- Pas d'audit repo complet ; pas de code metier modifie.
+- Pas de lecture secrets.
+
+## Lecture
+
+1. `.kagents/docs/architect-docs/INDEX.md`
+2. `.kagents/docs/architect-docs/decisions/DEC-*.md` (metadonnees + statut)
+3. `.kagents/docs/architect-docs/proposals/` si existe
+4. Livrables `outputs/` : uniquement entrees INDEX ou fichiers cites pour travaux ouverts / handoffs / A VALIDER
+
+## Aggregation
+
+- **Travaux ouverts** : section INDEX + lignes statut A VALIDER / travaux en cours
+- **Decisions** : par statut (A VALIDER, VALIDEE, REJETEE, REMPLACEE, PROPOSEE)
+- **Handoffs** : depuis derniers livrables (sections Handoff / Base) si mentionnes en INDEX ou entete — lecture ciblee max 3 fichiers recents
+- **Derniers livrables** : 3–5 entrees les plus recentes dans INDEX (toutes sections)
+- **Blocages** : questions BLOQUANT / INCONNU dans decisions ouvertes ou livrables
+
+Statuts decisions : PROPOSEE, A VALIDER, VALIDEE, REJETEE, REMPLACEE.
+
+## Sortie chat
+
+Structure adaptative : `# Architect — Etat du projet` — voir `workflows/architect-status.md` et exemples dans `commands/architect-status.md`.
+
+Ne pas lister tous les fichiers du repo.

package/skills/architect-write-output/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: architect-write-output
+description: >-
+  Ecrit le livrable Markdown dans .kagents/docs/architect-docs/outputs/ avec
+  nommage deterministe YYYY-MM-DD__type__slug__vN.md sans ecrasement silencieux.
+---
+
+# Architect write output
+
+## Repertoires
+
+| Type | Sous-dossier |
+|------|----------------|
+| architecture | `outputs/architecture/` |
+| impact | `outputs/impacts/` |
+| feature | `outputs/features/` |
+| spec | `outputs/specs/` |
+| design | `outputs/designs/` |
+| audit | `outputs/audits/` |
+
+**Choix du sous-dossier**
+
+- `architecture/` : `kagents architect`.
+- `features/` : evolution fonctionnelle (`architect:impact` focalise feature).
+- `impacts/` : `architect:impact` transversal sans focalisation feature.
+- `specs/` : `architect:spec`.
+- `designs/` : `architect:design`.
+- `audits/` : `architect:audit`.
+
+Creer les dossiers si absents.
+
+## Nom de fichier
+
+`YYYY-MM-DD__<type>__<slug-kebab>__vN.md`
+
+- `slug` : sujet metier court (ex. `finance-marge-facture`)
+- `vN` : incrementer si un fichier meme date+type+slug existe deja
+
+## Etapes
+
+1. Choisir type et sous-dossier.
+2. Verifier collision ; ajuster `vN`.
+3. Remplir `templates/architect-output/template.md`.
+4. Renseigner Metadonnees.Fichier avec chemin relatif.
+5. Ne pas inclure secrets ni SQL/migrations.
+
+## Resultat
+
+Chemin communique dans le chat (section Livrable).

package/templates/architect-decision/template.md

@@ -0,0 +1,47 @@
+# DEC-XXX — [Titre]
+
+## Metadonnees
+
+- ID : DEC-XXX
+- Statut : VALIDEE | REJETEE | REMPLACEE | PROPOSEE | A VALIDER
+- Date : YYYY-MM-DD
+- Source : humain (commande `kagents architect:decision`)
+- Domaine :
+- Decideur : Humain
+- Remplace : (optionnel, ex. DEC-001)
+- Remplace par : (optionnel, ex. DEC-012)
+
+## Decision
+
+(Texte explicitement enregistre — pas une inference agent seule.)
+
+## Contexte
+
+## Proposition ou question d'origine
+
+(Lien vers livrable `outputs/` ou entree `proposals/` si existante.)
+
+## Alternatives considerees
+
+(Uniquement si documentees.)
+
+## Justification
+
+(Uniquement si fournie ou ETABLI depuis contexte cite.)
+
+## Consequences
+
+(DEDUIT marque si deduction.)
+
+## Impacts / Handoffs
+
+### Database Architect
+
+(Si pertinent — informatif, pas prescriptif schema.)
+
+### Suite du travail
+
+## References
+
+- Livrables :
+- Propositions :

package/templates/architect-design/template.md

@@ -0,0 +1,31 @@
+# [Titre — Conception cible]
+
+## Metadonnees
+
+- Type : design
+- Commande : kagents architect:design
+- Date :
+- Statut : PROPOSITION / A VALIDER
+- Fichier :
+
+## Objectif
+
+## Architecture actuelle (resume ETABLI)
+
+## Options considerees
+
+## Architecture cible proposee
+
+## Compromis
+
+## Avantages
+
+## Risques
+
+## Dependances
+
+## Impacts
+
+## Decisions necessaires
+
+## Handoff

package/templates/architect-index/INDEX.template.md

@@ -0,0 +1,47 @@
+# Index — Architect / Spec
+
+Registre de navigation (pas un rapport). Mettre a jour via skill `architect-index`.
+
+## Architecture
+
+| Date | Fichier | Sujet | Niveau |
+|------|---------|-------|--------|
+| | | | |
+
+## Impacts / features
+
+| Date | Fichier | Sujet | Niveau | Statut |
+|------|---------|-------|--------|--------|
+| | | | | |
+
+## Specs
+
+| Date | Fichier | Sujet | Statut |
+|------|---------|-------|--------|
+| | | | |
+
+## Designs
+
+| Date | Fichier | Sujet | Statut |
+|------|---------|-------|--------|
+| | | | |
+
+## Audits
+
+| Date | Fichier | Sujet |
+|------|---------|-------|
+| | | |
+
+## Decisions (registre)
+
+| ID | Titre | Statut | Date | Domaine | Lien |
+|----|-------|--------|------|---------|------|
+| | | | | | |
+
+## Decisions ouvertes (questions / propositions non tranchees)
+
+- 
+
+## Travaux en cours
+
+- 

package/templates/architect-output/template.md

@@ -0,0 +1,95 @@
+# [Titre]
+
+## Metadonnees
+
+- Type : architecture | impact | feature | audit
+- Mode : Architecture | Impact
+- Niveau : L0 | L1 | L2 | L3
+- Statut : ETABLI | A VALIDER | BLOQUANT | ...
+- Date : YYYY-MM-DD
+- Domaine concerne :
+- Fichier : (chemin relatif depuis la racine projet)
+
+## Objectif
+
+## Demande initiale
+
+## Contexte
+
+## Perimetre
+
+## Constats du repository
+
+## Elements etablis
+
+## Deductions
+
+## Inconnues
+
+## Exigences
+
+## Contraintes
+
+## Niveau d'impact
+
+Justification :
+
+Condition d'escalade : (optionnel)
+
+## Analyse MVC
+
+### Modele
+
+### Controleur
+
+### Vue
+
+## Dependances
+
+## Architecture actuelle
+
+## Flux concernes
+
+## Proposition architecturale
+
+## Alternatives considerees
+
+(Uniquement si plusieurs options reelles)
+
+## Compromis
+
+## Risques
+
+## Securite
+
+(Si pertinent)
+
+## Tests
+
+(Si pertinent)
+
+## Performance / cout
+
+(Si pertinent)
+
+## Decisions validees
+
+## Decisions a valider
+
+## Questions ouvertes
+
+## Impact Database Architect (Base)
+
+Ce que Base doit analyser — sans decision BDD de la part de l'Architect.
+
+## Handoff
+
+Informations pour l'etape suivante (Base, validation humaine, implementation future).
+
+## Criteres de completude
+
+Conditions pour considerer l'analyse prete pour la suite.
+
+## References
+
+Sources reellement utiles (fichiers, docs, livrables).

package/templates/architect-spec/template.md

@@ -0,0 +1,39 @@
+# [Titre — Specification]
+
+## Metadonnees
+
+- Type : spec
+- Commande : kagents architect:spec
+- Date :
+- Niveau d'impact (si evalue) :
+- Fichier :
+
+## Objectif
+
+## Contexte
+
+## Comportement attendu
+
+## Exigences
+
+## Contraintes
+
+## Regles connues (ETABLI uniquement)
+
+## Cas nominaux
+
+## Cas limites
+
+## Criteres d'acceptation
+
+## Impact architectural
+
+(Voir distinction Impact vs Spec — synthese ou renvoi livrable impact)
+
+## Dependances
+
+## Decisions
+
+## Questions ouvertes
+
+## Handoff