citadel-ai 10.4.0 → 11.0.0

package/GETTING-STARTED.md

@@ -52,12 +52,20 @@ You'll see something like:
 ✅ CITADEL installed! 42 agents ready.
 
   AGENTS.md   Codex rules (lean, phased loading)
+  citadel/
+  ├── STATUS.md
+  ├── CONTEXT.md
+  ├── DECISIONS.md
+  ├── ARCHITECTURE.md
+  ├── TOKENS.md
+  ├── RUNBOOK.md
+  ├── HANDOFF.md
+  └── specs/
   .citadel/
-  ├── agents/  42 full agent personas (reference)
-  ├── teams/   12 team files and delivery pods (loaded per phase by IDE)
-  ├── specs/   PRD, ADR, Security, Data Model, Growth
-  ├── memory/  Session state (gitignored)
-  └── gates/   Gate progress (gitignored)
+  ├── state/   Session state (gitignored)
+  ├── gates/   Gate progress (gitignored)
+  ├── teams/   Delivery pods
+  └── skills/  Rules and specialist skills
 ```
 
 **Step 5: Start chatting**
@@ -89,10 +97,11 @@ Your AI now works like a team of 42 specialists instead of one generalist brain.
 When you describe what you want to build:
 
 1. **The C-Suite asks questions first** — product, architecture, security, data, growth. You answer.
-2. **Then specs get drafted** — PRD, architecture decisions, security requirements. Saved in `.citadel/specs/`.
+2. **Then specs get drafted** — PRD, architecture decisions, security requirements. Saved in `citadel/specs/`.
 3. **Makers build** — specialized agents write code per domain (backend, frontend, mobile, etc.)
 4. **Checkers review** — independent agents validate the work (the builder never reviews their own code)
 5. **Security has veto power** — nothing ships without a security check
+6. **Token budget stays visible** — you can check `citadel/TOKENS.md` or `status` before a session gets too expensive
 
 ## Useful commands (in the chat)
 
@@ -101,9 +110,13 @@ You can say these things to your AI at any time:
 | What you say | What happens |
 |-------------|-------------|
 | "help" or "I'm stuck" | ATLAS explains where you are and what to do next |
-| "status" | Shows which phase you're in and what's left |
+| "status" | Shows phase, gate, and token budget |
+| "estimate login flow" | Estimates context pressure before the next heavy task |
+| "start" | Runs the clarification and planning flow |
 | "build [feature]" | Starts the build with the right maker agents |
+| "fix [bug]" | Runs the hotfix flow with change-impact review |
 | "review" | Runs the checker team on your code |
+| "ship" | Runs release readiness and rollback checks |
 | "@bruce security check" | Asks the CISO to audit security |
 | Any description of what you want | ATLAS routes to the right expert |
 
@@ -120,7 +133,7 @@ If your IDE reads project files for context (most AI IDEs do), yes. CITADEL crea
 Yes. Run `npx citadel-ai init` in your project folder. It won't modify your existing code — it only adds CITADEL files.
 
 **What if I want to remove CITADEL?**
-Delete the `.citadel/` folder and the rule files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules). Your project code is untouched.
+Delete the `citadel/` and `.citadel/` folders plus the rule files (AGENTS.md, CLAUDE.md, GEMINI.md, .cursorrules, .windsurfrules). Your project code is untouched.
 
 **Is this free?**
 Yes. MIT license. Free forever.

package/README.fr.md

@@ -1,236 +1,145 @@
-# 🏰 CITADEL
+# CITADEL
 
-**Tu vibecodes. Ta démo marche. Mais est-ce que ton projet repose sur du sable ?**
+Construis avec l'IA sans finir avec une app fragile.
 
-CITADEL aide les vibe coders sérieux à construire avec de la structure, de la mémoire et de la review — pour que leur MVP ne s'effondre pas sous les erreurs cachées.
+CITADEL est une couche de gouvernance légère pour les outils de code assistés par IA. Il aide les solo founders, les PMs et les petites équipes à transformer leurs idées en MVPs solides en poussant l'IA à :
+
+- poser les bonnes questions avant de coder
+- garder la mémoire du projet entre les sessions
+- séparer la construction de la review
+- vérifier les risques avant le shipping
+- montrer le budget token avant que le contexte parte en vrille
 
 [![npm version](https://img.shields.io/npm/v/citadel-ai.svg)](https://www.npmjs.com/package/citadel-ai)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
-```bash
-npx citadel-ai init
-```
-
 Fonctionne avec **Codex** · **Claude Code** · **Cursor** · **Antigravity** · **Windsurf**
 
----
-
-## C'est pour toi ?
-
-### CITADEL est fait pour
+## C'est pour qui ?
 
-- Les solo founders qui construisent leur MVP avec l'IA
-- Les opérationnels et PMs qui vibecodent des outils internes
-- Les growth builders qui shippent vite sans équipe dev dédiée
-- Les développeurs non-traditionnels qui veulent des garde-fous, pas du gatekeeping
+CITADEL est fait pour :
 
-### CITADEL n'est PAS fait pour
+- les solo founders qui construisent avec l'IA
+- les PMs qui veulent transformer une idée en outil ou en MVP
+- les petites équipes sans vraie organisation engineering
 
-- Ceux qui cherchent des prompts one-shot
-- Les devs seniors qui ont déjà une discipline d'architecture solide
-- Les équipes qui ont besoin d'une plateforme CI/CD de production
-- Les débutants complets qui n'ont jamais rien construit avec l'IA
+CITADEL n'est pas fait pour :
 
----
+- ceux qui cherchent des prompts one-shot
+- les équipes qui ont déjà un process engineering très solide
+- les besoins enterprise complets dès le départ
 
-## Le problème
+## Pourquoi l'utiliser ?
 
-Quand tu vibecodes sans structure :
+Sans structure, coder avec l'IA est souvent impressionnant au début, puis douloureux quelques semaines plus tard.
 
-- L'IA skip l'architecture — elle génère du code qui marche aujourd'hui et casse demain
-- Personne ne review — le builder valide son propre travail (et rate ses propres erreurs)
-- Le contexte se perd — l'IA oublie ce qui a été décidé 3 messages plus tôt
-- Aucun standard — code spaghetti, magic numbers, business logic partout
-- La sécurité est un afterthought — auth, encryption, compliance arrivent "plus tard" (jamais)
+Problèmes classiques :
 
-Tu te retrouves avec un prototype qui démo bien et qui s'effondre en utilisation réelle.
+- l'IA code avant que le besoin soit clair
+- elle oublie les décisions prises dans les sessions précédentes
+- elle casse des parties qui marchaient déjà
+- personne ne review le travail indépendamment
+- le projet devient difficile à faire évoluer
 
----
+CITADEL ajoute du process autour de ton IA pour que tu puisses aller vite sans construire une house of cards.
 
 ## Ce que CITADEL fait
 
-CITADEL installe une couche de gouvernance dans ton IDE IA. Il ne remplace pas ton IA — il la fait travailler comme une équipe disciplinée au lieu d'un improvisateur solo.
-
-**Force la réflexion stratégique d'abord.** Avant tout code, un C-Suite virtuel pose des questions sur ton produit, ton architecture, la sécurité, les données et la croissance. Tu réponds. Ensuite les specs sont rédigées. Pas l'inverse.
-
-**Sépare la construction de la review.** L'agent qui écrit le code n'est jamais celui qui le review. Comme dans toute organisation d'ingénierie sérieuse.
-
-**Impose des checks de sécurité avant le shipping.** 5 gates obligatoires de l'inception au déploiement. La sécurité a un droit de veto — sans exception.
-
-**Garde la mémoire du projet entre les sessions.** Décisions, erreurs, choix d'architecture — tout est persisté localement. L'IA ne repart pas de zéro à chaque fois.
-
-**Charge uniquement ce qui est nécessaire.** Au lieu de charger les 42 profils d'agents en contexte (et de cramer ton quota de tokens), CITADEL ne charge que l'équipe pertinente pour la phase en cours. 88% de tokens en moins.
-
----
+Après l'installation, ton IA va :
 
-## Sans CITADEL / Avec CITADEL
+1. Poser des questions avant d'écrire du code
+2. Écrire le plan du projet et les décisions importantes
+3. Utiliser des rôles spécialisés pour construire
+4. Utiliser des rôles séparés pour reviewer
+5. Garder une mémoire projet pour reprendre proprement la session suivante
 
-| | Sans | Avec CITADEL |
-|--|------|-------------|
-| Démarrage | "Fais-moi une app" → l'IA fonce dans le code | Le C-Suite demande : c'est pour qui ? quelles données ? quelle sécurité ? |
-| Architecture | Ce que l'IA décide sur le moment | ADR explicite, reviewé par un agent architecture dédié |
-| Qualité du code | On espère que ça tient | Standards enforcés : 200 lignes/fichier, erreurs typées, pas de magic numbers |
-| Review | Tu relis toi-même (et tu rates des trucs) | Agents checkers indépendants avec une perspective différente |
-| Sécurité | "On ajoutera l'auth plus tard" | Review sécurité à chaque gate. Droit de veto sur le déploiement |
-| Session suivante | L'IA a tout oublié | La mémoire persiste décisions, erreurs et contexte projet |
-| Consommation tokens | Contexte complet à chaque message (~14K tokens) | Chargement par phase (~1 800 tokens par phase) |
+Sous le capot, CITADEL utilise une organisation structurée avec stratégie, makers, checkers, mémoire et gates. Tu n'as pas besoin d'apprendre toute cette mécanique pour en tirer de la valeur.
 
----
+## Installation en 2 minutes
 
-## Comment ça marche — 5 étapes
+Dans ton dossier projet :
 
-### Étape 1 : Clarifier ce que tu construis
-Le C-Suite (produit, architecture, sécurité, données, croissance) pose des questions avant que quoi que ce soit ne soit rédigé.
-
-### Étape 2 : Verrouiller la stratégie
-PRD, décisions d'architecture, exigences sécurité, modèle de données — tout écrit dans `.citadel/specs/` après tes réponses.
-
-### Étape 3 : Construire avec séparation des rôles
-Des agents makers spécialisés construisent par domaine (backend, frontend, mobile, API, auth, data). Chacun suit des standards de code stricts.
-
-### Étape 4 : Reviewer avant de shipper
-Des agents checkers indépendants valident la qualité du code, les tests, la performance, la sécurité, l'accessibilité. Builder ≠ reviewer — toujours.
-
-### Étape 5 : Shipper avec mémoire
-Décisions, erreurs et contexte persistent dans `.citadel/memory/`. La session suivante reprend là où tu t'es arrêté.
-
----
-
-## Démarrage rapide
-
-### Option 1 : Copie-colle dans ton chat IA (le plus simple)
-
-Ouvre ton IDE IA (Codex, Cursor, Antigravity, Claude Code, Windsurf) et colle ça :
-
-```
-Lance cette commande dans le terminal : npx citadel-ai init
-Puis lis le fichier AGENTS.md, CLAUDE.md ou GEMINI.md qui a été créé et suis ses instructions.
+```bash
+npx citadel-ai init
 ```
 
