⬡ AgentStack V2

Système multi-agents JO / BOB / DO pour Claude Code.
Architecture OS-light · Skills-first — validée en production sur du vrai travail produit.

⚡ Quick Start

# 1. Clone sans historique git
npx degit aminelamine/AgentStackV2-template mon-projet
cd mon-projet

# 2. Remplis les 3 fichiers de contexte
# agent-system/context/client_vision.md  ← vision, JTBD, contraintes
# agent-system/context/roadmap.md        ← features, KPIs, out-of-scope
# agent-system/context/design_guide.md   ← tokens UI, composants, anti-patterns

# 3. Lance ta première session
# /jo  "j'ai une idée : [description]"

Avec GitHub CLI ?

gh repo clone aminelamine/AgentStackV2-template mon-projet -- --depth=1

🆕 Ce qui change par rapport à V1

La V1 était un bon système. La V2 résout un problème que la V1 ignorait : l'OS coûtait trop cher.

	V1	V2
`CLAUDE.md`	~1 400 tokens chargés à chaque tour	~150 tokens — OS épuré
Contenu de l'OS	Vision, arborescence, workflow complet, esthétique frontend	Contraintes invariantes uniquement
Agents	System prompts dans l'OS	Chargés à la demande via `/slash`
Brief esthétique	Dans `CLAUDE.md` (dupliqué)	Dans le skill `frontend-design` uniquement
Mémoire longue	Absente	DO écrit les learnings après chaque verdict
Économie par session (20 tours)	—	~25 000 tokens

L'analogie : CLAUDE.md est l'OS. Les agents sont des applications. Les skills sont des modules. Seul l'OS est en RAM permanente — le reste se charge à la demande.

🧠 Ce que ce template contient

Composant	Rôle
CLAUDE.md	OS — ~150 tokens, contraintes invariantes uniquement
agent-system/agents/	System prompts JO, BOB, DO — chargés par les slash commands
agent-system/context/	Mémoire partagée — vision client, roadmap, design guide
agent-system/adr/	Architecture Decision Records — mémoire des décisions structurantes
agent-system/learnings/	Mémoire longue de DO — patterns distillés après chaque feature
agent-system/specs/	Specs vivantes générées par JO, consommées par BOB
agent-system/resources/	visual_reference.md — 15 font pairings + 9 palettes prêts à l'emploi
.claude/commands/	Slash commands `/jo` `/bob` `/do`
.claude/skills/frontend-design/	Brief esthétique BOB — gate non négociable avant le code

🤖 Les agents

Slash command	Agent	Phase	Mission
`/jo`	JO — Architecte & Strategist	PLAN	Challenge les idées · génère les specs · crée les ADRs
`/bob`	BOB — Builder & UI/UX	SHIP	Brief esthétique (gate) · implémente · commite avec conventions
`/do`	DO — Product QA & CX	ANALYZE	Score /20 · verdict VALIDÉ/REJETÉ · écrit les learnings

🔄 Workflow

/jo  "j'ai une idée : [description]"
      ↓
     JO challenge → génère specs/active/feature_[ID].md
     statut: VALIDÉE TALENT requis pour débloquer BOB
      ↓
/bob  "implémente feature_[ID]"
      ↓
     BOB lit spec + design_guide + ADRs
      ↓
     [BRIEF ESTHÉTIQUE — gate obligatoire]
     ⏸ BOB s'arrête et attend ta validation
     "ok" ou ajustements → BOB code
      ↓
     Ralph Loop : Structure → Scaffold → Logic → UI → États → Polish
      ↓
/do  "évalue feature_[ID]"
      ↓
     DO → score /20 · conformance spec + ADRs · verdict
      ↓
     Learnings écrits dans agent-system/learnings/feature_[ID]_learnings.md
      ↓
     Learnings lus par JO à la prochaine spec → le système s'améliore

🎨 BOB Gate — Brief Esthétique

C'est la décision la plus opinionée de ce template. BOB ne code jamais sans direction visuelle validée.

