zavrocKk/zav-sandbox · docs/apps
Index des applications connues — une ligne par app. Seul fichier du bundle scanné au PLAN, et seulement si la demande nomme une app ou un al
Open source Repository Open in the app JSON README (API)
About
> **Règle de chargement** (module [`memory.md`](../../.github/agents/modules/memory.md)) :
> cet index est le **seul** fichier scanné au PLAN, et **seulement** si la demande
> nomme une application ou un alias. Corps d'une fiche chargé sur match uniquement —
> **max 2 fiches par session**. Pas de match → rien n'est chargé.
| Identifiant | Description | Tags | Aliases |
|---|---|---|---|
| _(aucune fiche encore — voir « Ajouter une fiche »)_ | | | |
## Registre de types (contrat local du bundle)
| `type` | Champs requis | Champs custom |
|---|---|---|
| `application` | `type`, `title`, `description`, `timestamp` | `aliases`, `verified`, `criticality` |
Une fiche à qui il manque un champ requis est **non conforme** — le Scribe complète
avant de committer.
## Ajouter une fiche
1. Copier [`agents/templates/app-card.md`](../../agents/templates/app-card.md) vers `docs/apps/<slug>.md` (le chemin est l'identité OKF).
2. Remplir le front-matter (aliases : noms de services, codes JIRA, sur
Details
- Kind
- OKF bundles
- Topic
- Developer tools
- Publisher
- zavrockk
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 1
- Open pull requests
- 1
- Last push
- 2026-07-14T23:44:42Z
- Repository state
- ativo
- Language
- PowerShell
- Added
- 2026-09-08 22:13:12
- Updated
- 2026-09-08 22:13:12
- Origin id
zavrocKk/zav-sandbox:docs/apps/index.md
README
# zav-sandbox — Système d'agents virtuels mono-session
[](https://github.com/zavrocKk/zav-sandbox/releases)
Un 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**.
## Philosophie : mono-session par défaut, sous-agents réels sur demande
L'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.
- **Sessions très courtes (1-2 personas)** : impersonation inline — un seul orchestrateur, une seule conversation, zéro infrastructure supplémentaire.
- **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.
## Modes multi-personas
Deux 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) :
| | **Panel inline** (1-2 personas, mode minoritaire) | **Party mode (sous-agents)** (3+ personas — défaut multi-persona, sans borne sup.) | **Débat** (`/debate`) |
|---|---|---|---|
| Quand | Problème **fermé**, session très courte | Workflow complet ou multi-angle (≥ 3 personas) | Problème **ouvert** |
| Travail type | Question rapide à 2 angles, mini-design | Feature, audit, incident, stratégie tests, pipeline | Brainstorming, arbitrage |
| Mécanique | Impersonation inline, une passe | `runSubagent` + `.party/` handoffs | N rounds inter-persona |
| Tokens | Borné par construction | ~50-80 % moins que Panel inline équivalent | Volontairement plus élevé |
| Déclenchement | **Automatique** | **Automatique** (l'orchestrateur décide au PLAN) | `/debate` explicite |
Référence : [agents/protocols/light-panel.md](agents/protocols/light-panel.md), [agents/protocols/debate.md](agents/protocols/debate.md).
> **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.
## Structure du dépôt
```
.
├── .github/
│ ├── agents/
│ │ ├── orchestrator.agent.md # 🎼 Orchestrateur — custom agent principal
│ │ ├── devops.agent.md # 🛠️ Sous-agent DevOps (Party mode sous-agents)
│ │ ├── developer.agent.md # 💻 Sous-agent Developer (Party mode sous-agents)
│ │ ├── security.agent.md # 🔒 Sous-agent Security (Party mode sous-agents)
│ │ ├── architect.agent.md # 🏗️ Sous-agent Architect (Party mode sous-agents)
│ │ ├── qa.agent.md # 🧪 Sous-agent QA (Party mode sous-agents)
│ │ ├── product-analyst.agent.md # 📊 Sous-agent Product Analyst (Party mode sous-agents)
│ │ ├── data-engineer.agent.md # 🗄️ Sous-agent Data Engineer (Party mode sous-agents)
│ │ ├── scribe.agent.md # 📝 Sous-agent Scribe (Party mode sous-agents)
│ │ └── modules/ # Modules de délégation de l'orchestrateur
│ │ ├── core-rules.md # Périmètre, délégation, contrat PLAN → EXEC
│ │ ├── memory.md # Mémoire persistante et checkpoints
│ │ ├── party-mode.md # Panel, Débat, Party mode (sous-agents) + flow .party/
│ │ └── skills.md # Tableau des skills disponibles
│ └── copilot-instructions.md # Instructions globales (français, livrables, sécu)
├── agents/
│ ├── personas/ # Pointeurs inverses — source : .github/agents/*.agent.md
│ │ ├── orchestrator.md # 🎼 Meta-agent
│ │ ├── devops.md # 🛠️ Infra, CI/CD, monitoring
│ │ ├── developer.md # 💻 Code, tests, debug
│ │ ├── qa.md # 🧪 Stratégie tests, edge cases, couverture
│ │ ├── security.md # 🔒 OWASP, secrets, threat modeling
│ │ ├── architect.md # 🏗️ Patterns, ADR, diagrammes
│ │ ├── product-analyst.md # 📊 User stories, critères d'acceptation, métriques
│ │ ├── data-engineer.md # 🗄️ Schémas, pipelines, ETL/ELT, qualité data
│ │ └── scribe.md # 📝 Synthèse, doc, post-mortems
│ ├── workflows/
│ │ ├── incident-response.md # Panne / alerte production
│ │ ├── code-analysis.md # Audit / review d'un module
│ │ ├── bilan-remediation.md # Bilan d'analyse → remise dev → vérification fix
│ │ ├── feature-development.md # Nouvelle fonctionnalité
│ │ ├── architecture-design.md # Choix techno, refonte
│ │ ├── data-pipeline.md # ETL, migration, modélisation BI
│ │ └── onboarding.md # 👋 Guide 5 minutes — premier démarrage
│ ├── templates/
│ │ ├── incident-report.md # Post-mortem blameless
│ │ ├── adr.md # Architecture Decision Record (Nygard)
│ │ ├── memory-checkpoint.md # Checkpoint de mémoire inter-sessions
│ │ ├── prd.md # Product Requirements Document léger
│ │ ├── bilan.md # Bilan d'analyse destiné à un développeur
│ │ ├── party-context.md # Template context.md pour Party mode (sous-agents)
│ │ └── party-handoff.md # Template handoff-{agent}.md pour Party mode (sous-agents)
│ ├── skills/ # Skills techniques invocables (format Agent Skills)
│ │ ├── root-cause-analysis/SKILL.md # 🔍 RCA : 5 Pourquoi / Ishikawa
│ │ ├── party-mode/SKILL.md # 🎉 Index modes multi-personas + anti-patterns (v2.0.0)
│ │ ├── observability-triage/ # 📡 Évidence Splunk/Datadog/AWS (CloudWatch, Batch, FinOps, session SSO)/K8s-EKS
│ │ ├── jira-issue/SKILL.md # 🎫 Billet bug/defect prêt à coller (format Atlassian)
│ │ ├── snow-change/SKILL.md # 📋 Change request ITIL/ServiceNow (backout obligatoire)
│ │ └── confluence-doc/SKILL.md # 📚 Page Confluence par intention + fraîcheur
│ └── hooks/ # Agent hooks VS Code (opt-in, OFF par défaut)
│ ├── security-guard.ps1/.sh # PreToolUse : confirmation sur commandes destructives
│ ├── secrets-scanner.ps1/.sh # Stop : scan de secrets fin de session (warn-only)
│ ├── agent-telemetry.ps1/.sh # PostToolUse/Subagent* : journal JSONL passif
│ ├── memory-nudge.ps1/.sh # PreCompact/Stop : rappel /checkpoint + journal test terrain
│ └── hooks.json # Config (activation manuelle via settings)
├── docs/ # Tous les livrables produits par le Scribe
│ ├── incidents/ # Post-mortems (rapports d'incident)
│ ├── architecture/ # Notes d'archi, cadrages de phase (évolutifs)
│ ├── decisions/ # ADRs (NNNN-slug.md) — décisions fermées
│ ├── apps/ # Bundle OKF — fiches d'applications (index.md + log.md)
│ └── _scratch/ # Temporaire : bilans, plans, handoffs
│ ├── memory/ # Checkpoints de reprise inter-sessions
│ ├── mvp-inputs/ # Fixtures synthétiques de test (versionnées)
│ └── telemetry/ # Télémétrie runtime (git-ignorée)
├── .env.example # Gabarit jetons JIRA/Confluence/Control-M → copier vers .env (git-ignoré)
└── README.md
```
> **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.
>
> 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).
## Activer l'agent Orchestrator dans VS Code
> **Nouveau ?** Commence par le guide 5 minutes : [`agents/workflows/onboarding.md`](agents/workflows/onboarding.md).
1. Ouvre le workspace `zav-sandbox` dans VS Code (avec l'extension **GitHub Copilot Chat**).
2. Ouvre la vue **Chat** (raccourci : `Ctrl+Alt+I` sur Windows/Linux, `⌃⌘I` sur macOS).
3. 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).
4. Sélectionne l'**agent Orchestrator** dans le dropdown (Configure Custom Agents). VS Code détecte automatiquement les `.agent.md` sous `.github/agents/`.
5. (Optionnel) Vérifie via la palette de commandes (`Ctrl+Shift+P`) → `Chat: Configure Custom Agents` que `orchestrator` est bien listé.
> 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.
## Test rapide — 2 minutes
1. Active l'agent Orchestrator (voir ci-dessus).
2. Envoie ce prompt minimal :
```
Mon API /checkout renvoie du 502 depuis 10 min. /quick
```
3. **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/`.
Si ce cycle s'exécute correctement, le framework est opérationnel.
## Commandes disponibles
| Commande | Effet |
|---|---|
| `/quick` | Saute la confirmation PLAN (étape CONFIRM) — exécution directe |
| `/light` | Mode format allégé (en-têtes compacts, tables réserrées) — les règles restent actives |
| `/debate` | Bascule en mode Débat (N rounds, défaut 3) |
| `/debate max=N` | Débat avec N rounds maximum (ex. `/debate max=5`) |
| `/checkpoint` | Le Scribe crée un checkpoint de mémoire dans `docs/_scratch/memory/` |
| `/pre-pr` | Lance les garde-fous pré-PR (qualité, sécurité, conventions) |
| `/reset` | Recalibration LLM — voir ci-dessous |
> **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 ».
## Recalibration LLM drift (`/reset`)
Aprè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 :
```
/reset
```
L'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.
**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.
**Demande utilisateur :**
> « L'API `/checkout` renvoie du 502 depuis 10 minutes, le dashboard montre une explosion de la latence. Help. »
**Réponse de l'orchestrateur :**
```
## 🎼 Analyse
Incident production — API checkout, 502 + latence anormale, depuis ~10 min. Workflow : incident-response.
## 🎼 Plan
| # | Persona | Tâche | Livrable |
|---|--------------|------------------------------------------------|---------------------------------------|
| 1 | 🛠️ DevOps | Triage : sévérité, périmètre, changements récents | Observation + hypothèses |
| 2 | 🛠️ DevOps | Mitigation candidate (rollback ?) | Plan d'action — confirmation requise |
| 3 | 💻 Developer | Si cause applicative : analyse code + patch | Diff + tests |
| 4 | 🏗️ Architect | Durcissement (circuit breaker ? timeout ?) | Reco + ADR si structurant |
| 5 | 📝 Scribe | Post-mortem blameless | docs/incidents/2026-05-02-checkout-502.md |
Confirmes-tu ce plan ? (oui / ajuste / `/quick`)
```
→ 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/`.
## Exemple rapide — Cadrage d'une feature
**Demande utilisateur :**
> « Je veux ajouter un système de notifications push pour les utilisateurs mobile. »
**Réponse de l'orchestrateur :**
```
## 🎼 Analyse
Nouvelle feature. Besoin à cadrer avant tout design. Workflow : feature-development.
## 🎼 Plan
| # | Persona | Tâche | Livrable |
|---|--------------------|-----------------------------------------------------|-------------------------------------------|
| 1 | 📊 Product Analyst | Problème, segments, user stories, critères accept. | PRD léger |
| 2 | 🏗️ Architect | Options d'implémentation (FCM, SSE, WebPush...) | Reco + diagramme séquence |
| 3 | 🔒 Security | Threat model : tokens de device, opt-in, permissions | Contrôles à intégrer |
| 4 | 💻 Developer | Implémentation + tests unitaires | Diff + tests |
| 5 | 🧪 QA | Matrix de tests : permission rejetée, token expiré | Gaps + tests E2E |
| 6 | 🛠️ DevOps | Config infra push service, alertes taux délivraison | IaC + pipeline |
| 7 | 📝 Scribe | PRD final + ADR si décision structurante | docs/2026-05-02-feature-push-notifs.md |
Confirmes-tu ce plan ? (oui / ajuste / `/quick`)
```
## Architecture — le cycle d'une session
Ce que le diagramme montre : le **flux réel entre agents** — boucles de gate,
mémoire, approbation humaine — pas l'arborescence des dossiers (elle est plus haut).
```mermaid
flowchart TD
U[👤 Demande] --> O["🎼 Orchestrateur<br/>ANALYSE → PLAN<br/>(workflow + personas + fenêtre confirmée)"]
O -.->|"app nommée ?"| IDX[("docs/apps/index.md<br/>max 2 fiches pointées")]
IDX -.-> CTX
O -->|"1-2 personas"| INL["Panel inline<br/>(même cycle, sans .party/)"]
O -->|"3+ personas — auto"| CTX[".party/context.md<br/>objectif + régime + mémoire"]
CTX --> P["Persona du PLAN<br/>fenêtre fraîche + skills à la demande"]
P -->|"handoff ≤ 500 tokens"| G{"Gate binaire<br/>4 sections + budget +<br/>preuves falsifiables + Done quand"}
G -->|"non conforme — 1 re-essai"| P
G -->|conforme| Q{"Personas<br/>restants ?"}
Q -->|oui| P
Q -->|non| SC["📝 Scribe — SYNTHESIS<br/>lit tous les handoffs, consolide les Δ-mémoire"]
INL --> SC
SC --> LIV["Livrable : post-mortem / bilan / ADR<br/>+ ticket collable (skills jira-issue, snow-change, confluence-doc)"]
LIV --> H{"👤 Approbation<br/>humaine"}
H -->|amende| P
H -->|approuvé| DOCS[("docs/ — table de localisation<br/>+ fiches apps & log.md si Δ approuvé")]
```
> Le détail des phases par type de demande vit dans les
> [workflows](agents/workflows/) (chacun avec son propre diagramme) ; les règles
> du cycle dans les [modules](.github/agents/modules/).
## Fonctionnalités optionnelles
Le framework fonctionne sans rien activer. Ces fonctionnalités sont opt-in :
| Fonctionnalité | Description | Activation |
|---|---|---|
| **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) |
| **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) |
| **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) |
| **Memory nudge** | Rappelle de lancer `/checkpoint` avant compaction ou fin de session | Voir [`agents/hooks/README.md`](agents/hooks/README.md) |
| **Git hook pre-push** | Bloque les push directs sur `main` | `bash scripts/install-hooks.sh` (Windows : `scripts/install-hooks.ps1`) |
## Usage en équipe
Le framework est conçu pour une session 1:1. En équipe, suivre ces conventions
pour éviter les conflits :
| Risque | Convention |
|---|---|
| Checkpoints conflictuels | Nommer les checkpoints avec tes initiales : `phase-9-<initiales>.md` |
| ADRs aux mêmes numéros | Réserver une plage : ex. Zav = 0001–0099, contributeur A = 0100–0199 |
| ROADMAP.md divergent | Un seul éditeur à la fois, commits fréquents sur `main` |
| Checkpoints `closed` qui s'accumulent | `/memory-list` + nettoyage trimestriel (politique dans `docs/_scratch/memory/README.md`) |
## Comment ajouter un persona
**Note** : l'orchestrateur supporte 2 modes d'exécution pour les personas :
- **1-2 personas** : impersonation inline (aucun sous-agent requis)
- **≥ 3 personas ou workflow complet** : sous-agents réels via Party mode (sous-agents) (subagent requis — mode par défaut du multi-persona)
### Procédure pour un persona qui sera utilisé en Party mode (sous-agents) (recommended)
1. Crée `agents/personas/<nom>.md` avec les sections : `Identité`, `Ton`, `Domaines`, `Quand intervenir`, `Output type`, `Handoffs`, `Anti-patterns`.
2. **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.
3. Ajoute son emoji et sa ligne dans la **table des personas** de l'agent (`.github/agents/orchestrator.agent.md`, section « Personas disponibles »).
4. 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)).
5. Mets à jour le **mapping `demande → workflow → personas`** de l'agent si ce persona ouvre de nouveaux types de demandes.
6. 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.
### Procédure pour un persona inline-only (sessions 1-2 personas uniquement — cas rare)
1–5 comme ci-dessus, mais **omets l'étape 2** (pas de subagent). Documente l'exclusion dans les commentaires de `orchestrator.agent.md`.
## Comment ajouter un workflow
1. 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**.
2. Ajoute une ligne dans le mapping de l'agent reliant un type de demande à ce workflow.
## Comment ajouter un template
1. Crée `agents/templates/<nom>.md` avec une structure prête à remplir (placeholders entre `<…>`).
2. Référence-le dans le persona Scribe ou dans le workflow concerné.
## Conventions transversales
- Tous les `.md` sont en **français**, le code et les identifiants en **anglais**.
- Diagrammes : **Mermaid uniquement**.
- Citations de fichier : `chemin/relatif.ext:ligne`.
- Aucun secret en clair.
- Confirmation utilisateur obligatoire pour toute action destructive.
- Le **Scribe ferme toujours** le cycle.
Voir [.github/copilot-instructions.md](.github/copilot-instructions.md) pour les règles globales détaillées.