@atlashub/smartstack-cli 4.80.0 → 5.0.0

package/templates/skills/business-analyse/audit-use-cases/SKILL.md

@@ -0,0 +1,245 @@
+---
+name: ba-audit-use-cases
+description: >
+  Audits the use cases of a `.smartstack/ba/` module — completeness, step
+  quality, vague language, scope respect, actor references, redundancy, and
+  acceptance-criteria contract (UC-001..018). Reads the section `use-case.md`
+  files + the app `acteur.md` + the module `entité.md` (for AC entity refs),
+  writes a verdict to `<MODULE>/_audit/use-case.md`. Run after
+  `/ba-create-use-case` or as part of pre-dev readiness.
+allowed-tools: [Read, Write, Glob, Grep]
+---
+
+# ba-audit-use-cases — Use Cases audit
+
+You audit the use cases of a `.smartstack/ba/` module against the rules below and
+write a verdict file. The rules are unchanged from the SmartStack convention;
+only the I/O is file-based.
+
+## File model — how to audit
+
+1. **Read state**: `Glob .smartstack/ba/<APP>/<MODULE>/**/use-case.md` to find the
+   section-level use cases. `use-case.md` is authoritative at the **section**
+   level (`.smartstack/ba/<APP>/<MODULE>/<section>/use-case.md`) — read each one.
+   Each UC is a `### UC-{APP}-{MOD}-{SEC}-NNN — Title` heading with **Acteur
+   principal**, **Acteurs secondaires**, **Préconditions**, **Flux principal**,
+   **Flux alternatifs**, **Exceptions**, **Postconditions**, **Règles liées**,
+   **Écrans liés**, **Acceptance Criteria** fields (see `_workflow/doc-templates.md`).
+   Also read the module `index.md` (its `## Contexte` is the scope anchor for
+   UC-011), the app `acteur.md` (`.smartstack/ba/<APP>/acteur.md`) to validate
+   actor refs by `BA-{NNN}-AC-{NNN}` code, and the module `entité.md` (for the
+   AC entity-reference rule UC-018).
+2. **Apply** the rules UC-001..018 (below) to the use cases of this module.
+   UC-013..018 cover the **acceptance-criteria contract** under each UC's
+   `**Acceptance Criteria**` field — the test-scaffolder's input.
+3. **Write** the verdict to `.smartstack/ba/<APP>/<MODULE>/_audit/use-case.md`
+   (module-level aggregate of its sections' use cases) using the audit-verdict
+   skeleton from `_workflow/doc-templates.md`. Then print a 3–6 line business
+   summary in chat.
+
+There is no database, no `[ACTION]` envelope, no i18n label codes — the `.md`
+verdict IS the record. The verdict header (`0 err` = pass) is what a downstream
+gate reads.
+
+A field is **empty** when its bullet is absent or carries only an em-dash / "—" /
+"(aucun)" placeholder. Treat such a field as empty for the rules below; never
+infer content that is not written.
+
+## Scoping
+
+Audit ONLY the use cases of the active module (`.smartstack/ba/<APP>/<MODULE>/`).
+Use cases from other modules are out of scope and MUST NOT be counted, flagged,
+or compared.
+
+In particular: **UC-010 (redundancy) compares ONLY UCs of the same module**. Two
+UCs with similar titles in different modules (e.g. "Créer un brouillon" in
+`BILLING/INVOICES` and `BILLING/CREDIT_NOTES`) are legitimate. Never flag
+inter-module redundancy.
+
+## Verdict
+
+A single `err` finding makes the verdict fail (`N err` with N ≥ 1 in the header),
+which **blocks the next phase** (business rules). The user must correct the
+offending UCs and re-audit. UC-001..013 and UC-019 emit only `err` or `ok`
+(blocking gates). UC-014..018 (acceptance-criteria contract) may emit `warn`
+(non-blocking quality signals). Emit one finding per applicable rule, even
+when `ok`.
+
+## Rules
+
+### UC-001 — At least 1 use case exists per module
+- **Severity**: err if 0 UCs in the audited module, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-002 — Every section has at least 1 use case
+- **Severity**: err if any section has 0 UCs, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-003 — Every UC has a non-empty main flow
+- **Severity**: err if any UC has an empty **Flux principal**, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-004 — Every UC has at least 1 precondition
+- **Severity**: err if any UC has empty **Préconditions**, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-005 — Every UC has at least 1 postcondition
+- **Severity**: err if any UC has empty **Postconditions**, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-006 — Every UC has at least 1 alternative OR exception flow
+- **Severity**: err if any UC has BOTH empty **Flux alternatifs** AND empty
+  **Exceptions**, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-007 — No vague language and no placeholder steps
+Scan every step in **Flux principal**, **Préconditions**, **Postconditions**,
+alternative/exception flow steps:
+
+- **Vague verbs (anywhere in a step)**: `gere`, `gère`, `traite`, `handle`, `manage`, `process`, `facilement`, `easily`, `rapidement`, `quickly`, `efficacement`, `efficiently`, `correctement`, `correctly`, `fait`, `does`. A vague verb passes only if followed by a precise object phrase (e.g. "gérer le rapprochement bancaire" passes; "gérer la facture" fails).
+- **Placeholder steps (whole step matches)**: `TODO`, `tbd`, `fixme`, `à compléter`, `a completer`, `à faire`, `…`, `...`, single-character entries.
+- **Severity**: err if any UC contains at least one vague-verb or placeholder occurrence, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-008 — All actor references point to existing actors
+Check **Acteur principal** and every code in **Acteurs secondaires** against the
+app `acteur.md` (`.smartstack/ba/<APP>/acteur.md`). Grep the `BA-{NNN}-AC-{NNN}`
+code there — if it is not found, the reference is orphan.
+- **Severity**: err if any reference is orphan, ok else.
+- Fix: `/ba-create-actors`.
+
+### UC-009 — Every UC's main flow has at least 3 imperative steps
+A 1- or 2-step main flow is not a flow; it is a stub.
+- **Severity**: err if any UC's **Flux principal** has fewer than 3 steps, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-010 — No redundancy WITHIN the audited module
+Two UCs of the **same module** are redundant if either holds:
+- Their normalised titles are identical (lowercase, accents removed, leading articles `le/la/les/un/une/the/a/an` stripped, trailing punctuation trimmed).
+- ≥ 80 % of their main-flow steps are textually equivalent after the same normalisation.
+
+Compare ONLY UCs that share the same module. Never compare across modules — same
+title in two modules is legitimate.
+- **Severity**: err if any redundant pair is detected, ok else.
+- Fix: `/ba-create-use-case`.
+- **solution** template: `Fusionne ou supprime le doublon entre <UC-A> et <UC-B>. Garde le plus complet et redirige les références.`
+
+### UC-011 — Every UC stays within its module's business scope
+The title and every step (in **Flux principal**, alt/exception flows,
+**Préconditions**, **Postconditions**) of each UC MUST describe activities
+consistent with the parent module's `## Contexte` (read from the module
+`index.md`).
+
+Out-of-scope examples:
+- A UC under `BILLING` that talks about salary management or absences (HR territory)
+- A UC under `HR` that adjusts inventory levels (STOCK territory)
+- A UC under `STOCK` that schedules meals (RESTAURATION territory)
+
+Anchor on the module's `## Contexte` text (always present in the module
+`index.md`). When a step or title introduces a concept that the module's context
+does not name and that does not chain logically from the section's purpose, flag
+it. The burden of proof falls on the foreign concept, not on the auditor — when
+in doubt, flag and let the user decide.
+
+- **Severity**: err if any UC drifts outside its module's domain, ok else.
+- Fix: `/ba-create-use-case`.
+- **solution** template: `<UC-code> sort du périmètre du module <module>. Soit supprime-le, soit déplace-le vers <module-cible>, soit recadre titre et étapes dans le contexte de <module>.`
+
+### UC-012 — Acceptance criteria populated for `user-goal` UCs
+Every UC at `user-goal` level MUST have acceptance criteria (≥ 1 entry) under a
+`**Acceptance Criteria**` field. Subfunctions and summary-level UCs are exempt.
+(When the UC level is not stated, treat a UC bound to a primary actor goal as
+`user-goal`.) The AC field must be present and contain ≥ 1 `- [ ] AC-NN — …` bullet.
+- **Severity**: err if any user-goal UC has empty acceptance criteria, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-013 — AC id format & locality
+Every acceptance criterion id matches `^AC-\d{2}$` (zero-padded 2 digits, local to
+its UC — globally unique form is `<UC-code>#AC-NN`). The bullet shape is
+`- [ ] AC-NN — <assertion>`. Catches drift from the legacy `AC-US{n}-{m}` global
+scheme and accidental `AC-1`/`AC-001` typos.
+- **Severity**: err if any AC bullet does not match, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-014 — AC ids unique within UC, sequential, no gaps
+Within each UC, the `NN` indices of `AC-NN` are unique, start at `01`, and have
+no gap. Gaps break the test-scaffolder's `[Fact]` numbering and make AC
+references in business rules ambiguous.
+- **Severity**: warn if a gap or duplicate is found, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-015 — Each AC is a single assertion (no compound)
+Each `- [ ] AC-NN — …` line is a single sentence with one assertion. Lines chaining
+two independent clauses with ` and / et / or / ou ` (outside a noun phrase) must
+be split into separate AC ids — `scaffold-tests-from-ac` emits one `[Fact]` per
+AC, so a compound AC silently collapses two test cases into one.
+- **Severity**: warn if any AC chains two independent clauses, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-016 — AC uses testable verbs (indicative, not modal)
+Each AC uses an **imperative testable verb** (`renvoie`, `rejette`, `affiche`,
+`persiste`, `émet`, `returns`, `rejects`, `displays`, `persists`, `emits`) in the
+indicative; modal phrasing (`devrait`, `peut`, `should`, `might`, `may`) is
+banned because it is not testable. Also reject vague verbs (`gère`, `traite`,
+`handles`, `manages`, `supports`) without a concrete observable outcome.
+- **Severity**: warn if any AC uses a modal or vague verb, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-017 — AC has no unspecified non-functional adjective
+Reject AC that include `rapidement`, `intuitif`, `performant`, `user-friendly`,
+`fast`, `scalable`, `responsive` without a concrete numeric threshold (e.g.
+`< 200 ms`, `≥ 60 fps`, `≤ 1 MB`). Vague non-functional claims are not testable.
+- **Severity**: warn if any AC contains a banned adjective with no concrete
+  threshold, ok else.
+- Fix: `/ba-create-use-case`.
+
+### UC-018 — AC entity references resolve upstream
+When an AC names an entity (PascalCase token that does not equal the UC's own
+section name and is not a HTTP verb / status code / common noun), that entity
+exists in the module's `entité.md` (PascalCase name or BA `ENT-…` code). Catches
+ACs that assert against an entity nobody declared.
+- **Severity**: warn if any AC names an undeclared entity, ok else.
+- Fix: `/ba-create-data-model` (declare the entity) or `/ba-create-use-case`
+  (rephrase the AC).
+
+### UC-019 — UC code section exists in the menu tree
+Every UC's code is `UC-{APP}-{MOD}-{SEC}-NNN`. The `{SEC}` segment MUST
+correspond to a section folder currently present in the menu tree —
+`<baRoot>/<APP>/<MOD>/<sec-folder>/index.md` MUST exist, with the section
+code derived from the kebab folder name (uppercase + `-` → `_`,
+`opportunites` → `OPPORTUNITES`, `exchange-history` → `EXCHANGE_HISTORY`).
+Catches orphan UCs left behind when the menu was edited (`/ba-create-menu`)
+after the use cases were generated. The block is greppable but `/ba-develop`
+crashes on invalid section codes during scaffolding.
+- **Severity**: err if any UC code references a deleted/renamed section, ok
+  else.
+- Fix: `/ba-reconcile-menu` (preflight that renames or deletes orphans with
+  user validation), then re-run `/ba-loop` to re-enrich.
+
+## Output
+
+Write `_audit/use-case.md` per the doc-templates audit-verdict skeleton:
+- Anchor `<!-- ba:audit dimension=use-case scope=<APP>/<MODULE> -->`.
+- Header `# Audit cas d'usage — <APP> / <MODULE>` + `_<date> · Verdict : <emoji>
+  N warn · M err · K ok_` (UC-014..018 may emit `warn`; UC-001..013 and
+  UC-019 emit only `err` or `ok`).
+- `## ✅ Conforme`, `## ⚠️ Avertissements`, `## ❌ Bloquants` sections; one bullet
+  per finding. For each finding: what's wrong (offending UC codes **bold**, AC
+  ids when applicable), why it matters, and a `→` fix naming `/ba-create-use-case`
+  (or `/ba-create-actors` for UC-008 — a missing actor; or `/ba-create-data-model`
+  for UC-018 — a missing entity declaration; or `/ba-reconcile-menu` for UC-019
+  — a stale section reference). Cite the offending UC codes and AC ids verbatim
+  from the files.
+- Rule codes (`UC-001`, …) stay **bold** so they remain greppable, but explain
+  them in business terms.
+- Re-Write the whole file each run (overwrite — it's a fresh verdict).
+
+Then a 3–6 line chat summary in the user's language — business terms, not rule
+codes. If any `err`, state clearly that the use cases must be fixed before moving
+on to the business rules.
+
+## Used by the readiness orchestrator
+
+`/ba-audit-pre-dev` runs every dimension and aggregates the verdicts. When invoked
+by it, still write `_audit/use-case.md` as usual — the orchestrator reads these
+files.

package/templates/skills/business-analyse/create-actors/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: ba-create-actors
+description: >
+  Phase 2 of business analysis. Defines the project's actors (roles) that
+  interact with the applications, and writes them to `acteur.md` at the
+  Application level under `.smartstack/ba/`. Conversational: reads the menu tree
+  and existing actors, proposes coverage per app, asks the user to validate, then
+  writes the file. Run after the menu (`/ba-create-menu`), before use cases.
+allowed-tools: [Read, Write, Edit, Glob, Grep, AskUserQuestion]
+---
+
+# ba-create-actors — Project-scoped actors
+
+You define the **actors** (roles) that interact with the applications — the WHO,
+not the permissions (those come later in RBAC). Actors are **project-scoped**: an
+actor defined once can be linked to several applications. Reuse is the default.
+
+## File model — state & persistence (read first, every turn)
+
+State lives in `.smartstack/ba/`. There is no database and no action blocks.
+
+1. **Read state**: `Glob .smartstack/ba/**/index.md` for the menu tree (apps =
+   top-level folders; read each app `index.md` `## Contexte` to know what it
+   does). Read existing `.smartstack/ba/<APP>/acteur.md` files for actors already
+   defined (reuse candidates).
+2. **Propose** actors per application in prose (list each `code` + label + type).
+3. **Ask** the user to validate with **AskUserQuestion** (one multi-select per
+   application). Open exploration questions go in prose.
+4. **Write** `acteur.md` with the **Write** tool once validated. A Write
+   overwrites the file — re-list every actor that must survive.
+
+If the menu tree is empty, defer: tell the user to define the menu first
+(`/ba-create-menu`). Do not propose actors without applications.
+
+### Where actors are written (authority)
+
+`acteur.md` is **authoritative at the Application level**:
+`.smartstack/ba/<APP>/acteur.md`. The placeholder `acteur.md` that the menu phase
+left at module/section/resource levels stays a **rollup pointer** — replace it
+with one line `> Acteurs hérités — voir [../acteur.md](../acteur.md)` (do not
+duplicate actor content downward). An actor active on several apps is written in
+each of those apps' `acteur.md`, with its `Périmètre` line saying which
+modules/sections it covers.
+
+### `acteur.md` shape (authoritative, at the app)
+
+```markdown
+<!-- ba:acteur level=application code=CRM -->
+# Acteurs — CRM
+
+### BA-001-AC-001 — Commercial
+- **Type** : internal
+- **Description** : Gère son portefeuille de prospects et opportunités.
+- **Périmètre** : CRM (toute l'application)
+- **Origine** : conversation
+
+### BA-001-AC-002 — Manager commercial
+- **Type** : internal
+- **Description** : Supervise l'équipe et valide les remises.
+- **Périmètre** : CRM / PIPELINE
+- **Origine** : code (rôle détecté)
+```
+
+## Actor fields
+
+| Field | Rules |
+|-------|-------|
+| code | `BA-{analysisSeq}-AC-{NNN}` — `analysisSeq` is the 3-digit project sequence (first project = `001`), `NNN` a 3-digit per-project counter. Grep existing `acteur.md` headings to find taken numbers and increment. The number, never the label, is the identity. |
+| label | Human label in the user's language (accents OK). |
+| Type | `internal` (employees/admins, direct access), `external` (clients/partners/candidates via a portal), or `system` (background services). |
+| Description | One sentence on the role. **Required.** |
+| Périmètre | The app, optionally a module/section, the actor covers. App-wide when only the app is named; module-restricted when a module is named. |
+| Origine | Traceability: where the proposal came from (conversation / code / user decision). **Required.** |
+
+## Exploration — before proposing
+
+1. **Read existing actors** from the `acteur.md` files (reuse candidates — never
+   re-create an actor that exists; add a `Périmètre` line instead).
+2. **Scan existing code** if the project has any: authorization attributes, role
+   enums, permission seeds, frontend role constants. Extract the real role
+   identifiers — use the codebase's own names, don't invent.
+3. **Read each app's `## Contexte`** — it tells you who interacts with the app.
+4. **Present a short summary**: actors already defined (N), roles found in code
+   (M), applications in the project. No invented content — if a category is
+   empty, say so.
+
+## Proposing actors
+
+For each application, propose the interacting actors via one AskUserQuestion
+multi-select (pre-select the obvious ones). Every actor MUST trace to the user's
+request, the app `## Contexte`, the code scan, or the user's explicit answers.
+Tag each as *réutilisé* / *détecté* / *inféré* in the prose, with a concrete
+source. Ask open questions about the organisation when context is thin — never
+dump a generic list.
+
+## Absolute prohibitions
+
+1. **Never hardcode domain archetypes** (HR managers, accountants, "admin",
+   "user", "viewer") without anchoring them to the user's actual organisation.
+2. **Never use CRUD-style codes** (`CREATE_USER`, `READ_ACCESS`) — those are
+   permissions, not roles. Actors are WHO, not WHAT-THEY-DO.
+3. **Never invent codes or labels** — every actor traces to the conversation,
+   the code scan, or an existing `acteur.md`.
+4. **Never assign a `Type` without justification** — ask if uncertain.
+5. **Never reuse a removed actor number** in the same project.
+
+## Self-check before writing (actors → use-cases gate)
+
+Before writing, verify each actor has a well-formed `BA-…-AC-…` code, a `Type`, a
+non-empty `Description`, and an `Origine`. Surface any gap to the user instead of
+writing a half-defined actor. (The deeper audit — duplicates, missing types,
+coverage ACT-001..006 — is run by `/ba-audit-actors`, which reads the
+`acteur.md` files and writes its verdict; you don't produce audit findings here.)
+
+## After writing → hand off to use cases
+
+Acknowledge in one line ("4 acteurs définis pour CRM."). Then, per the fixed
+order, the next phase is **use cases** — propose continuing with
+`/ba-create-use-case` (don't ask "what next?"). Convert any descendant
+`acteur.md` placeholders you encounter into the one-line rollup pointer.
+
+## Edge cases
+
+| Situation | Action |
+|-----------|--------|
+| Actor already exists, only a new app link | Don't re-create — add a `Périmètre` line in that app's `acteur.md` |
+| User removes an actor from an app | Re-Write the app's `acteur.md` without it (overwrite drops it) |
+| Actor exists with a different label | Confirm the change with the user, keep the code |
+| Same actor across several apps | Write it in each app's `acteur.md`, code identical, `Périmètre` per app |

package/templates/skills/business-analyse/create-ba-order/SKILL.md

@@ -0,0 +1,182 @@
+---
+name: ba-create-ba-order
+description: >
+  After Phase 1 (menu), produces a BA creation order plan — a topologically-sorted
+  ordering of modules showing which modules to work on first across all BA phases
+  (actors → use cases → rules → RBAC → data model → screens). Conversational:
+  reads module contexts, infers inter-module dependencies, asks the user to
+  validate, then writes the plan. Run after /ba-create-menu, before /ba-create-actors.
+group: G
+argument-hint: '[APP1] [APP2] …'
+allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]  # Bash: CLI invocation
+---
+
+# BA Creation Order — Phase 1.5
+
+You are the **BA ordering planner**. After the menu tree is complete, you
+determine in which order the user should work on each module across the
+remaining BA phases (actors → use cases → rules → RBAC → data model → screens).
+
+## Why ordering matters
+
+If module BILLING depends on module REFERENCES (because invoices use
+currencies, countries, statuses defined in the reference data module), then the
+data model, use cases, and rules of REFERENCES must be defined **before**
+BILLING — otherwise cross-module FK references, shared actors, and
+business rules cannot be properly specified.
+
+## Inputs
+
+The `.smartstack/ba/` tree must already exist with at least one application and
+its modules (i.e., `/ba-create-menu` Phase 1 is complete).
+
+Optional argument: application codes to scope (e.g., `ERP BILLING`). If
+omitted, all applications in the tree are included.
+
+## Workflow
+
+### Step 1 — Discover modules
+
+Read the BA tree to find all modules:
+
+```
+Glob .smartstack/ba/**/index.md
+```
+
+Filter to `level=module` nodes (anchor contains `level=module`). For each,
+read the `## Contexte` section (2-3 sentences describing the module's
+business purpose).
+
+### Step 2 — Infer dependencies
+
+Read **all** module contexts together and infer the dependency graph:
+
+- A module that manages **reference data** (countries, currencies, statuses,
+  categories…) is likely **foundational** — other modules depend on it.
+- A module whose context mentions concepts managed by another module likely
+  **depends on** that module.
+- A module that manages **transactional data** (orders, invoices, tickets…)
+  often depends on reference data and master data modules.
+- There is **no fixed taxonomy** — any module can depend on any other.
+  A transactional module can depend on another transactional module.
+- Look for **explicit mentions** in `## Contexte` and `## Hors-périmètre`
+  that reference other module names or concepts.
+- Cross-application dependencies are valid (e.g., `BILLING/INVOICES` depends
+  on `CRM/CONTACTS`).
+
+Build a list:
+
+```
+MODULE_A depends on: (nothing — foundational)
+MODULE_B depends on: MODULE_A (uses A's reference data)
+MODULE_C depends on: MODULE_A, MODULE_B (uses both)
+```
+
+### Step 3 — User validation
+
+Present the full dependency graph as a **single AskUserQuestion** with a
+table of modules and their inferred dependencies. Two choices:
+**Valider** or **Corriger**.
+
+Example presentation:
+
+```
+J'ai analysé les contextes de vos 5 modules. Voici le graphe de dépendances
+que j'en déduis :
+
+| Module | Dépend de | Raison |
+|--------|-----------|--------|
+| ERP/REFERENCES | — | Reference data (countries, currencies, statuses) |
+| ERP/CUSTOMERS | ERP/REFERENCES | Customers use reference countries and currencies |
+| ERP/BILLING | ERP/REFERENCES, ERP/CUSTOMERS | Invoices linked to customers and currencies |
+| ERP/REPORTS | ERP/BILLING, ERP/CUSTOMERS | Reporting on invoices and customers |
+| ERP/SETTINGS | — | Application configuration independent |
+
+→ Cela donne 3 vagues :
+  Wave 1 : REFERENCES, SETTINGS (aucune dépendance)
+  Wave 2 : CUSTOMERS (dépend de Wave 1)
+  Wave 3 : BILLING, REPORTS (dépendent de Wave 1-2)
+```
+
+On **Corriger**: parse the user's free-text corrections, update the graph,
+and re-present. On **Valider**: proceed to Step 4.
+
+### Step 4 — Generate the plan
+
+Invoke the CLI to produce the topologically sorted plan:
+
+```bash
+npx tsx skills/business-analyse/create-ba-order/cli/create-ba-order/index.ts \
+  --spec '{"baRoot": ".smartstack/ba", "apps": ["ERP"], "modules": [
+    {"appCode": "ERP", "moduleCode": "REFERENCES", "dependsOn": []},
+    {"appCode": "ERP", "moduleCode": "CUSTOMERS", "dependsOn": ["ERP/REFERENCES"]},
+    {"appCode": "ERP", "moduleCode": "BILLING", "dependsOn": ["ERP/REFERENCES", "ERP/CUSTOMERS"]}
+  ]}'
+```
+
+The CLI writes:
+- `.smartstack/ba/_plan/ba-order.md` — human-readable plan (summary + waves + Mermaid graph + next steps)
+- `.smartstack/ba/_plan/ba-order.json` — machine-readable plan for downstream tools
+
+### Step 5 — Update module index.md files
+
+For each module, update its `index.md` to persist the dependency metadata:
+
+**Anchor comment** — add `depends=` attribute (comma-separated ModuleKeys):
+
+```markdown
+<!-- ba:node kind=node level=module code=BILLING depends=ERP/REFERENCES,ERP/CUSTOMERS -->
+```
+
+If the module has no dependencies, omit the `depends=` attribute entirely (don't
+write `depends=`).
+
+**New `## Dépendances` section** — insert between `## Hors-périmètre` and
+`## Enfants` (or after `## Contexte` if there is no `## Hors-périmètre`):
+
+For a module **with** dependencies:
+```markdown
+## Dépendances
+- [REFERENTIELS](../REFERENTIELS/index.md) — utilise les devises, pays, statuts
+- [CLIENTS](../CLIENTS/index.md) — factures liées aux clients
+```
+
+For a module **without** dependencies:
+```markdown
+## Dépendances
+_Aucune — module fondationnel._
+```
+
+Use `Edit` to update each `index.md`. Preserve existing content. If a
+`## Dépendances` section already exists, replace it.
+
+### Step 6 — Hand off
+
+Acknowledge completion and offer two paths:
+
+> "Ordre BA établi — X modules répartis en Y vagues."
+>
+> - **`/ba-loop`** — lancement automatique des phases 2-7 (create → audit → fix
+>   en boucle, un subagent par phase par module)
+> - **`/ba-create-actors`** — démarrage manuel, phase par phase
+
+## Decision table
+
+| Situation | Action |
+|-----------|--------|
+| No modules found | Error: run `/ba-create-menu` first |
+| Single module | Trivial plan (Wave 1 only), still write the files |
+| Circular dependency detected | Warn, place cycle members in same wave |
+| Cross-app dependency within scope | Normal internal edge |
+| Cross-app dependency outside scope | Wave 0 external prerequisite |
+| User says "Corriger" | Parse corrections, rebuild graph, re-present |
+| User says "Valider" | Invoke CLI, write plan, update index.md |
+
+## Guard rails
+
+- Never invent modules that don't exist in the tree.
+- Never change the `## Contexte` or `## Enfants` of an `index.md` — only
+  add/update the anchor `depends=` attribute and the `## Dépendances` section.
+- The dependency graph is **directional**: A depends on B means B must be
+  analysed first (not vice versa).
+- Always present the full graph before invoking the CLI — no silent generation.