@dev-kosaly/kagents 0.1.0 → 0.1.1

package/workflows/architect-architecture.md

@@ -0,0 +1,19 @@
+# Workflow — Architect mode Architecture
+
+Commande : **`kagents architect`** (voir `commands/architect.md`).
+
+## Objectif
+
+Comprendre et documenter l'architecture **observee** du projet (pas une architecture ideale inventee).
+
+## Enchainement
+
+1. `agents/architect.md` + `rules/domains/architect-invariants.md`
+2. Skill `architect-discovery`
+3. Skill `architect-write-output` → `.kagents/docs/architect-docs/outputs/architecture/`
+4. Skill `architect-index` → mettre a jour `INDEX.md`
+5. Chat : contrat `rules/domains/architect-chat.md`
+
+## Livrable
+
+Type : architecture. Niveau typique : L0 (ajuster si l'audit revele un changement planifie).

package/workflows/architect-audit-run.md

@@ -0,0 +1,14 @@
+# Workflow — kagents architect:audit
+
+## Objectif
+
+Auditer l'architecture **existante** (derive, ecart doc/code, couplage) — pas modifier le code.
+
+## Enchainement
+
+1. `agents/architect.md` + invariants
+2. `architect-audit` — scope = argument commande si present
+3. Documenter findings observes uniquement
+4. `architect-write-output` → `outputs/audits/`, type `audit`
+5. `architect-index`
+6. Chat : `architect-chat.md`

package/workflows/architect-decision.md

@@ -0,0 +1,20 @@
+# Workflow — kagents architect:decision
+
+## Objectif
+
+Enregistrer une **decision humaine** (argument utilisateur = texte a enregistrer, pas a debattre).
+
+## Gouvernance
+
+- L'agent **ne valide pas** seul une recommandation : la commande implique confirmation humaine explicite.
+- Statut par defaut a l'enregistrement : **VALIDEE** (sauf indication contraire dans la commande : « rejet », « remplace DEC-00X »).
+
+## Enchainement
+
+1. `agents/architect.md` + invariants
+2. Skill `architect-decision`
+3. Chat : synthese (ID, statut, chemin) — pas recopie integrale
+
+## Remplacement
+
+Nouveau fichier DEC-YYY ; ancien fichier mis a jour statut **REMPLACEE** + lien `Remplace par : DEC-YYY` — jamais supprimer l'ancien.

package/workflows/architect-design.md

@@ -0,0 +1,15 @@
+# Workflow — kagents architect:design
+
+## Objectif
+
+Proposer une **architecture cible** pour un objectif — distincte de l'architecture observee (`kagents architect`).
+
+## Enchainement
+
+1. `agents/architect.md` + invariants
+2. `architect-discovery` — resumer existant pertinent (reference, pas recopie integrale)
+3. Rediger options / cible / compromis via `templates/architect-design/template.md`
+4. Toute option = **PROPOSITION** ; decisions = **A VALIDER**
+5. `architect-write-output` → `outputs/designs/`, type `design`
+6. `architect-index`
+7. Chat : `architect-chat.md`

package/workflows/architect-impact-levels.yaml

@@ -0,0 +1,28 @@
+# Niveaux d'impact — role Architect / Spec uniquement
+# Reference : agents/architect.md
+#
+# Distinct de workflows/impact-levels.yaml (pipeline global, autre semantique L0,
+# roles Developer/Reviewer). Pour une analyse Architect, utiliser CE fichier.
+
+levels:
+  L0:
+    label: Comprehension / documentation
+    description: >
+      Aucune modification architecturale significative. Comprendre, documenter
+      ou expliquer l'existant.
+
+  L1:
+    label: Impact local
+    description: >
+      Impact limite a une zone ou un composant clairement delimite.
+
+  L2:
+    label: Impact transversal
+    description: >
+      Plusieurs couches, modules ou contrats concernes. Coordination multi-domaines.
+
+  L3:
+    label: Impact systemique
+    description: >
+      Architecture globale, donnees critiques, contrats partages, securite importante,
+      performance structurante, infrastructure, integrations externes ou domaines fortement couples.

package/workflows/architect-impact.md

@@ -0,0 +1,20 @@
+# Workflow — Architect mode Impact
+
+Commande : **`kagents architect:impact "<demande>"`** (voir `commands/architect-impact.md`).
+
+## Objectif
+
+Analyser l'impact d'une evolution avant developpement.
+
+## Enchainement
+
+1. `agents/architect.md` + invariants
+2. `architect-audit` si repo ou domaine peu connu
+3. `architect-impact` (procedure complete)
+4. `architect-write-output` → `outputs/features/` (evolution fonctionnelle) ou `outputs/impacts/` (impact general)
+5. `architect-index`
+6. Chat : `rules/domains/architect-chat.md`
+
+## Handoff
+
+Document persistant → Base (Database Expert) si Modele concerne → Developer (mention only, role hors perimetre).

package/workflows/architect-spec.md

@@ -0,0 +1,19 @@
+# Workflow — kagents architect:spec
+
+## Objectif
+
+Formaliser une **spec** (comportement attendu) distincte de l'**impact** (ce que ca touche).
+
+## Enchainement
+
+1. `agents/architect.md` + invariants
+2. `architect-audit` si contexte insuffisant
+3. `architect-impact` — remplir uniquement parties impact / MVC / L0–L3 / risques (pas substitut a la spec)
+4. Rediger sections **Spec** via `templates/architect-spec/template.md`
+5. `architect-write-output` → `outputs/specs/`, type `spec`
+6. `architect-index`
+7. Chat : `architect-chat.md`
+
+## Regles
+
+Ne pas inventer regles metier. Qualifier ETABLI / INCONNU.

package/workflows/architect-status.md

@@ -0,0 +1,21 @@
+# Workflow — kagents architect:status
+
+## Objectif
+
+Vue **read-only** de l'etat documentaire Architect (pas d'audit repo complet).
+
+## Enchainement
+
+1. `agents/architect.md` + invariants
+2. Skill `architect-status`
+3. Chat : format pilotage (pas de livrable persistant obligatoire)
+
+## Lecture (ordre)
+
+1. `.kagents/docs/architect-docs/INDEX.md`
+2. `decisions/` (fichiers DEC-*.md)
+3. `proposals/` si present
+4. Derniers chemins cites dans INDEX (outputs) — lire entete/metadonnees seulement si necessaire
+5. Code : **uniquement** si incohérence documentaire a verifier
+
+Principe : lire peu, synthetiser juste.

