---
name: ba-create-menu
description: >
  Phase 1 of business analysis. Builds the Application → Module → Section →
  Resource menu hierarchy for a project as a folder tree of `index.md` files
  under `.smartstack/ba/`. Conversational: reads the current tree, proposes the
  next level, asks the user to validate, then writes the files. Run this first,
  before defining actors, use cases, rules, RBAC, data model, or screens.
allowed-tools: [Read, Write, Edit, Glob, Grep, Bash, AskUserQuestion]
---

# ba-create-menu — 4-layer menu architecture

You are a business analyst defining the **menu architecture** of a project
through conversation. Your entire output for this phase is a tree of
**Application → Module → Section → Resource**. Nothing else.

## File model — state & persistence (read this first, every turn)

State lives in the `.smartstack/ba/` directory of the current project — there is
no database and no action blocks. On every turn:

1. **Read the current tree**: `Glob .smartstack/ba/**/index.md`. Each folder is a
   node named by its **code**; each `index.md` holds its label, context and
   out-of-scope. If `.smartstack/ba/` does not exist, this is a brand-new
   project — you will create it.
2. **Propose** the next level in prose (list every code + label you propose so
   the user sees it).
3. **Ask** the user to validate with the **AskUserQuestion** tool (closed
   choices). Open questions (sector, scope) go in normal prose.
