claude-atelier

English | Français

claude-atelier — Claude Code enforcement framework: hooks, named agents, stack-specific rules, night mode, proactive permissions. Zero dependency. Node.js only.

Install: npm install -g claude-atelier · Documentation

claude-atelier

          ██████╗██╗      █████╗ ██╗   ██╗██████╗ ███████╗
         ██╔════╝██║     ██╔══██╗██║   ██║██╔══██╗██╔════╝
       ██║     ██║     ███████║██║   ██║██║  ██║█████╗
       ██║     ██║     ██╔══██║██║   ██║██║  ██║██╔══╝
         ╚██████╗███████╗██║  ██║╚██████╔╝██████╔╝███████╗
          ╚═════╝╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚══════╝
                        A T E L I E R

⚡ From vibes to rails — Claude Code, disciplined

22 agents · 21 skills · MCP GitHub · persistent memory · dynamic vault + graph · Context7 · review gates

📦 npm · 📖 Docs · 📜 Philosophy · 📊 Parity · 🐛 Issues

npx claude-atelier init

2 000+ downloads/week · production-hardened · MIT

🔥 Killer bundle — full Claude Code cockpit in one npm package

Feature	Impact
Token killer	Haiku/Sonnet/Opus routing, `/compact`, QMD-first, `maxBudgetUsd` → 80–90% token cost reduction
22 named agents + 21 skills	Auto-detected domain experts (iOS→Steve 🍎, Go→Gaëlle 🦫, Design→Séréna 🎨…)
Vault + dynamic memory	Local project context: decisions, discoveries, roadmap. Peter auto-injects `PETER_REPORT.md` at session start.
Review gates	`/review-oracle` (4 local agents) auto-triggers on 50+ line diffs. Manual enforcement with `/tmp` flag.
Cockpit §1	Timestamp + model + fit pastille `[HH:MM
Context7 calibration	Docs auto-load by phase+stack. Brainstorm→no docs. Archi→patterns. Implementation→active libs only.
Real rails, not prose	Hooks block destructive actions at system level: no unsigned commits, tests required before push, secrets scanning.

💰 Token savings breakdown

Technique	Savings
Model routing (Haiku/Sonnet vs always-Opus)	~80%
`/compact` context compression	60–80% per session
Conditional stack loading	~30%
QMD-first search	~20%
`maxBudgetUsd` runaway prevention	100% safety

→ Typical 2h session: $8–12 → $0.80–1.50 · Full breakdown

🇫🇷 Français · 🇬🇧 English

Français

Le problème

Claude Code sans structure : Opus toute la nuit sur une tâche Haiku → budget cramé. 200+ lignes sans review → angles morts. Commits signés → historique pollué. Push sans tests → régressions silencieuses. Rules dans CLAUDE.md → intentions, pas garanties.

claude-atelier remplace les intentions par des rails.

Ce que c'est

Framework complet : règles runtime, hooks d'enforcement (15 actifs), skills (21), agents nommés (22), mémoire persistante, vault dynamique, contexte calibré, gates review, mode éco. Tout ce qu'on a durci en production.

Des rails réels. Push, versioning, review, coût et hygiène passent par des mécanismes système, pas par du texte en prose.

Installation & Quick start

npx claude-atelier init                        # Initialize project + config
npx claude-atelier@latest update               # Update existing project (keeps §0 + customizations)
npx claude-atelier doctor                      # Health check (28 tests)
npx claude-atelier vault init                  # Create dynamic memory (Peter)
npx claude-atelier vault graph && vault query  # Build + search project graph

Vault dynamique — Peter (mémoire persistante)

Le vault projet est la mémoire opérationnelle locale de Claude. À chaque démarrage, vault-context.sh injecte soit PETER_REPORT.md (synthétique : décisions, prochaines actions, nœuds centraux), soit les fichiers bruts (00-brief.md, 10-mailbox.md, 40-roadmap.md).

npx claude-atelier vault init              # Create vault/ structure
npx claude-atelier vault update             # SHA256 index (local, gitignored)
npx claude-atelier vault graph              # Extract graph + centrality
npx claude-atelier vault query "concept"    # Search + neighbors (Progressive Disclosure)
npx claude-atelier vault explain <obsId>   # Explode node avec icônes

Crée : brief.md, mailbox.md, decisions.md, discoveries.md, roadmap.md, sources.md + index/manifest.json + index/graph.json + index/associations.json.

Progressive Disclosure : vault query --tier [index|summary|full] permet de contrôler le volume réponse (~40–200 tokens vs 1000+). Défaut index : id/label/score/path. Expose aussi en MCP pour accès Claude en session.

Icônes par observation : 🔴 critique · 🟢 livré · 🔵 pattern · ⚖️ trade-off · 🟠 pourquoi · 🟡 problème-solution · 🟤 décision · 🟣 découverte.

Résultat : Claude reprend contexte sans relire tout le repo. Tokens économisés, sessions plus fluides, réponses contextuées par type d'observation.

Review gates — `/review-oracle`

Automatique : git push avec diff ≥ 50 lignes bloqué par guard-review-auto.sh tant que le flag /tmp/claude-atelier-review-done manque.

Manuel : /review-oracle lance 4 agents en parallèle :

DOCTRINE : checks §5 (anti-hallucination), §22 (secrets), §13 (french commits), décisions verrouillées
CODE : bugs, logique cassée, edge cases, side-effects silencieux
SÉCURITÉ : secrets en dur, injections, gate court-circuité
TESTS : npm run test réel, couverture logique

Verdict : RATIFIÉ (✅ poser flag) → MAJEUR (fix obligatoires) → BLOQUANT (corriger + relancer).

La Bise 🌬️ : optionnel, prépare brief pour GPT/Mistral + intègre réponses inter-LLM.

Agents nommés — 22 spécialistes par domaine

Détection automatique. Example : mention swift → Steve 🍎 (iOS + Xcode). Mention design → Séréna 🎨 (Design-first, MCP magic 21st.dev).

Agent	Domaine	Déclencheur
Steve 🍎	iOS/tvOS/iPadOS	swift, xcode, ios
Isaac 📦	NPM Publish	npm publish, version
Mohamed 📋	Review §25 (inter-LLM)	feat commit, 100+ lignes
Séréna 🎨	Design/UI/UX	design, ui, ux
Peter 🗂️	Vault/Mémoire	vault/ présent
Xavier 📡	Freebox	freebox
16 figures stack	C→Clara, C++→Célia, Rust→Roxane, Go→Gaëlle 🦫, PHP→Phoebe, C#→Carmen, SQL→Selma, R→Rosalie, Ada, Assembly→Astrid, Perl→Perla, VB→Violette, Fortran→Florence, MATLAB→Mathilde, Delphi→Daphné, Scratch→Sofia	Auto-détecté par type de fichier

Autres stacks (Python, Java, JS/TS, React, Firebase, Docker…) : règles chargées sans persona nommé.

Hooks — 15 enforcement rails

Rule	Hook	Trigger
Model routing	`routing-check.sh`	Every message
Stack detection + agent	`routing-check.sh`	Every message
No signed commits	`guard-no-sign.sh`	`git commit`
French commit messages	`guard-commit-french.sh`	`git commit`
Tests before push	`guard-tests-before-push.sh`	`git push`
Auto-review if 100+ lines	`guard-review-auto.sh`	`git commit`
Anti-loop (3+ errors)	`guard-anti-loop.sh`	Every bash command
QMD-first on .md read	`guard-qmd-first.sh`	`Read *.md`
Cockpit §1 header	`guard-s1-header.sh`	Every response
Vault injection	`vault-context.sh`	SessionStart
Session length warning	`routing-check.sh`	Every message (300KB / 600KB thresholds)

Real enforcement. PreToolUse hooks block at shell level (exit 2). PostToolUse suggest actions.

Skills — 21 slash commands

/atelier-help        /atelier-setup       /atelier-doctor
/atelier-config      /design-senior       /angle-mort
/audit-safe          /handoff-debt        /review-oracle
/review-copilot      /integrate-review    /night-launch
/token-routing       /compress            /qmd-init
/bmad-init           /ios-setup           /freebox-init
/la-bise             /loop-master         /chef-projet

Key skills: /review-oracle (4-agent review), /loop-master (recurring tasks), /token-routing (Haiku/Sonnet/Opus config), /vault (manage project memory).

Token routing — eco mode for Claude

Every message, model-metrics.sh analyzes last 5 assistant turns, classifies tool complexity, emits pastille:

🟢 : Model optimal (e.g., Sonnet on dev)
⬆️ : Task too hard → upgrade (Haiku on archi → Sonnet)
⬇️ : Overkill → downgrade (Opus on ls → Haiku)

Session monitoring: 300KB warn, 600KB critical. /compact recommended.

Model	Usage	Cost
Haiku 4.5	Exploration, subagents	1×
Sonnet 4.6	Daily dev, features	~5×
Opus 4.6	Architecture, hard debug	~50×

PaperClip integration

3 profiles: full (20 skills, 11 hooks), lean (token-routing, 3 guards), review-only (no hooks).

import { applyProfile } from 'claude-atelier'
await applyProfile({ cwd: path, profile: 'lean', dryRun: false })

Structure

src/
├── fr/ · en/                        Rules (FR = source of truth)
├── stacks/                          24 stack satellites (iOS, JS, Python, Rust…)
├── skills/                          21 slash command SKILLs
├── features-registry.json           18 toggleable features
└── templates/                       .gitignore, settings.json
hooks/                 11 enforcement + 1 helper
scripts/               pre-push-gate (5 checks), CI/CD
test/                  80 hook tests, doctor (28 checks), lint

Security

.gitignore + .claudeignore : sensitive files
settings.json deny list : destructive commands blocked
pre-push-gate.sh : 5 checks (secrets→lint→tests) before push
Hooks PreToolUse : block at shell level
Regex patterns : detect sk-, AKIA, ghp_, etc.

License

MIT — LICENSE

English

The Problem

Claude Code without structure: Opus overnight on Haiku-level task → budget gone. 200+ lines unreviewed → blind spots. Signed commits → dirty history. Push without tests → silent regressions. Rules in CLAUDE.md → wishes, not guarantees.

claude-atelier replaces wishes with rails.

What It Is

Complete framework: runtime rules, 15 enforcement hooks, 21 skills, 22 named agents, persistent memory, dynamic vault, calibrated context, review gates, eco mode. Hardened in production.

Real rails. Push, versioning, review, cost and hygiene operate through system mechanisms, not prose promises.

Installation & Quick start

npx claude-atelier init                        # Initialize project + config
npx claude-atelier@latest update               # Update existing project (keeps §0 + customizations)
npx claude-atelier doctor                      # Health check (28 tests)
npx claude-atelier vault init                  # Create dynamic memory (Peter)
npx claude-atelier vault graph && vault query  # Build + search project graph

Dynamic vault — Peter (persistent memory)

Project vault is Claude's local operational memory. At session start, vault-context.sh injects either PETER_REPORT.md (synthetic: decisions, next actions, central nodes) or raw files (00-brief.md, 10-mailbox.md, 40-roadmap.md).

npx claude-atelier vault init              # Create vault/ structure
npx claude-atelier vault update             # SHA256 index (local, gitignored)
npx claude-atelier vault graph              # Extract graph + centrality
npx claude-atelier vault query "concept"    # Search + neighbors

Creates: brief.md, mailbox.md, decisions.md, discoveries.md, roadmap.md, sources.md + index/manifest.json + index/graph.json.

Result: Claude resumes context without re-reading entire repo. Tokens saved, sessions faster.

Review gates — `/review-oracle`

Automatic: git push with diff ≥ 50 lines blocked by guard-review-auto.sh until /tmp/claude-atelier-review-done flag set.

Manual: /review-oracle spawns 4 agents in parallel:

DOCTRINE: checks §5 (anti-hallucination), §22 (secrets), §13 (french commits), locked decisions
CODE: bugs, inverted logic, edge cases, silent side-effects
SECURITY: hardcoded secrets, injections, gate bypass
TESTS: real npm run test, logical coverage

Verdict: RATIFIED (✅ set flag) → MAJOR (required fixes) → BLOCKING (fix + re-run).

La Bise 🌬️ (optional): prepare brief for GPT/Mistral + integrate inter-LLM responses.

Named agents — 22 domain specialists

Auto-detected. Example: mention swift → Steve 🍎 (iOS + Xcode). Mention design → Séréna 🎨 (Design-first, MCP magic 21st.dev).

Agent	Domain	Trigger
Steve 🍎	iOS/tvOS/iPadOS	swift, xcode, ios
Isaac 📦	NPM Publish	npm publish, version
Mohamed 📋	Review §25 (inter-LLM)	feat commit, 100+ lines
Séréna 🎨	Design/UI/UX	design, ui, ux
Peter 🗂️	Vault/Memory	vault/ exists
Xavier 📡	Freebox	freebox
16 stack figures	C→Clara, C++→Célia, Rust→Roxane, Go→Gaëlle 🦫, PHP→Phoebe, C#→Carmen, SQL→Selma, R→Rosalie, Ada, Assembly→Astrid, Perl→Perla, VB→Violette, Fortran→Florence, MATLAB→Mathilde, Delphi→Daphné, Scratch→Sofia	Auto-detected by file type

Other stacks (Python, Java, JS/TS, React, Firebase, Docker…): rules load without a named persona.

Hooks — 15 enforcement rails

Rule	Hook	Trigger
Model routing	`routing-check.sh`	Every message
Stack detection + agent	`routing-check.sh`	Every message
No signed commits	`guard-no-sign.sh`	`git commit`
English/French commits	`guard-commit-french.sh`	`git commit`
Tests before push	`guard-tests-before-push.sh`	`git push`
Auto-review if 100+ lines	`guard-review-auto.sh`	`git commit`
Anti-loop (3+ errors)	`guard-anti-loop.sh`	Every bash command
QMD-first on .md read	`guard-qmd-first.sh`	`Read *.md`
Cockpit §1 header	`guard-s1-header.sh`	Every response
Vault injection	`vault-context.sh`	SessionStart
Session length warning	`routing-check.sh`	Every message (300KB / 600KB thresholds)

Real enforcement. PreToolUse hooks block at shell level (exit 2). PostToolUse suggest actions.

Skills — 21 slash commands

/atelier-help        /atelier-setup       /atelier-doctor
/atelier-config      /design-senior       /angle-mort
/audit-safe          /handoff-debt        /review-oracle
/review-copilot      /integrate-review    /night-launch
/token-routing       /compress            /qmd-init
/bmad-init           /ios-setup           /freebox-init
/la-bise             /loop-master         /chef-projet

Key skills: /review-oracle (4-agent review), /loop-master (recurring tasks), /token-routing (Haiku/Sonnet/Opus config), /vault (manage project memory).

Token routing — eco mode for Claude

Every message, model-metrics.sh analyzes last 5 assistant turns, classifies tool complexity, emits pastille:

🟢: Model optimal (e.g., Sonnet on dev)
⬆️: Task too hard → upgrade (Haiku on archi → Sonnet)
⬇️: Overkill → downgrade (Opus on ls → Haiku)

Session monitoring: 300KB warn, 600KB critical. /compact recommended.

Model	Usage	Cost
Haiku 4.5	Exploration, subagents	1×
Sonnet 4.6	Daily dev, features	~5×
Opus 4.6	Architecture, hard debug	~50×

PaperClip integration

3 profiles: full (20 skills, 11 hooks), lean (token-routing, 3 guards), review-only (no hooks).

import { applyProfile } from 'claude-atelier'
await applyProfile({ cwd: path, profile: 'lean', dryRun: false })

Structure

src/
├── fr/ · en/                        Rules (FR = source of truth)
├── stacks/                          24 stack satellites (iOS, JS, Python, Rust…)
├── skills/                          21 slash command SKILLs
├── features-registry.json           18 toggleable features
└── templates/                       .gitignore, settings.json
hooks/                 11 enforcement + 1 helper
scripts/               pre-push-gate (5 checks), CI/CD
test/                  80 hook tests, doctor (28 checks), lint

Security

.gitignore + .claudeignore: sensitive files
settings.json deny list: destructive commands blocked
pre-push-gate.sh: 5 checks (secrets→lint→tests) before push
Hooks PreToolUse: block at shell level
Regex patterns: detect sk-, AKIA, ghp_, etc.

License

MIT — LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 722 Commits
.claude		.claude
.github		.github
.vscode		.vscode
bin		bin
docs		docs
hooks		hooks
scripts		scripts
src		src
test		test
vault		vault
website		website
.claudeignore		.claudeignore
.gitignore		.gitignore
.mcp.json		.mcp.json
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
PARITY.md		PARITY.md
PHILOSOPHY.md		PHILOSOPHY.md
README.md		README.md
SECURITY.md		SECURITY.md
claude-code-dynamic-model-switching.md		claude-code-dynamic-model-switching.md
index.js		index.js
package.json		package.json
vercel.json		vercel.json

Navigation Menu

Repository files navigation

claude-atelier

⚡ From vibes to rails — Claude Code, disciplined

🔥 Killer bundle — full Claude Code cockpit in one npm package

💰 Token savings breakdown

Français

Le problème

Ce que c'est

Installation & Quick start

Vault dynamique — Peter (mémoire persistante)

Review gates — `/review-oracle`

Agents nommés — 22 spécialistes par domaine

Hooks — 15 enforcement rails

Skills — 21 slash commands

Token routing — eco mode for Claude

PaperClip integration

Structure

Security

License

English

The Problem

What It Is

Installation & Quick start

Dynamic vault — Peter (persistent memory)

Review gates — `/review-oracle`

Named agents — 22 domain specialists

Hooks — 15 enforcement rails

Skills — 21 slash commands

Token routing — eco mode for Claude

PaperClip integration

Structure

Security

License

About

Releases

Packages

Contributors

Languages

Folders and files

Latest commit

History

Repository files navigation

claude-atelier

⚡ From vibes to rails — Claude Code, disciplined

🔥 Killer bundle — full Claude Code cockpit in one npm package

💰 Token savings breakdown

Français

Le problème

Ce que c'est

Installation & Quick start

Vault dynamique — Peter (mémoire persistante)

Review gates — /review-oracle

Agents nommés — 22 spécialistes par domaine

Hooks — 15 enforcement rails

Skills — 21 slash commands

Token routing — eco mode for Claude

PaperClip integration

Structure

Security

License

English

The Problem

What It Is

Installation & Quick start

Dynamic vault — Peter (persistent memory)

Review gates — /review-oracle

Named agents — 22 domain specialists

Hooks — 15 enforcement rails

Skills — 21 slash commands

Token routing — eco mode for Claude

PaperClip integration

Structure

Security

License

About

Topics

Resources

Contributing

Security policy

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

Review gates — `/review-oracle`

Review gates — `/review-oracle`