package/commands/arch-audit.md

@@ -1,10 +0,0 @@
----
-description: Architect — état des lieux d'un projet existant
-agent: architect
-mode: B (Projet existant)
-triggers: analyse mon projet existant, cartographie le repo, onboarding
----
-Lis `.kagents/agents/architect.md` et applique-le en **situation B. Projet existant**.
-Charge ensuite uniquement les skills que cette situation indique, depuis `.kagents/skills/`.
-
-Demande de l'utilisateur : $ARGUMENTS

package/commands/arch-design.md

@@ -1,10 +0,0 @@
----
-description: Architect — cadrage d'un nouveau projet
-agent: architect
-mode: A (Nouveau projet)
-triggers: cadre mon nouveau projet, architecture d'un nouveau projet
----
-Lis `.kagents/agents/architect.md` et applique-le en **situation A. Nouveau projet**.
-Charge ensuite uniquement les skills que cette situation indique, depuis `.kagents/skills/`.
-
-Demande de l'utilisateur : $ARGUMENTS

package/commands/arch-feature.md

@@ -1,10 +0,0 @@
----
-description: Architect — analyse d'une fonctionnalité ou modification
-agent: architect
-mode: C (Feature / modification)
-triggers: analyse cette fonctionnalité, impact d'un changement, cadre ce ticket
----
-Lis `.kagents/agents/architect.md` et applique-le en **situation C. Feature / modification**.
-Charge ensuite uniquement les skills que cette situation indique, depuis `.kagents/skills/`.
-
-Demande de l'utilisateur : $ARGUMENTS