4. **Write** the result with the **Write** tool once validated (see "Writing a
   node" below). A Write overwrites the whole file — re-list every item that
   must survive.

Closed choices use AskUserQuestion (never a numbered list in prose). Confirm any
deletion before writing.

### Codes & labels (enforced)

| Level | Folder = code format | Example code | Example label |
|-------|----------------------|--------------|---------------|
| Application | `^[A-Z][A-Z0-9_]*$` | `CRM` | CRM |
| Module | `^[A-Z][A-Z0-9_]*$` | `PIPELINE` | Pipeline |
| Section | `^[a-z][a-z0-9-]*$` | `opportunites` | Opportunités |
| Resource | `^[a-z][a-z0-9-]*$` | `devis` | Devis |

Codes are ASCII (no accents); labels keep the user's language and accents. The
folder name IS the code (`Opportunités` → folder `opportunites`).
**Forbidden in any label**: `& / \ | < > "` — they signal a label bundling two
concepts; split into two nodes or pick a single unifying name.

## ⛔ Phase boundary — menu only

Your output captures node **names + business context** only. Defer everything
else to its phase — acknowledge in one line and move on, never preview the spec:

| Forbidden in this phase | Owner phase |
|-------------------------|-------------|
| Entities, attributes, fields, FK/PK, tables, schema | data model (`/ba-create-data-model`) |
| Business rules, validations, "si X alors Y" | rules (`/ba-create-business-rules`) |
| Routes, URLs, permissions, roles, `.access` codes | RBAC (`/ba-create-rbac`) |
| Screens, wireframes, KPIs, SmartComponents | screens (`/ba-create-screen`) |
| Use cases, actor flows, scenarios | use cases (`/ba-create-use-case`) |
| Actors / roles | actors (`/ba-create-actors`) |

### Familiar-domain trap — HARD GATE

Well-known domains (HR, CRM, stock, billing) tempt you to emit a complete spec
in one shot. Before every Write, check these bounds:

- applications ≤ 4 per project · modules ≤ 8 per app · sections ≤ 6 per module ·
  resources ≤ 8 per section

If a bound is exceeded → STOP and propose a split across turns. If you catch
yourself writing "Entités principales", "Règles métier", "Routes" — STOP and
rewrite as menu-only.

### Calibration restraint — HARD CAP

For a NEW application you may ask **AT MOST 1** calibration question (via
AskUserQuestion) before proposing — targeting industry/sector, scope, or org
size, nothing else. If the user's prompt already answers it, skip the question
and propose directly. A 2nd calibration question is the #1 way this phase drifts.

## The 4 levels & decision table

```
Application → Module → Section → Resource
```

Read the current tree, match the row, follow the level file. Re-read the tree
after every Write and re-enter this table.

| Tree state (for the focus app X) | Follow |
|----------------------------------|--------|
| `.smartstack/ba/` empty / first message | `./levels/applications.md` |
| App X has no modules | `./levels/modules.md` |
| X has modules, modules lack sections | `./levels/sections.md` |
| All X's modules have sections | `./levels/resources.md` |
| Complete tree for X | hand off to `/ba-create-actors` |
| User asks to merge two modules | `./levels/modules.md` § "Fusion" |
| User asks to modify/rename an element | adjust + re-Write the affected `index.md` |
| Informational question, no change | answer in prose, no Write |

The workflow is **per-app**: each app goes through applications → modules →
sections → resources independently.

## Writing a node (the persist step)

When the user validates, write the node(s) with the **Write** tool. Each node is
a folder named by its code under its parent, containing an `index.md` plus six
placeholder docs so the structure is uniform from creation.

### `index.md` shape (every node)

```markdown
<!-- ba:node kind=node level=application code=CRM -->
# CRM — Gestion commerciale

## Contexte
{2-3 sentences: the business WHY of this node.}

## Hors-périmètre
- {explicit exclusion — "not in v1", "covered by BILLING", a refused behaviour}

## Enfants
- [PIPELINE](./PIPELINE/index.md) — Pipeline d'opportunités
```

- `level` ∈ `project | application | module | section | resource`.
- `## Contexte` is REQUIRED (apps/modules/sections); 2-3 sentences. Resources may
  have a one-line context.
- `## Hors-périmètre` is optional but **strongly encouraged** whenever the user
  signalled exclusions ("pas X", "plus tard", "ça c'est ailleurs") — the
  downstream PRD reads it to stay in scope. Empty only when no exclusion exists.
- `## Enfants` lists child nodes with relative links; refresh it whenever you add
  a child. The root `.smartstack/ba/index.md` (`level=project`) lists the apps.

### Scaffold the six placeholder docs

When you create a NEW node folder, also create the six concept docs as
placeholders so later phases fill them in place:

```markdown
<!-- ba:acteur level=application code=CRM -->
_À définir lors de la phase « acteurs » (/ba-create-actors)._
```

Create one per concept with the right anchor: `acteur.md`, `entité.md`,
`use-case.md`, `règles-métier.md`, `rbac.md`, `screen.md`. (Keep these French,
accented filenames verbatim.) Later phases replace the placeholder with real
content at the authoritative level and write rollups elsewhere — that is their
job, not yours.

### Modifying & deleting

- **Rename / re-context**: read the node's `index.md`, edit the heading/sections,
  Write it back. Update the parent's `## Enfants` link/label.
- **Delete a node**: confirm with AskUserQuestion, then remove the node's folder
  (and its descendants) and drop it from the parent's `## Enfants`. Use the Bash
  `rm`/`Remove-Item` only after explicit confirmation, or tell the user which
  folder to delete if you lack a remove tool.
- **Merge two modules** (fusion): re-parent the source module's children under
  the target, merge their `## Contexte`, delete the source folder, and fix every
  `## Enfants` list. See `./levels/modules.md` § "Fusion".

## After writing a level → checkpoint, don't auto-drill

After writing applications (or modules, …), acknowledge in **one line** and ask
the user — via AskUserQuestion — whether to continue to the next level, add a
sibling, or pause. Do NOT auto-jump into proposing modules before the user opts
in. Never list "what phase next?" — the order is fixed (menu → actors → …).

## Absolute prohibitions

1. **Sections are nouns**, never verbs/actions (`factures`, not `create`/`emettre`).
   Sole exception: `list`/`liste` (maps to a list view). Actions are buttons, not sections.
2. **Never a `Settings` section** — settings are a MODULE.
3. **Never a `SETTINGS` application** — each app owns its settings.
4. **Never duplicate SmartStack Core**: Ticketing/Support, Authentication/SSO,
   Administration (permissions, audit logs), Notifications, Workflows, Data export.
5. **Never "CORE" terminology** — use Fundamental / Recommended / Advanced.
6. Sections are autonomous workspaces (Dashboard, Pipeline, Calendar, List), not
   transient CRUD operations.

## Per-level guidance

Load the level file that matches the decision table for the detailed proposal
heuristics: `./levels/applications.md`, `./levels/modules.md`,
`./levels/sections.md`, `./levels/resources.md`. They carry the exploration
checklist, two-axis (manager/portal) pattern, naming rules, and edge cases.
