@promptbook/cli 0.114.0-5 → 0.114.0-50

package/src/cli/cli-commands/coder/generate-boilerplates.ts

@@ -12,6 +12,9 @@ import {
     CODER_GIT_SYNC_DESCRIPTION,
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import type { BoilerplateCount } from './boilerplateCount';
 import {
@@ -39,7 +42,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
     command.description(
         spaceTrim(
             (block) => `
-                Generate prompt boilerplate files with unique emoji tags
+                Generate prompt boilerplate files with one unique emoji tag per file
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
             `,
@@ -59,8 +62,11 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
     );
     addCoderGitSyncOptions(command);
 
+    addWorkspaceRepositoryOptions(command);
+
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const { count: countOption, template: templateOption } = cliOptions as {
                 readonly count: string;
                 readonly template?: string;
@@ -68,14 +74,19 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 
             const boilerplateCount = parseBoilerplateCount(countOption);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
-            const projectPath = process.cwd();
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'mutate',
+                isAskingQuestionsEnabled: cliOptions.questions,
+            });
+            const { projectPath } = workspace;
 
             // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
+            const { $commitCoderChanges, $startCoderGitSync } = await import(
                 '../../../../scripts/run-codex-prompts/git/coderGitSync'
             );
 
-            await $pullCoderChanges({ gitSync, projectPath });
+            const commitScope = await $startCoderGitSync({ gitSync, workspace });
 
             await generatePromptBoilerplate({
                 projectPath,
@@ -85,7 +96,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 
             await $commitCoderChanges({
                 gitSync,
-                projectPath,
+                commitScope,
                 commitMessage: `Prompts ${formatBoilerplateCount(boilerplateCount)}`,
             });
 
@@ -95,7 +106,7 @@ export function $initializeCoderGenerateBoilerplatesCommand(program: Program): $
 }
 
 /**
- * Generates boilerplate prompt files with unique emoji tags.
+ * Generates boilerplate prompt files with one unique emoji tag per file.
  *
  * @private internal function of `generatePromptBoilerplate` command
  */
@@ -107,7 +118,7 @@ export async function generatePromptBoilerplate({
     readonly projectPath: string;
     readonly boilerplateCount: BoilerplateCount;
     readonly templateOption?: string;
-}): Promise<void> {
+}): Promise<ReadonlyArray<string>> {
     const { filesCount, promptsPerFileCount } = boilerplateCount;
 
     // Note: Import these dynamically to avoid circular dependencies and keep CLI fast
@@ -134,10 +145,10 @@ export async function generatePromptBoilerplate({
         colors.blue(`Highest existing number for ${promptNumbering.datePrefix} found: ${highestNumberFormatted}`),
     );
 
-    // Note: Every single generated prompt is one separate coding task, so each of them reserves its own fresh emoji tag
     const promptsCount = filesCount * promptsPerFileCount;
     const { availableCount, selectedEmojis } = await getFreshPromptEmojiTags({
-        count: promptsCount,
+        // Note: Each generated file reserves one fresh emoji tag shared by all of its prompt sections
+        count: filesCount,
         rootDir: projectPath,
     });
 
@@ -154,9 +165,7 @@ export async function generatePromptBoilerplate({
     for (let i = 0; i < filesCount; i++) {
         const number = promptNumbering.startNumber + i * promptNumbering.step;
         const title = titles[i % titles.length]!;
-        const emojiTags = selectedEmojis
-            .slice(i * promptsPerFileCount, (i + 1) * promptsPerFileCount)
-            .map((emoji) => formatPromptEmojiTag(emoji));
+        const emojiTag = formatPromptEmojiTag(selectedEmojis[i]!);
         const filename = buildPromptFilename(
             promptNumbering.datePrefix,
             number,
@@ -165,7 +174,8 @@ export async function generatePromptBoilerplate({
         const filepath = join(PROMPTS_DIRECTORY_PATH, filename);
         const absoluteFilepath = join(projectPath, filepath);
         const content = buildBoilerplatePromptFileContent({
-            emojiTags,
+            emojiTag,
+            promptsPerFileCount,
             title,
             body: promptTemplate.content,
         });
@@ -175,7 +185,7 @@ export async function generatePromptBoilerplate({
             absoluteFilepath,
             filename,
             content,
-            emojiTags,
+            emojiTag,
             number,
         });
     }
@@ -185,7 +195,7 @@ export async function generatePromptBoilerplate({
 
     for (const file of filesToCreate) {
         writeFileSync(file.absoluteFilepath, file.content, 'utf-8');
-        console.info(colors.green(`✓ Created: ${file.filename} with ${file.emojiTags.join(' ')}`));
+        console.info(colors.green(`✓ Created: ${file.filename} with ${file.emojiTag}`));
     }
 
     console.info(
@@ -193,34 +203,36 @@ export async function generatePromptBoilerplate({
             ` Successfully created ${promptsCount} prompts in ${filesToCreate.length} prompt boilerplate files! `,
         ),
     );
+    return filesToCreate.map(({ filepath }) => filepath);
 }
 
 /**
- * Builds the markdown content of one generated prompt file with one prompt section per emoji tag.
+ * Builds the markdown content of one generated prompt file with one prompt section per prompt.
  *
- * Multiple prompts in one file are separated by the `---` separator, exactly like the prompt runner expects them.
+ * Multiple prompts in one file share the file emoji tag and are separated by the `---` separator,
+ * exactly like the prompt runner expects them.
  *
  * @private internal utility of `generatePromptBoilerplate` command
  */
 function buildBoilerplatePromptFileContent({
-    emojiTags,
+    emojiTag,
+    promptsPerFileCount,
     title,
     body,
 }: {
-    readonly emojiTags: ReadonlyArray<string>;
+    readonly emojiTag: string;
+    readonly promptsPerFileCount: number;
     readonly title: string;
     readonly body: string;
 }): string {
-    return emojiTags
-        .map((emojiTag) =>
-            buildCoderPromptSection({
-                statusLine: '[-]',
-                emojiTag,
-                title,
-                body,
-            }),
-        )
-        .join('\n\n---\n\n');
+    return Array.from({ length: promptsPerFileCount }, () =>
+        buildCoderPromptSection({
+            statusLine: '[-]',
+            emojiTag,
+            title,
+            body,
+        }),
+    ).join('\n\n---\n\n');
 }
 
 /**

package/src/cli/cli-commands/coder/getCoderInitializationCommitPaths.ts

@@ -0,0 +1,44 @@
+import { join, relative } from 'path';
+import type { WorkspaceRepositoryContext } from '../common/workspaceRepository';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
+import type { CoderReferencedArtifactStatus } from './coderReferencedArtifacts';
+import { CODER_AGENTS_DIRECTORY_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_GITATTRIBUTES_FILE_PATH } from './ensureCoderGitattributesFile';
+import type { CoderInitializationSummary } from './initializeCoderProjectConfiguration';
+
+/**
+ * Restricts an explicit initialization commit to the initializer's write set, in repository-relative paths.
+ * The shared snapshot still excludes pre-existing files that initialization did not actually change.
+ *
+ * @private internal utility of the shared project initializer
+ */
+export function getCoderInitializationCommitPaths(
+    workspace: WorkspaceRepositoryContext,
+    summary: CoderInitializationSummary,
+    boilerplatePaths: ReadonlyArray<string>,
+): ReadonlyArray<string> {
+    const artifacts: ReadonlyArray<{
+        readonly relativeFilePath: string;
+        readonly status: CoderReferencedArtifactStatus;
+    }> = [
+        { relativeFilePath: 'prompts/README.md', status: summary.promptsReadmeFileStatus },
+        {
+            relativeFilePath: `${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}`,
+            status: summary.adamAgentFileStatus,
+        },
+        { relativeFilePath: '.env', status: summary.envFileStatus },
+        { relativeFilePath: '.gitignore', status: summary.gitignoreFileStatus },
+        { relativeFilePath: CODER_GITATTRIBUTES_FILE_PATH, status: summary.gitattributesFileStatus },
+        { relativeFilePath: 'package.json', status: summary.packageJsonFileStatus },
+        { relativeFilePath: '.vscode/settings.json', status: summary.vscodeSettingsFileStatus },
+        ...summary.referencedArtifactStatuses,
+    ];
+    return [
+        ...artifacts
+            .filter(({ status }) => status === 'created' || status === 'updated' || status === 'augmented')
+            .map(({ relativeFilePath }) => relativeFilePath),
+        ...boilerplatePaths,
+    ].map((path) => relative(workspace.repositoryRoot!, join(workspace.projectPath, path)).replace(/\\/gu, '/'));
+}
+
+// Note: [🟡] Code for initialization commit paths [getCoderInitializationCommitPaths](src/cli/cli-commands/coder/getCoderInitializationCommitPaths.ts) should never be published outside of `@promptbook/cli`

package/src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts

@@ -1,16 +1,82 @@
+import { AGENTS_FILE_PATH } from './agentsFile';
 import { DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE } from './boilerplateCount';
+import { COMMON_PROMPT_TEMPLATE_FILE_PATH } from './boilerplateTemplates';
+import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { formatDisplayPath } from './formatDisplayPath';
+import { CHECK_SETUP_PLACEHOLDER_COMMAND } from '../../../../scripts/run-codex-prompts/checks/projectCheck';
+
+/**
+ * Name of the npm script which `ptbk coder run` uses to verify the project.
+ */
+const CHECK_SCRIPT_NAME = 'check';
+
+/**
+ * One npm script initialized by `ptbk coder init`.
+ */
+type CoderPackageJsonScriptDefinition = {
+    /**
+     * Name of the npm script.
+     */
+    readonly scriptName: string;
+
+    /**
+     * Shell command of the npm script.
+     */
+    readonly scriptCommand: string;
+
+    /**
+     * Project-relative paths of the artifacts the command points at.
+     *
+     * Non-role artifacts are created with newly added scripts; role Books are always initialized when missing.
+     */
+    readonly referencedArtifactPaths: ReadonlyArray<string>;
+};
 
 /**
  * Default npm scripts initialized by `ptbk coder init`.
+ *
+ * Note: Using NPX because `ptbk` can be installed globally or locally, and NPX will resolve it correctly in either case.
  */
-const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
-    'coder:generate-boilerplates': `ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ./prompts/templates/common.md`,
-    'coder:add': 'ptbk coder add --template ./prompts/templates/common.md',
-    'coder:run':
-        'ptbk coder run --harness openai-codex --model gpt-5.6-terra --thinking-level max --agent agents/developer.book --context AGENTS.md --test-before yes-and-fix',
-    // 'coder:find-refactor-candidates': 'npx ptbk coder find-refactor-candidates',
-    'coder:verify': 'ptbk coder verify',
-} as const satisfies Readonly<Record<string, string>>;
+const DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS: ReadonlyArray<CoderPackageJsonScriptDefinition> = [
+    {
+        scriptName: 'coder:generate-boilerplates',
+        scriptCommand: `npx ptbk coder generate-boilerplates --count ${DEFAULT_BOILERPLATE_COUNT_OPTION_VALUE} --template ${formatCoderScriptFilePath(
+            COMMON_PROMPT_TEMPLATE_FILE_PATH,
+        )}`,
+        referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:add',
+        scriptCommand: `npx ptbk coder add --template ${formatCoderScriptFilePath(COMMON_PROMPT_TEMPLATE_FILE_PATH)}`,
+        referencedArtifactPaths: [COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:plan',
+        scriptCommand: 'npx ptbk coder plan --harness openai-codex',
+        referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH, COMMON_PROMPT_TEMPLATE_FILE_PATH],
+    },
+    {
+        scriptName: 'coder:run',
+        scriptCommand: [
+            'npx ptbk coder run --harness openai-codex --thinking-level max',
+            `--check "npm run ${CHECK_SCRIPT_NAME}" --check-before yes-and-fix`,
+        ].join(' '),
+        referencedArtifactPaths: [CODER_DEVELOPER_AGENT_FILE_PATH, AGENTS_FILE_PATH],
+    },
+    // { scriptName: 'coder:find-refactor-candidates', scriptCommand: 'npx ptbk coder find-refactor-candidates', referencedArtifactPaths: [] },
+    {
+        scriptName: 'coder:verify',
+        scriptCommand: 'npx ptbk coder verify',
+        referencedArtifactPaths: [],
+    },
+    {
+        // Note: The verification command of `coder:run` is a project-owned script, so every project can decide
+        //       what "verified" means without touching the `coder:run` script itself
+        scriptName: CHECK_SCRIPT_NAME,
+        scriptCommand: CHECK_SETUP_PLACEHOLDER_COMMAND,
+        referencedArtifactPaths: [],
+    },
+];
 
 /**
  * Lists the default npm scripts initialized by `ptbk coder init`.
@@ -18,7 +84,35 @@ const DEFAULT_CODER_PACKAGE_JSON_SCRIPTS = {
  * @private internal utility of `coder init` command
  */
 export function getDefaultCoderPackageJsonScripts(): Readonly<Record<string, string>> {
-    return DEFAULT_CODER_PACKAGE_JSON_SCRIPTS;
+    return Object.fromEntries(
+        DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.map(({ scriptName, scriptCommand }) => [
+            scriptName,
+            scriptCommand,
+        ]),
+    );
+}
+
+/**
+ * Collects the project-relative artifact paths referenced by the given default coder scripts.
+ *
+ * @private internal utility of `coder init` command
+ */
+export function resolveCoderPackageJsonScriptReferencedArtifactPaths(
+    scriptNames: ReadonlyArray<string>,
+): ReadonlySet<string> {
+    return new Set(
+        DEFAULT_CODER_PACKAGE_JSON_SCRIPT_DEFINITIONS.filter(({ scriptName }) => scriptNames.includes(scriptName))
+            .map(({ referencedArtifactPaths }) => referencedArtifactPaths)
+            .flat(),
+    );
+}
+
+/**
+ * Formats one project-relative path as an explicitly project-rooted path usable inside a shell command.
+ */
+function formatCoderScriptFilePath(relativeFilePath: string): string {
+    return `./${formatDisplayPath(relativeFilePath)}`;
 }
 
 // Note: [🟡] Code for coder init package scripts [getDefaultCoderPackageJsonScripts](src/cli/cli-commands/coder/getDefaultCoderPackageJsonScripts.ts) should never be published outside of `@promptbook/cli`
+// Note: [💞] Ignore a discrepancy between file name and exported helper names

package/src/cli/cli-commands/coder/init.ts

@@ -2,24 +2,38 @@ import type {
     Command as Program /* <- Note: [🔸] Using Program because Command is misleading name */,
 } from 'commander';
 import { spaceTrim } from 'spacetrim';
+import { ParseError } from '../../../errors/ParseError';
+import { EnvironmentMismatchError } from '../../../errors/EnvironmentMismatchError';
 import type { $side_effect } from '../../../utils/organization/$side_effect';
+import { ADAM_AGENT_BOOK_RELATIVE_PATH } from '../common/ensureAdamAgentBook';
 import type { CoderGitSyncCliOptions } from '../common/coderGitSyncCliOptions';
 import {
     addCoderGitSyncOptions,
     CODER_GIT_SYNC_DESCRIPTION,
     normalizeCoderGitSyncCliOptions,
 } from '../common/coderGitSyncCliOptions';
+import { $preflightWorkspaceRepository } from '../common/workspaceRepository';
+import { addWorkspaceRepositoryOptions } from '../common/workspaceRepositoryCliOptions';
+import { normalizeProjectCliOptions } from '../common/projectCliOptions';
 import { handleActionErrors } from '../common/handleActionErrors';
 import { $ensureHarnessInstallations } from '../common/harness/$ensureHarnessInstallations';
 import { getHarnessDefinition } from '../common/harness/HarnessDefinition';
+import {
+    addQuestionsOption,
+    normalizeQuestionsCliOptions,
+    QUESTIONS_DESCRIPTION,
+    type QuestionsCliOptions,
+} from '../common/questionsCliOptions';
 import type { PromptRunnerHarnessName } from '../common/promptRunnerCliOptions';
-import { AGENT_CODING_FILE_PATH } from './agentCodingFile';
 import { AGENTS_FILE_PATH } from './agentsFile';
 import { DEFAULT_BOILERPLATE_COUNT } from './boilerplateCount';
-import { getDefaultCoderProjectPromptTemplateDefinitions } from './boilerplateTemplates';
-import { CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { getDefaultCoderProjectPromptTemplateDefinitions, PROMPTS_DIRECTORY_PATH } from './boilerplateTemplates';
+import { CODER_AGENTS_DIRECTORY_PATH, CODER_DEVELOPER_AGENT_FILE_PATH } from './ensureCoderDeveloperAgentFile';
+import { CODER_GITATTRIBUTES_FILE_PATH } from './ensureCoderGitattributesFile';
+import { isDirectoryEmpty } from './ensureDirectory';
 import { formatDisplayPath } from './formatDisplayPath';
 import { generatePromptBoilerplate } from './generate-boilerplates';
+import { getCoderInitializationCommitPaths } from './getCoderInitializationCommitPaths';
 import { initializeCoderProjectConfiguration } from './initializeCoderProjectConfiguration';
 import { printInitializationSummary } from './printInitializationSummary';
 
@@ -48,57 +62,133 @@ export function $initializeCoderInitCommand(program: Program): $side_effect {
     command.description(
         spaceTrim(
             (block) => `
-                Initialize Promptbook coder configuration for current project
+                Initialize Git and Promptbook coder configuration for current project
+
+                Equivalent entrypoints: \`ptbk init\`, \`ptbk coder init\`, and \`ptbk coder initialize\`.
+                Creates a local Git working tree automatically when missing, including with \`--no-questions\`.
+                Reuses an enclosing repository without changing its history, configuration or index.
+                Does not stage existing files or create a first commit unless \`--commit\` is explicitly requested.
 
                 Creates or updates:
                 - prompts/
+                - prompts/README.md (offline PRD and workflow guide; existing README is preserved)
                 - prompts/done/
                 ${block(listDefaultCoderProjectPromptTemplateDisplayPaths())}
                 - ${CODER_DEVELOPER_AGENT_FILE_PATH}
+                - agents/planner.book
+                - agents/lawyer.book
+                - agents/copywriter.book
+                - ${CODER_AGENTS_DIRECTORY_PATH}/${ADAM_AGENT_BOOK_RELATIVE_PATH}
                 - ${AGENTS_FILE_PATH}
-                - ${AGENT_CODING_FILE_PATH}
-                - .gitignore
+                - .gitignore with node_modules and local artifacts from every supported harness
+                - ${CODER_GITATTRIBUTES_FILE_PATH} with automatic text detection and LF line endings (existing file is preserved)
                 - package.json
                 - .vscode/settings.json
 
+                Never overwrites what the project already owns:
+                - Existing package.json scripts and .vscode/settings.json settings are kept, only missing ones are added
+                - Missing Developer, Planner, Lawyer, Copywriter and Adam Books are initialized even when scripts already exist
+                - Adds missing local Lawyer and Copywriter TEAM references to Developer and Planner, preserving existing content
+                - Helpers advise on relevant tasks; declaring TEAM does not run them for every task
+                - Reports created, augmented, unchanged and unresolved Books; invalid or conflicting files are left untouched
+                - Missing AGENTS.md is initialized independently of scripts; existing content is preserved
+
                 Ensures required coding-agent environment variables in .env:
                 - CODING_AGENT_GIT_NAME
                 - CODING_AGENT_GIT_EMAIL
                 - CODING_AGENT_GIT_SIGNING_KEY
 
-                Checks that the coding harnesses are installed globally and up to date:
+                Checks that the coding harnesses are installed and up to date unless \`--no-questions\` is used:
                 ${block(listCheckedHarnessLabels())}
 
                 ${block(CODER_GIT_SYNC_DESCRIPTION)}
+
+                ${block(QUESTIONS_DESCRIPTION)}
             `,
         ),
     );
 
     addCoderGitSyncOptions(command);
+    addQuestionsOption(command);
+
+    addWorkspaceRepositoryOptions(command);
 
     command.action(
         handleActionErrors(async (cliOptions) => {
+            const projectOptions = normalizeProjectCliOptions(cliOptions);
             const gitSync = normalizeCoderGitSyncCliOptions(cliOptions as CoderGitSyncCliOptions);
-            const projectPath = process.cwd();
-
-            // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
-            const { $commitCoderChanges, $pullCoderChanges } = await import(
-                '../../../../scripts/run-codex-prompts/git/coderGitSync'
-            );
-
-            await $pullCoderChanges({ gitSync, projectPath });
-
-            const summary = await initializeCoderProjectConfiguration(projectPath);
-            printInitializationSummary(summary);
-            await generatePromptBoilerplate({ projectPath, boilerplateCount: DEFAULT_BOILERPLATE_COUNT });
-
-            await $commitCoderChanges({
-                gitSync,
-                projectPath,
-                commitMessage: 'Initialize Promptbook Coder',
+            const questionsOptions = normalizeQuestionsCliOptions(cliOptions as QuestionsCliOptions);
+            const workspace = await $preflightWorkspaceRepository({
+                ...projectOptions,
+                policy: 'initialize',
+                ...questionsOptions,
             });
-
-            await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES);
+            const { projectPath } = workspace;
+
+            const completedSteps = [`Git repository ${workspace.repositoryStatus}: ${workspace.repositoryRoot}`];
+            try {
+                // Note: Import the git synchronization dynamically to keep the CLI fast for runs without `--commit`
+                const { $commitCoderChanges, $startCoderGitSync } = await import(
+                    '../../../../scripts/run-codex-prompts/git/coderGitSync'
+                );
+
+                const commitScope = await $startCoderGitSync({ gitSync, workspace });
+                completedSteps.push('Requested Git synchronization and initial change scope');
+                // Check before initialization adds the README, templates and archive directory.
+                const isPromptsDirectoryEmpty = await isDirectoryEmpty(projectPath, PROMPTS_DIRECTORY_PATH);
+
+                const summary = await initializeCoderProjectConfiguration(projectPath, (step) =>
+                    completedSteps.push(step),
+                );
+                printInitializationSummary(summary, workspace);
+
+                if (
+                    summary.adamAgentFileStatus === 'unresolved' ||
+                    summary.referencedArtifactStatuses.some(({ status }) => status === 'unresolved')
+                ) {
+                    throw new ParseError(
+                        spaceTrim(
+                            'Some default Books or TEAM references remain **unresolved**. Review the diagnostics above, fix the affected files, and run `ptbk coder init` again.',
+                        ),
+                    );
+                }
+
+                let boilerplatePaths: ReadonlyArray<string> = [];
+                if (isPromptsDirectoryEmpty) {
+                    boilerplatePaths = await generatePromptBoilerplate({
+                        projectPath,
+                        boilerplateCount: DEFAULT_BOILERPLATE_COUNT,
+                    });
+                    completedSteps.push('Prompt boilerplates');
+                }
+
+                await $commitCoderChanges({
+                    gitSync,
+                    commitScope,
+                    commitMessage: 'Initialize Promptbook Coder',
+                    relevantPaths: getCoderInitializationCommitPaths(workspace, summary, boilerplatePaths),
+                });
+
+                if (gitSync.isCommitEnabled) completedSteps.push('Scoped initialization commit');
+                await $ensureHarnessInstallations(CODER_INIT_CHECKED_HARNESS_NAMES, {
+                    isAskingQuestionsEnabled: questionsOptions.isAskingQuestionsEnabled && Boolean(process.stdin.isTTY),
+                });
+                console.info('Promptbook project initialized.');
+            } catch (error) {
+                throw new EnvironmentMismatchError(
+                    spaceTrim(
+                        (block) => `
+                    Promptbook project initialization is incomplete in \`${projectPath}\`.
+
+                    Completed setup steps:
+                    ${block(completedSteps.map((step) => `- ${step}`).join('\n'))}
+
+                    The failing step may have left partial files. Review them and rerun \`ptbk init\`.
+                    ${block(error instanceof Error ? error.message : String(error))}
+                `,
+                    ),
+                );
+            }
         }),
     );
 }