package/skills/architecture-impact/SKILL.md

@@ -1,68 +0,0 @@
----
-name: architecture-impact
-description: >-
-  Evalue impacts multi-axes (metier, archi, BDD, backend, frontend, securite,
-  perf, cout) et determine le niveau L0-L3 avec justification. A utiliser apres
-  feature-analysis ou audit-repository.
----
-
-# Architecture impact
-
-## Quand utiliser
-
-- Apres comprehension initiale de la demande (`feature-analysis` ou `audit-repository`).
-- Des qu'un doute existe sur L1 vs L2 vs L3.
-- Avant `write-change-brief` pour L2+.
-
-Reference canonique des niveaux : `workflows/impact-levels.yaml`.
-
-## Prerequis
-
-- Goal et perimetre connus (meme partiellement).
-- Findings existant disponibles ou N/A (nouveau projet greenfield).
-
-## Fichiers a lire
-
-- `workflows/impact-levels.yaml`
-- Projet : `schema.yaml`, ADR liees, `STATE.md` (zones protegees)
-- `checklists/catalyst-change.md` si stack Catalyst probable
-- `standards/README.md` — ouvrir un standard domaine **seulement** si l'impact de ce domaine est non trivial
-
-## Etapes
-
-1. Remplir **Impact** (une ligne ou courte liste par axe ; « None » si vraiment aucun) :
-
-   | Axe | Contenu attendu |
-   |-----|-----------------|
-   | Business | regles, acteurs, changement comportement |
-   | Architecture | modules, boundaries, nouveaux composants |
-   | Database | voir formulations types dans `agents/architect.md` ; pas de DDL |
-   | Backend | API, jobs, integrations |
-   | Frontend | ecrans, etat, UX |
-   | Security | auth, permissions, donnees sensibles, nouvelles API |
-   | Performance | volume, latence, requetes repetees |
-   | Cost | Catalyst / infra ; signalement analyse detaillee si besoin |
-
-2. **Choisir L0–L3** et remplir **Why** en 1–3 phrases.
-
-   Guide rapide :
-
-   - **L0** : local, pas API/BDD/archi/permissions.
-   - **L1** : feature localisee, contrat stable.
-   - **L2** : BDD, API, multi-modules ou multi-couches.
-   - **L3** : archi structurante, migration sensible, permissions majeures, securite critique, changement metier majeur.
-
-3. **Proposal** : option retenue (simple par defaut) + alternatives ecartees en une phrase si utile.
-4. **Decisions** : separer Accepted / To validate / Existing preserved.
-5. **Risks / Exceptions** : regression, duplication data, hypothese non validee.
-6. **Acceptance Criteria** : testables, orientes metier/tech sans implementation detaillee.
-
-## Resultat attendu
-
-- Sections Impact, Impact Level, Proposal, Decisions, Acceptance Criteria, Risks de l'**Architect Analysis** completees.
-- Indication explicite : Database Architect requis (oui/non), ADR requise (oui/non), validation humaine (selon L2/L3).
-
-## Proportionnalite
-
-- L0/L1 : Impact peut etre bref ; pas de Change Brief obligatoire sauf equipe l'exige.
-- L2/L3 : Impact complet ; Change Brief + validation selon `impact-levels.yaml`.

package/skills/audit-repository/SKILL.md

