@dev-kosaly/kagents 0.1.0

package/bin/kagents.js

@@ -0,0 +1,348 @@
+#!/usr/bin/env node
+'use strict';
+// KAgents : installe le kit d'agents IA dans le projet courant.
+// Sans dépendance. Voir `kagents --help`.
+
+const fs = require('fs');
+const path = require('path');
+
+const PKG_ROOT = path.resolve(__dirname, '..');
+const PKG = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8'));
+const KIT_DIRS = ['agents', 'skills', 'commands', 'templates', 'checklists', 'workflows', 'governance'];
+const SKIP = new Set(['README.md', '.gitkeep']);
+const BLOCK_RE = /<!-- kagents:start -->[\s\S]*?<!-- kagents:end -->/;
+
+// Adaptateurs : un outil = une liste [dossier du kit, destination, type].
+// type : files (fichiers), dirs (dossiers), agents (fichiers .md avec `name:`).
+const ADAPTERS = {
+  agents: [['skills', '.agents/skills', 'dirs']],
+  claude: [
+    ['commands', '.claude/commands', 'files'],
+    ['skills', '.claude/skills', 'dirs'],
+    ['agents', '.claude/agents', 'agents'],
+  ],
+  cursor: [
+    ['commands', '.cursor/commands', 'files'],
+    ['skills', '.cursor/skills', 'dirs'],
+    ['agents', '.cursor/agents', 'agents'],
+  ],
+};
+
+const HELP = `kagents ${PKG.version}
+
+Usage : kagents [install] [--tools claude,cursor,agents|auto] [--copy]
+        kagents uninstall
+        kagents --help | --version
+
+À lancer depuis la racine du projet.
+  --tools   outils à brancher (défaut : auto = agents + claude/cursor s'ils sont détectés)
+  --copy    copies au lieu de liens symboliques (aussi la variable KAGENTS_MODE=copy)
+  uninstall retire ce que KAgents a installé (docs/ est conservé)
+`;
+
+const log = (m) => console.log(`kagents: ${m}`);
+const warn = (m) => console.warn(`kagents: ATTENTION ${m}`);
+const die = (m) => {
+  console.error(`kagents: ${m}`);
+  process.exit(1);
+};
+
+// --- Arguments ----------------------------------------------------------------
+function parseArgs(argv) {
+  const o = { cmd: 'install', tools: 'auto', copy: process.env.KAGENTS_MODE === 'copy' };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') o.cmd = 'help';
+    else if (a === '-v' || a === '--version') o.cmd = 'version';
+    else if (a === '--copy') o.copy = true;
+    else if (a === '--tools') o.tools = argv[++i] || die('--tools attend une valeur');
+    else if (a.startsWith('--tools=')) o.tools = a.slice(8);
+    else if (a === 'install' || a === 'uninstall') o.cmd = a;
+    else if (/^[a-z,]+$/.test(a)) o.tools = a; // compat : kagents claude,cursor
+    else die(`argument inconnu : ${a}\n${HELP}`);
+  }
+  return o;
+}
+
+// --- Utilitaires --------------------------------------------------------------
+// Frontmatter YAML d'une ligne par clé : { name, docs, description, ... }
+function frontmatter(file) {
+  const lines = fs.readFileSync(file, 'utf8').split(/\r?\n/);
+  const fm = {};
+  if (lines[0] !== '---') return fm;
+  for (let i = 1; i < lines.length && lines[i] !== '---'; i++) {
+    const m = lines[i].match(/^([A-Za-z_-]+):[ \t]*(.*)$/);
+    if (m) fm[m[1]] = m[2];
+  }
+  return fm;
+}
+
+const exists = (p) => {
+  try {
+    fs.lstatSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+const listDir = (d) => (fs.existsSync(d) ? fs.readdirSync(d).sort() : []);
+const listFiles = (dir) =>
+  listDir(dir).flatMap((n) => {
+    const p = path.join(dir, n);
+    if (SKIP.has(n)) return [];
+    return fs.statSync(p).isDirectory() ? listFiles(p) : [p];
+  });
+
+// --- Installateur -------------------------------------------------------------
+class Installer {
+  constructor(target, copy) {
+    this.target = target;
+    this.copy = copy;
+    this.kagents = path.join(target, '.kagents');
+    this.manifest = path.join(this.kagents, '.installed');
+    this.entries = [];
+  }
+
+  rel(p) {
+    return path.relative(this.target, p).split(path.sep).join('/');
+  }
+
+  // Place src en dest : lien relatif (repli en copie), sans jamais écraser.
+  place(src, dest) {
+    if (!fs.existsSync(src)) return;
+    if (exists(dest)) {
+      warn(`${this.rel(dest)} existe déjà et n'est pas géré par KAgents : conservé`);
+      return;
+    }
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    let linked = false;
+    if (!this.copy) {
+      try {
+        const type = fs.statSync(src).isDirectory() ? 'dir' : 'file';
+        fs.symlinkSync(path.relative(path.dirname(dest), src), dest, type);
+        linked = true;
+      } catch {
+        /* pas de droits de lien (Windows) : copie */
+      }
+    }
+    if (!linked) fs.cpSync(src, dest, { recursive: true });
+    this.entries.push(this.rel(dest));
+  }
+
+  cleanup() {
+    if (!fs.existsSync(this.manifest)) return [];
+    const removed = [];
+    for (const line of fs.readFileSync(this.manifest, 'utf8').split('\n')) {
+      const p = line.trim();
+      if (!p || path.isAbsolute(p) || p.split('/').includes('..')) continue;
+      const full = path.join(this.target, p);
+      if (exists(full)) fs.rmSync(full, { recursive: true, force: true });
+      removed.push(full);
+    }
+    fs.writeFileSync(this.manifest, '');
+    return removed;
+  }
+
+  copyKit() {
+    for (const dir of KIT_DIRS) {
+      for (const f of listFiles(path.join(PKG_ROOT, dir))) {
+        const dest = path.join(this.kagents, path.relative(PKG_ROOT, f));
+        if (exists(dest)) {
+          warn(`${this.rel(dest)} existe déjà et n'est pas géré par KAgents : conservé`);
+          continue;
+        }
+        fs.mkdirSync(path.dirname(dest), { recursive: true });
+        fs.copyFileSync(f, dest);
+        this.entries.push(this.rel(dest));
+      }
+    }
+    const v = path.join(this.kagents, 'VERSION');
+    fs.writeFileSync(v, PKG.version + '\n');
+    this.entries.push(this.rel(v));
+  }
+
+  createDocs() {
+    fs.mkdirSync(path.join(this.kagents, 'docs', 'knowledge'), { recursive: true });
+    for (const f of listDir(path.join(this.kagents, 'agents'))) {
+      if (!f.endsWith('.md')) continue;
+      const docs = frontmatter(path.join(this.kagents, 'agents', f)).docs;
+      if (docs) fs.mkdirSync(path.join(this.kagents, 'docs', docs), { recursive: true });
+    }
+    const ctx = path.join(this.kagents, 'docs', 'knowledge', 'context.md');
+    if (!fs.existsSync(ctx)) {
+      fs.writeFileSync(
+        ctx,
+        `# Contexte projet
+
+Document partagé, écrit par l'utilisateur. Les agents le lisent, ne l'écrivent pas.
+
+## Intention
+
+- Ce que le système doit faire, pour qui :
+
+## Stack
+
+-
+
+## Contraintes
+
+-
+
+## Références
+
+-
+`,
+      );
+    }
+  }
+
+  renderBlock() {
+    const agentsDir = path.join(this.kagents, 'agents');
+    const cmdDir = path.join(this.kagents, 'commands');
+    const agentRows = [];
+    const names = {};
+    for (const f of listDir(agentsDir).filter((n) => n.endsWith('.md'))) {
+      const fm = frontmatter(path.join(agentsDir, f));
+      const stem = f.replace(/\.md$/, '');
+      names[stem] = fm.name || stem;
+      const desc = (fm.description || '').split('. ')[0] || '—';
+      agentRows.push(`| ${names[stem]} | \`.kagents/agents/${f}\` | ${desc} |`);
+    }
+    const routeRows = [];
+    for (const f of listDir(cmdDir).filter((n) => n.endsWith('.md'))) {
+      const fm = frontmatter(path.join(cmdDir, f));
+      const agent = names[fm.agent] || fm.agent || '—';
+      routeRows.push(
+        `| ${fm.triggers || fm.description || '—'} | \`/${f.replace(/\.md$/, '')}\` | ${agent} | ${fm.mode || '—'} |`,
+      );
+    }
+    return [
+      '<!-- kagents:start -->',
+      '## KAgents',
+      '',
+      `Kit d'agents IA installé dans \`.kagents/\` (v${PKG.version}). Ce bloc est régénéré par \`kagents\` : ne pas l'éditer.`,
+      '',
+      "**Utilisation** : lance une commande (ex. `/base-audit`). Sans commandes dans ton outil, lis le fichier indiqué dans `.kagents/commands/` et applique-le. Contexte partagé : `.kagents/docs/knowledge/context.md`. Chaque agent n'écrit que dans son espace `.kagents/docs/<agent>-docs/`.",
+      '',
+      '### Agents',
+      '',
+      '| Agent | Fichier | Rôle |',
+      '|---|---|---|',
+      ...agentRows,
+      '',
+      '### Routage',
+      '',
+      '| Demande | Commande | Agent | Mode |',
+      '|---|---|---|---|',
+      ...routeRows,
+      '<!-- kagents:end -->',
+    ].join('\n');
+  }
+
+  writeAgentsMd() {
+    const file = path.join(this.target, 'AGENTS.md');
+    const block = this.renderBlock();
+    let out;
+    if (fs.existsSync(file)) {
+      const cur = fs.readFileSync(file, 'utf8');
+      out = BLOCK_RE.test(cur) ? cur.replace(BLOCK_RE, () => block) : cur.replace(/\n*$/, '\n\n') + block + '\n';
+    } else {
+      out = block + '\n';
+    }
+    fs.writeFileSync(file, out);
+  }
+
+  resolveTools(tools) {
+    if (tools !== 'auto') return tools.split(',').filter(Boolean);
+    const t = ['agents'];
+    const has = (p) => fs.existsSync(path.join(this.target, p));
+    if (has('.claude') || has('CLAUDE.md')) t.push('claude');
+    if (has('.cursor')) t.push('cursor');
+    return t;
+  }
+
+  runAdapters(tools) {
+    for (const tool of this.resolveTools(tools)) {
+      if (!ADAPTERS[tool]) {
+        warn(`outil inconnu : ${tool} (disponibles : ${Object.keys(ADAPTERS).join(', ')})`);
+        continue;
+      }
+      for (const [from, to, kind] of ADAPTERS[tool]) {
+        const srcDir = path.join(this.kagents, from);
+        for (const name of listDir(srcDir)) {
+          const src = path.join(srcDir, name);
+          if (SKIP.has(name)) continue;
+          const isDir = fs.statSync(src).isDirectory();
+          if (kind === 'dirs' && !isDir) continue;
+          if (kind !== 'dirs' && isDir) continue;
+          if (kind === 'agents') {
+            if (!name.endsWith('.md')) continue;
+            if (!frontmatter(src).name) {
+              warn(`agent ${name} sans frontmatter 'name:' : non exposé à l'outil`);
+              continue;
+            }
+          }
+          this.place(src, path.join(this.target, to, name));
+        }
+      }
+      log(`${tool} : branché`);
+    }
+  }
+
+  saveManifest() {
+    fs.mkdirSync(this.kagents, { recursive: true });
+    fs.writeFileSync(this.manifest, this.entries.join('\n') + '\n');
+  }
+
+  // Supprime les dossiers vides laissés par la désinstallation (jamais .claude/.cursor eux-mêmes).
+  prune(removed) {
+    const keep = new Set([this.target, path.join(this.target, '.claude'), path.join(this.target, '.cursor')]);
+    for (const p of removed) {
+      for (let d = path.dirname(p); d.startsWith(this.target) && !keep.has(d); d = path.dirname(d)) {
+        if (!fs.existsSync(d) || fs.readdirSync(d).length) break;
+        fs.rmdirSync(d);
+      }
+    }
+  }
+
+  install(tools) {
+    fs.mkdirSync(this.kagents, { recursive: true });
+    this.cleanup();
+    this.copyKit();
+    this.createDocs();
+    this.writeAgentsMd();
+    this.runAdapters(tools);
+    this.saveManifest();
+    log(`installé dans ${this.kagents} (${this.copy ? 'copies' : 'liens'})`);
+  }
+
+  uninstall() {
+    const removed = this.cleanup();
+    const file = path.join(this.target, 'AGENTS.md');
+    if (fs.existsSync(file)) {
+      const cur = fs.readFileSync(file, 'utf8');
+      if (BLOCK_RE.test(cur)) {
+        const out = cur.replace(BLOCK_RE, '').replace(/\n{3,}/g, '\n\n').replace(/\s+$/, '');
+        if (out) fs.writeFileSync(file, out + '\n');
+        else fs.rmSync(file);
+      }
+    }
+    fs.rmSync(this.manifest, { force: true });
+    this.prune(removed);
+    log('désinstallé (.kagents/docs/ conservé : ce sont vos livrables)');
+  }
+}
+
+// --- Main ---------------------------------------------------------------------
+function main() {
+  const o = parseArgs(process.argv.slice(2));
+  if (o.cmd === 'help') return console.log(HELP);
+  if (o.cmd === 'version') return console.log(PKG.version);
+  const target = process.cwd();
+  if (path.resolve(target) === PKG_ROOT) die("à lancer depuis la racine d'un projet, pas depuis le kit.");
+  const inst = new Installer(target, o.copy);
+  if (o.cmd === 'uninstall') inst.uninstall();
+  else inst.install(o.tools);
+}
+
+main();

package/checklists/catalyst-change.md

@@ -0,0 +1,10 @@
+# Checklist — Changement Catalyst
+
+- [ ] Data Store / ZCQL : requetes necessaires et bornees
+- [ ] Functions : decoupage et frequence d'appel raisonnables
+- [ ] Cache : usage justifie, invalidation claire
+- [ ] APIs : pas de transferts inutiles
+- [ ] Evenements / polling : pas de boucle active inutile
+- [ ] Auth : flux conforme au standard projet
+
+Reference future : `standards/catalyst/`

package/checklists/review.md

@@ -0,0 +1,26 @@
+# Checklist — Revue
+
+## General
+
+- [ ] Coherent avec `STATE.md` et ADR
+- [ ] Change Brief respecte si L2+
+- [ ] Tests adequats
+
+## Architecture
+
+- [ ] Pas de decision archi non documentee
+
+## Donnees
+
+- [ ] Source de verite unique ou exception documentee
+- [ ] Migrations reversibles ou plan de rollback
+
+## Securite
+
+- [ ] Pas de secret en clair
+- [ ] Permissions justifiees
+
+## Performance et cout
+
+- [ ] Pas de N+1 / requetes repetees evidentes
+- [ ] Catalyst : voir `catalyst-change.md` si applicable

package/commands/arch-audit.md

@@ -0,0 +1,10 @@
+---
+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

@@ -0,0 +1,10 @@
+---
+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

@@ -0,0 +1,10 @@
+---
+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/commands/base-audit.md

@@ -0,0 +1,10 @@
+---
+description: Base — audit de la base de données
+agent: database_expert
+mode: B (Audit)
+triggers: audite ma base, analyse ma base de données, vérifie mon schéma
+---
+Lis `.kagents/agents/database_expert.md` et applique-le en **mode B (Audit)**.
+Charge ensuite uniquement les skills que ce mode indique, depuis `.kagents/skills/`.
+
+Demande de l'utilisateur : $ARGUMENTS

package/commands/base-design.md

@@ -0,0 +1,10 @@
+---
+description: Base — conception du modèle de données
+agent: database_expert
+mode: A (Conception)
+triggers: conçois ma base, modèle de données d'un nouveau projet
+---
+Lis `.kagents/agents/database_expert.md` et applique-le en **mode A (Conception)**.
+Charge ensuite uniquement les skills que ce mode indique, depuis `.kagents/skills/`.
+
+Demande de l'utilisateur : $ARGUMENTS

package/commands/base-evolve.md

@@ -0,0 +1,10 @@
+---
+description: Base — analyse d'impact d'une fonctionnalité sur la base
+agent: database_expert
+mode: C (Évolution)
+triggers: impact d'une fonctionnalité sur la base, je dois ajouter/modifier une table
+---
+Lis `.kagents/agents/database_expert.md` et applique-le en **mode C (Évolution)**.
+Charge ensuite uniquement les skills que ce mode indique, depuis `.kagents/skills/`.
+
+Demande de l'utilisateur : $ARGUMENTS

package/governance/actions.yaml

@@ -0,0 +1,36 @@
+# Matrice de gouvernance — Engineering Harness
+# Niveaux : automatic | propose | human_required | forbidden
+
+categories:
+  automatic:
+    description: L'agent peut executer sans validation prealable.
+    examples:
+      - Lire le code et la documentation du repo
+      - Executer les scripts de validation du harness (scripts/)
+      - Corriger typos dans docs/harness sans changement de gouvernance
+      - Ajouter ou ajuster rules/skills/workflows dans ce repo apres validation humaine du PR
+
+  propose:
+    description: L'agent prepare le changement ; merge ou application apres revue humaine.
+    examples:
+      - Nouvelle rule ou skill
+      - Modification de standards/
+      - Refactoring structurel du harness
+      - Change Brief ou ADR draft (dans le repo projet)
+
+  human_required:
+    description: Validation humaine explicite avant execution ou deploiement.
+    examples:
+      - Decision d'architecture (ADR acceptee)
+      - Schema BDD significatif ou migration destructive
+      - Permissions, securite, donnees sensibles
+      - Production, suppression de donnees
+      - Release semver du harness (tag VERSION)
+
+  forbidden:
+    description: Interdit pour tout agent en conditions normales.
+    examples:
+      - Acces direct a la production ou secrets live
+      - push --force sur main
+      - Contourner hooks ou CI
+      - Centraliser STATE/schema d'un projet client dans ce repo

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@dev-kosaly/kagents",
+  "version": "0.1.0",
+  "description": "Kit d'agents IA d'ingénierie installable dans un projet (Claude Code, Cursor, AGENTS.md)",
+  "bin": {
+    "kagents": "bin/kagents.js"
+  },
+  "files": [
+    "bin",
+    "agents",
+    "skills",
+    "commands",
+    "templates",
+    "checklists",
+    "workflows",
+    "governance"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": ["ai", "agents", "claude-code", "cursor", "agents-md", "database"],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/ScaleTaBoite/kosaly-dev-ai-agents.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node scripts/smoke-test.js",
+    "prepublishOnly": "npm test"
+  },
+  "license": "SEE LICENSE IN LICENSE"
+}

package/skills/README.md

@@ -0,0 +1,31 @@
+# Skills
+
+Une procedure = un dossier avec `SKILL.md` (frontmatter `name`, `description`).
+
+## Architect / Spec (implementees)
+
+| 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 |
+
+Role canonique : `agents/architect.md`.
+
+## Base / base de donnees (implementees)
+
+| Skill | Role |
+|-------|------|
+| `schema-exploration/` | Explorer le repo et reconstruire le modele |
+| `catalyst-export/` | Exploiter l'export JSON Catalyst |
+| `db-analysis/` | Grille d'analyse et severites |
+| `db-docs/` | Modeles 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/architecture-impact/SKILL.md

@@ -0,0 +1,68 @@
+---
+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

@@ -0,0 +1,53 @@
+---
+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).