-Ton IA fait le reste. Décris ce que tu veux construire.
+Ensuite, ouvre ton IDE IA et commence à parler.
 
-### Option 2 : Une commande dans le terminal
+Si ton IA ne sait pas quoi faire, dis-lui :
 
-Ouvre le terminal dans ton IDE (appuie sur `` Ctrl+` `` dans la plupart des IDEs) et tape :
-
-```bash
-npx citadel-ai init
+```text
+Suis CITADEL. Pose des questions d'abord, fais un plan, protège ce qui ne doit pas casser, puis construis, review, et shippe proprement.
 ```
 
-Retourne dans ton chat IA et commence à parler.
+## Ce qui est installé
 
-### Jamais utilisé un terminal ?
+CITADEL ajoute :
 
-Voir [GETTING-STARTED.md](GETTING-STARTED.md) — un guide pas-à-pas sans aucun prérequis.
+- des fichiers de règles IDE comme `AGENTS.md`, `CLAUDE.md`, `.cursorrules`
+- un hub projet visible `citadel/` pour le statut, le contexte, les décisions, l'architecture, le runbook et le handoff
+- une télémétrie token visible dans `citadel/TOKENS.md`
+- un moteur caché `.citadel/` pour l'état interne, les gates, les équipes, les agents et les skills
 
----
+Dans la plupart des cas, tu n'as rien à configurer à la main.
 
-## Ce qui est installé
+## Ce qui se passe ensuite
 
-```
-ton-projet/
-├── AGENTS.md              ← Chargé auto par Codex
-├── CLAUDE.md              ← Chargé auto par Claude Code
-├── GEMINI.md              ← Chargé auto par Antigravity
-├── .cursorrules           ← Chargé auto par Cursor
-├── .windsurfrules         ← Chargé auto par Windsurf
-├── .claude/commands/      ← /citadel-help, /citadel-build, /citadel-review...
-├── .cursor/commands/
-├── .citadel/
-│   ├── agents/            ← 42 personas d'agents complètes (référence)
-│   ├── teams/             ← 12 fichiers équipe et pods de delivery (chargement par phase)
-│   ├── specs/             ← PRD, ADR, Sécurité, Data Model, Growth
-│   ├── memory/            ← État persistant (gitignored)
-│   └── gates/             ← Suivi des gates (gitignored)
-```
+Une fois installé, le flow est simple :
 
-Tout est installé. L'IDE ne lit que ce qui est contextuel.
+1. Tu décris ce que tu veux construire
+2. Tu réponds aux questions de clarification
+3. Tu valides le plan
+4. Tu laisses l'IA construire ou corriger le bon morceau
+5. Tu laisses l'IA reviewer avant de shipper
 
-| IDE | Comment démarrer |
-|-----|-----------------|
-| Claude Code | `/citadel-help` |
-| Cursor | `/citadel-help` |
-| Codex | Commence à chatter (`AGENTS.md` est chargé) |
-| Antigravity | Commence à chatter |
-| Windsurf | Commence à chatter |
+## Commandes
 
-CLI optionnel (nécessite une clé API) :
 ```bash
-export ANTHROPIC_API_KEY=sk-ant-...  # ou OPENAI_API_KEY
+npx citadel-ai init
+npx citadel-ai update
 npx citadel-ai run
+npx citadel-ai status
+npx citadel-ai estimate "flow login"
+npx citadel-ai agents
 ```
 
----
-
-## Pourquoi c'est différent
-
-La plupart des frameworks IA donnent **plus d'agents**. CITADEL donne **plus de discipline**.
-
-- **Organisation > cerveau unique.** 42 agents avec des rôles, règles et personnalités distincts — mais chargés par phase, pas tous en même temps.
-- **Gouvernance > vitesse.** Questions avant specs. Review avant ship. Veto sécurité avant déploiement.
-- **Mémoire > amnésie.** Décisions, choix d'architecture et erreurs passées persistent localement entre les sessions.
-- **Efficacité > force brute.** Chargement de contexte par phase : ~1 800 tokens au lieu de ~14 000.
-
----
+Dans Claude Code ou Cursor, tu peux aussi utiliser :
 
-## Les 42 agents
+- `/citadel-start`
+- `/citadel-help`
+- `/citadel-build`
+- `/citadel-fix`
+- `/citadel-review`
+- `/citadel-ship`
+- `/citadel-estimate`
+- `/citadel-snapshot`
+- `/citadel-status`
 
-Chaque agent a une persona complète : nom, inspiration, philosophie, voix, règles immuables et system prompt. Tout stocké dans `.citadel/agents/`.
+## Si tu n'as jamais utilisé de terminal
 
-**Stratégie (C-Suite) :** ATLAS (Orchestrateur) · LINUS (CTO) · MARTY (CPO) · SEAN (CGO) · BRUCE (CISO) · MONICA (CDO)
+Voir [GETTING-STARTED.md](GETTING-STARTED.md).
 
-**Constructeurs (Makers) :** UNCLE BOB · DAN · STEIPETE · KELSEY · JONY · TERESA · STRUNK · DJ PATIL · CYRUS · CHAMATH · FILIPPO · MOXIE · MAX · CODD · KARPATHY · HARRISON · ALEX · GRACE · CHARITY · RICH
+## Limites
 
-**Validateurs (Checkers) :** GUIDO · KENT · BRENDAN · JAKOB · RAZOR · LISA · NATE · ALEYDA · PEEP · CHARLIE · WINDOW · DATE · DEMING · FLYWAY · AARON · TRAIL
+- CITADEL améliore la façon dont ton IA travaille, mais ne remplace pas le jugement
+- c'est surtout utile pour les MVPs, les outils internes et les produits early-stage
+- le projet évolue encore
 
-`npx citadel-ai agents` les liste tous avec leurs rôles et équipes.
-
----
-
-## Limites connues
-
-- **Early stage.** C'est la v1, en développement actif. Des aspérités sont à prévoir.
-- **Pas autonome.** CITADEL structure le travail IA — il ne tourne pas sans supervision.
-- **Pas un remplacement d'équipe.** Excellent pour les MVPs et l'outillage interne. Pour scaler en production, il faut de vrais développeurs et un CTO.
-- **Dépendant de l'IDE.** Le chargement par phase dépend de comment ton IDE lit les fichiers de contexte. Le comportement varie.
-
----
-
-## Roadmap
-
-- [ ] Wizard d'onboarding (10 premières minutes guidées)
-- [ ] Vidéo démo (60 secondes)
-- [ ] Optimisations spécifiques par IDE
-- [ ] Système de plugins pour agents personnalisés
-- [ ] Cas d'usage non-code (équipes growth, marketing, ops)
-
----
-
-## Commandes CLI
-
-| Commande | Description |
-|---------|-------------|
-| `npx citadel-ai init` | Installe CITADEL dans ton projet |
-| `npx citadel-ai update` | Met à jour le framework (garde tes données) |
-| `npx citadel-ai run` | CLI interactif (nécessite clé API) |
-| `npx citadel-ai agents` | Liste les 42 agents |
-| `npx citadel-ai status` | Phase & gate en cours |
-| `npx citadel-ai help` | Toutes les commandes |
+## Pourquoi c'est différent
 
----
+La plupart des setups IA cherchent surtout à générer plus de code.
 
-## Contribuer
+CITADEL cherche surtout à obtenir :
 
-CITADEL est construit pour les gens qui construisent avec l'IA sans être développeurs traditionnels. Si c'est toi, tu es le bienvenu ici.
+- de meilleures décisions avant le code
+- une meilleure mémoire entre les sessions
+- des changements plus sûrs
+- une meilleure review avant le shipping
 
-Voir [CONTRIBUTING.md](CONTRIBUTING.md) pour les guidelines.
+## English
 
----
+Version anglaise : [README.md](README.md)
 
 ## Licence
 
 MIT
-
----
-
-Construit avec 🏰 par des humains qui parlent aux machines.