@frontfactory/brigade 1.1.0 → 1.2.0

package/README.md

@@ -4,7 +4,11 @@
 [![Downloads](https://flat.badgen.net/npm/dt/@frontfactory/brigade)](https://www.npmjs.com/package/@frontfactory/brigade)
 [![License](https://flat.badgen.net/npm/license/@frontfactory/brigade)](https://www.npmjs.com/package/@frontfactory/brigade)
 
-Sets up a Claude Code architecture in any project, new or existing, without fuss.
+Claude Code, organized like a kitchen brigade.
+
+Brigade sets up a Claude Code architecture in any web project, new or existing, without fuss: a main session that
+thinks and orchestrates, an `implementer` that writes the code and a `git-operator` that handles git, each limited to
+its mission, with guardrails built in.
 
 ```sh
 npx @frontfactory/brigade init
@@ -14,18 +18,19 @@ npx @frontfactory/brigade init
 
 Three roles, each limited to its mission:
 
-| Role | Model (default effort) | Mission |
-|---|---|---|
-| Main session | Opus in Plan Mode (medium) | Discuss, think, orchestrate, verify, propose, answer. Goes back and forth with the subagents. |
-| `implementer` | Sonnet (medium) | Development, nothing else. |
-| `git-operator` | Haiku (low) | Git, nothing else, once the work is done. |
+| Role           | Model (default effort)     | Mission                                                                                       |
+|----------------|----------------------------|-----------------------------------------------------------------------------------------------|
+| Main session   | Opus in Plan Mode (medium) | Discuss, think, orchestrate, verify, propose, answer. Goes back and forth with the subagents. |
+| `implementer`  | Sonnet (medium)            | Development, nothing else.                                                                    |
+| `git-operator` | Haiku (low)                | Git, nothing else, once the work is done.                                                     |
 
 Plus base rules for work, security and efficiency, adapted to the stack (web for now). The setup is shared with the
 project and committed with it. Each developer can override their own effort locally with `/brigade-effort`.
 
 The rest of the kit, all under `.claude/`:
 
-- Skills: `session-start` (where things stand before the first task), `feature` (branch + state file for multi-step work),
+- Skills: `session-start` (where things stand before the first task), `feature` (branch + state file for multi-step
+  work),
   `audit` (keep an audit file between sessions).
 - Commands: `/brigade-effort` (your effort per role) and `/brigade-language` (your reply language), both local and
   not committed.
@@ -35,41 +40,54 @@ The rest of the kit, all under `.claude/`:
 
 ## Install
 
-`init` detects the default branch, the package manager, the commit convention and the language, and asks you to
-validate each one. `--yes` (or `-y`) accepts everything detected. `--stack <name>` forces the stack instead of
-detecting it (only `web` for now).
+`init` detects the default branch, the package manager, the commit convention and the language, then shows what will
+be set up in one card. Choose "Install as is" (the default) or "Customize" to answer every option one by one. An option
+that cannot be detected is asked even in the express path. After "Customize", or when something had to be asked, a recap
+is shown before anything is written: "Everything is right" installs, "Change something" lets you pick the groups to
+redo (branches, package manager, commit format, languages) and shows the recap again. There are two language
+questions: the language of Claude's replies, then the language of code and docs together, or "Different for code and
+docs" to choose each apart. Customize also asks your own reply language, which stays on your machine. Cancelling writes
+nothing. `--yes` (or `-y`) accepts everything detected. `--stack <name>` forces the stack instead of detecting it (only
+`web` for now).
 
 Brigade never touches your `CLAUDE.md`: its instructions live in `.claude/rules/brigade.md`, which Claude Code loads
 at launch like a `CLAUDE.md`.
 
 When Brigade is already installed, `init` asks whether to keep the installed version or update to the one you run.
-Updating does not repeat the setup: your stored answers are reused and only the options that are new to the manifest
-are asked. On the same version it offers to change your options (every question is asked again, files only change if
-an answer does) or to leave everything as it is. Without a terminal, it updates.
+Updating does not repeat the setup: your answers stored in `.claude/brigade.json` are reused and only the options the
+new version added are asked (your personal reply language is not one of them). A downgrade does the same and keeps the
+answers the older version does not know. On the same version it offers to change your options (every question is asked
+again, files only change if an answer does) or to leave everything as it is. Without a terminal, it updates.
 
 An existing file is never overwritten. If it differs from the kit, a `.proposed` file is written next to it; if it is
 identical, nothing happens. A file Brigade wrote and nobody touched is updated. `.gitignore` and `.gitattributes` only
-get the lines they miss. `.claude/context/decisions.md` is written once and then belongs to the team: it is never
-updated nor proposed over.
+get the lines they miss. `.claude/context/decisions.md` and `.claude/context/architecture.md` are written once and then
+belong to the
+project: they are never updated nor proposed over.
 
 ## Update
 
 Re-run `npx @frontfactory/brigade init`. Kit files you never touched are updated. A file you edited is left as it is
 and a `<file>.proposed` is written next to it: diff it, merge what you want, then delete the `.proposed`.
 
-An update does not ask your options again. It reuses the answers stored in `.claude/brigade.json` and asks only the
-options the new version added (your personal reply language is not one of them). A downgrade does the same and keeps
-the answers the older version does not know. To change your options on purpose, run `init` again on the same version
-and choose "Change my options".
+Older installs had your options written inside `.claude/rules/brigade.md`. They now live in the generated
+`.claude/rules/brigade-options.md`, and `brigade.md` is pure kit. If you never edited your `brigade.md`, it is updated
+silently. If you did (or the manifest is lost), a `brigade.md.proposed` is written with a note: merge it, or delete
+your edits and re-run.
+
+To change your options on purpose, run `init` again on the same version and choose "Change my options" (see Install).
 
 Brigade records what it did in `.claude/brigade.json`: its version, your answers and the sha256 of each file it wrote.
-That is how it tells an untouched file from an edited one. Do not edit it by hand.
+That is how it tells an untouched file from an edited one. Do not edit it by hand. Commit it with the rest of
+`.claude/`:
+the install is shared by the whole team, and anyone can then update it from any machine.
 
 ## Troubleshooting
 
 - `Unknown stack` or `Unknown option` from `init`: only `--yes` (`-y`) and `--stack <name>` exist, and `web` is the only
   stack for now. Run `npx @frontfactory/brigade --help` to see the usage.
-- `.proposed` files keep coming back: a proposal is rewritten only when the kit changed since the last one. Once you have
+- `.proposed` files keep coming back: a proposal is rewritten only when the kit changed since the last one. Once you
+  have
   merged what you want, delete the `.proposed`.
 - No terminal (CI, pipe): nothing is asked. `init` behaves like `--yes`: a new install accepts every detected answer, an
   existing install is updated with its stored answers, and a new option gets its detected or default value. The run
@@ -93,18 +111,23 @@ Only `git-operator` writes to git, enforced by a hook. Writing on the default or
 `rebase` ask for confirmation; destructive commands are denied. Brigade proposes a commit once a piece of work is
 finished and never commits without your go.
 
-A feature (work over several steps or sessions) gets its own branch and a state file `.claude/context/features/<branch>.md` (slashes become dashes), committed with the branch, so
+A feature (work over several steps or sessions) gets its own branch and a state file
+`.claude/context/features/<branch>.md` (slashes become dashes), committed with the branch, so
 the work survives between developers and machines. `CLAUDE.local.md` stays personal.
 
 ## Add a stack
 
-Create `templates/<name>/` with the same layout as `templates/web/`, then add one entry in `src/stacks.js`. Placeholders:
+Create `templates/<name>/` with the same layout as `templates/web/`, then add one entry in `src/stacks.js`.
+Placeholders:
 `__DEFAULT_BRANCH__`, `__BASE_BRANCH__`, `__PACKAGE_MANAGER__`, `__COMMIT_FORMAT__`, `__REPLY_LANGUAGE__`,
-`__CODE_LANGUAGE__`, `__DOCS_LANGUAGE__`.
+`__CODE_LANGUAGE__`, `__DOCS_LANGUAGE__`. Do not use them in `.claude/rules/brigade.md`: it stays pure kit, and the
+answers reach it through `.claude/rules/brigade-options.md`, which Brigade generates from the answers (see
+`renderOptions` in `src/install.js`).
 
 ## Develop
 
-`npm test` runs the tests (`node --test`, no dependency). Commits follow Conventional Commits, checked by commitlint. Node >= 24 is required.
+`npm test` runs the tests (`node --test`, no dependency). Commits follow Conventional Commits, checked by commitlint.
+Node >= 24 is required.
 
 Releases are automatic: on a push to `main` or `beta`, once the tests pass, the CI runs semantic-release, which
 derives the version from the commits, updates the changelog and publishes `@frontfactory/brigade` to npm.

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@frontfactory/brigade",
-    "version": "1.1.0",
-    "description": "Sets up a Claude Code architecture in any web project: a main session, a Sonnet implementer, a Haiku git-operator and a git guard.",
+    "version": "1.2.0",
+    "description": "Claude Code, organized like a kitchen brigade.",
     "type": "module",
     "scripts": {
         "prepare": "husky",

package/src/cli.js

@@ -1,5 +1,7 @@
-import { CONVENTIONS } from './conventions.js';
+import { parseArgs } from 'node:util';
+
 import { runInit } from './init.js';
+import { recapRows } from './options.js';
 import { STACKS } from './stacks.js';
 import { VERSION } from './version.js';
 
@@ -22,41 +24,51 @@ const WORDS = {
 };
 
 function parse(args) {
-    const options = { yes: false, stack: undefined };
-    for (let i = 0; i < args.length; i++) {
-        if (args[i] === '--yes' || args[i] === '-y') options.yes = true;
-        else if (args[i] === '--stack') {
-            const value = args[++i];
-            if (!value || value.startsWith('-')) throw new Error(`--stack needs a value (${Object.keys(STACKS).join(', ')})`);
-            options.stack = value;
+    let values;
+    try {
+        ({ values } = parseArgs({ args, options: { yes: { type: 'boolean', short: 'y' }, stack: { type: 'string' } } }));
+    } catch (error) {
+        const arg = /'([^']+)'/.exec(error.message)?.[1];
+        if (error.code === 'ERR_PARSE_ARGS_INVALID_OPTION_VALUE' && arg?.startsWith('--stack')) {
+            throw new Error(`--stack needs a value (${Object.keys(STACKS).join(', ')})`);
         }
-        else throw new Error(`Unknown option: ${args[i]}`);
+        if (error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION' || error.code === 'ERR_PARSE_ARGS_UNEXPECTED_POSITIONAL') {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        throw error;
     }
+    const options = { yes: values.yes ?? false, stack: values.stack };
+    if (options.stack === '') throw new Error(`--stack needs a value (${Object.keys(STACKS).join(', ')})`);
     if (options.stack && !STACKS[options.stack]) throw new Error(`Unknown stack: ${options.stack}`);
     return options;
 }
 
+// Plain-text rows, the label padded to a common column.
+const plain = (rows) => rows.map(([label, value]) => `${label.padEnd(17)}${value}`).join('\n');
+
 function summary({ version, answers, report, ignored, repo, personal, local, asked = [] }) {
-    const lines = report.map(({ path, status }) => `${WORDS[status].padEnd(28)} ${path}${status === 'proposed' ? '.proposed' : ''}`);
+    const files = report.map(({ path, status }) => ({
+        done: status === 'created' || status === 'updated',
+        label: `${path}${status === 'proposed' ? '.proposed' : ''}`,
+        detail: WORDS[status],
+        plain: `${WORDS[status].padEnd(28)} ${path}${status === 'proposed' ? '.proposed' : ''}`
+    }));
     for (const { path, status, added } of ignored) {
-        if (status === 'updated') lines.push(`${'lines added'.padEnd(28)} ${path} (${added.join(', ')})`);
+        if (status === 'updated') files.push({ done: true, label: path, detail: `lines added (${added.join(', ')})`, plain: `${'lines added'.padEnd(28)} ${path} (${added.join(', ')})` });
     }
 
-    const settings = [
-        `Brigade          ${version}`,
-        `Default branch   ${answers.defaultBranch}`,
-        `Reference branch ${answers.baseBranch}`,
-        `Package manager  ${answers.packageManager}`,
-        `Commit format    ${CONVENTIONS[answers.commitConvention]?.label ?? 'Custom'}`,
-        `Replies          ${answers.replyLanguage} (project default)`,
-        `Code             ${answers.codeLanguage}`,
-        `Documentation    ${answers.docsLanguage}`,
-        `Replies for you  ${personal.language && local?.status === 'written' ? `${personal.language} (your machine only)` : 'project default'}`
+    const notes = report.filter(({ note }) => note).map(({ path, note }) => `${path}: ${note}`);
+    const rows = [
+        ['Brigade', version],
+        ...recapRows(answers),
+        ['Replies for you', personal.language && local?.status === 'written' ? `${personal.language} (your machine only)` : 'project default']
     ];
     const added = asked.flat().map((key) => `${key}: ${answers[key]}`).join(', ');
-    return { files: lines.join('\n'), settings: settings.join('\n'), added, kept: report.some(({ status }) => status === 'proposed'), repo };
+    return { files, notes, rows, added, kept: report.some(({ status }) => status === 'proposed'), repo };
 }
 
+const plainFiles = (files, notes) => [...files.map(({ plain }) => plain), ...(notes.length ? ['', ...notes] : [])].join('\n');
+
 function print(result, interactive) {
     const { prompter } = result;
     if (result.kept) {
@@ -65,20 +77,26 @@ function print(result, interactive) {
         return;
     }
 
-    const { files, settings, added, kept, repo } = summary(result);
+    const { files, notes, rows, added, kept, repo } = summary(result);
 
     if (!interactive) {
         const news = added ? `\n\nNew options, default used: ${added}` : '';
-        console.log(`Brigade installed (stack: ${result.stack}).\n\n${files}\n\n${settings}${news}`);
+        console.log(`Brigade installed (stack: ${result.stack}).\n\n${plainFiles(files, notes)}\n\n${plain(rows)}${news}\n\nCommit .claude/ including .claude/brigade.json so the install is shared with your team and can be updated from any machine.`);
         return;
     }
 
-    prompter.note(files, 'Files');
-    prompter.note(settings, 'Your setup');
+    prompter.step(3, 3, 'Installation');
+    prompter.files(files);
+    for (const note of notes) prompter.info(note);
+    prompter.card('Your setup', rows);
     if (added) prompter.info(`New options set up: ${added}`);
     if (kept) prompter.warn('Some files of yours differ from the kit: they were kept. Merge the .proposed version if you want it.');
     if (!repo) prompter.warn('Remember to run `git init` before your first commit.');
-    prompter.outro('Done. Run `claude` here, use Plan Mode (Shift+Tab) to discuss, and /brigade-language and /brigade-effort for your own settings.');
+    prompter.done('Done. Brigade is ready.', [
+        'Commit `.claude/` (with `brigade.json`) to share the install.',
+        'Run `claude` here, Shift+Tab for Plan Mode.',
+        '/brigade-language and /brigade-effort set your own preferences.'
+    ]);
 }
 
 const isHelp = (arg) => arg === '--help' || arg === '-h';

package/src/init.js

@@ -1,5 +1,5 @@
 import { isGitRepo } from './detect.js';
-import { appendMissingLines, installFiles, readManifest, writeLocalSettings, writeManifest } from './install.js';
+import { appendMissingLines, hasKitFiles, installFiles, MANIFEST, readManifest, writeLocalSettings, writeManifest, writeOptionsFile } from './install.js';
 import { askOptions } from './options.js';
 import { createPrompter } from './prompt.js';
 import { DEFAULT_STACK, STACKS, detectStack } from './stacks.js';
@@ -38,7 +38,7 @@ export async function runInit({ cwd, yes = false, stack, stackDir, version = VER
 
     prompter ??= createPrompter({ interactive: Boolean(interactive) });
     const repo = isGitRepo(cwd);
-    prompter.intro(`Brigade ${version}`);
+    prompter.banner(version);
     prompter.info(`Stack: ${name}${stack ? '' : ' (the only one available for now)'}.`);
 
     const installed = previous?.version;
@@ -50,12 +50,16 @@ export async function runInit({ cwd, yes = false, stack, stackDir, version = VER
     if (!repo) {
         prompter.warn('No git repository here. Brigade will not create one: run `git init` when you are ready. The branch names below are kept for then.');
     }
+    if (!previous && hasKitFiles({ cwd, stackDir: dir })) {
+        prompter.warn(`${MANIFEST} is missing but Brigade files already exist here. Nothing is overwritten: files identical to the kit are adopted and files that differ get a .proposed. If the manifest exists in your team's repo, restore it from git first.`);
+    }
     // A version change replays the kit with the stored answers and only asks the missing options. Otherwise (first
     // install, same version) every question is asked.
     const update = choice === 'update' && installed !== version;
     const { answers, personal, asked } = await askOptions({ cwd, prompter, previous: previous?.answers ?? {}, full: !update });
 
     const { report, hashes } = installFiles({ cwd, stackDir: dir, answers, previous });
+    report.push(writeOptionsFile({ cwd, answers }));
     writeManifest({ cwd, version, stack: name, answers, hashes });
     const ignored = appendMissingLines(cwd);
     const local = personal.language ? writeLocalSettings(cwd, { language: personal.language }) : null;

package/src/install.js

@@ -3,6 +3,7 @@ import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, st
 import { dirname, join, relative } from 'node:path';
 
 export const MANIFEST = '.claude/brigade.json';
+export const OPTIONS_FILE = '.claude/rules/brigade-options.md';
 
 // Lines Brigade appends to the project files when missing. Existing lines are never touched or duplicated.
 const APPENDS = {
@@ -10,11 +11,14 @@ const APPENDS = {
     '.gitattributes': ['.claude/hooks/* text eol=lf']
 };
 
+const RULES_PATH = '.claude/rules/brigade.md';
+const MIGRATION_NOTE = "The kit's brigade.md no longer holds your options: they moved to .claude/rules/brigade-options.md. Merge brigade.md.proposed into your file, or delete your file's edits and re-run to take the new one.";
+
 // Written once, then the team's own: never updated, never proposed over.
-const WRITE_ONCE = new Set(['.claude/context/decisions.md']);
+const WRITE_ONCE = new Set(['.claude/context/decisions.md', '.claude/context/architecture.md']);
 
 // Line endings do not count: a CRLF checkout of a kit file is the same file.
-const sha = (content) => createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex');
+export const sha = (content) => createHash('sha256').update(content.replace(/\r\n/g, '\n')).digest('hex');
 
 function listFiles(dir) {
     return readdirSync(dir, { withFileTypes: true }).flatMap((entry) => {
@@ -24,6 +28,11 @@ function listFiles(dir) {
     });
 }
 
+// True when the project already holds at least one file of the kit.
+export function hasKitFiles({ cwd, stackDir }) {
+    return listFiles(stackDir).some((source) => existsSync(join(cwd, relative(stackDir, source))));
+}
+
 export function render(content, answers) {
     const values = {
         DEFAULT_BRANCH: answers.defaultBranch,
@@ -93,7 +102,9 @@ export function installFiles({ cwd, stackDir, answers, previous }) {
             const same = existsSync(proposed) && sha(readFileSync(proposed, 'utf8')) === wanted;
             if (!same) write(proposed);
             if (previous?.files?.[path]) hashes[path] = previous.files[path];
-            report.push({ path, status: 'proposed' });
+            const entry = { path, status: 'proposed' };
+            if (path === RULES_PATH && !readFileSync(target, 'utf8').includes('brigade-options.md')) entry.note = MIGRATION_NOTE;
+            report.push(entry);
         }
     }
 
@@ -107,6 +118,35 @@ export function installFiles({ cwd, stackDir, answers, previous }) {
     return { report, hashes };
 }
 
+// The project's answers in plain English. Not a kit file: generated from the answers at every install, always overwritten.
+export function renderOptions(answers) {
+    return `# Brigade options
+
+<!-- Generated by Brigade from .claude/brigade.json. Do not edit: changes are overwritten at the next install or update. -->
+
+Options of this project, referred to by \`.claude/rules/brigade.md\`.
+
+- Default branch: \`${answers.defaultBranch}\`.
+- Reference branch of the work: \`${answers.baseBranch}\`.
+- Package manager: \`${answers.packageManager}\`.
+- Commit format: ${answers.commitFormat}
+- Code, comments and commit messages language: ${answers.codeLanguage}.
+- Documentation language: ${answers.docsLanguage}.
+- Reply language, project default: ${answers.replyLanguage}.
+`;
+}
+
+export function writeOptionsFile({ cwd, answers }) {
+    const file = join(cwd, OPTIONS_FILE);
+    const content = renderOptions(answers);
+    const exists = existsSync(file);
+    if (exists && sha(readFileSync(file, 'utf8')) === sha(content)) return { path: OPTIONS_FILE, status: 'unchanged' };
+
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, content);
+    return { path: OPTIONS_FILE, status: exists ? 'updated' : 'created' };
+}
+
 const normalize = (line) => line.trim().replace(/^\//, '');
 
 export function appendMissingLines(cwd) {

package/src/options.js

@@ -9,29 +9,41 @@ import {
 
 const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
 const LANGUAGES = ['English', 'French'];
+const ENGLISH = LANGUAGES[0];
+const DIFFERENT = '__different__';
+const LANGUAGE_KEYS = ['replyLanguage', 'codeLanguage', 'docsLanguage'];
 
 const languages = (current) => [...new Set([current, ...LANGUAGES].filter(Boolean))].map((value) => ({ value, label: value }));
 
 // The options of the kit, in the order they are asked. `keys` are the names stored in the manifest `answers`: a group
 // is missing when any of its keys is. `ask(ctx)` returns the values of its keys. Every answer is detected first, then
-// validated by the dev; a previous answer wins over detection.
-// ctx: { cwd, prompter, previous (stored answers), answers (decided so far), full (asked from scratch), personal }
+// validated by the dev; a previous answer wins over detection. `detect(ctx)` returns the same values without asking
+// (express install), or null when they cannot be told.
+// ctx: { cwd, prompter, previous (stored answers), current (answers being edited), answers (decided so far), full (asked from scratch), personal }
 export const OPTIONS = [
     {
         keys: ['defaultBranch'],
-        ask: async ({ cwd, prompter: { validate, text }, previous }) => ({
+        detect: ({ cwd, previous }) => {
+            const defaultBranch = previous.defaultBranch || detectDefaultBranch(cwd);
+            return defaultBranch ? { defaultBranch } : null;
+        },
+        ask: async ({ cwd, prompter: { validate, text }, previous, current }) => ({
             defaultBranch: await validate(
                 'Default branch of the repository',
                 previous.defaultBranch || detectDefaultBranch(cwd),
-                () => text('Default branch of the repository', 'main')
+                () => text('Default branch of the repository', current.defaultBranch || 'main')
             )
         })
     },
     {
         keys: ['baseBranch'],
-        ask: async ({ cwd, prompter: { choose }, previous, answers }) => {
+        detect: ({ previous, answers }) => {
+            const baseBranch = previous.baseBranch || answers.defaultBranch;
+            return baseBranch ? { baseBranch } : null;
+        },
+        ask: async ({ cwd, prompter: { choose }, previous, current, answers }) => {
             const { defaultBranch } = answers;
-            const baseCandidates = [previous.baseBranch, defaultBranch, localBranches(cwd).includes('develop') && 'develop'].filter(Boolean);
+            const baseCandidates = [current.baseBranch, previous.baseBranch, defaultBranch, localBranches(cwd).includes('develop') && 'develop'].filter(Boolean);
             return {
                 baseBranch: await choose(
                     'Reference branch of the work',
@@ -46,9 +58,13 @@ export const OPTIONS = [
     },
     {
         keys: ['packageManager'],
-        ask: async ({ cwd, prompter: { validate, choose }, previous }) => {
+        detect: ({ cwd, previous }) => {
+            const packageManager = previous.packageManager || detectPackageManager(cwd).value;
+            return packageManager ? { packageManager } : null;
+        },
+        ask: async ({ cwd, prompter: { validate, choose }, previous, current }) => {
             const manager = detectPackageManager(cwd);
-            const managers = [...new Set([...manager.candidates, ...PACKAGE_MANAGERS])];
+            const managers = [...new Set([current.packageManager, ...manager.candidates, ...PACKAGE_MANAGERS].filter(Boolean))];
             return {
                 packageManager: await validate(
                     'Package manager',
@@ -64,8 +80,13 @@ export const OPTIONS = [
     },
     {
         keys: ['commitConvention', 'commitFormat'],
-        ask: async ({ cwd, prompter: { validate, choose, text }, previous }) => {
-            const start = previous.commitConvention || detectCommitConvention(cwd) || 'conventional';
+        detect: ({ cwd, previous }) => {
+            const commitConvention = previous.commitConvention || detectCommitConvention(cwd) || 'conventional';
+            if (commitConvention === 'custom') return previous.commitFormat ? { commitConvention, commitFormat: previous.commitFormat } : null;
+            return CONVENTIONS[commitConvention] ? { commitConvention, commitFormat: CONVENTIONS[commitConvention].format } : null;
+        },
+        ask: async ({ cwd, prompter: { validate, choose, text }, previous, current }) => {
+            const start = previous.commitConvention || current.commitConvention || detectCommitConvention(cwd) || 'conventional';
             const commitConvention = await validate(
                 'Commit convention',
                 start,
@@ -74,32 +95,75 @@ export const OPTIONS = [
                     [
                         ...Object.entries(CONVENTIONS).map(([value, { label, example }]) => ({ value, label, hint: example })),
                         { value: 'custom', label: 'Custom', hint: 'you describe it in one sentence' }
-                    ],
+                    ].sort((a, b) => (b.value === current.commitConvention) - (a.value === current.commitConvention)),
                     { other: false }
                 ),
                 CONVENTIONS[start]?.label
             );
             const commitFormat = commitConvention === 'custom'
-                ? await text('Describe your commit format in one sentence', previous.commitFormat)
+                ? await text('Describe your commit format in one sentence', previous.commitFormat || current.commitFormat)
                 : CONVENTIONS[commitConvention].format;
             return { commitConvention, commitFormat };
         }
     },
     {
-        keys: ['replyLanguage'],
+        keys: LANGUAGE_KEYS,
+        // The recommended setup: stored values first, then the language found (none when unknown), English for code and docs.
+        detect: ({ previous }) => {
+            const replyLanguage = previous.replyLanguage || detectLanguage();
+            const codeLanguage = previous.codeLanguage || ENGLISH;
+            return { ...(replyLanguage && { replyLanguage }), codeLanguage, docsLanguage: previous.docsLanguage || codeLanguage };
+        },
         ask: async (ctx) => {
-            const { prompter: { validate, choose }, previous } = ctx;
-            const replyLanguage = await validate(
-                "Default language of Claude's replies for this project (each developer can use their own later)",
-                previous.replyLanguage || detectLanguage(),
-                () => choose("Default language of Claude's replies for this project", languages())
+            const { prompter: { choose }, previous, current } = ctx;
+            const known = { ...current, ...previous };
+
+            // First question: replies. The language found comes first, stored values lead.
+            const detected = detectLanguage();
+            const replyOptions = languages(known.replyLanguage || detected);
+            if (!known.replyLanguage) replyOptions[0].hint = 'recommended';
+            const replyLanguage = await choose(
+                "Language of Claude's replies for this project (each developer can use their own later)",
+                replyOptions,
+                { other: false }
             );
+
+            // Second question: code and docs together, or apart. A stored split keeps "Different" first.
+            const together = known.codeLanguage && known.codeLanguage === known.docsLanguage ? known.codeLanguage : undefined;
+            const split = known.codeLanguage && known.docsLanguage && !together;
+            const sameChoices = [...new Set([ENGLISH, replyLanguage])].map((value) => ({ value, label: value }));
+            if (together && !sameChoices.some(({ value }) => value === together)) sameChoices.push({ value: together, label: together });
+            const different = { value: DIFFERENT, label: 'Different for code and docs', hint: 'you choose each language' };
+            const first = split ? different : sameChoices.find(({ value }) => value === (together || ENGLISH));
+            const codeDocs = await choose(
+                'Language of the code, comments, commit messages and documentation',
+                [first, ...[...sameChoices, different].filter((option) => option !== first)],
+                { other: false }
+            );
+
+            let languagesChosen;
+            if (codeDocs === DIFFERENT) {
+                const codeLanguage = await choose(
+                    'Language of the code, comments and commit messages (shared by the team)',
+                    languages(known.codeLanguage)
+                );
+                const docsLanguage = await choose(
+                    'Language of the documentation (shared by the team)',
+                    languages(known.docsLanguage || codeLanguage)
+                );
+                languagesChosen = { replyLanguage, codeLanguage, docsLanguage };
+            } else {
+                languagesChosen = { replyLanguage, codeLanguage: codeDocs, docsLanguage: codeDocs };
+            }
+
             // The personal choice lives in settings.local.json, not in the manifest: only asked from scratch.
+            delete ctx.personal.language;
             if (ctx.full) {
+                const { replyLanguage } = languagesChosen;
                 const mine = await choose(
                     'And for you? This stays on your machine',
                     [
-                        { value: 'keep', label: `Keep the project language (${replyLanguage || LANGUAGES[0]})` },
+                        { value: 'keep', label: `Keep the project language (${replyLanguage})` },
                         { value: 'own', label: 'Use another language for me' }
                     ],
                     { other: false }
@@ -111,31 +175,112 @@ export const OPTIONS = [
                     );
                 }
             }
-            return { replyLanguage: replyLanguage || LANGUAGES[0] };
-        }
-    },
-    {
-        keys: ['codeLanguage', 'docsLanguage'],
-        ask: async ({ prompter: { choose }, previous }) => {
-            const codeLanguage = await choose(
-                'Language of the code, comments and commit messages (shared by the team)',
-                languages(previous.codeLanguage)
-            );
-            const docsLanguage = await choose(
-                'Language of the documentation (shared by the team)',
-                languages(previous.docsLanguage || codeLanguage)
-            );
-            return { codeLanguage, docsLanguage };
+            return languagesChosen;
         }
     }
 ];
 
+// The answers as the dev reads them, before and after the files are written. Missing ones are still to be chosen.
+export function recapRows(answers) {
+    const show = (value, text = value) => (value === undefined ? 'to choose' : text);
+    return [
+        ['Default branch', show(answers.defaultBranch)],
+        ['Reference branch', show(answers.baseBranch)],
+        ['Package manager', show(answers.packageManager)],
+        ['Commit format', show(answers.commitConvention, CONVENTIONS[answers.commitConvention]?.label ?? 'Custom')],
+        ['Replies', show(answers.replyLanguage, `${answers.replyLanguage} (project default)`)],
+        ['Code', show(answers.codeLanguage)],
+        ['Documentation', show(answers.docsLanguage)]
+    ];
+}
+
 // `previous`: the stored answers. Returns the options (groups of keys) that have no stored value yet.
 export const missingOptions = (previous = {}) => OPTIONS.filter(({ keys }) => keys.some((key) => previous[key] === undefined));
 
+// What each option would be without asking. The ones that cannot be told are left out of the state.
+function propose(ctx) {
+    const answers = {};
+    for (const option of OPTIONS) {
+        const found = option.detect({ ...ctx, answers });
+        for (const [key, value] of Object.entries(found ?? {})) if (value !== undefined) answers[key] = value;
+    }
+    return answers;
+}
+
+// The groups the dev can re-open from the recap, each covering some options of OPTIONS.
+const GROUPS = [
+    { value: 'branches', label: 'Branches', options: [0, 1] },
+    { value: 'packageManager', label: 'Package manager', options: [2] },
+    { value: 'commit', label: 'Commit format', options: [3] },
+    { value: 'languages', label: 'Languages', options: [4] }
+];
+
+// Asks the given options in order, each one seeing the answers decided so far.
+async function askEach(options, ctx) {
+    for (const option of options) Object.assign(ctx.answers, await option.ask(ctx));
+}
+
+// A first install with a dev to ask. Everything is detected and shown in one card; "Install as is" takes it (the
+// options that cannot be told are still asked), "Customize" asks every option. After a customization, or when
+// something had to be asked, the recap can be edited group by group until it is right. Nothing is written before it
+// returns, so cancelling leaves the project untouched.
+async function askInteractive({ cwd, prompter, previous }) {
+    prompter.step(1, 3, 'Detection');
+    const personal = {};
+    const answers = propose({ cwd, prompter, previous, current: {}, answers: {}, full: true, personal });
+    const unresolved = OPTIONS.filter(({ keys }) => keys.some((key) => answers[key] === undefined));
+
+    prompter.step(2, 3, 'Review');
+    prompter.card('Here is what will be set up', recapRows(answers));
+    const mode = await prompter.choose(
+        'How do you want to set up Brigade?',
+        [
+            { value: 'asis', label: 'Install as is', hint: unresolved.length ? 'the options still to choose will be asked' : undefined },
+            { value: 'customize', label: 'Customize', hint: 'every option, one by one' }
+        ],
+        { other: false }
+    );
+
+    let reviewed = false;
+    if (mode === 'customize') {
+        for (const key of Object.keys(answers)) delete answers[key];
+        await askEach(OPTIONS, { cwd, prompter, previous, current: {}, answers, full: true, personal });
+        reviewed = true;
+    } else if (unresolved.length) {
+        await askEach(unresolved, { cwd, prompter, previous, current: {}, answers, full: false, personal });
+        reviewed = true;
+    } else {
+        prompter.info('Installing as detected.');
+    }
+
+    while (reviewed) {
+        prompter.card('Your setup', recapRows(answers));
+        const verdict = await prompter.choose(
+            'Is the setup right?',
+            [
+                { value: 'ok', label: 'Everything is right' },
+                { value: 'change', label: 'Change something' }
+            ],
+            { other: false }
+        );
+        if (verdict === 'ok') break;
+
+        const chosen = await prompter.multi('What do you want to change?', GROUPS.map(({ value, label }) => ({ value, label })));
+        // Re-asked options skip "Is that right?" and start from the current values.
+        const editor = { ...prompter, validate: async (_message, _detected, pick) => pick() };
+        const current = { ...answers };
+        const options = GROUPS.filter(({ value }) => chosen.includes(value)).flatMap(({ options }) => options.map((index) => OPTIONS[index]));
+        await askEach(options, { cwd, prompter: editor, previous: {}, current, answers, full: true, personal });
+    }
+    return { answers: { ...previous, ...answers }, personal, asked: [] };
+}
+
 // Asks the options in order. From scratch (`full`) every option is asked; otherwise only the missing ones and the
 // others keep their stored answers. Keys the kit does not know (older version) are kept as they are.
+// Without a dev to ask (`prompter.interactive` false) every question resolves to its default.
 export async function askOptions({ cwd, prompter, previous = {}, full }) {
+    if (full && prompter.interactive) return askInteractive({ cwd, prompter, previous });
+
     const missing = new Set(missingOptions(previous));
     const answers = {};
     const personal = {};
@@ -143,7 +288,7 @@ export async function askOptions({ cwd, prompter, previous = {}, full }) {
 
     for (const option of OPTIONS) {
         if (full || missing.has(option)) {
-            Object.assign(answers, await option.ask({ cwd, prompter, previous, answers, full, personal }));
+            Object.assign(answers, await option.ask({ cwd, prompter, previous, current: {}, answers, full, personal }));
             if (!full) asked.push(option.keys);
         } else {
             for (const key of option.keys) answers[key] = previous[key];

package/src/prompt.js

@@ -1,16 +1,20 @@
 import * as p from '@clack/prompts';
 
+import * as ui from './ui.js';
+
 const OTHER = Symbol('other');
 
 // Non-interactive (no TTY or `--yes`): every question resolves to its default and nothing is printed.
 export function createPrompter({ interactive }) {
+    const cancelled = () => {
+        console.log(`\n${ui.dim('Cancelled. Nothing was written.')}`);
+        process.exit(1);
+    };
+
     // Nothing is written before the last question, so cancelling leaves the project untouched.
     const answer = async (pending) => {
         const value = await pending;
-        if (p.isCancel(value)) {
-            p.cancel('Cancelled. Nothing was written.');
-            process.exit(1);
-        }
+        if (p.isCancel(value)) cancelled();
         return value;
     };
 
@@ -39,17 +43,28 @@ export function createPrompter({ interactive }) {
         return keep ? detected : pick();
     }
 
+    // Several values among `options` ([{ value, label, hint? }]), at least one. Nothing is asked without a dev.
+    async function multi(message, options) {
+        if (!interactive) return [];
+        return answer(p.multiselect({ message, options: options.map(({ value, label, hint }) => ({ value, label, hint })), required: true }));
+    }
+
     const when = (fn) => (...args) => interactive && fn(...args);
 
     return {
         text,
+        interactive,
         choose,
+        multi,
         validate,
-        intro: when((title) => p.intro(title)),
-        info: when((message) => p.log.info(message)),
-        warn: when((message) => p.log.warn(message)),
-        note: when((message, title) => p.note(message, title)),
-        outro: when((message) => p.outro(message)),
+        banner: when((version) => console.log(ui.banner(version))),
+        step: when((n, total, label) => console.log(ui.step(n, total, label))),
+        card: when((title, rows) => console.log(ui.card(title, rows))),
+        files: when((items) => console.log(`\n${ui.checklist(items)}`)),
+        info: when((message) => console.log(`${ui.dim('·')} ${ui.dim(message)}`)),
+        warn: when((message) => console.log(`${ui.accent('!')} ${message}`)),
+        outro: when((message) => console.log(`\n${message}`)),
+        done: when((message, lines) => console.log(`\n${ui.success('✓')} ${ui.bright(message)}\n${ui.bullets(lines)}\n`)),
         close: () => {}
     };
 }

package/src/ui.js

@@ -0,0 +1,71 @@
+import { styleText } from 'node:util';
+
+// The only place with colors and layout. `styleText` drops the escape codes by itself when the output is not a
+// terminal or when NO_COLOR is set, so every helper degrades to plain text.
+// Palette: amber accent, bright (cream) text, dim secondary, green for success, red for errors only.
+const paint = (format, text) => styleText(format, text);
+
+export const accent = (text) => paint(['bold', 'yellow'], text);
+export const bright = (text) => paint('whiteBright', text);
+export const dim = (text) => paint('gray', text);
+export const success = (text) => paint('green', text);
+export const warning = (text) => paint('yellow', text);
+export const danger = (text) => paint('red', text);
+
+const TAGLINE = 'Claude Code, organized like a kitchen brigade.';
+const FALLBACK_COLUMNS = 80;
+
+// A terminal reporting 0 columns (or none) is treated as 80.
+const columnsOf = (columns = process.stdout.columns) => (columns > 0 ? columns : FALLBACK_COLUMNS);
+
+const truncate = (text, max) => (text.length <= max ? text : `${text.slice(0, Math.max(0, max - 1))}…`);
+
+// Compact welcome header: letter-spaced wordmark, dimmed version, a rule, the tagline.
+export function banner(version) {
+    const wordmark = [...'BRIGADE'].join(' ');
+    return [
+        '',
+        `  ${accent(wordmark)}  ${dim(version)}`,
+        `  ${dim('─'.repeat(TAGLINE.length))}`,
+        `  ${dim(TAGLINE)}`,
+        ''
+    ].join('\n');
+}
+
+// A section label such as "1/3  Detection".
+export function step(n, total, label) {
+    return `\n${accent(`${n}/${total}`)}  ${bright(label)}`;
+}
+
+// An aligned key/value card with rounded borders, fitted to its content and capped to the terminal width.
+// `rows`: [[label, value]].
+export function card(title, rows, { columns } = {}) {
+    const keyWidth = Math.max(0, ...rows.map(([key]) => key.length));
+    const content = Math.max(title.length + 2, ...rows.map(([, value]) => keyWidth + 2 + value.length));
+    const inner = Math.max(12, Math.min(content, columnsOf(columns) - 4));
+    const valueWidth = Math.max(0, inner - keyWidth - 2);
+
+    const name = truncate(title, inner - 2);
+    const top = `${dim('╭─')} ${accent(name)} ${dim(`${'─'.repeat(inner - name.length - 2)}─╮`)}`;
+    const body = rows.map(([key, value]) => {
+        const shown = truncate(value, valueWidth);
+        const pad = ' '.repeat(Math.max(0, inner - keyWidth - 2 - shown.length));
+        return `${dim('│')} ${dim(key.padEnd(keyWidth))}  ${bright(shown)}${pad} ${dim('│')}`;
+    });
+    const bottom = dim(`╰${'─'.repeat(inner + 2)}╯`);
+    return ['', top, ...body, bottom].join('\n');
+}
+
+// A tidy list. `items`: [{ done, label, detail? }]. Done items get a green check, the others are dimmed.
+export function checklist(items) {
+    const width = Math.max(0, ...items.map(({ label }) => label.length));
+    return items.map(({ done, label, detail = '' }) => {
+        const gap = ' '.repeat(width - label.length);
+        return done
+            ? `  ${success('✓')} ${bright(label)}${gap}  ${dim(detail)}`
+            : `  ${dim('-')} ${dim(label)}${gap}  ${dim(detail)}`;
+    }).join('\n');
+}
+
+// Short lines with accent bullets.
+export const bullets = (lines) => lines.map((line) => `  ${accent('›')} ${bright(line)}`).join('\n');

package/templates/web/.claude/rules/brigade.md

@@ -1,6 +1,6 @@
 # Brigade
 
-Rules of the Brigade setup of this web project. Work is split between three roles.
+Rules of the Brigade setup of this web project. Work is split between three roles. The options of this project (branches, package manager, commit format, languages) are in `.claude/rules/brigade-options.md`, generated by Brigade.
 
 ## Roles
 
@@ -12,19 +12,19 @@ A brief to a subagent states the goal, the branch, the relevant files, the const
 
 ## Git
 
-- Default branch: `__DEFAULT_BRANCH__`. Reference branch of the work: `__BASE_BRANCH__`. Both are protected: writing on them needs the user's confirmation.
+- The default branch and the reference branch of the work are protected: writing on them needs the user's confirmation. Their names are in `.claude/rules/brigade-options.md`.
 - Check the current branch before any code.
 - A feature (several steps, sessions or files) = its own branch + a state file. Small work (a fix, a few files, one sitting) has neither: it ends with a commit on the current branch. Before any code, judge which it is and follow the skill `feature`: propose, wait for the user's answer, then `git-operator` creates the branch (with the user's go).
 - When the work is finished and its open questions are settled, propose the commit in one sentence. Never call `git-operator` without the user's go. The user can ask for a commit at any moment.
 - The feature file `.claude/context/features/<branch-with-slashes-as-dashes>.md` is shared and travels with the branch. `implementer` updates it at important steps; mention it in the `git-operator` brief so it goes in the same commit.
 - Pushing needs the user's confirmation. At the end of a session, or on pause/handoff, if commits are not pushed, propose the push in one sentence: without a push nothing survives.
-- Commit format, for `git-operator`: __COMMIT_FORMAT__
+- Commit format, for `git-operator`: the one in `.claude/rules/brigade-options.md`.
 
 ## Rules
 
 - At the start of a session, read `.claude/context/decisions.md` (team decisions, shared).
 - Keep changes small and focused.
-- Use the project's package manager: `__PACKAGE_MANAGER__`.
+- Use the project's package manager, given in `.claude/rules/brigade-options.md`.
 - Run lint, build or tests only when the user asks or the task needs them. Do not assume they exist.
 - Never read or write secrets (`.env*`, keys, tokens).
 - Say so before adding a dependency.
@@ -33,9 +33,8 @@ A brief to a subagent states the goal, the branch, the relevant files, the const
 
 ## Languages
 
-- Code, comments and commit messages: __CODE_LANGUAGE__.
-- Documentation: __DOCS_LANGUAGE__.
-- Replies: set by the `language` setting. The project default is __REPLY_LANGUAGE__; each developer can use their own with `/brigade-language`.
+- Code, comments, commit messages and documentation: the languages in `.claude/rules/brigade-options.md`.
+- Replies: set by the `language` setting. The project default is in `.claude/rules/brigade-options.md`; each developer can use their own with `/brigade-language`.
 
 ## Local effort