@frontfactory/brigade 1.0.0 → 1.1.1

package/README.md

@@ -42,14 +42,51 @@ 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. On
-the same version it offers to change your options (the questions are asked again, files only change if an answer
-does) or to leave everything as it is. Without a terminal, it updates.
+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.
 
 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".
+
+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. 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
+  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
+  prints one line naming the new options and the value used; it never fails for that.
+- "No git repository" warning: run `git init` yourself. Brigade never creates a repository.
+- A broken `.claude/settings.local.json` (invalid JSON) is left untouched, so your personal language is not written
+  there. Fix the file and run `init` again.
+
+## Security model of the git guard
+
+The hook (`templates/web/.claude/hooks/git-guard.mjs`, PreToolUse on Bash) is a safety net against mistakes, not a
+security boundary. It parses the text of the command, so it can miss indirect forms: subshells, `bash -c`, aliases,
+scripts. The real protections are the `permissions` in `settings.json` and branch protection on the remote.
+
+"Never read or write secrets" is a rule given to Claude, not an enforcement, beyond the `deny` `Read` rules in
+`settings.json`.
 
 ## Git
 

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@frontfactory/brigade",
-    "version": "1.0.0",
+    "version": "1.1.1",
     "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.",
     "type": "module",
     "scripts": {

package/src/cli.js

@@ -1,11 +1,16 @@
 import { CONVENTIONS } from './conventions.js';
 import { runInit } from './init.js';
 import { STACKS } from './stacks.js';
+import { VERSION } from './version.js';
 
 const HELP = `Usage: brigade init [--yes] [--stack <name>]
+       brigade --version
 
   --yes           accept every detected or default answer, ask nothing
+                  (an installed project is updated with its stored answers; new options get their default)
   --stack <name>  force the stack (${Object.keys(STACKS).join(', ')}); detected otherwise
+  -h, --help      show this help
+  -v, --version   show the version
 `;
 
 const WORDS = {
@@ -20,14 +25,18 @@ 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') options.stack = args[++i];
+        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;
+        }
         else throw new Error(`Unknown option: ${args[i]}`);
     }
     if (options.stack && !STACKS[options.stack]) throw new Error(`Unknown stack: ${options.stack}`);
     return options;
 }
 
