{
  "markdown": "# zav-sandbox — Système d'agents virtuels mono-session\n\n[![Version](https://img.shields.io/github/v/release/zavrocKk/zav-sandbox)](https://github.com/zavrocKk/zav-sandbox/releases)\n\nUn orchestrateur unique (custom chat mode VS Code) qui simule une **équipe d'experts virtuels** — DevOps, Developer, QA, Security, Architect, Product Analyst, Data Engineer, Scribe — au sein d'**une seule conversation**.\n\n## Philosophie : mono-session par défaut, sous-agents réels sur demande\n\nL'idée : conserver le **bénéfice cognitif** de la multiplicité des perspectives (chaque persona apporte son angle) sans la complexité opérationnelle du multi-agent.\n\n- **Sessions très courtes (1-2 personas)** : impersonation inline — un seul orchestrateur, une seule conversation, zéro infrastructure supplémentaire.\n- **Sessions multi-personas (3+, mode par défaut)** : Party mode (sous-agents) — chaque persona est invoqué comme **sous-agent réel** avec une fenêtre de contexte fraîche. Aucune borne supérieure (3, 5, 7… personas, même traitement). Réduction estimée ~50 à 80 % des tokens input selon la taille de la session.\n\n## Modes multi-personas\n\nDeux axes — **format** (Panel / Débat) × **mécanisme** (inline / sous-agents) — sélectionnés automatiquement par l'orchestrateur. Le **Party mode (sous-agents)** — anciennement « Party Real » — est le Panel exécuté en sous-agents (3+ personas) :\n\n| | **Panel inline** (1-2 personas, mode minoritaire) | **Party mode (sous-agents)** (3+ personas — défaut multi-persona, sans borne sup.) | **Débat** (`/debate`) |\n|---|---|---|---|\n| Quand | Problème **fermé**, session très courte | Workflow complet ou multi-angle (≥ 3 personas) | Problème **ouvert** |\n| Travail type | Question rapide à 2 angles, mini-design | Feature, audit, incident, stratégie tests, pipeline | Brainstorming, arbitrage |\n| Mécanique | Impersonation inline, une passe | `runSubagent` + `.party/` handoffs | N rounds inter-persona |\n| Tokens | Borné par construction | ~50-80 % moins que Panel inline équivalent | Volontairement plus élevé |\n| Déclenchement | **Automatique** | **Automatique** (l'orchestrateur décide au PLAN) | `/debate` explicite |\n\nRéférence : [agents/protocols/light-panel.md](agents/protocols/light-panel.md), [agents/protocols/debate.md](agents/protocols/debate.md).\n\n> **L'utilisateur n'a pas à spécifier le mode.** L'orchestrateur choisit Panel ou Party mode (sous-agents) selon le nombre de personas du PLAN, et le déclare explicitement. Seul `/debate` requiert une action de l'utilisateur.\n\n## Structure du dépôt\n\n```\n.\n├── .github/\n│   ├── agents/\n│   │   ├── orchestrator.agent.md        # 🎼 Orchestrateur — custom agent principal\n│   │   ├── devops.agent.md              # 🛠️ Sous-agent DevOps (Party mode sous-agents)\n│   │   ├── developer.agent.md           # 💻 Sous-agent Developer (Party mode sous-agents)\n│   │   ├── security.agent.md            # 🔒 Sous-agent Security (Party mode sous-agents)\n│   │   ├── architect.agent.md           # 🏗️ Sous-agent Architect (Party mode sous-agents)\n│   │   ├── qa.agent.md                  # 🧪 Sous-agent QA (Party mode sous-agents)\n│   │   ├── product-analyst.agent.md     # 📊 Sous-agent Product Analyst (Party mode sous-agents)\n│   │   ├── data-engineer.agent.md       # 🗄️ Sous-agent Data Engineer (Party mode sous-agents)\n│   │   ├── scribe.agent.md              # 📝 Sous-agent Scribe (Party mode sous-agents)\n│   │   └── modules/                     # Modules de délégation de l'orchestrateur\n│   │       ├── core-rules.md            # Périmètre, délégation, contrat PLAN → EXEC\n│   │       ├── memory.md                # Mémoire persistante et checkpoints\n│   │       ├── party-mode.md            # Panel, Débat, Party mode (sous-agents) + flow .party/\n│   │       └── skills.md               # Tableau des skills disponibles\n│   └── copilot-instructions.md          # Instructions globales (français, livrables, sécu)\n├── agents/\n│   ├── personas/                        # Pointeurs inverses — source : .github/agents/*.agent.md\n│   │   ├── orchestrator.md              # 🎼 Meta-agent\n│   │   ├── devops.md                    # 🛠️ Infra, CI/CD, monitoring\n│   │   ├── developer.md                 # 💻 Code, tests, debug\n│   │   ├── qa.md                        # 🧪 Stratégie tests, edge cases, couverture\n│   │   ├── security.md                  # 🔒 OWASP, secrets, threat modeling\n│   │   ├── architect.md                 # 🏗️ Patterns, ADR, diagrammes\n│   │   ├── product-analyst.md           # 📊 User stories, critères d'acceptation, métriques\n│   │   ├── data-engineer.md             # 🗄️ Schémas, pipelines, ETL/ELT, qualité data\n│   │   └── scribe.md                    # 📝 Synthèse, doc, post-mortems\n│   ├── workflows/\n│   │   ├── incident-response.md         # Panne / alerte production\n│   │   ├── code-analysis.md             # Audit / review d'un module\n│   │   ├── bilan-remediation.md         # Bilan d'analyse → remise dev → vérification fix\n│   │   ├── feature-development.md       # Nouvelle fonctionnalité\n│   │   ├── architecture-design.md       # Choix techno, refonte\n│   │   ├── data-pipeline.md             # ETL, migration, modélisation BI\n│   │   └── onboarding.md                # 👋 Guide 5 minutes — premier démarrage\n│   ├── templates/\n│   │   ├── incident-report.md           # Post-mortem blameless\n│   │   ├── adr.md                       # Architecture Decision Record (Nygard)\n│   │   ├── memory-checkpoint.md         # Checkpoint de mémoire inter-sessions\n│   │   ├── prd.md                       # Product Requirements Document léger\n│   │   ├── bilan.md                     # Bilan d'analyse destiné à un développeur\n│   │   ├── party-context.md             # Template context.md pour Party mode (sous-agents)\n│   │   └── party-handoff.md             # Template handoff-{agent}.md pour Party mode (sous-agents)\n│   ├── skills/                          # Skills techniques invocables (format Agent Skills)\n│   │   ├── root-cause-analysis/SKILL.md # 🔍 RCA : 5 Pourquoi / Ishikawa\n│   │   ├── party-mode/SKILL.md          # 🎉 Index modes multi-personas + anti-patterns (v2.0.0)\n│   │   ├── observability-triage/        # 📡 Évidence Splunk/Datadog/AWS (CloudWatch, Batch, FinOps, session SSO)/K8s-EKS\n│   │   ├── jira-issue/SKILL.md          # 🎫 Billet bug/defect prêt à coller (format Atlassian)\n│   │   ├── snow-change/SKILL.md         # 📋 Change request ITIL/ServiceNow (backout obligatoire)\n│   │   └── confluence-doc/SKILL.md      # 📚 Page Confluence par intention + fraîcheur\n│   └── hooks/                           # Agent hooks VS Code (opt-in, OFF par défaut)\n│       ├── security-guard.ps1/.sh       # PreToolUse : confirmation sur commandes destructives\n│       ├── secrets-scanner.ps1/.sh      # Stop : scan de secrets fin de session (warn-only)\n│       ├── agent-telemetry.ps1/.sh      # PostToolUse/Subagent* : journal JSONL passif\n│       ├── memory-nudge.ps1/.sh         # PreCompact/Stop : rappel /checkpoint + journal test terrain\n│       └── hooks.json                   # Config (activation manuelle via settings)\n├── docs/                                # Tous les livrables produits par le Scribe\n│   ├── incidents/                       # Post-mortems (rapports d'incident)\n│   ├── architecture/                    # Notes d'archi, cadrages de phase (évolutifs)\n│   ├── decisions/                       # ADRs (NNNN-slug.md) — décisions fermées\n│   ├── apps/                            # Bundle OKF — fiches d'applications (index.md + log.md)\n│   └── _scratch/                        # Temporaire : bilans, plans, handoffs\n│       ├── memory/                      # Checkpoints de reprise inter-sessions\n│       ├── mvp-inputs/                  # Fixtures synthétiques de test (versionnées)\n│       └── telemetry/                   # Télémétrie runtime (git-ignorée)\n├── .env.example                         # Gabarit jetons JIRA/Confluence/Control-M → copier vers .env (git-ignoré)\n└── README.md\n```\n\n> **Note `.party/`** : lors d'une session Party mode (sous-agents), l'orchestrateur crée un dossier `.party/` transitoire à la racine (gitignore-d) pour les échanges inter-agents (`context.md` + `handoff-{agent}.md`). Ce dossier est **supprimé à la clôture** de chaque session.\n>\n> Chaque handoff est **borné** (cible ≤ 500 tokens, plafond 1000 — pointeur vers les fichiers du repo plutôt que recopie) et **validé par un gate** (structure, budget, critères « Done quand » du persona) avant d'invoquer l'agent suivant. Le PLAN déclare aussi le **régime** de lecture des handoffs : **convergent** (construction séquentielle, défaut) ou **divergent** (diagnostic/RCA — chaque agent ne lit que `context.md`, indépendance des angles). Détails : [`.github/agents/modules/party-mode.md`](.github/agents/modules/party-mode.md).\n## Activer l'agent Orchestrator dans VS Code\n\n> **Nouveau ?** Commence par le guide 5 minutes : [`agents/workflows/onboarding.md`](agents/workflows/onboarding.md).\n\n1. Ouvre le workspace `zav-sandbox` dans VS Code (avec l'extension **GitHub Copilot Chat**).\n2. Ouvre la vue **Chat** (raccourci : `Ctrl+Alt+I` sur Windows/Linux, `⌃⌘I` sur macOS).\n3. En haut de la vue Chat, ouvre le **dropdown des agents** (à côté du champ de saisie, là où il est écrit « Ask », « Edit » ou « Agent » par défaut).\n4. Sélectionne l'**agent Orchestrator** dans le dropdown (Configure Custom Agents). VS Code détecte automatiquement les `.agent.md` sous `.github/agents/`.\n5. (Optionnel) Vérifie via la palette de commandes (`Ctrl+Shift+P`) → `Chat: Configure Custom Agents` que `orchestrator` est bien listé.\n\n> Si `orchestrator` n'apparaît pas : recharge la fenêtre (`Developer: Reload Window`), vérifie que le fichier est bien à `.github/agents/orchestrator.agent.md` et que son frontmatter YAML est valide.\n\n## Test rapide — 2 minutes\n\n1. Active l'agent Orchestrator (voir ci-dessus).\n2. Envoie ce prompt minimal :\n\n   ```\n   Mon API /checkout renvoie du 502 depuis 10 min. /quick\n   ```\n\n3. **Résultat attendu** : l'orchestrateur produit un PLAN incident (persona DevOps en tête), enchaîne les personas avec leurs en-têtes `─── emoji nom — titre ───`, et le Scribe ferme avec un post-mortem dans `docs/incidents/`.\n\nSi ce cycle s'exécute correctement, le framework est opérationnel.\n\n## Commandes disponibles\n\n| Commande | Effet |\n|---|---|\n| `/quick` | Saute la confirmation PLAN (étape CONFIRM) — exécution directe |\n| `/light` | Mode format allégé (en-têtes compacts, tables réserrées) — les règles restent actives |\n| `/debate` | Bascule en mode Débat (N rounds, défaut 3) |\n| `/debate max=N` | Débat avec N rounds maximum (ex. `/debate max=5`) |\n| `/checkpoint` | Le Scribe crée un checkpoint de mémoire dans `docs/_scratch/memory/` |\n| `/pre-pr` | Lance les garde-fous pré-PR (qualité, sécurité, conventions) |\n| `/reset` | Recalibration LLM — voir ci-dessous |\n\n> **Mode playbook (automatique)** : sur un type de demande **connu du mapping** (incident, audit, stratégie de tests…) sans action destructive au plan, l'orchestrateur applique `/quick` de lui-même et le déclare dans le PLAN (`Mode playbook — exécution directe`). Tu n'as rien à taper ; pour forcer une confirmation, dis simplement « confirme d'abord ».\n\n## Recalibration LLM drift (`/reset`)\n\nAprès une longue session ou plusieurs échanges, le modèle peut dériver (oublier des règles, mélanger les rôles, produire de la prose au lieu d'un plan). Utilise `/reset` pour forcer une recalibration :\n\n```\n/reset\n```\n\nL'orchestrateur relèse les 4 invariants du PRE-FLIGHT, réaffiche les règles binaires (délégation, ordre ANALYSE→PLAN→CONFIRM→EXECUTE→SYNTHESIS, Scribe en dernier) et redémarre le cycle sur la demande courante.\n\n**Signaux de dérive** à surveiller : réponse technique sans plan, Scribe absent, personas mélangés, oubli des en-têtes `───`. Si tu détectes l'un de ces signaux, envoie `/reset` avant de continuer.\n\n**Demande utilisateur :**\n> « L'API `/checkout` renvoie du 502 depuis 10 minutes, le dashboard montre une explosion de la latence. Help. »\n\n**Réponse de l'orchestrateur :**\n\n```\n## 🎼 Analyse\nIncident production — API checkout, 502 + latence anormale, depuis ~10 min. Workflow : incident-response.\n\n## 🎼 Plan\n| # | Persona      | Tâche                                          | Livrable                              |\n|---|--------------|------------------------------------------------|---------------------------------------|\n| 1 | 🛠️ DevOps    | Triage : sévérité, périmètre, changements récents | Observation + hypothèses             |\n| 2 | 🛠️ DevOps    | Mitigation candidate (rollback ?)              | Plan d'action — confirmation requise  |\n| 3 | 💻 Developer | Si cause applicative : analyse code + patch    | Diff + tests                          |\n| 4 | 🏗️ Architect | Durcissement (circuit breaker ? timeout ?)     | Reco + ADR si structurant             |\n| 5 | 📝 Scribe    | Post-mortem blameless                          | docs/incidents/2026-05-02-checkout-502.md |\n\nConfirmes-tu ce plan ? (oui / ajuste / `/quick`)\n```\n\n→ Après confirmation utilisateur, l'orchestrateur enchaîne les personas avec leurs en-têtes visuels, puis le **Scribe ferme** avec bilan + livrable créé dans `docs/incidents/`.\n## Exemple rapide — Cadrage d'une feature\n\n**Demande utilisateur :**\n> « Je veux ajouter un système de notifications push pour les utilisateurs mobile. »\n\n**Réponse de l'orchestrateur :**\n\n```\n## 🎼 Analyse\nNouvelle feature. Besoin à cadrer avant tout design. Workflow : feature-development.\n\n## 🎼 Plan\n| # | Persona            | Tâche                                               | Livrable                                  |\n|---|--------------------|-----------------------------------------------------|-------------------------------------------|\n| 1 | 📊 Product Analyst  | Problème, segments, user stories, critères accept.  | PRD léger                                 |\n| 2 | 🏗️ Architect       | Options d'implémentation (FCM, SSE, WebPush...)      | Reco + diagramme séquence                 |\n| 3 | 🔒 Security        | Threat model : tokens de device, opt-in, permissions | Contrôles à intégrer                       |\n| 4 | 💻 Developer        | Implémentation + tests unitaires                    | Diff + tests                              |\n| 5 | 🧪 QA             | Matrix de tests : permission rejetée, token expiré  | Gaps + tests E2E                          |\n| 6 | 🛠️ DevOps          | Config infra push service, alertes taux délivraison  | IaC + pipeline                            |\n| 7 | 📝 Scribe          | PRD final + ADR si décision structurante              | docs/2026-05-02-feature-push-notifs.md    |\n\nConfirmes-tu ce plan ? (oui / ajuste / `/quick`)\n```\n## Architecture — le cycle d'une session\n\nCe que le diagramme montre : le **flux réel entre agents** — boucles de gate,\nmémoire, approbation humaine — pas l'arborescence des dossiers (elle est plus haut).\n\n```mermaid\nflowchart TD\n    U[👤 Demande] --> O[\"🎼 Orchestrateur<br/>ANALYSE → PLAN<br/>(workflow + personas + fenêtre confirmée)\"]\n    O -.->|\"app nommée ?\"| IDX[(\"docs/apps/index.md<br/>max 2 fiches pointées\")]\n    IDX -.-> CTX\n    O -->|\"1-2 personas\"| INL[\"Panel inline<br/>(même cycle, sans .party/)\"]\n    O -->|\"3+ personas — auto\"| CTX[\".party/context.md<br/>objectif + régime + mémoire\"]\n    CTX --> P[\"Persona du PLAN<br/>fenêtre fraîche + skills à la demande\"]\n    P -->|\"handoff ≤ 500 tokens\"| G{\"Gate binaire<br/>4 sections + budget +<br/>preuves falsifiables + Done quand\"}\n    G -->|\"non conforme — 1 re-essai\"| P\n    G -->|conforme| Q{\"Personas<br/>restants ?\"}\n    Q -->|oui| P\n    Q -->|non| SC[\"📝 Scribe — SYNTHESIS<br/>lit tous les handoffs, consolide les Δ-mémoire\"]\n    INL --> SC\n    SC --> LIV[\"Livrable : post-mortem / bilan / ADR<br/>+ ticket collable (skills jira-issue, snow-change, confluence-doc)\"]\n    LIV --> H{\"👤 Approbation<br/>humaine\"}\n    H -->|amende| P\n    H -->|approuvé| DOCS[(\"docs/ — table de localisation<br/>+ fiches apps & log.md si Δ approuvé\")]\n```\n\n> Le détail des phases par type de demande vit dans les\n> [workflows](agents/workflows/) (chacun avec son propre diagramme) ; les règles\n> du cycle dans les [modules](.github/agents/modules/).\n\n## Fonctionnalités optionnelles\n\nLe framework fonctionne sans rien activer. Ces fonctionnalités sont opt-in :\n\n| Fonctionnalité | Description | Activation |\n|---|---|---|\n| **Security guard** | Bloque les commandes destructives de l'IA (rm -rf, DROP, force push…) en demandant une confirmation | Voir [`agents/hooks/README.md`](agents/hooks/README.md) |\n| **Secrets scanner** | Scan de fin de session des fichiers modifiés (~25 familles de secrets) — warn-only, fail-open, findings rédigés dans un log local git-ignoré | Voir [`agents/hooks/README.md`](agents/hooks/README.md) |\n| **Agent telemetry** | Journal JSONL passif des événements agent (perf, sous-agents) — métadonnées seulement, jamais le contenu | Voir [`agents/hooks/README.md`](agents/hooks/README.md) |\n| **Memory nudge** | Rappelle de lancer `/checkpoint` avant compaction ou fin de session | Voir [`agents/hooks/README.md`](agents/hooks/README.md) |\n| **Git hook pre-push** | Bloque les push directs sur `main` | `bash scripts/install-hooks.sh` (Windows : `scripts/install-hooks.ps1`) |\n\n## Usage en équipe\n\nLe framework est conçu pour une session 1:1. En équipe, suivre ces conventions\npour éviter les conflits :\n\n| Risque | Convention |\n|---|---|\n| Checkpoints conflictuels | Nommer les checkpoints avec tes initiales : `phase-9-<initiales>.md` |\n| ADRs aux mêmes numéros | Réserver une plage : ex. Zav = 0001–0099, contributeur A = 0100–0199 |\n| ROADMAP.md divergent | Un seul éditeur à la fois, commits fréquents sur `main` |\n| Checkpoints `closed` qui s'accumulent | `/memory-list` + nettoyage trimestriel (politique dans `docs/_scratch/memory/README.md`) |\n\n## Comment ajouter un persona\n\n**Note** : l'orchestrateur supporte 2 modes d'exécution pour les personas :\n- **1-2 personas** : impersonation inline (aucun sous-agent requis)\n- **≥ 3 personas ou workflow complet** : sous-agents réels via Party mode (sous-agents) (subagent requis — mode par défaut du multi-persona)\n\n### Procédure pour un persona qui sera utilisé en Party mode (sous-agents) (recommended)\n\n1. Crée `agents/personas/<nom>.md` avec les sections : `Identité`, `Ton`, `Domaines`, `Quand intervenir`, `Output type`, `Handoffs`, `Anti-patterns`.\n2. **Crée `.github/agents/<nom>.agent.md`** (fichier de sous-agent) en calquant sur un agent existant (ex. `developer.agent.md`). Restreins les `tools` au périmètre du persona.\n3. Ajoute son emoji et sa ligne dans la **table des personas** de l'agent (`.github/agents/orchestrator.agent.md`, section « Personas disponibles »).\n4. Déclare-le dans la **liste des agents disponibles** pour Party mode (sous-agents) (section « Agents disponibles » de [`.github/agents/modules/party-mode.md`](.github/agents/modules/party-mode.md)).\n5. Mets à jour le **mapping `demande → workflow → personas`** de l'agent si ce persona ouvre de nouveaux types de demandes.\n6. Si le persona est utilisé dans un **workflow 3+ personas** (la majorité), mets à jour les **modules** (`.github/agents/modules/party-mode.md`, etc.) si pertinent.\n\n### Procédure pour un persona inline-only (sessions 1-2 personas uniquement — cas rare)\n\n1–5 comme ci-dessus, mais **omets l'étape 2** (pas de subagent). Documente l'exclusion dans les commentaires de `orchestrator.agent.md`.\n\n## Comment ajouter un workflow\n\n1. Crée `agents/workflows/<nom>.md` avec : un **diagramme Mermaid** des phases, une **table persona par étape**, des **règles spécifiques**, des **anti-patterns**, un **livrable final**.\n2. Ajoute une ligne dans le mapping de l'agent reliant un type de demande à ce workflow.\n\n## Comment ajouter un template\n\n1. Crée `agents/templates/<nom>.md` avec une structure prête à remplir (placeholders entre `<…>`).\n2. Référence-le dans le persona Scribe ou dans le workflow concerné.\n\n## Conventions transversales\n\n- Tous les `.md` sont en **français**, le code et les identifiants en **anglais**.\n- Diagrammes : **Mermaid uniquement**.\n- Citations de fichier : `chemin/relatif.ext:ligne`.\n- Aucun secret en clair.\n- Confirmation utilisateur obligatoire pour toute action destructive.\n- Le **Scribe ferme toujours** le cycle.\n\nVoir [.github/copilot-instructions.md](.github/copilot-instructions.md) pour les règles globales détaillées.\n",
  "bytes": 20369,
  "sha": "659e1211f0efe61d239fa4f39448853f1ebf3e6d988be7a324448ab23909a925",
  "repo_slug": "zavrockk/zav-sandbox",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_zavrockk_zav_sandbox_docs_apps_index_md_af63f536/readme"
}