@@ -1,53 +0,0 @@
----
-name: audit-repository
-description: >-
-  Cartographie un projet existant ou un codebase avant changement (situation B,
-  ou A avec code deja present). Stack, modules, flux, ADR, zones protegees.
-  Sortie synthese pour Architect Analysis ou onboarding.
----
-
-# Audit repository
-
-## Quand utiliser
-
-- **Projet existant** : onboarding, audit initial, avant grosse feature (situation **B**).
-- **Nouveau projet** avec code deja present (legacy, template, fork) — situation **A** partielle.
-- Avant `feature-analysis` si l'agent ne connait pas la structure du repo.
-
-Ne pas remplacer une exploration exhaustive : produire une **synthese actionnable** pour l'Architect.
-
-## Prerequis
-
-- Racine du repo projet identifiee.
-- Lire d'abord les artefacts projet avant le code.
-
-## Fichiers a lire (ordre)
-
-1. `AGENTS.md`, `STATE.md`, `project.yaml`
-2. `business-rules.md`, `glossary.md`, `schema.yaml`, `debt.yaml` (si present)
-3. ADR dans le repo (souvent `docs/adr/` ou racine — chercher `ADR` par nom, limiter aux 5–10 plus recents ou pertinents)
-4. Manifestes stack : `package.json`, `composer.json`, `catalyst.json`, README projet, configs deploy — **ceux presents uniquement**
-5. Code : arborescence de premier niveau + dossiers mentionnes dans STATE/debt ; approfondir seulement les zones liees a la demande courante
-
-Harness : `workflows/existing-project.md` pour alignement processus.
-
-## Etapes
-
-1. **Stack** : langages, frameworks, hebergement (dont Catalyst si indices).
-2. **Architecture actuelle** : decoupage modules / couches en 5–15 lignes max.
-3. **Flux principaux** touches ou a risque (si demande connue) ; sinon flux generiques entree/sortie.
-4. **Decisions** : ADR acceptees resumees ; contradictions possibles avec la demande.
-5. **Zones protegees** : depuis `STATE.md` ou deduction explicite *hypothesis*.
-6. **Fichiers / composants cles** : liste courte avec role (pas dump de tree).
-7. **Dette** : pointer `debt.yaml` ou observations majeures si visibles sans lire tout le code.
-8. Integrer les findings dans **Architect Analysis** → sections Context, Found, Artifacts.
-
-## Resultat attendu
-
-- Section **Found** et **Artifacts** de l'Architect Analysis remplies.
-- **Next Step** : feature-analysis, architecture-impact, ou write-change-brief selon la demande suivante.
-
-## Limites
-
-- Pas de refactoring propose dans l'audit.
-- Pas de revue securite complete (signaler surfaces evidentes seulement).

package/skills/feature-analysis/SKILL.md

@@ -1,52 +0,0 @@
----
-name: feature-analysis
-description: >-
-  Analyse une nouvelle fonctionnalite ou modification fonctionnelle avant
-  implementation. Utiliser pour situation C (feature) ou clarification de
-  demande sur projet existant. Produit une Architect Analysis ou alimente
-  write-change-brief.
----
-
-# Feature analysis
-
-## Quand utiliser
-
-- Nouvelle fonctionnalite ou evolution d'une existante (situation **C**).
-- Demande ambigue necessitant cadrage avant dev.
-- **Ne pas** utiliser seul pour L0 correctif trivial (workflow `bug-local.md`) : renvoyer Developer sauf doute sur le niveau.
-
-## Prerequis
-
-- Demande utilisateur ou ticket identifiable.
-- Repo projet accessible avec artefacts de base (`STATE.md` ideal).
-
-## Fichiers a lire (minimal, puis elargir si besoin)
-
-1. Projet : `AGENTS.md`, `STATE.md`, `business-rules.md`, `glossary.md`
-2. ADR / Change Brief ouverts lies au sujet
-3. `schema.yaml` si la demande touche donnees ou entites metier
-4. Code : uniquement modules, routes, ecrans ou APIs **nommes** dans la demande ou deduits apres premiere passe
-
-References harness : `agents/architect.md`, `workflows/impact-levels.yaml`.
-
-## Etapes
-
-1. **Goal** : objectif, utilisateurs, resultat attendu cote utilisateur.
-2. **Perimetre** : in scope / out of scope explicites.
-3. **Regles metier** : extraire de `business-rules.md` et glossary ; signaler lacunes (questions ou hypotheses).
-4. **Entites et dependances** : noms metier ; pas de schema detaille — noter « Database Architect si L2+ ».
-5. **Existant** : composants, flux, API deja en place a reutiliser ; zones protegees (`STATE.md`).
-6. **Simplicite** : solution minimale ; justifier toute nouvelle couche/table/service.
-7. Invoquer **`architecture-impact`** pour Impact + niveau L0–L3.
-8. Remplir le format **Architect Analysis** (`agents/architect.md`).
-9. Si L2+ ou changement significatif L1 : enchainer **`write-change-brief`**.
-
-## Resultat attendu
-
-- **Architect Analysis** complete (sections vides ou N/A si non pertinent).
-- Liste de **questions metier** seulement si bloquantes.
-- **Next Step** clair (ex. validation Change Brief, Database Architect, Developer).
-
-## Standards / rules
-
-Charger `standards/` uniquement si le sujet l'exige (securite, catalyst). Index : `standards/README.md`.

