create-agentic-workspace 0.2.1 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-agentic-workspace",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "The pre-session bootstrap wizard for an Agentic Foundry workspace: declares (never grants) the permission floor, absorbs foundry-bootstrap.sh's out-of-session identity wiring, and scaffolds a seven-file schema-valid workspace. Zero dependencies, no lifecycle scripts, no telemetry.",
   "license": "MIT",
   "type": "module",
@@ -34,7 +34,7 @@
     "marketplace_name": "agentic-foundry",
     "marketplace_repo": "lukasrepublic/agentic-foundry",
     "plugin_name": "foundry",
-    "plugin_version": "1.2.1",
+    "plugin_version": "1.3.0",
     "pins_researched": "2026-08-02"
   }
 }

package/permission-floor.json

@@ -1,7 +1,7 @@
 {
   "schema_version": 1,
   "plugin_root_glob": "~/.claude/plugins/cache/*/foundry/*",
-  "generated_for_plugin_version": "1.2.1",
+  "generated_for_plugin_version": "1.3.0",
   "entries": [
     {
       "rule": "Bash(~/.claude/plugins/cache/*/foundry/*/scripts/foundry-acceptance-contract-validate.py:*)",

package/src/answers.mjs

@@ -9,6 +9,45 @@ function coerceBoolean(raw) {
   return v === 'y' || v === 'yes' || v === 'true' || v === '1';
 }
 
+/** The bracketed default (AC-WPD-5/-6/-7). A boolean renders `[y]`/`[n]` rather than its literal
+ * value — `[false]` reads as a type, not an affordance, on a yes/no question. An empty-string
+ * default renders `[blank]`: it states positively that a default exists, that it is blank, and
+ * therefore that Enter is safe. Rendering `[]` would read as noise instead. */
+export function defaultToken(rec) {
+  if (rec.default === undefined) return '';
+  if (rec.type === 'boolean') return rec.default ? '[y]' : '[n]';
+  return rec.default === '' ? '[blank]' : `[${rec.default}]`;
+}
+
+/** `(choices) [default]` — both when both are declared (AC-WPD-4). A boolean carries the implicit
+ * `(y/n)` vocabulary (AC-WPD-7). */
+export function promptSuffix(rec) {
+  const parts = [];
+  if (rec.choices) parts.push(`(${rec.choices.join('/')})`);
+  else if (rec.type === 'boolean') parts.push('(y/n)');
+  const dflt = defaultToken(rec);
+  if (dflt) parts.push(dflt);
+  return parts.length ? ` ${parts.join(' ')}` : '';
+}
+
+/** The description block printed ABOVE the prompt line (AC-WPD-2), with one indented line per
+ * enumerated choice BETWEEN the description and the prompt (AC-WPD-3). Derived from the question
+ * table and from no second list (AC-WPD-12). */
+export function renderPromptBlock(rec) {
+  // Leading blank line: readline echoes no newline after a piped answer, so without this the next
+  // question's description starts on the same line as the previous prompt. Separating the blocks
+  // is also simply easier to read in a real terminal.
+  const lines = ['', ...String(rec.description).split('\n')];
+  if (rec.choices) {
+    const width = Math.max(...rec.choices.map((c) => c.length));
+    for (const c of rec.choices) {
+      const note = (rec.choiceDescriptions || {})[c] || '';
+      lines.push(`  ${c.padEnd(width)}  ${note}`.trimEnd());
+    }
+  }
+  return lines.join('\n') + '\n';
+}
+
 /** yesMode is true when --yes was given OR stdin is not a TTY (AC-BCL-2): both suppress every
  * prompt, including the write-phase confirmation (AC-BCL-3). */
 export function isYesMode(values, isTTY) {
@@ -41,8 +80,11 @@ export async function resolveAnswers(table, parsed, { yesMode, input, output })
         resolved[rec.id] = rec.default;
         continue;
       }
-      const suffix = rec.choices ? ` (${rec.choices.join('/')})` : rec.default !== undefined && rec.default !== '' ? ` [${rec.default}]` : '';
-      const answer = (await rl.question(`${rec.prompt}${suffix}: `)).trim();
+      // The suffix is ADDITIVE (AC-WPD-4): choices and default render TOGETHER. The prior
+      // mutually-exclusive ternary suppressed the default on every record declaring choices —
+      // structurally, so the one record where a default matters most could never show it.
+      output.write(renderPromptBlock(rec));
+      const answer = (await rl.question(`${rec.prompt}${promptSuffix(rec)}: `)).trim();
       if (rec.type === 'boolean') {
         const b = coerceBoolean(answer);
         resolved[rec.id] = b === undefined ? rec.default : b;

package/src/argv.mjs

@@ -60,6 +60,19 @@ export function renderHelp(table, { programName = 'create-agentic-workspace' } =
     const req = rec.required ? ' (required)' : rec.default !== undefined && rec.default !== '' ? ` (default: ${rec.default})` : '';
     const choices = rec.choices ? ` [choices: ${rec.choices.join('|')}]` : '';
     lines.push(`  ${flagCol.padEnd(24)} ${rec.prompt}${choices}${req}`);
+    // The description renders as an indented continuation beneath its flag line (AC-WPD-10),
+    // across as many physical lines as the description itself contains, then one further
+    // indented line per declared choice (AC-WPD-11). Same table, no second list (AC-WPD-12).
+    for (const dline of String(rec.description).split('\n')) {
+      lines.push(dline ? `${' '.repeat(27)}${dline}` : '');
+    }
+    if (rec.choices) {
+      const width = Math.max(...rec.choices.map((c) => c.length));
+      for (const c of rec.choices) {
+        const note = (rec.choiceDescriptions || {})[c] || '';
+        lines.push(`${' '.repeat(27)}  ${c.padEnd(width)}  ${note}`.trimEnd());
+      }
+    }
   }
   lines.push('');
   lines.push('This CLI collects and transmits nothing: no telemetry.');

package/src/preview.mjs

@@ -23,12 +23,29 @@ export function renderPreview({ plan, machineScopeWrites, map }) {
   return lines.join('\n');
 }
 
-export const TRUST_HANDOFF_TEXT = (dir) => `
+// `isGitRepo` is computed by the CALLER and passed in, so this module stays pure (it renders text;
+// it does not probe the filesystem).
+//
+// WHY THE GIT STEP IS PRINTED AND NOT PERFORMED. A workspace that is not a git repository is a
+// dead end: the factory's whole discipline is branch-per-atom → PR → merge floor, and the setup
+// path tells the reader to apply branch protection a few steps later — which needs a repo AND a
+// remote. This CLI ALREADY writes a `.gitignore`, which means nothing without one.
+//
+// It is still printed rather than run. This CLI's contract is that it writes exactly the files it
+// previewed and nothing else; `git init` would be an un-previewed side effect, and the choice of
+// remote is genuinely the reader's. `create-vite` prints its next steps the same way, for the same
+// reason. Telling keeps the promise; doing would quietly break it.
+export const TRUST_HANDOFF_TEXT = (dir, { isGitRepo = true } = {}) => `
 The workspace has been written. The permission floor above is a declaration, not a grant: the
 platform's trust dialog is the consent ceremony, and the \`allow\` rules take effect only after
 you accept it — the dialog lists them.
 
-  cd ${dir}
+  cd ${dir}${isGitRepo ? '' : `
+  git init && git add -A && git commit -m 'workspace seed'
+  # ^ this directory is NOT a git repository yet. The factory works through
+  #   branch-per-atom → PR → the merge floor, so it needs a repo and a remote.
+  #   Create the remote too (e.g. \`gh repo create <you>/<project>-handbook --private --source=. --push\`)
+  #   before you reach the branch-protection step.`}
   claude
   > (accept the trust dialog when prompted)
   > /foundry:init

package/src/questions.mjs

@@ -1,8 +1,20 @@
 // questions.mjs — THE single question table (AC-BCL-2). Every accepted long flag, every --help
 // line and every interactive prompt are derived from this table and from no second list.
 //
-// Record shape: { id, flag, type: 'string'|'boolean', prompt, default? , required?, choices?,
-//                 interactive } — `default` XOR `required: true` (never both, never neither).
+// Record shape: { id, flag, type: 'string'|'boolean', prompt, description, default? , required?,
+//                 choices?, choiceDescriptions?, writesOutsideProject?, interactive }
+//               `default` XOR `required: true` (never both, never neither).
+//
+// `description` (AC-WPD-1) is prose stating what the answer DOES — rendered above the interactive
+// prompt (AC-WPD-2) and as an indented continuation in --help (AC-WPD-10). `choiceDescriptions`
+// carries one line per enumerated value (AC-WPD-3/-11); `choices` stays a plain string[] so
+// argv.mjs's membership check and the frozen AC-BCL-2 refusal test are untouched.
+//
+// `writesOutsideProject` (AC-WPD-9) marks a record whose answer writes outside the target root.
+// Its description MUST state the scope of the effect AND name each such artifact (AC-WPD-8/-14).
+// Naming the file without naming the scope is the failure this annotation exists to prevent: the
+// draft copy ("writes global git config, machine-wide") was read by the framework's own operator
+// as changing their global identity, which it does not do.
 
 export const QUESTION_TABLE = [
   {
@@ -10,6 +22,11 @@ export const QUESTION_TABLE = [
     flag: 'dir',
     type: 'string',
     prompt: 'Workspace directory to create',
+    description:
+      'The folder your specs, config, and factory wiring will live in — one\n' +
+      'per project (e.g. ./my-project-handbook). Relative to where you are\n' +
+      'now, or an absolute path.\n' +
+      'Required — there is no default, so Enter alone will not do.',
     required: true,
     interactive: true,
   },
@@ -17,7 +34,11 @@ export const QUESTION_TABLE = [
     id: 'existing',
     flag: 'existing',
     type: 'boolean',
-    prompt: 'Target directory already exists and is non-empty (scaffold into it; never clobbers)',
+    prompt: 'Scaffold into an existing folder?',
+    description:
+      'Nothing already there is overwritten — existing files are left alone and\n' +
+      'only the missing pieces are added.\n' +
+      'Enter alone means no. y, yes, true or 1 mean yes.',
     default: false,
     interactive: true,
   },
@@ -26,23 +47,53 @@ export const QUESTION_TABLE = [
     flag: 'stage-mode',
     type: 'string',
     prompt: 'Stage mode',
+    description:
+      'How much process ceremony this workspace enforces.\n' +
+      "Recorded in your workspace's CLAUDE.md; agents read it each session,\n" +
+      'and you can change it later by editing that line.',
     default: 'lean',
     choices: ['lean', 'scale'],
+    choiceDescriptions: {
+      lean: 'development loop with lighter ceremony — the solo/small-team norm',
+      scale: 'higher ceremony loop enforced end to end',
+    },
     interactive: true,
   },
   {
     id: 'ghAccount',
     flag: 'gh-account',
     type: 'string',
-    prompt: 'GitHub account slug for commit-identity isolation (blank to skip)',
+    prompt: 'GitHub account slug (blank to skip)',
+    description:
+      'GitHub account for commit identity.\n' +
+      'On a machine with more than one GitHub account, this makes sure commits\n' +
+      'in THIS workspace are always authored by the right one.\n' +
+      '\n' +
+      '  Leave blank to skip. Nothing outside this folder is written.\n' +
+      '\n' +
+      '  If you enter a slug, your global git identity is NOT changed. Git is\n' +
+      '  taught a rule that applies ONLY inside this folder:\n' +
+      '    - a small identity file is created at ~/.config/git/identity-<slug>\n' +
+      '    - two "only inside this folder" rules are added to your ~/.gitconfig,\n' +
+      '      pointing at that file\n' +
+      '    - inside this repo, git is told never to guess an identity, so a\n' +
+      '      mistake fails loudly instead of committing as the wrong you',
     default: '',
+    writesOutsideProject: true,
     interactive: true,
   },
   {
     id: 'gitAuthor',
     flag: 'git-author',
     type: 'string',
-    prompt: 'Git author "Name <email>" (blank: try gh, then prompt, then fail closed — only used with --gh-account)',
+    prompt: 'Git author name and email (blank to look up)',
+    description:
+      'Name and email to record in that identity file.\n' +
+      'Only used if you entered an account slug above — otherwise ignored.\n' +
+      'Format: Name <email@example.com>\n' +
+      'Leave blank to look it up from your GitHub account. If that cannot be\n' +
+      "determined you'll be asked; if it still cannot be resolved the run stops\n" +
+      'rather than committing under a guessed identity.',
     default: '',
     interactive: true,
   },
@@ -50,7 +101,12 @@ export const QUESTION_TABLE = [
     id: 'yes',
     flag: 'yes',
     type: 'boolean',
-    prompt: 'Accept every default and the write-phase confirmation without prompting',
+    prompt: 'Accept every default and skip the confirmation',
+    description:
+      'Non-interactive mode: every question resolves to its\n' +
+      'default and the final write confirmation is skipped.\n' +
+      'Required flags must be given on the command line or the\n' +
+      'run refuses. Also implied when stdin is not a terminal.',
     default: false,
     interactive: false,
   },
@@ -58,7 +114,11 @@ export const QUESTION_TABLE = [
     id: 'dryRun',
     flag: 'dry-run',
     type: 'boolean',
-    prompt: 'Print the preview only; make no write and no side effect',
+    prompt: 'Print the preview only; make no write',
+    description:
+      'Shows exactly what would be written — files inside the\n' +
+      'workspace and any machine-scope writes outside it — then\n' +
+      'exits. Nothing is created; no child process is spawned.',
     default: false,
     interactive: false,
   },
@@ -67,6 +127,9 @@ export const QUESTION_TABLE = [
     flag: 'help',
     type: 'boolean',
     prompt: 'Show this help and exit',
+    description:
+      'Prints every option with the same explanation the\n' +
+      'interactive prompt shows.',
     default: false,
     interactive: false,
   },

package/src/run.mjs

@@ -194,7 +194,12 @@ export async function runCli(argv, { cwd, isTTY, input, output, homeDir, pkgDir
       for (const f of findings) print(`  [${f.class}] ${JSON.stringify(f)}`);
     }
 
-    print(TRUST_HANDOFF_TEXT(targetRoot));
+    // Probed here, not inside preview.mjs, which renders text and never touches the filesystem.
+    // `.git` is a DIRECTORY in a normal clone and a FILE in a worktree/submodule, so `existsSync`
+    // on the path is the check that covers both — a directory-only test would tell a worktree user
+    // to re-init a repository they already have.
+    const isGitRepo = fs.existsSync(path.join(targetRoot, '.git'));
+    print(TRUST_HANDOFF_TEXT(targetRoot, { isGitRepo }));
 
     return { exitCode: exitCodeForPlan(plan), output: lines.join('\n') };
   } catch (e) {