-function summary({ version, answers, report, ignored, repo, personal, local }) {
+function summary({ version, answers, report, ignored, repo, personal, local, asked = [] }) {
     const lines = report.map(({ path, status }) => `${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(', ')})`);
@@ -44,7 +53,8 @@ function summary({ version, answers, report, ignored, repo, personal, local }) {
         `Documentation    ${answers.docsLanguage}`,
         `Replies for you  ${personal.language && local?.status === 'written' ? `${personal.language} (your machine only)` : 'project default'}`
     ];
-    return { files: lines.join('\n'), settings: settings.join('\n'), kept: report.some(({ status }) => status === 'proposed'), repo };
+    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 };
 }
 
 function print(result, interactive) {
@@ -55,25 +65,41 @@ function print(result, interactive) {
         return;
     }
 
-    const { files, settings, kept, repo } = summary(result);
+    const { files, settings, added, kept, repo } = summary(result);
 
     if (!interactive) {
-        console.log(`Brigade installed (stack: ${result.stack}).\n\n${files}\n\n${settings}`);
+        const news = added ? `\n\nNew options, default used: ${added}` : '';
+        console.log(`Brigade installed (stack: ${result.stack}).\n\n${files}\n\n${settings}${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');
+    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.outro('Done. Commit `.claude/` with `.claude/brigade.json` to share the install with your team: anyone can then update it from any machine. Run `claude` here, use Plan Mode (Shift+Tab) to discuss, and /brigade-language and /brigade-effort for your own settings.');
 }
 
+const isHelp = (arg) => arg === '--help' || arg === '-h';
+
 export async function main(argv) {
     const [command, ...rest] = argv;
+    if (command === undefined || command === 'help' || isHelp(command)) {
+        console.log(HELP);
+        return 0;
+    }
+    if (command === '--version' || command === '-v') {
+        console.log(VERSION);
+        return 0;
+    }
     if (command !== 'init') {
+        console.error(`brigade: Unknown command: ${command}\n\n${HELP}`);
+        return 1;
+    }
+    if (rest.some(isHelp)) {
         console.log(HELP);
-        return command === undefined || command === '--help' ? 0 : 1;
+        return 0;
     }
 
     try {

package/src/conventions.js

@@ -1,22 +1,25 @@
+// Shared by every convention text.
+const LIMIT = '72 characters max.';
+
 export const CONVENTIONS = {
     conventional: {
         label: 'Conventional Commits',
         example: 'feat(auth): add login form',
-        format: 'Conventional Commits: `type(scope): description` (`feat`, `fix`, `chore`, `refactor`, `docs`, `test`), imperative mood, 72 characters max.'
+        format: 'Conventional Commits: `type(scope): description` (`feat`, `fix`, `chore`, `refactor`, `docs`, `test`), imperative mood, ' + LIMIT
     },
     angular: {
         label: 'Angular',
         example: 'fix(core): handle empty list',
-        format: 'Angular: `type(scope): description` with the types `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `test`, imperative mood, 72 characters max.'
+        format: 'Angular: `type(scope): description` with the types `build`, `ci`, `docs`, `feat`, `fix`, `perf`, `refactor`, `test`, imperative mood, ' + LIMIT
     },
     gitmoji: {
         label: 'Gitmoji',
         example: '✨ Add login form',
-        format: 'Gitmoji: `<emoji> Description` (e.g. `✨ Add login form`), imperative mood, 72 characters max.'
+        format: 'Gitmoji: `<emoji> Description` (e.g. `✨ Add login form`), imperative mood, ' + LIMIT
     },
     imperative: {
         label: 'Simple imperative',
         example: 'Add login form',
-        format: 'A single imperative sentence without prefix (e.g. `Add login form`), 72 characters max.'
+        format: 'A single imperative sentence without prefix (e.g. `Add login form`), ' + LIMIT
     }
 };

package/src/init.js

@@ -1,111 +1,10 @@
-import { CONVENTIONS } from './conventions.js';
-import {
-    detectCommitConvention,
-    detectDefaultBranch,
-    detectLanguage,
-    detectPackageManager,
-    isGitRepo,
-    localBranches
-} from './detect.js';
-import { appendMissingLines, installFiles, readManifest, writeLocalSettings, writeManifest } from './install.js';
+import { isGitRepo } from './detect.js';
+import { appendMissingLines, hasKitFiles, installFiles, MANIFEST, readManifest, writeLocalSettings, writeManifest } from './install.js';
+import { askOptions } from './options.js';
 import { createPrompter } from './prompt.js';
 import { DEFAULT_STACK, STACKS, detectStack } from './stacks.js';
 import { VERSION, compareVersions } from './version.js';
 
-const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
-const LANGUAGES = ['English', 'French'];
-
-// Every answer is detected first, then validated by the dev. A previous answer wins over detection.
-async function ask({ cwd, prompter, previous = {} }) {
-    const { validate, choose, text } = prompter;
-    const branches = localBranches(cwd);
-
-    const defaultBranch = await validate(
-        'Default branch of the repository',
-        previous.defaultBranch || detectDefaultBranch(cwd),
-        () => text('Default branch of the repository', 'main')
-    );
-
-    const baseCandidates = [previous.baseBranch, defaultBranch, branches.includes('develop') && 'develop'].filter(Boolean);
-    const baseBranch = await choose(
-        'Reference branch of the work',
-        [...new Set(baseCandidates)].map((value) => ({
-            value,
-            label: value,
-            hint: value === defaultBranch ? 'default branch' : 'feature branches start from it'
-        }))
-    );
-
-    const manager = detectPackageManager(cwd);
-    const managers = [...new Set([...manager.candidates, ...PACKAGE_MANAGERS])];
-    const packageManager = await validate(
-        'Package manager',
-        previous.packageManager || manager.value,
-        () => choose(
-            'Package manager',
-            managers.map((value) => ({ value, label: value, hint: manager.candidates.includes(value) ? 'found in the project' : undefined })),
-            { other: false }
-        )
-    );
-
-    const conventionKey = await validate(
-        'Commit convention',
-        previous.commitConvention || detectCommitConvention(cwd) || 'conventional',
-        () => choose(
-            'Commit convention',
-            [
-                ...Object.entries(CONVENTIONS).map(([value, { label, example }]) => ({ value, label, hint: example })),
-                { value: 'custom', label: 'Custom', hint: 'you describe it in one sentence' }
-            ],
-            { other: false }
-        ),
-        CONVENTIONS[previous.commitConvention || detectCommitConvention(cwd) || 'conventional']?.label
-    );
-    const commitFormat = conventionKey === 'custom'
-        ? await text('Describe your commit format in one sentence', previous.commitFormat)
-        : CONVENTIONS[conventionKey].format;
-
-    const languages = (current) => [...new Set([current, ...LANGUAGES].filter(Boolean))].map((value) => ({ value, label: value }));
-
-    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 mine = await choose(
-        'And for you? This stays on your machine',
-        [
-            { value: 'keep', label: `Keep the project language (${replyLanguage || LANGUAGES[0]})` },
-            { value: 'own', label: 'Use another language for me' }
-        ],
-        { other: false }
-    );
-    const ownLanguage = mine === 'own'
-        ? await choose('Your own reply language', languages().filter(({ value }) => value !== replyLanguage))
-        : '';
-
-    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)
-    );
-
-    const answers = {
-        defaultBranch,
-        baseBranch,
-        packageManager,
-        commitConvention: conventionKey,
-        commitFormat,
-        replyLanguage: replyLanguage || LANGUAGES[0],
-        codeLanguage,
-        docsLanguage
-    };
-    return { answers, personal: { language: ownLanguage } };
-}
-
 // Asked whenever Brigade is already installed. The first option is the answer when nothing can be asked.
 async function chooseVersion({ prompter, installed, version }) {
     if (installed === version) {
@@ -125,7 +24,7 @@ async function chooseVersion({ prompter, installed, version }) {
     return prompter.choose(
         newer ? 'A newer version is available' : 'This Brigade is older than the installed one',
         [
-            { value: 'update', label: `${newer ? 'Update' : 'Switch'} to ${version}`, hint: 'new kit files, and the questions are asked again. Files you edited are kept' },
+            { value: 'update', label: `${newer ? 'Update' : 'Switch'} to ${version}`, hint: 'new kit files, your answers are kept and only new options are asked. Files you edited are kept' },
             { value: 'keep', label: `Keep ${installed}`, hint: 'nothing is written' }
         ],
         { other: false }
@@ -143,19 +42,26 @@ export async function runInit({ cwd, yes = false, stack, stackDir, version = VER
     prompter.info(`Stack: ${name}${stack ? '' : ' (the only one available for now)'}.`);
 
     const installed = previous?.version;
-    if (installed && await chooseVersion({ prompter, installed, version }) === 'keep') {
+    const choice = installed && await chooseVersion({ prompter, installed, version });
+    if (choice === 'keep') {
         return { kept: installed, stack: previous.stack ?? name, answers: previous.answers, report: [], ignored: [], repo, prompter, personal: {}, local: null };
     }
 
     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.');
     }
-    const { answers, personal } = await ask({ cwd, prompter, previous: previous?.answers });
+    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 });
     writeManifest({ cwd, version, stack: name, answers, hashes });
     const ignored = appendMissingLines(cwd);
     const local = personal.language ? writeLocalSettings(cwd, { language: personal.language }) : null;
 
-    return { version, stack: name, answers, report, ignored, repo, prompter, personal, local };
+    return { version, stack: name, answers, report, ignored, repo, prompter, personal, local, asked };
 }

package/src/install.js

@@ -1,5 +1,5 @@
 import { createHash } from 'node:crypto';
-import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, relative } from 'node:path';
 
 export const MANIFEST = '.claude/brigade.json';
@@ -11,9 +11,10 @@ const APPENDS = {
 };
 
 // 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']);
 
-const sha = (content) => createHash('sha256').update(content).digest('hex');
+// Line endings do not count: a CRLF checkout of a kit file is the same file.
+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) => {
@@ -23,6 +24,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,
@@ -36,59 +42,73 @@ export function render(content, answers) {
     return content.replace(/__([A-Z_]+)__/g, (match, key) => values[key] ?? match);
 }
 
+// A missing manifest means a first install. An unreadable one is an error: guessing would overwrite the install.
 export function readManifest(cwd) {
+    const file = join(cwd, MANIFEST);
+    if (!existsSync(file)) return null;
     try {
-        return JSON.parse(readFileSync(join(cwd, MANIFEST), 'utf8'));
+        const manifest = JSON.parse(readFileSync(file, 'utf8'));
+        if (manifest && typeof manifest === 'object' && !Array.isArray(manifest)) return manifest;
     } catch {
-        return null;
+        // Reported below, same as a valid JSON of the wrong shape.
     }
+    throw new Error(`${MANIFEST} is corrupted. Fix it or delete it to start over (Brigade will then treat this as a first install).`);
 }
 
 // Never overwrites a file that differs from what Brigade last wrote: that one gets a `.proposed` next to it.
+// Everything is planned first (reads only), then written, so an error while planning leaves the project untouched.
 export function installFiles({ cwd, stackDir, answers, previous }) {
     const report = [];
     const hashes = {};
+    const writes = [];
+    const removals = [];
 
     for (const source of listFiles(stackDir)) {
         const path = relative(stackDir, source).split('\\').join('/');
         const target = join(cwd, path);
         const content = render(readFileSync(source, 'utf8'), answers);
         const mode = statSync(source).mode & 0o777;
-
-        const write = (file) => {
-            mkdirSync(dirname(file), { recursive: true });
-            writeFileSync(file, content, { mode });
-            chmodSync(file, mode);
-        };
+        const wanted = sha(content);
+        const proposed = `${target}.proposed`;
+        const write = (file) => writes.push({ file, content, mode });
 
         if (!existsSync(target)) {
             write(target);
-            hashes[path] = sha(content);
+            hashes[path] = wanted;
             report.push({ path, status: 'created' });
             continue;
         }
 
         const current = sha(readFileSync(target, 'utf8'));
         if (WRITE_ONCE.has(path)) {
-            report.push({ path, status: current === sha(content) ? 'unchanged' : 'kept' });
+            report.push({ path, status: current === wanted ? 'unchanged' : 'kept' });
             continue;
         }
-        if (current === sha(content)) {
+        if (current === wanted) {
+            // The target caught up with the kit: an old proposal is stale.
+            if (existsSync(proposed)) removals.push(proposed);
             hashes[path] = current;
             report.push({ path, status: 'unchanged' });
         } else if (previous?.files?.[path] === current) {
             write(target);
-            hashes[path] = sha(content);
+            if (existsSync(proposed)) removals.push(proposed);
+            hashes[path] = wanted;
             report.push({ path, status: 'updated' });
         } else {
-            const proposed = `${target}.proposed`;
-            const same = existsSync(proposed) && sha(readFileSync(proposed, 'utf8')) === sha(content);
+            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' });
         }
     }
 
+    for (const { file, content, mode } of writes) {
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, content, { mode });
+        chmodSync(file, mode);
+    }
+    for (const file of removals) rmSync(file, { force: true });
+
     return { report, hashes };
 }
 
@@ -98,14 +118,16 @@ export function appendMissingLines(cwd) {
     return Object.entries(APPENDS).map(([path, lines]) => {
         const file = join(cwd, path);
         const existing = existsSync(file) ? readFileSync(file, 'utf8') : '';
-        const known = new Set(existing.split('\n').map(normalize));
+        const known = new Set(existing.split(/\r?\n/).map(normalize));
         const missing = lines.filter((line) => !known.has(normalize(line)));
 
         if (missing.length === 0) return { path, status: 'unchanged' };
 
-        const separator = existing === '' || existing.endsWith('\n') ? '' : '\n';
-        const heading = existing === '' ? '' : '\n';
-        writeFileSync(file, `${existing}${separator}${heading}## Claude\n${missing.join('\n')}\n`);
+        // Keep the file's own line endings.
+        const eol = existing.includes('\r\n') ? '\r\n' : '\n';
+        const separator = existing === '' || existing.endsWith('\n') ? '' : eol;
+        const heading = existing === '' ? '' : eol;
+        writeFileSync(file, `${existing}${separator}${heading}## Claude${eol}${missing.join(eol)}${eol}`);
         return { path, status: 'updated', added: missing };
     });
 }

package/src/options.js

@@ -0,0 +1,153 @@
+import { CONVENTIONS } from './conventions.js';
+import {
+    detectCommitConvention,
+    detectDefaultBranch,
+    detectLanguage,
+    detectPackageManager,
+    localBranches
+} from './detect.js';
+
+const PACKAGE_MANAGERS = ['npm', 'pnpm', 'yarn', 'bun'];
+const LANGUAGES = ['English', 'French'];
+
+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 }
+export const OPTIONS = [
+    {
+        keys: ['defaultBranch'],
+        ask: async ({ cwd, prompter: { validate, text }, previous }) => ({
+            defaultBranch: await validate(
+                'Default branch of the repository',
+                previous.defaultBranch || detectDefaultBranch(cwd),
+                () => text('Default branch of the repository', 'main')
+            )
+        })
+    },
+    {
+        keys: ['baseBranch'],
+        ask: async ({ cwd, prompter: { choose }, previous, answers }) => {
+            const { defaultBranch } = answers;
+            const baseCandidates = [previous.baseBranch, defaultBranch, localBranches(cwd).includes('develop') && 'develop'].filter(Boolean);
+            return {
+                baseBranch: await choose(
+                    'Reference branch of the work',
+                    [...new Set(baseCandidates)].map((value) => ({
+                        value,
+                        label: value,
+                        hint: value === defaultBranch ? 'default branch' : 'feature branches start from it'
+                    }))
+                )
+            };
+        }
+    },
+    {
+        keys: ['packageManager'],
+        ask: async ({ cwd, prompter: { validate, choose }, previous }) => {
+            const manager = detectPackageManager(cwd);
+            const managers = [...new Set([...manager.candidates, ...PACKAGE_MANAGERS])];
+            return {
+                packageManager: await validate(
+                    'Package manager',
+                    previous.packageManager || manager.value,
+                    () => choose(
+                        'Package manager',
+                        managers.map((value) => ({ value, label: value, hint: manager.candidates.includes(value) ? 'found in the project' : undefined })),
+                        { other: false }
+                    )
+                )
+            };
+        }
+    },
+    {
+        keys: ['commitConvention', 'commitFormat'],
+        ask: async ({ cwd, prompter: { validate, choose, text }, previous }) => {
+            const start = previous.commitConvention || detectCommitConvention(cwd) || 'conventional';
+            const commitConvention = await validate(
+                'Commit convention',
+                start,
+                () => choose(
+                    'Commit convention',
+                    [
+                        ...Object.entries(CONVENTIONS).map(([value, { label, example }]) => ({ value, label, hint: example })),
+                        { value: 'custom', label: 'Custom', hint: 'you describe it in one sentence' }
+                    ],
+                    { other: false }
+                ),
+                CONVENTIONS[start]?.label
+            );
+            const commitFormat = commitConvention === 'custom'
+                ? await text('Describe your commit format in one sentence', previous.commitFormat)
+                : CONVENTIONS[commitConvention].format;
+            return { commitConvention, commitFormat };
+        }
+    },
+    {
+        keys: ['replyLanguage'],
+        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())
+            );
+            // The personal choice lives in settings.local.json, not in the manifest: only asked from scratch.
+            if (ctx.full) {
+                const mine = await choose(
+                    'And for you? This stays on your machine',
+                    [
+                        { value: 'keep', label: `Keep the project language (${replyLanguage || LANGUAGES[0]})` },
+                        { value: 'own', label: 'Use another language for me' }
+                    ],
+                    { other: false }
+                );
+                if (mine === 'own') {
+                    ctx.personal.language = await choose(
+                        'Your own reply language',
+                        languages().filter(({ value }) => value !== replyLanguage)
+                    );
+                }
+            }
+            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 };
+        }
+    }
+];
+
+// `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));
+
+// 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.
+export async function askOptions({ cwd, prompter, previous = {}, full }) {
+    const missing = new Set(missingOptions(previous));
+    const answers = {};
+    const personal = {};
+    const asked = [];
+
+    for (const option of OPTIONS) {
+        if (full || missing.has(option)) {
+            Object.assign(answers, await option.ask({ cwd, prompter, previous, answers, full, personal }));
+            if (!full) asked.push(option.keys);
+        } else {
+            for (const key of option.keys) answers[key] = previous[key];
+        }
+    }
+    return { answers: { ...previous, ...answers }, personal, asked };
+}