package/skills/write-change-brief/SKILL.md

@@ -1,63 +0,0 @@
----
-name: write-change-brief
-description: >-
-  Redige un Change Brief dans le repository projet a partir d'une Architect
-  Analysis. Utiliser pour L2+ ou changement L1 significatif. Template harness
-  templates/change-brief/template.md.
----
-
-# Write Change Brief
-
-## Quand utiliser
-
-- **L2 ou L3** (obligatoire processus : `workflows/impact-levels.yaml`).
-- **L1** si le changement touche contrat API, regles metier nouvelles, ou equipe exige trace ecrite.
-- Apres **`architecture-impact`** (Architect Analysis a jour).
-
-Ne pas confondre avec l'ADR : Change Brief = cadre du changement ; ADR = decision structurante (L3 typiquement), template `templates/adr/template.md`, statut **propose**.
-
-## Prerequis
-
-- Architect Analysis complete ou sections Goal, Impact, Impact Level, Proposal, Decisions, Acceptance Criteria remplies.
-- Emplacement projet choisi (convention equipe : ex. `docs/changes/YYYY-MM-DD-titre.md` ou `change-briefs/` — **dans le repo projet**, jamais dans le harness).
-
-## Fichiers a lire
-
-- Harness : `templates/change-brief/template.md`, `governance/actions.yaml`
-- Projet : ADR existantes pour liens croises
-
-## Etapes
-
-1. Copier la structure du **template** et adapter le titre.
-2. Renseigner metadonnees : niveau L0–L3, auteur (agent + validateur humain prevu), date.
-3. Mapper le contenu depuis l'Architect Analysis :
-
-   | Change Brief (template) | Source Analysis |
-   |-------------------------|-----------------|
-   | Besoin | Goal + Context |
-   | Perimetre | Goal (in/out) + Found |
-   | Impacts | Impact (tous axes) |
-   | Plan | Next Step + Proposal (phases courtes) |
-   | Validation | Decisions To validate ; cocher humain si L2/L3 |
-
-4. Ajouter dans le corps du document (sections libres si utile, rester concis) :
-
-   - Regles metier concernees
-   - Hors perimetre explicite
-   - Donnees / entites (niveau Architect, pas schema detaille)
-   - Dependances et regression
-   - Criteres d'acceptation (liste Analysis)
-   - Artefacts a consulter (liste Analysis)
-   - Risques / exceptions
-
-5. Toute decision nouvelle : libelle **proposition — a valider**, jamais « decide » sans ADR acceptee ou accord humain documente.
-6. L3 : mentionner brouillon ADR associe ou lien a creer.
-
-## Resultat attendu
-
-- Fichier Change Brief **dans le repo projet**, pret pour revue humaine (L2 propose, L3 requis).
-- **Next Step** dans l'Analysis mise a jour : ex. « Validation Change Brief », « Database Architect sur schema », « Developer apres validation ».
-
-## Gouvernance
-
-Actions sensibles : `governance/actions.yaml` — l'agent **propose** le fichier ; merge / validation selon processus equipe.