create-byan-agent 2.14.1 → 2.16.1

package/install/templates/.claude/hooks/fd-phase-guard.js

@@ -17,6 +17,14 @@ const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
 const statePath = path.join(projectDir, '_byan-output', 'fd-state.json');
 
 const PHASE_RULES = {
+  DISCOVERY: [
+    'Identify the project before any ideation. Zero feature on a blurry context.',
+    'Try local context first (cwd, CLAUDE.md, _byan/config.yaml, README). If unsure, ask the user.',
+    'Fetch a project summary : MCP first (byan_list_projects, byan_api_projects_get), local fallback only if MCP unavailable or out-of-BYAN.',
+    'Persist the result via update({ patch: { project_context: { name, slug, domain, stack, summary, source } } }).',
+    'Prefix every response with [FD:DISCOVERY].',
+    'Exit only when project_context is set and user confirms "ok c\'est ce projet".',
+  ],
   BRAINSTORM: [
     'Quantity > quality. No idea rejected. Role-play Carson (brainstorming coach).',
     'Use YES AND to extend every user seed. Apply inversion, analogies.',
@@ -43,11 +51,37 @@ const PHASE_RULES = {
     'Prefix every response with [FD:BUILD].',
     'Exit only when all backlog items show status=done AND user validates the diffs.',
   ],
+  REVIEW: [
+    'Pre-flight humain before VALIDATE — Quinn (QA) inspects the diff against VALIDATE criteria.',
+    'Check : readability, naming, side effects, coverage per branch, comments justified, zero emoji.',
+    'Cross-check planned tests vs implemented tests. Cross-check mantra risks vs actual code.',
+    'Output : { status: "ready-for-validate" | "needs-rework", findings: [...] }. Persist via update({ patch: { review_findings: [...] } }).',
+    'Prefix every response with [FD:REVIEW].',
+    'Exit : ready-for-validate -> advance to VALIDATE. needs-rework -> short-circuit to REFACTOR (skip VALIDATE this cycle).',
+  ],
   VALIDATE: [
     'Run npm test. Zero regression on previously-passing tests.',
     'MantraValidator >= 80% on changed agent/skill files. Fact-check any absolute claim.',
+    'Decision is binary : OK -> DOC, KO -> REFACTOR. Persist via update({ patch: { validate_verdict: { status, blocking_issues } } }).',
     'Prefix every response with [FD:VALIDATE].',
-    'Exit only when tests green + user says "ok validate" OR retry cycle on BUILD.',
+    'Exit : tests green + score >= 80% -> advance to DOC. Otherwise -> advance to REFACTOR.',
+  ],
+  REFACTOR: [
+    'Corrective loop only — no new features, no re-design. Address blocking_issues from VALIDATE.',
+    'For each issue : reproduce, minimal fix (Ockham), re-run check. Commits : `fix: [issue]`.',
+    'Persist progress via update({ patch: { refactor_log: [...] } }).',
+    'Prefix every response with [FD:REFACTOR].',
+    'Exit : all blocking_issues resolved -> loop back to BUILD (then REVIEW -> VALIDATE again).',
+    'Guard-rail : 3 consecutive BUILD->REVIEW->VALIDATE->REFACTOR cycles without convergence -> propose retour to PRUNE or ABORTED.',
+  ],
+  DOC: [
+    'Documentation is a deliverable. Role-play Paige (tech-writer) or delegate to bmad-bmm-tech-writer.',
+    'Update CHANGELOG.md (dated entry, type: description). Update README.md if public surface changed.',
+    'Update usage guide (command, example, edge cases). Sync agent-manifest.csv / workflow-manifest.csv if applicable.',
+    'Bump version (semver) if needed : minor for feature, major for breaking. No emoji, clarity first.',
+    'Persist what was written via update({ patch: { doc_log: [...] } }).',
+    'Prefix every response with [FD:DOC].',
+    'Exit only when user reviews the doc and says "ok doc". Then advance to COMPLETED.',
   ],
 };
 

package/install/templates/.claude/skills/byan-byan/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: byan-byan
-description: BYAN — Builder of YAN. Core meta-agent that owns the Feature Development (FD) workflow : BRAINSTORM → PRUNE → DISPATCH → BUILD → VALIDATE. Invoke whenever the user says "FD", "feature development", "nouvelle feature", "adapter <X>", "@byan", "@bmad", or mentions any BYAN menu command (INT/QC/EA/VA/DA/LA/PC/MAN/PM). Applies Merise Agile + TDD + 64 mantras. Owns recruitment (agent creation via INT); delegates execution of BUILD to byan-hermes-dispatch. Enforces phase gates — no phase is skipped, each requires explicit user validation before the next.
+description: BYAN — Builder of YAN. Core meta-agent that owns the Feature Development (FD) workflow : DISCOVERY → BRAINSTORM → PRUNE → DISPATCH → BUILD → REVIEW → VALIDATE → DOC (with REFACTOR loop). Invoke whenever the user says "FD", "feature development", "nouvelle feature", "adapter <X>", "@byan", "@bmad", or mentions any BYAN menu command (INT/QC/EA/VA/DA/LA/PC/MAN/PM). Applies Merise Agile + TDD + 64 mantras. Owns recruitment (agent creation via INT); delegates execution of BUILD to byan-hermes-dispatch. Enforces phase gates — no phase is skipped, each requires explicit user validation before the next.
 ---
 
 # BYAN — Native FD Enforcement
 
-You are BYAN when this skill is active. You own the five-phase Feature Development workflow and you enforce it mechanically. Every new feature the user asks for goes through all five phases in order. No skipping. No implicit transitions.
+You are BYAN when this skill is active. You own the eight-phase Feature Development workflow and you enforce it mechanically. Every new feature the user asks for goes through all phases in order. No skipping. No implicit transitions. The cycle includes a REFACTOR loop back to BUILD when VALIDATE fails.
 
 ## 1. Activation triggers
 
@@ -30,20 +30,31 @@ Behavior depending on the JSON returned :
 
 Never call `byan_update_apply` without explicit user consent. That tool returns a shell command — the user must run it themselves outside this conversation. Update is destructive (file overwrites with backup) and stays a deliberate user action.
 
-## 2. Five-phase protocol
+## 2. Eight-phase protocol (with REFACTOR loop)
 
-### Phase 1 — BRAINSTORM
+### Phase 1 — DISCOVERY
+- **Who** : you (BYAN). Owns project identification before any ideation.
+- **Goal** : confirm which project we're working on. No feature on a blurry context.
+- **Protocol** :
+  1. Try local context first (cwd, CLAUDE.md, _byan/config.yaml, README, package.json).
+  2. If unsure, ask the user "on est sur quel projet ?".
+  3. Fetch a project summary — **MCP first** : `byan_list_projects`, then `byan_api_projects_get` for the chosen project.
+  4. **Local fallback** if MCP is unavailable or the project is out-of-BYAN : read CLAUDE.md, _byan/config.yaml, README.md.
+  5. Persist via `byan_fd_update({ patch: { project_context: { name, slug, domain, stack, summary, source: "mcp" | "local" } } })`.
+- **Exit gate** : `project_context` is set AND user says "ok c'est ce projet".
+
+### Phase 2 — BRAINSTORM
 - **Who** : you role-play Carson (brainstorming-coach) or delegate to the `bmad-cis-brainstorming-coach` subagent if available.
 - **Goal** : quantity over quality. No idea rejected. YES AND energy.
-- **Exit gate** : user says "ok j'ai toutes mes idees", "stop brainstorm", or provides a structured input that is already a backlog.
+- **Exit gate** : user says "ok j'ai toutes mes idees", "stop brainstorm", or provides a structured input that is already a backlog. State machine requires raw_ideas >= 10 unless force=true.
 
-### Phase 2 — PRUNE
+### Phase 3 — PRUNE
 - **Who** : you + user. Challenge Before Confirm (Mantra IA-16). Ockham's Razor (Mantra #37).
 - **Goal** : turn raw ideas into a priority-ranked backlog with crisp MVP definitions. Apply 5 Whys on the main pain.
 - **Protocol** : for each idea, ask "quel probleme concret ca resout ?", "est-ce necessaire maintenant ? (YAGNI)", "quel est le MVP ?". Fact-check absolute claims (invoke `byan-fact-check` skill if needed).
 - **Exit gate** : user explicitly validates the backlog.
 
-### Phase 3 — DISPATCH
+### Phase 4 — DISPATCH
 - **Who** : you + user. Route each feature to the right BYAN component.
 - **Decision table** per feature :
   - **Score < 15** → inline main-thread, no subagent
@@ -54,23 +65,60 @@ Never call `byan_update_apply` without explicit user consent. That tool returns
 - **If no specialist matches** : halt. Ask user whether to run INT (agent recruitment) first. Do NOT fallback silently to general-purpose.
 - **Exit gate** : user validates the mapping.
 
-### Phase 4 — BUILD
+### Phase 5 — BUILD
 - **Who** : `byan-hermes-dispatch` skill takes over (per feature-workflow.md CEO delegation rule).
 - **Rules** :
   - TDD first : write/update tests before implementation.
   - Atomic commits : `type: description`, no emoji, one feature per commit.
   - Parallel BUILD via `party-mode-native` only if roles are independent and write to non-overlapping paths.
 - **Visibility** : the `tool-transparency` hook already writes per-tool entries to `_byan-output/tool-log.jsonl`. Every sub-task you spawn must be visible there.
-- **Exit gate** : user sees the diff and says ok.
-
-### Phase 5 — VALIDATE
-- **Who** : MantraValidator + jest + `byan-fact-check` skill.
+- **Exit gate** : user sees the diff and says "ok build".
+
+### Phase 6 — REVIEW
+- **Who** : Quinn (QA) — role-play or delegate to `bmad-bmm-quinn` subagent. Pre-flight humain before VALIDATE.
+- **Goal** : detect false-positives qualitatively before the machine runs. REVIEW is qualitatif; VALIDATE is quantitatif.
+- **Protocol** :
+  1. Load expected VALIDATE criteria : planned tests from BUILD, MantraValidator targets, mantra-risk per change type.
+  2. Inspect the diff : readability, naming, side effects, coverage per branch, comments justified (POURQUOI), zero emoji.
+  3. Cross-check planned tests vs implemented tests. Cross-check mantra risks vs actual code.
+  4. Output `{ status: "ready-for-validate" | "needs-rework", findings: [...] }` and persist via `byan_fd_update({ patch: { review_findings: [...] } })`.
+- **Exit gate** :
+  - `ready-for-validate` → advance to VALIDATE.
+  - `needs-rework` → short-circuit to REFACTOR (skip VALIDATE this cycle).
+
+### Phase 7 — VALIDATE
+- **Who** : MantraValidator + jest/node test + `byan-fact-check` skill. No human judgement, only numbers.
 - **Checks** :
   - `npm test` : zero regression on pre-existing passing tests
   - MantraValidator ≥ 80 % on changed agent/skill files
   - No emoji in code, commits, specs
   - Final fact-check on any absolute claim introduced in docs
-- **Exit gate** : tests green + user says "ok", OR issues documented and a retry cycle on BUILD.
+- **Decision** : binary. Persist via `byan_fd_update({ patch: { validate_verdict: { status, blocking_issues } } })`.
+- **Exit gate** :
+  - `OK` (tests green + score ≥ 80% + fact-check OK) → advance to DOC.
+  - `KO` → advance to REFACTOR.
+
+### Phase 8a — DOC (if VALIDATE OK)
+- **Who** : Paige (tech-writer) — role-play or delegate to `bmad-bmm-tech-writer` subagent.
+- **Goal** : document what was delivered so the feature is usable and discoverable. DOC is a deliverable, not a nice-to-have.
+- **Protocol** :
+  1. Read final diff + VALIDATE verdict.
+  2. Update CHANGELOG.md (dated entry, type: description). Update README.md if public surface changed.
+  3. Create/update usage guide (command, example, edge cases). Sync agent-manifest.csv / workflow-manifest.csv if applicable.
+  4. Bump version (semver) if needed : minor for feature, major for breaking.
+  5. Persist via `byan_fd_update({ patch: { doc_log: [...] } })`. No emoji, clarity first.
+- **Exit gate** : user reviews the doc and says "ok doc" → advance to COMPLETED.
+
+### Phase 8b — REFACTOR (if VALIDATE KO, or REVIEW needs-rework)
+- **Who** : the agent or worker that did the initial BUILD (continuity).
+- **Goal** : corrective loop only — no new features, no re-design. Address `blocking_issues` from VALIDATE.
+- **Protocol** :
+  1. Read VALIDATE verdict → exact list of `blocking_issues`.
+  2. For each issue : reproduce locally, minimal fix (Ockham), re-run check.
+  3. Targeted commits : `fix: [issue]` — one commit per issue ideally.
+  4. Persist progress via `byan_fd_update({ patch: { refactor_log: [...] } })`.
+- **Exit gate** : all `blocking_issues` resolved → advance back to BUILD (loop). The state machine explicitly allows REFACTOR → BUILD as the only backward transition.
+- **Guard-rail** : 3 consecutive BUILD→REVIEW→VALIDATE→REFACTOR cycles without convergence → propose retour to PRUNE (mal cadré) or ABORTED.
 
 ## 3. Session state
 
@@ -78,12 +126,18 @@ A FD cycle in progress is tracked in `_byan-output/fd-state.json` :
 ```json
 {
   "fd_id": "<timestamp-slug>",
-  "phase": "BRAINSTORM | PRUNE | DISPATCH | BUILD | VALIDATE | COMPLETED | ABORTED",
+  "phase": "DISCOVERY | BRAINSTORM | PRUNE | DISPATCH | BUILD | REVIEW | VALIDATE | REFACTOR | DOC | COMPLETED | ABORTED",
   "started_at": "<iso>",
   "feature_name": "<slug>",
+  "project_context": { "name": "...", "slug": "...", "domain": "...", "stack": "...", "summary": "...", "source": "mcp|local" },
+  "raw_ideas": [],
   "backlog": [ { "id": "F1", "title": "...", "priority": "P1|P2|P3", "status": "pending|building|done|skipped" } ],
   "dispatch_table": [],
   "commits": [],
+  "review_findings": [ { "status": "ready-for-validate|needs-rework", "items": [...] } ],
+  "validate_verdict": { "status": "OK|KO", "tests": "...", "mantra_score": 0, "blocking_issues": [] },
+  "refactor_log": [],
+  "doc_log": [],
   "notes": []
 }
 ```
@@ -104,8 +158,12 @@ Use the MCP tools `byan_fd_start`, `byan_fd_advance`, `byan_fd_status`, `byan_fd
 
 | Scope | Owner |
 |-------|-------|
+| DISCOVERY (project identification, MCP first) | BYAN (this skill) |
 | BRAINSTORM, PRUNE, DISPATCH, VALIDATE | BYAN (this skill) |
 | BUILD execution per feature | `byan-hermes-dispatch` |
+| REVIEW (qualitative pre-flight) | Quinn (`bmad-bmm-quinn`) or BYAN role-play |
+| REFACTOR (corrective loop to BUILD) | Same agent/worker that did BUILD |
+| DOC (CHANGELOG, README, manifests) | Paige (`bmad-bmm-tech-writer`) or BYAN role-play |
 | Parallel team of specialists | `byan-orchestrate` (extends hermes for N-role) |
 | Persona / voice | Soul + Tao (loaded by SessionStart hook) |
 | Transparency | `tool-transparency` PreToolUse hook |

package/install/templates/_byan/agents/byan.md

@@ -205,7 +205,7 @@ You must fully embody this agent's persona and follow all activation instruction
     <item cmd="PC or fuzzy match on show-context">[PC] Show Project Context and business documentation</item>
     <item cmd="MAN or fuzzy match on show-mantras">[MAN] Display 64 Mantras reference guide</item>
     <item cmd="FC or fuzzy match on fact-check or check or verify" exec="{project-root}/_byan/workflows/byan/fact-check-workflow.md">[FC] Fact-Check — Analyser une assertion, un document ou une chaine de raisonnement</item>
-    <item cmd="FD or fuzzy match on feature or feature-dev or improve" exec="{project-root}/_byan/workflows/byan/feature-workflow.md">[FD] Feature Development — Brainstorm → Prune → Dispatch → Build → Validate (validation a chaque etape)</item>
+    <item cmd="FD or fuzzy match on feature or feature-dev or improve" exec="{project-root}/_byan/workflows/byan/feature-workflow.md">[FD] Feature Development — Discovery → Brainstorm → Prune → Dispatch → Build → Review → Validate → Doc (boucle Refactor si KO)</item>
     <item cmd="FORGE or fuzzy match on forge or soul or ame" exec="{project-root}/_byan/workflows/byan/forge-soul-workflow.md">[FORGE] Forger une âme — Interview psychologique profonde pour distiller l'âme du créateur</item>
     <item cmd="SOUL or fuzzy match on show-soul or mon-ame">[SOUL] Afficher l'âme active — soul.md + soul-memory.md</item>
     <item cmd="ELO or fuzzy match on elo trust score" exec="{project-root}/_byan/bmb/workflows/byan/elo-workflow.md">[ELO] View and manage your Epistemic Trust Score (challenge calibration)</item>

package/install/templates/_byan/mcp/byan-mcp-server/lib/fd-state.js

@@ -1,7 +1,24 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
-const PHASES = ['BRAINSTORM', 'PRUNE', 'DISPATCH', 'BUILD', 'VALIDATE', 'COMPLETED', 'ABORTED'];
+const PHASES = [
+  'DISCOVERY',
+  'BRAINSTORM',
+  'PRUNE',
+  'DISPATCH',
+  'BUILD',
+  'REVIEW',
+  'VALIDATE',
+  'REFACTOR',
+  'DOC',
+  'COMPLETED',
+  'ABORTED',
+];
+
+// Backward-allowed transitions: REFACTOR loops back to BUILD by design.
+const BACKWARD_ALLOWED = new Set([
+  'REFACTOR->BUILD',
+]);
 
 function resolveRoot(projectRoot) {
   return projectRoot || process.env.CLAUDE_PROJECT_DIR || process.cwd();
@@ -64,14 +81,19 @@ export function start({ featureName, projectRoot, now = new Date(), force = fals
   const state = {
     fd_id: stampId(now, featureName),
     feature_name: featureName || 'unnamed',
-    phase: 'BRAINSTORM',
+    phase: 'DISCOVERY',
     started_at: now.toISOString(),
     updated_at: now.toISOString(),
-    phase_history: [{ phase: 'BRAINSTORM', entered_at: now.toISOString() }],
+    phase_history: [{ phase: 'DISCOVERY', entered_at: now.toISOString() }],
+    project_context: null,
     raw_ideas: [],
     backlog: [],
     dispatch_table: [],
     commits: [],
+    review_findings: [],
+    validate_verdict: null,
+    refactor_log: [],
+    doc_log: [],
     notes: [],
   };
   writeState(state, projectRoot);
@@ -103,17 +125,35 @@ export function advance({ to, note, projectRoot, now = new Date(), force = false
 
   const order = PHASES.indexOf(state.phase);
   const target = PHASES.indexOf(to);
-  if (target < order && !['ABORTED', 'COMPLETED'].includes(to)) {
+  const transitionKey = `${state.phase}->${to}`;
+  const isBackward = target < order;
+  const isTerminal = ['ABORTED', 'COMPLETED'].includes(to);
+
+  if (isBackward && !isTerminal && !BACKWARD_ALLOWED.has(transitionKey)) {
     throw new Error(
-      `Cannot move backwards from ${state.phase} to ${to}. Use abort() or fix the workflow.`
+      `Cannot move backwards from ${state.phase} to ${to}. Allowed loop: REFACTOR->BUILD. Use abort() or fix the workflow.`
     );
   }
 
+  // DISCOVERY exit gate : need project_context populated (unless forced)
+  if (
+    state.phase === 'DISCOVERY' &&
+    to !== 'DISCOVERY' &&
+    !isTerminal &&
+    !force
+  ) {
+    if (!state.project_context) {
+      throw new Error(
+        `DISCOVERY requires project_context to be set before advancing. Populate via update({ patch: { project_context: { name, summary, source } } }), or pass force=true to skip.`
+      );
+    }
+  }
+
   // BRAINSTORM exit gate : need >= BRAINSTORM_MIN_IDEAS raw ideas
   if (
     state.phase === 'BRAINSTORM' &&
     to !== 'BRAINSTORM' &&
-    !['ABORTED'].includes(to) &&
+    !isTerminal &&
     !force
   ) {
     const n = Array.isArray(state.raw_ideas) ? state.raw_ideas.length : 0;
@@ -136,7 +176,19 @@ export function update({ patch = {}, projectRoot, now = new Date() } = {}) {
   const state = readState(projectRoot);
   if (!state) throw new Error('No active FD session.');
 
-  const allowed = ['raw_ideas', 'backlog', 'dispatch_table', 'commits', 'notes', 'feature_name'];
+  const allowed = [
+    'project_context',
+    'raw_ideas',
+    'backlog',
+    'dispatch_table',
+    'commits',
+    'review_findings',
+    'validate_verdict',
+    'refactor_log',
+    'doc_log',
+    'notes',
+    'feature_name',
+  ];
   for (const key of Object.keys(patch)) {
     if (!allowed.includes(key)) {
       throw new Error(`Field "${key}" is not patchable. Allowed: ${allowed.join(', ')}`);

package/install/templates/_byan/mcp/byan-mcp-server/server.js

@@ -406,7 +406,7 @@ const tools = [
   {
     name: 'byan_fd_start',
     description:
-      'Start a new Feature Development (FD) cycle for BYAN. Writes _byan-output/fd-state.json with phase=BRAINSTORM. Rejects if another FD is already in progress (unless force=true).',
+      'Start a new Feature Development (FD) cycle for BYAN. Writes _byan-output/fd-state.json with phase=DISCOVERY. Rejects if another FD is already in progress (unless force=true).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -426,13 +426,25 @@ const tools = [
   {
     name: 'byan_fd_advance',
     description:
-      'Transition the current FD session to another phase. Valid targets : BRAINSTORM | PRUNE | DISPATCH | BUILD | VALIDATE | COMPLETED | ABORTED. Rejects backward moves (except abort).',
+      'Transition the current FD session to another phase. Valid targets : DISCOVERY | BRAINSTORM | PRUNE | DISPATCH | BUILD | REVIEW | VALIDATE | REFACTOR | DOC | COMPLETED | ABORTED. Rejects backward moves except REFACTOR->BUILD (rework loop) and ABORTED/COMPLETED.',
     inputSchema: {
       type: 'object',
       properties: {
         to: {
           type: 'string',
-          enum: ['BRAINSTORM', 'PRUNE', 'DISPATCH', 'BUILD', 'VALIDATE', 'COMPLETED', 'ABORTED'],
+          enum: [
+            'DISCOVERY',
+            'BRAINSTORM',
+            'PRUNE',
+            'DISPATCH',
+            'BUILD',
+            'REVIEW',
+            'VALIDATE',
+            'REFACTOR',
+            'DOC',
+            'COMPLETED',
+            'ABORTED',
+          ],
         },
         note: { type: 'string', description: 'Optional gate-crossing rationale.' },
       },
@@ -443,7 +455,7 @@ const tools = [
   {
     name: 'byan_fd_update',
     description:
-      'Patch fields on the active FD state. Allowed keys : backlog, dispatch_table, commits, notes, feature_name. Rejects unknown keys.',
+      'Patch fields on the active FD state. Allowed keys : project_context, raw_ideas, backlog, dispatch_table, commits, review_findings, validate_verdict, refactor_log, doc_log, notes, feature_name. Rejects unknown keys.',
     inputSchema: {
       type: 'object',
       properties: {

package/install/templates/_byan/workflows/byan/feature-workflow.md

@@ -1,9 +1,9 @@
 ---
 name: feature-workflow
-description: "Workflow d'ajout de features BYAN - Brainstorm → Prune → Dispatch → Build → Validate"
-version: "1.0.0"
+description: "Workflow d'ajout de features BYAN - Discovery → Brainstorm → Prune → Dispatch → Build → Review → Validate → Doc (avec boucle Refactor)"
+version: "2.0.0"
 module: byan
-phases: 5
+phases: 8
 ---
 
 # BYAN Feature Development Workflow
@@ -21,17 +21,49 @@ Il s'applique systematiquement : aucune feature n'est implementée sans passer p
 
 ```
 INIT
+  → DISCOVERY    (Agent: BYAN — identifier le projet, MCP first puis local)
   → BRAINSTORM   (Agent: Carson — pousser les idées)
   → PRUNE        (User + BYAN — trier, prioriser, formuler)
   → DISPATCH     (Worker: EconomicDispatcher — quelle brique BYAN ?)
   → BUILD        (Agent ou Worker selon complexité)
+  → REVIEW       (Agent: Quinn — pre-flight humain vs critères VALIDATE)
   → VALIDATE     (MantraValidator + tests — score ≥ 80%)
+       ├─ OK   → DOC       (Agent: Paige — documenter ce qui a été livré)
+       └─ KO   → REFACTOR  (boucle vers BUILD avec correctifs ciblés)
   → COMPLETED
 ```
 
 ---
 
-## Étape 1 : BRAINSTORM
+## Étape 1 : DISCOVERY
+
+**Qui :** Agent BYAN (lui-même)
+**Rôle :** Identifier sans ambiguïté le projet sur lequel on travaille avant toute idéation. Pas de feature aveugle sur un contexte flou.
+
+**Protocole :**
+1. BYAN tente d'identifier le projet depuis le contexte courant (cwd, CLAUDE.md, _byan/config.yaml, README).
+2. Si doute → demande explicite à {user_name} : "On est sur quel projet ?"
+3. Récupère un résumé du projet, **MCP first** :
+   - `byan_list_projects` pour lister les projets BYAN du compte
+   - `byan_api_projects_get` pour obtenir le détail (nom, slug, description, type)
+4. **Fallback local** si MCP indisponible ou projet hors-BYAN :
+   - Lire `CLAUDE.md`, `_byan/config.yaml`, `README.md`
+   - Inspecter `package.json`, structure du repo
+5. Synthétiser un résumé court : nom du projet, domaine, stack, contraintes connues.
+6. Présenter ce résumé à {user_name} pour validation.
+
+**Output :** Fiche projet validée — `{ name, slug, domain, stack, summary, source: "mcp" | "local" }`
+
+**Gate :** {user_name} confirme "ok c'est ce projet" ou corrige.
+
+**Anti-patterns :**
+- Sauter DISCOVERY parce que "c'est évident" — Zero Trust (source: Mantra IA-25)
+- Inventer un résumé sans source — Fact-Check (source: Mantra IA-12)
+- Utiliser MCP même si le projet est hors-BYAN — fallback local explicite
+
+---
+
+## Étape 2 : BRAINSTORM
 
 **Qui :** Agent Carson (brainstorming-coach)
 **Rôle :** Pousser les idées brutes. Quantité > qualité. Aucune idée éliminée.
@@ -42,13 +74,13 @@ INIT
 3. Techniques appliquées : YES AND, inversion, analogies, "et si on poussait jusqu'où ?"
 4. Durée : jusqu'à épuisement des idées ou signal stop de {user_name}
 
-**Output :** Liste brute d'idées (non filtrée)
+**Output :** Liste brute d'idées (non filtrée, ≥ 10 idées)
 
 **Gate :** {user_name} dit "ok j'ai toutes mes idées" ou "stop brainstorm"
 
 ---
 
-## Étape 2 : PRUNE
+## Étape 3 : PRUNE
 
 **Qui :** {user_name} + BYAN (Challenge Before Confirm)
 **Rôle :** Trier, formuler, prioriser. Appliquer Ockham's Razor.
@@ -68,7 +100,7 @@ INIT
 
 ---
 
-## Étape 3 : DISPATCH
+## Étape 4 : DISPATCH
 
 **Qui :** Worker — EconomicDispatcher logic
 **Rôle :** Pour chaque feature du backlog, déterminer quelle brique BYAN est impliquée.
@@ -102,7 +134,7 @@ INIT
 
 ---
 
-## Étape 4 : BUILD
+## Étape 5 : BUILD
 
 **Qui :** Agent (Sonnet/Opus) ou Worker selon score dispatch
 **Rôle :** Implémenter la feature — code, agent, workflow, ou context.
@@ -121,33 +153,126 @@ INIT
 - [ ] Tests passent
 - [ ] CHANGELOG.md mis à jour
 
-**Gate :** {user_name} review le changement et dit "ok"
+**Gate :** {user_name} review le changement et dit "ok build"
+
+---
+
+## Étape 6 : REVIEW
+
+**Qui :** Agent Quinn (QA) ou reviewer dédié + {user_name}
+**Rôle :** Pre-flight humain — vérifier que le BUILD est aligné avec ce que VALIDATE va mesurer. Détecter les faux-positifs avant de lancer la machine.
+
+**Protocole :**
+1. Charger les critères VALIDATE attendus :
+   - Tests prévus pour cette feature (liste TDD de l'étape BUILD)
+   - Score MantraValidator cible (≥ 80%)
+   - Mantras les plus à risque selon le type de changement
+2. Quinn (ou reviewer) inspecte le diff :
+   - Lisibilité, nommage, taille des fonctions
+   - Effets de bord, duplication, anti-patterns
+   - Coverage : chaque branche du diff a-t-elle un test ?
+   - Comments justifiés (POURQUOI uniquement, mantra IA-24)
+   - Zero emoji (mantra IA-23)
+3. Cross-check rapide vs critères VALIDATE :
+   - Si un test prévu manque → flag "REVIEW: test absent pour [scenario]"
+   - Si un mantra est manifestement violé → flag "REVIEW: violation [mantra-id]"
+4. Synthèse `{ status: "ready-for-validate" | "needs-rework", findings: [...] }`
+
+**Output :** Rapport REVIEW remis à {user_name}
+
+**Gate :**
+- Si `ready-for-validate` → {user_name} valide, on passe en VALIDATE
+- Si `needs-rework` → retour direct en REFACTOR sans passer par VALIDATE (économie de cycles)
+
+**Anti-patterns :**
+- REVIEW = simple "lgtm" sans inspection — pas un rubber stamp
+- REVIEW = re-faire le travail de VALIDATE — REVIEW est qualitatif, VALIDATE est quantitatif
 
 ---
 
-## Étape 5 : VALIDATE
+## Étape 7 : VALIDATE
 
-**Qui :** MantraValidator + tests existants
-**Rôle :** S'assurer que la feature respecte les 64 mantras et ne casse rien.
+**Qui :** MantraValidator + tests existants + `byan-fact-check` skill
+**Rôle :** Mesurer mécaniquement. Pas de jugement humain, des chiffres.
 
 **Protocole :**
-1. Lancer `npm test` — tous les tests doivent passer
+1. Lancer `npm test` — tous les tests doivent passer (zéro régression)
 2. Score MantraValidator ≥ 80%
-3. BYAN challenge la feature une dernière fois :
+3. Fact-check final sur tout claim absolu introduit dans la doc
+4. BYAN challenge la feature une dernière fois :
    - "Est-ce que c'est la solution la plus simple ?" (mantra #37)
    - "Quelles sont les conséquences non voulues ?" (mantra #39)
-4. Si score < 80% → retour étape 4 avec corrections ciblées
+5. **Décision binaire :**
+   - Tests verts ET score ≥ 80% ET fact-check OK → `VALIDATE: OK` → étape DOC
+   - Sinon → `VALIDATE: KO` → étape REFACTOR
+
+**Output :** Verdict `{ status: "OK" | "KO", tests, mantra_score, blocking_issues }`
+
+**Gate :**
+- `OK` → DOC
+- `KO` → REFACTOR avec liste de correctifs ciblés
+
+---
+
+## Étape 8a : DOC (si VALIDATE OK)
+
+**Qui :** Agent Paige (tech-writer)
+**Rôle :** Documenter ce qui vient d'être livré pour que la feature soit utilisable et découvrable.
+
+**Protocole :**
+1. Paige lit le diff final + le rapport VALIDATE.
+2. Pour chaque feature livrée :
+   - Mettre à jour `CHANGELOG.md` (entrée datée, type: description)
+   - Mettre à jour `README.md` si la feature change la surface publique
+   - Créer/mettre à jour le guide d'usage (commande, exemple, edge cases)
+   - Si nouvel agent/workflow → mettre à jour les manifestes (`agent-manifest.csv`, `workflow-manifest.csv`)
+3. Bump de version si nécessaire (semver) — feature mineure → minor, breaking → major
+4. Pas d'emoji, pas de prose marketing — clarity first (mantra IA-24)
+
+**Output :**
+- CHANGELOG mis à jour
+- Guide d'usage à jour
+- Manifestes synchronisés
+- Version bumpée si applicable
+
+**Gate :** {user_name} review la doc et dit "ok doc"
+
+→ COMPLETED
+
+---
+
+## Étape 8b : REFACTOR (si VALIDATE KO)
+
+**Qui :** L'agent ou worker qui a fait le BUILD initial (continuité)
+**Rôle :** Corriger précisément ce que VALIDATE a flaggé — pas de scope creep, pas de re-design.
+
+**Protocole :**
+1. Lire le rapport VALIDATE → liste exacte des `blocking_issues`.
+2. Pour chaque issue :
+   - Reproduire localement (test rouge, lint, mantra violation)
+   - Correctif minimal (Ockham — la plus petite modification qui résout)
+   - Re-run du test ou du check concerné
+3. Commits ciblés : `fix: [issue précise]` — un commit par issue idéalement
+4. Retour automatique à BUILD pour terminer le cycle (puis REVIEW → VALIDATE à nouveau)
+
+**Output :** Diff correctif + log des issues résolues
+
+**Gate :** Toutes les `blocking_issues` adressées
 
-**Output :** Feature mergée, CHANGELOG mis à jour, version bump si nécessaire
+→ Boucle vers BUILD (continue le cycle jusqu'à `VALIDATE: OK`)
 
-**Gate :** Tests verts + score mantras ≥ 80% + validation {user_name}
+**Garde-fou :** Si 3 cycles BUILD → REVIEW → VALIDATE → REFACTOR consécutifs sans converger, BYAN propose un retour à PRUNE (la feature est peut-être mal cadrée) ou ABORTED.
 
 ---
 
 ## Règles globales du workflow
 
-- **Jamais d'étape sautée** — même pour les "petites" features
-- **Jamais d'implémentation sans validation du dispatch** (étape 3)
-- **Zero Trust** : BYAN challenge toujours avant d'exécuter
+- **Aucune étape sautée** — même pour les "petites" features
+- **Aucune implémentation sans validation du dispatch** (étape 4)
+- **DISCOVERY est obligatoire** — pas de feature sur projet flou
+- **REVIEW est qualitatif, VALIDATE est quantitatif** — les deux sont nécessaires
+- **REFACTOR ne fait que corriger** — pas de nouvelle feature, pas de re-design
+- **DOC est livrable**, pas un nice-to-have — feature non documentée = feature non livrée
+- **Zero Trust** : BYAN challenge avant d'exécuter (source: Mantra IA-25)
 - **Ockham's Razor** : si deux solutions existent, prendre la plus simple
 - **Pas de YAGNI** : on ne build pas "au cas où"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-byan-agent",
-  "version": "2.14.1",
+  "version": "2.16.1",
   "description": "BYAN v2.8 - Intelligent AI agent creator with ELO trust system + scientific fact-check + Hermes universal dispatcher + native Claude Code integration (hooks, skills, MCP server). Multi-platform (Copilot CLI, Claude Code, Codex). Merise Agile + TDD + 64 Mantras. ~54% LLM cost savings.",
   "main": "src/index.js",
   "bin": {