Avant la première ligne de code, BOB génère et présente :

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[BRIEF ESTHÉTIQUE — Feature 001 : [Nom de ta feature]]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 Direction    : [1 phrase — l'intention spécifique]

🔤 Typographie  : [Heading font] / [Body font]
                  → [raison en 5 mots]

🎨 Palette      : Primary [hex] · Accent [hex] · BG [hex]

⚡ Tension      : [opposition choisie]

📐 Composition  : [approche spatiale]

⚠️  Éviter ici  : [2–3 patterns génériques à éviter]
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
✅ Validez en 1 ligne ou indiquez vos ajustements.

Pourquoi ce gate ? Corriger une direction esthétique après le code coûte 10× plus cher qu'ici. 2 minutes de brief = 30 à 60 minutes de rework évitées.

📐 Système ADR — Mémoire des décisions

agent-system/adr/ contient les Architecture Decision Records.
C'est ce qui empêche BOB de contredire en session 5 une décision prise en session 1.

agent-system/adr/
├── ADR_INDEX.md        ← Registre — lu par tous les agents
├── ADR_TEMPLATE.md     ← Template à copier pour chaque décision
└── adr-001-*.md        ← Décisions actives (créées par JO, validées par toi)

Quand créer un ADR : nouvelle dépendance npm · choix architectural structurant · décision de scope multi-features · tout choix dont le pourquoi ne doit pas se perdre.

🔁 Learnings Loop — Mémoire longue de DO

Après chaque verdict, DO écrit un fichier feature_[ID]_learnings.md avec :

Patterns qui ont fonctionné → BOB les réutilise
Anti-patterns détectés → BOB les évite
Ambiguïtés de spec à anticiper → JO les intègre proactivement
Signaux CX → remontent dans les prochaines user stories

JO lit les 3 learnings les plus récents avant de générer chaque spec.
Le système s'améliore à chaque feature — sans intervention manuelle.

📁 Structure complète

AgentStackV2-template/
│
├── CLAUDE.md                              ← OS — ~150 tokens, toujours chargé
├── README.md
├── .gitignore                             ← sessions/ exclu, learnings conservés
│
├── .claude/
│   ├── commands/
│   │   ├── jo.md                          ← /jo  — Architecte & Strategist
│   │   ├── bob.md                         ← /bob — Builder & UI/UX
│   │   └── do.md                          ← /do  — Product QA & CX
│   └── skills/
│       └── frontend-design/
│           └── SKILL.md                   ← Brief esthétique BOB (gate)
│
└── agent-system/
    ├── agents/
    │   ├── JO_system_prompt.md            ← Chargé par /jo
    │   ├── BOB_system_prompt.md           ← Chargé par /bob
    │   └── DO_system_prompt.md            ← Chargé par /do
    ├── context/
    │   ├── client_vision.md               ← [À REMPLIR] Vision, JTBD, contraintes
    │   ├── roadmap.md                     ← [À REMPLIR] Features, KPIs, backlog
    │   └── design_guide.md               ← [À REMPLIR] Tokens, composants, anti-patterns
    ├── adr/
    │   ├── ADR_INDEX.md                   ← Registre des décisions actives
    │   └── ADR_TEMPLATE.md               ← Template pour créer un ADR
    ├── learnings/
    │   └── LEARNINGS_INDEX.md             ← Index des learnings DO
    ├── sessions/                          ← Checkpoints BOB (exclu du git)
    ├── specs/
    │   ├── active/                        ← Spec en cours (0–1 à la fois)
    │   ├── backlog/
    │   ├── shipped/
    │   ├── dropped/
    │   └── feature_template.md            ← Template spec Gherkin + critères binaires
    └── resources/
        └── visual_reference.md            ← 15 pairings typo + 9 palettes

🔑 Générique vs. projet-spécifique

Fichier	Générique	Projet-spécifique
`CLAUDE.md`	Structure	Nom du projet, stack si différente
`.claude/commands/*.md`	✅ Tout	Rien
`.claude/skills/frontend-design/SKILL.md`	✅ Tout	Rien
`agent-system/agents/*.md`	✅ Tout	Rien
`client_vision.md`	Structure	Tout le contenu
`roadmap.md`	Structure	Tout le contenu
`design_guide.md`	Structure	Tokens, stack UI, décisions
`visual_reference.md`	15 pairings + 9 palettes	Tes ajouts custom
`adr/ADR_INDEX.md`	Structure	Décisions du projet
`adr/ADR_TEMPLATE.md`	✅ Tout	Rien
`feature_template.md`	✅ Tout	Rien

🛠️ Installation manuelle

Option A — GitHub Template (recommandé)

Sur ce repo : Use this template → créer un nouveau repo
git clone [url-nouveau-repo] && cd [repo]
Remplis les 3 fichiers context/

Option B — degit (sans historique git)

npx degit aminelamine/AgentStackV2-template mon-projet
cd mon-projet

Option C — GitHub CLI

gh repo clone aminelamine/AgentStackV2-template mon-projet -- --depth=1
cd mon-projet

⚙️ Configuration post-clone

1. Remplis les 3 fichiers de contexte (priorité absolue)

agent-system/context/client_vision.md
→ Vision produit, JTBD, anti-patterns, contraintes connues.
JO refusera de spécer sans ce fichier.

agent-system/context/roadmap.md
→ Features in/out-of-scope, KPIs, décisions prises.
Définit ce que JO a le droit de spécer.

agent-system/context/design_guide.md
→ Direction esthétique, tokens CSS, composants Shadcn autorisés, anti-patterns visuels.
BOB et DO lisent ce fichier à chaque session.

2. Adapte la stack si nécessaire

Ce template suppose Next.js · TypeScript strict · Tailwind · Shadcn/ui · Lucide React.
Si ta stack diffère, édite :

La ligne Stack → dans CLAUDE.md
La section "Qualité de code" dans BOB_system_prompt.md
Crée un ADR pour documenter le choix (/jo te guide)

3. Figma MCP (optionnel)

Pour activer l'intégration Figma avec le skill design-workflow :

npm install --save-dev figma-console-mcp

Configure le token dans .mcp.json (à créer, ne jamais commiter) :

{
  "mcpServers": {
    "figma-console-mcp": {
      "command": "npx",
      "args": ["-y", "figma-console-mcp"],
      "env": { "FIGMA_ACCESS_TOKEN": "TON_TOKEN_ICI" }
    }
  }
}

Ajoute .mcp.json à ton .gitignore — ne commite jamais un vrai token.

⚠️ Notes importantes

Premier run : JO demandera que client_vision.md et roadmap.md soient remplis avant de générer quoi que ce soit. C'est voulu.
Le BOB gate est non négociable : si tu dis "skip le brief", BOB refusera. C'est une protection, pas une bureaucratie.
Les learnings s'accumulent : plus tu utilises le système, plus JO anticipe les problèmes de spec avant qu'ils arrivent.
TypeScript strict : les agents supposent TypeScript strict. Si ta stack diffère, crée un ADR dès le départ.
sessions/ est exclu du git (.gitignore) : c'est éphémère par design.

📊 Ce que le système produit

Métrique	Résultat typique
Erreurs TypeScript	0 — strict enforced par DO
Contrainte 150 lignes	Respectée — DO rejette sinon
Iterations sur la palette	0 — brief esthétique validé avant le code
Tokens OS par tour (avant)	~1 400 (setup classique)
Tokens OS par tour (après)	~150 — économie de ~25 000 / session

Conçu et validé par @aminelamine — Product Designer, AI workflows.
Basé sur l'architecture skills-first d'Anthropic Claude Code.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

⬡ AgentStack V2

⚡ Quick Start

🆕 Ce qui change par rapport à V1

🧠 Ce que ce template contient

🤖 Les agents

🔄 Workflow

🎨 BOB Gate — Brief Esthétique

📐 Système ADR — Mémoire des décisions

🔁 Learnings Loop — Mémoire longue de DO

📁 Structure complète

🔑 Générique vs. projet-spécifique

🛠️ Installation manuelle

⚙️ Configuration post-clone

1. Remplis les 3 fichiers de contexte (priorité absolue)

2. Adapte la stack si nécessaire

3. Figma MCP (optionnel)

⚠️ Notes importantes

📊 Ce que le système produit

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.claude		.claude
agent-system		agent-system
.gitignore		.gitignore
CLAUDE.md		CLAUDE.md
README.md		README.md

Folders and files

Latest commit

History

Repository files navigation

⬡ AgentStack V2

⚡ Quick Start

🆕 Ce qui change par rapport à V1

🧠 Ce que ce template contient

🤖 Les agents

🔄 Workflow

🎨 BOB Gate — Brief Esthétique

📐 Système ADR — Mémoire des décisions

🔁 Learnings Loop — Mémoire longue de DO

📁 Structure complète

🔑 Générique vs. projet-spécifique

🛠️ Installation manuelle

⚙️ Configuration post-clone

1. Remplis les 3 fichiers de contexte (priorité absolue)

2. Adapte la stack si nécessaire

3. Figma MCP (optionnel)

⚠️ Notes importantes

📊 Ce que le système produit

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Packages